LDDS

Submodules

ldds.base module

Module description …

Reference: - Surename1, Forename1 Initials., Surename2, Forename2 Initials, YEAR. Publication/Book title Publisher, Number(Volume No), pp.142-161.

ldds.base.EulerMaruyama_solver(t_initial, u_initial, vector_field, time_step, noise_amplitude=[0, 0], noise_type='additive')

Returns next time and state in the evolution of a stochastic ODE system via the Euler-Maruyama method.

Euler-Maruyama scheme:

t_next = t_initial + dt u_next = u_initial + v(t_initial, u_initial)*dt + b*dW

with u = (x, y)

NOTE: Depending on the ‘noise_type’ b will be a random constant (additive) or a vector (multiplicative).

Currently only implemented for 2D vector fields.

Parameters

• t_initial (float) – initial time-point of all initial points in phase space.

• u_initial (array_like, shape(n,)) – initial points in phase space to determine their evolution at time t_next.

• vector_field (function) – vector field over phase space.

• time_step (float) –

• noise_amplitude (list of floats) – amplitude values multiplying Weiner process.

• noise_type (string) – options ‘additive’ (default) or ‘multiplicative’.

Returns

• t_next (float) – next time-point in the evolution of stochastic system.

• u_next (array_like, shape(n,)) – next states in the evolution of stochastic system.

ldds.base.check_if_points_escape_box(u, box_boundaries)

Determine if points in phase space u have scaped box with user-defined defined dimensions

Parameters

• u (ndarray, shape(n, )) – points in phase space to check if outside box boundaries

• box_boundaries (list of 2-tuples of floats) – box lower and upper limits along X and Y axes

Returns

u_indices – array of True/False bool values if points inside/outside the box

Return type

ndarray, shape(n, )

ldds.base.compute_lagrangian_descriptor(grid_parameters, vector_field, tau, p_value=0.5, box_boundaries=False, rtol=0.0001)

Returns the values of the LD function from integrated trajectories from initial conditions in phase space.

Parameters

• grid_parameters (list of 3-tuples of floats) – input parameters of limits and size of mesh per axis

• vector_field (function) – vector field over phase space, must return 2D array of vectors over a 2D array of initial conditions and given as input to the API function vector_field_flat to be turned into a 1D array (column).

• tau (float) – Upper limit of integration.

• p_value (float, optional) – Exponent in Lagrangian descriptor definition. 0 is the acton-based LD, 0 < p_value < 1 is the Lp quasinorm, 1 <= p_value < 2 is the Lp norm LD, 2 is the arclength LD. The default is 0.5.

• box_boundaries (list of 2-tuples, optional) – Box boundaries for escape condition of variable time integration. Boundaries are infinite by default.

• rtol (float,) – Relative tolerance of integration step.

Returns

LD – Array of computed Lagrangian descriptor values for all initial conditions.

Return type

ndarray, shape (Nx, Ny)

ldds.base.fit_pes(filename, clip_max=False)

Returns a 1- or 2-dimensional spline function (potential energy surface) fitted to data located in pylds/pes_files/filename.hdf5.

Parameters

• filename (string) –

  Name of file containing data:

  coordslist of ndarrays

  [x] or [x,y] contain coordinates.

  pes_datandarray, shape(len(x)) or shape(len(y),len(x))

  Array of potential energy values.

• clip_max (float) – Limit for clipping potential values that are not of interest. The default is False.

Returns

fspline – fspline returns the potential at (x0) or (x0,y0).

Return type

function

ldds.base.fit_vector_field(filename)

Returns a 2-dimensional function (vector field) fitted to data located in pylds/vector_field_files/filename.hdf5.

Parameters

filename (string) –

Name of file containing data: sample_time_points: 1d array,

time-points in a sample time-interval.

sample_coordslist of ndarrays,

[x,y] contain coordinates.

vector_field_datandarray, len(t),

Array of function/vector field values.

Returns

vector_field_interpolated – returns a vector field function to be evaluated at (t, u). with t a float and u (n,2)-array.

Return type

function

