class BickleyJet

class deeptime.data.BickleyJet(h: float, n_steps: int, full_periodic=True)

Implementation of the Bickley jet. Based on [1].

The parameters are set to

\[\begin{aligned} U_0 &= 5.4138 \times \frac{10^6\mathrm{m}}{\mathrm{day}},\\ L_0 &= 1.77 \times 10^6\,\mathrm{m},\\ r_0 &= 6.371 \times 10^6\,\mathrm{m},\\ c &= (0.1446, 0.205, 0.461)^\top U_0,\\ \mathrm{eps} &= (0.075, 0.15, 0.3)^\top,\\ k &= (2,4,6)^\top \frac{1}{r_0}. \end{aligned}\]

Parameters:

• h (float) – Step size of the RK45 integrator.

• n_steps (int) – Number of steps before recording it in the trajectory.

• full_periodic (bool, optional, default=True) – Whether the quasi-periodic boundary is already built into right-hand side evaluation.

References

[1]

Alireza Hadjighasem, Daniel Karrasch, Hiroshi Teramoto, and George Haller. Spectral-clustering approach to lagrangian vortex detection. Physical Review E, 93(6):063107, 2016.

Attributes

L0	The characteristic length scale \(L_0 = 1.77\) in \(10^6\;\mathrm{m}\).
U0	The characteristic velocity scale \(U_0 = 5.4138\) in \(10^6 \frac{\mathrm{m}}{\mathrm{day}}\).
c	Traveling speeds \(c = (0.1446, 0.205, 0.461)^\top U_0\).
dimension	The dimension of the system's state.
eps	Wave amplitudes \(\varepsilon = (0.075, 0.15, 0.3)^\top\).
f	The right-hand side of the system as callable function.
h	The integration step size.
has_potential_function	Whether the system defines a potential.
integrator	The type of integrator.
k	Wave numbers \(k = (2,4,6)^\top \frac{1}{r_0}\).
n_steps	The number of integration steps between each evaluation of the state.
periodic_bc	Whether periodic boundary conditions are applied.
r0	The mean radius of the earth \(r_0 = 6.371\) in \(10^6\;\mathrm{m}\).
time_dependent	Whether the potential (if available) and the right-hand side depend on time.
vectorized_f	Yields whether the right-hand side function is vectorized.

Methods

apply_periodic_boundary_conditions(trajectory)	Applies periodic boundary conditions for domain \(\Omega = [0, 20)\times [-3, 3)\).
generate(n_particles[, n_jobs, seed])	Generates a trajectory with a fixed number of particles / test points for 401 evaluation steps, i.e., 401 * self.n_steps * self.h integration steps.
potential(time, points)	Evaluates the system's potential function at given points in state space at a specified time.
to_3d(data[, radius])	Maps a generated trajectory into 3d space by transforming it through
trajectory(t0, x0, length[, seed, n_jobs, ...])	Generates one or multiple trajectories for the Bickley jet.

__call__(t0, test_points, seed=-1, n_jobs=None)

Evolves the provided tests points under the dynamic for n_steps and returns.

Parameters:

• t0 (array_like) – The initial time. Can be picked as single float across all test points or individually.

• test_points (array_like) – The test points.

• seed (int, optional, default=-1) – The seed for reproducibility. In case it is set to seed >= 0 the number of jobs needs to be fixed to n_jobs=1.

• n_jobs (int, optional, default=None) – Specify number of jobs according to deeptime.util.parallel.handle_n_jobs().

Returns:

points – The evolved test points.

Return type:

np.ndarray

static apply_periodic_boundary_conditions(trajectory, inplace=False)

Applies periodic boundary conditions for domain \(\Omega = [0, 20)\times [-3, 3)\).

Notes

This method operates not in-place by default, i.e., makes a copy of the trajectory. This behavior can be changed by setting inplace=True.

Parameters:

• trajectory ((..., 2) ndarray) – Input trajectory, last axis must have length two for x and y, respectively.

• inplace (bool, optional, default=False) – Whether to operate in-place.

Returns:

Trajectory with applied boundary conditions.

Return type:

trajectory