ldds.base.generate_points(grid_parameters)

Returns a 1D array of all points from a on a uniform grid with dimensions and size defined by list of input parameters. An additional dimension initiallised with zeros is added for the calculation of Lagrangian Descriptors. NOTE: For n-DoF systems, currently energy conservation is only used to determine momenta dimensions.

Parameters

grid_parameters (list (1-DoF systems) or dict (n-DoF systems)) –

if 1-DoF, list should have two 3-tuples of floats entries are input parameters of limits and size of mesh per axis

if n-DoF, dict should have the following keys * ‘slice_parameters’ : ndarray or list, should have two 3-tuples of floats, for a 2D slice * ‘dims_slice’ : ndarray or list of 0 and 1, ones indicate slice axes * ‘dims_fixed’ : ndarray or list of 0 and 1, ones indicate fixed axes * ‘dims_fixed_values’ : ndarray or list of values on fixed axes * ‘energy_level’ : float, energy value for energy conservation condition and either one of * ‘Hamiltonian’ : function for the Hamiltonian * ‘potential_energy’ : potential energy function, sum-of-squares kinetic energy will be assumed and either one of * ‘momentum_sign’ : int, -1 / 1, for negative/positive momentum for remaining axis * ‘remaining_coordinate_bounds’ : ndarray or list of values that bracket the values of the remaining coordinate (not necessarily momentum coordinate)

Returns

• mesh (ndarray,) – Flattened array of initial conditions.

• mask (ndarray,) – Masks Nan values in further calculations.

ldds.base.lagrangian_descriptor(u, v, p_value=0.5)

Vector field equation for Lagrangian descriptor.

Parameters

• v (ndarray, shape(n,2)) – Vector field at given point.

• p_value (float, optional) – Exponent in Lagrangian descriptor definition. 0 is the acton-based LD, 0 < p_value < 1 is the Lp quasinorm, 1 <= p_value < 2 is the Lp norm LD, 2 is the arclength LD. The default is 0.5.

Returns

LD – Vector field for Lagrangian descriptor dimension.

Return type

ndarray, shape(n,1)

ldds.base.perturb_field(vector_field, perturbation)

Returns the vector field function with a linearly added pertubation Both input function should input (t, u), with t: float, and u: ndarray Also, the output of these funcs must be ndarrays of the same shape

Parameters

• vector_field (function) – unperturbed vector field

• perturbation (function) – forcing added to the vector field

Returns

Return type

perturbed function

ldds.base.remaining_coordinate_quadratic(phase_space_axes, H0, Hamiltonian, momentum_sign)

Returns a 1D array of values for the remaining momentum coordinate, assuming the kinetic energy is a sum-of-squares function of the momenta (0.5*px**2+0.5*py**2+…). The sign of the returned values is given by momentum_sing.

Parameters

• phase_space_axes (ndarray,) – Array of coordinate values, where the remaining momentum is 0.

• H0 (float,) – Value of energy.

• Hamiltonian (function,) – Function of (t,y) that returns the value of the Hamiltonian at time t and point y.

• momentum_sign (int,) – +1 returns positive momentum values, -1 negative.

Returns

points_dims_remaining – Array of remaining momentum values.

Return type

ndarray,

ldds.base.remaining_coordinate_value(u, ind_remaining, remaining_coordinate_bounds, H0, Hamiltonian)

Returns a 1D array of values for the remaining coordinate (not necessarily momentum) using Brent’s method in the bracketing interval remaining_coordinate_bounds.

Parameters

• u (ndarray, shape(n,)) – Coordinate values of a single point, where the remaining momentum .

• remaining_coordinate_bounds (ndarray, shape(2,)) – Bracketing interval for root-finding method.

• H0 (float,) – Value of energy.

• Hamiltonian (function,) – Function of (t,y) that returns the value of the Hamiltonian at time t and point y.

Returns

point_dim_remaining – Value of coordinate or, if root-finding is unsuccessfull, np.nan.

Return type

float,

ldds.base.vector_field_flat(t, points, vector_field, p_value, box_boundaries)