generate(n_particles, n_jobs=None, seed=None) → ndarray

Generates a trajectory with a fixed number of particles / test points for 401 evaluation steps, i.e., 401 * self.n_steps * self.h integration steps.

Parameters:

• n_particles (int) – Number of particles.

• n_jobs (int, optional, default=None) – Number of jobs.

• seed (int or None, optional, default=None) – Random seed used for initialization of particle positions at \(t=0\).

Returns:

Z – Trajectories for m uniformly distributed test points in Omega = [0, 20] x [-3, 3].

Return type:

np.ndarray (m, 401, 2)

potential(time, points)

Evaluates the system’s potential function at given points in state space at a specified time.

Parameters:

• time (float) – The evaluation time.

• points (array_like) – The points.

Returns:

energy – The energy for each of these points.

Return type:

np.ndarray

Raises:

AssertionError – If the system does not have a potential function defined.

static to_3d(data: ndarray, radius: float = 1.0) → ndarray

Maps a generated trajectory into 3d space by transforming it through

\[\begin{pmatrix} x \\ y \end{pmatrix} \mapsto \begin{pmatrix} r\cdot \cos\left( 2\pi \frac{x}{20} \right) \\ r\cdot \sin\left( 2\pi \frac{x}{20} \right) \\ \frac{y}{3} \end{pmatrix}\]

which means that the particles are now on the surface of a cylinder with a fixed radius, i.e., periodic boundary conditions are directly encoded in the space.

Parameters:

• data ((T, 2) ndarray) – The generated trajectory.

• radius (float, default=1) – The radius of the cylinder.

Returns:

xyz – Trajectory on the cylinder.

Return type:

(T, 3) np.ndarray

trajectory(t0, x0, length, seed=-1, n_jobs=None, return_time=False)

Generates one or multiple trajectories for the Bickley jet.

Parameters:

• t0 (array_like) – The initial time. Can be picked as single float across all test points or individually.

• x0 (array_like) – The initial condition. Must be compatible in shape to a (n_test_points, dimension)-array.

• length (int) – The length of the trajectory that is to be generated.

• seed (int, optional, default=-1) – The random seed. In case it is specified to be something else than -1, n_jobs must be set to n_jobs=1.

• n_jobs (int, optional, default=None) – Specify number of jobs according to deeptime.util.parallel.handle_n_jobs().

• return_time (bool, optional, default=False) – Whether to return the evaluation times too.

property L0

The characteristic length scale \(L_0 = 1.77\) in \(10^6\;\mathrm{m}\).

property U0

The characteristic velocity scale \(U_0 = 5.4138\) in \(10^6 \frac{\mathrm{m}}{\mathrm{day}}\).

property c

Traveling speeds \(c = (0.1446, 0.205, 0.461)^\top U_0\).

property dimension: int

The dimension of the system’s state.

Type:

int

property eps

Wave amplitudes \(\varepsilon = (0.075, 0.15, 0.3)^\top\).

property f: Callable[[float, ndarray], ndarray]

The right-hand side of the system as callable function. In case of SDEs, this only evaluates the deterministic part of the function definition.

Some of these definitions are vectorized.

Returns:

right_hand_side – The right-hand side.

Return type:

Callable[[float, ndarray], ndarray]

property h: float

The integration step size.

property has_potential_function: bool

Whether the system defines a potential. This means that the deterministic part of the right-hand side is the negative gradient of that potential.

property integrator: str

The type of integrator.

Type:

str

property k

Wave numbers \(k = (2,4,6)^\top \frac{1}{r_0}\).

property n_steps: int

The number of integration steps between each evaluation of the state.

property periodic_bc: bool

Whether periodic boundary conditions are applied.

Getter:

Yields the current value. True corresponds to periodic boundaries.

Setter:

Sets a new value.

Type:

bool

property r0

The mean radius of the earth \(r_0 = 6.371\) in \(10^6\;\mathrm{m}\).

property time_dependent: bool

Whether the potential (if available) and the right-hand side depend on time.

Type:

bool

property vectorized_f: bool

Yields whether the right-hand side function is vectorized.

Type:

bool