Returns vector field values for integration of flattened input array.

Parameters

• t (float) – time

• points (ndarray, shape(n,3)) –

• vector_field (function) – vector field over phase space, must return 2D array of vectors over a 2D array of initial conditions and given as input to the API function vector_field_flat to be turned into a 1D array (column).

• p_value (float, optional) – Exponent in Lagrangian descriptor definition. 0 is the acton-based LD, 0 < p_value < 1 is the Lp quasinorm, 1 <= p_value < 2 is the Lp norm LD, 2 is the arclength LD. The default is 0.5.

• box_boundaries (list of 2-tuples, optional) – box boundaries for escape condition of variable time integration boundaries are infinite by default.

Returns

y0 values for integrator

Return type

1d array

ldds.tools module

ldds.tools.draw_all_lds(LD_forward, LD_backward, grid_parameters, tau=nan, p_value=nan, interactive=False)

Draws the forward, backward and total Lagrangian descriptor contour plots and a contour plots showing the magnitude of its gradient field.

Parameters

• LD_forward (ndarray, shape(n, )) – Array of Lagrangian Descriptor values in forward time.

• LD_backward (ndarray, shape(n, )) – Array of Lagrangian Descriptor values in backward time.

• grid_parameters (list of 3-tuples of floats) – Limits and size of mesh per axis.

• tau (float, optional) – Time of integration. Default is np.nan.

• p_value (float, optional) – Exponent in Lagrangian descriptor definition. Default is np.nan.

• interactive (bool, optional) – True allows interactively adjusting the gradient plot minimum and maximum. Default is False.

Returns

Return type

List of tuples of the form (fig, ax)

ldds.tools.draw_ld(fig, axis, LD, grid_parameters, subplot_title, interactive, cmap='viridis')

Draws a Lagrangian descriptor contour plot and a contour plot showing the magnitude of its gradient field.

Parameters

• fig (matplotlib.figure.Figure) – Figure where contour plot will be drawn.

• axis (matplotlib.axes._subplots.AxesSubplot) – Axis handle of subplot in figure.

• LD (ndarray, shape(n, )) – Array to be plotted.

• grid_parameters (list of 3-tuples of floats) – Limits and size of mesh per axis.

• subplot_title (string) – Subplot title.

• interactive (bool) – True allows interactively adjusting the gradient contouor plot minimum and maximum.

• cmap (string) – Name of matplotlib colormap for plot.

ldds.tools.draw_ld_pair(LD, LD_gradient, grid_parameters, plot_title, interactive, cmap_gradient)

Lagrangian descriptor plot wrapper.

Parameters

• LD (ndarray, shape(n, )) – Array of Lagrangian Descriptor values.

• LD_gradient (ndarray, shape(n, )) – Array of Lagrangian Descriptor gradient values.

• grid_parameters (list of 3-tuples of floats) – Limits and size of mesh per axis.

• plot_title (string) – Plot title.

• interactive (bool) – True allows interactively adjusting the gradient contouor plot minimum and maximum.

• cmap_gradient (string) – Name of matplotlib colormap for gradient contour plot.

Returns

• fig (~.figure.Figure)

• ax (.axes.Axes or array of Axes)

ldds.tools.get_gradient_magnitude(LD)

Calculates magnitude of the gradient of input array LD.

Parameters

LD (ndarray, shape(n, )) – Array of input values.

Returns

gradient_magnitude – Magnitude of the gradient of input array LD.

Return type

ndarray, shape(n, )

ldds.tools.normalise(A)

Normalises an array.

Parameters

A (ndarray, shape(n, )) – Array of input values.

Returns

Normalised array

Return type

ndarray, shape(n, )

ldds.vector_fields module

ldds.vector_fields.DoubleGyre(t, u, PARAMETERS=[0, 0.25, 6.283185307179586, 0, 0, 1, 0.25])

Returns 2D Double Gyre vector field at time t, for an array of points in phase space. Number of model parameters: 6 . PARAMETERS = [phase_shift, A, phi, psi, mu, s, epsilon] Functional form:

vx = -pi*A*sin(pi*f(t + phase_shift, x)/s)*cos(pi*y/s) - mu*x vy = pi*A*cos(pi*f(t + phase_shift, x)/s)*sin(pi*y/s)*df(t + phase_shift,x)/dx - mu*y

with

f(t, x) = epsilon*sin(phi*t + psi)*x**2 + (1 - 2*epsilon*sin(phi*t + psi))*x df/dx(t,x) = 2*epsilon*sin(phi*t + psi)*x + (1 - 2*epsilon*sin(phi*t + psi)) u = (x, y) :param t: fixed time-point of vector field, for all points in phase space. :type t: float :param u: points in phase space to determine vector field at time t. :type u: array_like, shape(n,) :param PARAMETERS: vector field parameters :type PARAMETERS: list of floats

Returns

v – vector field corresponding to points u, in phase space at time t

Return type

array_like, shape(n,)

ldds.vector_fields.Duffing1D(t, u, PARAMETERS=[1, 1])

Returns vector field for the Duffing oscillator. Number of model parameters: 2 . PARAMETERS = [alpha, beta] Functional form: v = (y, alpha*x - beta*x**3), with u = (x, y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• PARAMETERS (list of floats, optional) – Vector field parameters [alpha, beta]. Default is [1, 1].

Returns

v – Vector field at points u and time t..

Return type

ndarray, shape(n,)

ldds.vector_fields.HamCenter1D(t, u, PARAMETERS=[1])

Returns vector field for a 1DoF centre at time t, for an array of points in phase space. Number of model parameters: 1 . PARAMETERS = [omega] Functional form: v = (omega*y, - omega*x), with u = (x, y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• PARAMETERS (list of floats) – Vector field parameters.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

ldds.vector_fields.HamSN1D(t, u, PARAMETERS=[None])

Returns vector field for the 1DoF saddle-node model. Number of model parameters: 0 . PARAMETERS = [None] Functional form: v = (y, -x -x**2), with u = (x, y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• PARAMETERS (list of floats) – Vector field parameters.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

ldds.vector_fields.HamSaddle1D(t, u, PARAMETERS=[1])

Returns vector field for a 1DoF saddle at time t, for an array of points in phase space. Number of model parameters: 1 . PARAMETERS = [lamda] Functional form: v = (lamda*y, lamda*x), with u = (x, y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• PARAMETERS (list of floats) – Vector field parameters.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

ldds.vector_fields.HenonHeiles_vector_field(t, u)

Returns Henon-Heiles vector field (2DoF). Functional form: v = (p_x, p_y, -x - 2*x*y, -x**2 -y + y**2), with u = (x, y, p_x, p_y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

ldds.vector_fields.forcing(t, u, perturbation_params=[0, 1, 0.15, 0.5])

Returns vector field for a perturbation. Number of model parameters: 3. perturbation_params = [phase_shift, perturbation_type, amplitude, frequency] Functional form: v = (, ), with u = (x, y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• perturbation_params (list of floats, [phase_shift, perturbation_type, amplitude, frequency]) – Perturbation parameters.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

ldds.vector_fields.quadratic_normalform_saddlecenter(t, u, PARAMETERS=[1, 1])

Returns vector field for a 2D index-1 saddle. Functional form: v = (p_x, p_y, x, -y), with u = (x, y, p_x, p_y)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• PARAMETERS (list of floats) – Vector field parameters.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

ldds.vector_fields.quadratic_normalform_saddlecentercenter(t, u, PARAMETERS=[1, 1, 1])

Returns vector field for a 3D index-1 saddle. Functional form: v = (p_x, p_y, p_z, x, -y, -z), with u = (x, y, z, p_x, p_y, p_z)

Parameters

• t (float) – Time. (This vector field is independent of time.)

• u (ndarray, shape(n,)) – Points in phase space.

• PARAMETERS (list of floats) – Vector field parameters.

Returns

v – Vector field at points u and time t.

Return type

ndarray, shape(n,)

Module contents

PyLDs init