Integration modules

The modules used to numerically integrate the model forward in time. Users may add their own recipes here.

Integrate module

Module with the function to integrate the ordinary differential equations

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

of the model and its linearized version.

Description of the module functions

Two main functions:

qgs.integrators.integrate.integrate_runge_kutta(f, t0, t, dt, ic=None, forward=True, write_steps=1, b=None, c=None, a=None)[source]

Integrate the ordinary differential equations (ODEs)

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

with a specified Runge-Kutta method. The function \(\boldsymbol{f}\) should be a Numba jitted function. This function must have a signature f(t, x) where x is the state value and t is the time.

Parameters

  • f (callable) – The Numba-jitted function \(\boldsymbol{f}\). Should have the signature``f(t, x)`` where x is the state value and t is the time.

  • t0 (float) – Initial time of the time integration. Corresponds to the initial condition. Important if the ODEs are non-autonomous.

  • t (float) – Final time of the time integration. Corresponds to the final condition. Important if the ODEs are non-autonomous.

  • dt (float) – Timestep of the integration.

  • ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the system. Can be a 1D or a 2D array:

    • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

    If None, use a zero initial condition. Default to None. If the forward argument is False, it specifies final conditions.

  • forward (bool, optional) – Whether to integrate the ODEs forward or backward in time. In case of backward integration, the initial condition ic becomes a final condition. Default to forward integration.

  • write_steps (int, optional) – Save the state of the integration in memory every write_steps steps. The other intermediary steps are lost. It determines the size of the returned objects. Default is 1. Set to 0 to return only the final state.

  • b (None or ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • c (None or ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • a (None or ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

Returns

time, traj – The result of the integration:

  • time: Time at which the state of the system was saved. Array of shape (n_step,) where n_step is the number of saved states of the integration.

  • traj: Saved dynamical system states. 3D array of shape (n_traj, n_dim, n_steps). If n_traj = 1, a 2D array of shape (n_dim, n_steps) is returned instead.

Return type

ndarray

Examples

>>> from numba import njit
>>> import numpy as np
>>> from qgs.integrators.integrate import integrate_runge_kutta
>>> a = 0.25
>>> F = 16.
>>> G = 3.
>>> b = 6.
>>> # Lorenz 84 example
>>> @njit
... def fL84(t, x):
...     xx = -x[1] ** 2 - x[2] ** 2 - a * x[0] + a * F
...     yy = x[0] * x[1] - b * x[0] * x[2] - x[1] + G
...     zz = b * x[0] * x[1] + x[0] * x[2] - x[2]
...     return np.array([xx, yy, zz])
>>> # no ic
>>> # write_steps is 1 by default
>>> tt, traj = integrate_runge_kutta(fL84, t0=0., t=10., dt=0.1)  # 101 steps
>>> print(traj.shape)
(3, 101)
>>> # 1 ic
>>> ic = 0.1 * np.random.randn(3)
>>> tt, traj = integrate_runge_kutta(fL84, t0=0., t=10., dt=0.1, ic=ic)  # 101 steps
>>> print(ic.shape)
(3,)
>>> print(traj.shape)
(3, 101)
>>> # 4 ic
>>> ic = 0.1 * np.random.randn(4, 3)
>>> tt, traj = integrate_runge_kutta(fL84, t0=0., t=10., dt=0.1, ic=ic)  # 101 steps
>>> print(ic.shape)
(4, 3)
>>> print(traj.shape)
(4, 3, 101)
qgs.integrators.integrate.integrate_runge_kutta_tgls(f, fjac, t0, t, dt, ic=None, tg_ic=None, forward=True, adjoint=False, inverse=False, boundary=None, write_steps=1, b=None, c=None, a=None)[source]

Integrate simultaneously the ordinary differential equations (ODEs)

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

and its tangent linear model, i.e. the linearized ODEs

\[\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\]

where \(\boldsymbol{\mathrm{J}} = \frac{\partial \boldsymbol{f}}{\partial \boldsymbol{x}}\) is the Jacobian matrix of \(\boldsymbol{f}\), with a specified Runge-Kutta method. To solve this equation, one has to integrate simultaneously both ODEs.

The function \(\boldsymbol{f}\) and \(\boldsymbol{J}\) should be Numba jitted functions. These functions must have a signature f(t, x) and J(t, x) where x is the state value and t is the time.

Parameters

  • f (callable) – The Numba-jitted function \(\boldsymbol{f}\). Should have the signature``f(t, x)`` where x is the state value and t is the time.

  • fjac (callable) – The Numba-jitted Jacobian \(\boldsymbol{J}\). Should have the signature``J(t, x)`` where x is the state value and t is the time.

  • t0 (float) – Initial time of the time integration. Corresponds to the initial conditions.

  • t (float) – Final time of the time integration. Corresponds to the final conditions.

  • dt (float) – Timestep of the integration.

  • ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the ODEs \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\). Can be a 1D or a 2D array:

    • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

    If None, use a zero initial condition. Default to None. If the forward argument is False, it specifies final conditions.

  • tg_ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the linear ODEs \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\).

    Can be a 1D, a 2D or a 3D array:

    • 1D: Provide a single initial condition. This initial condition of the linear ODEs will be the same used for each initial condition ic of the ODEs \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\) Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Two sub-cases:

      • If tg_ic.shape[0]`=`ic.shape[0], assumes that each initial condition ic[i] of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\), correspond to a different initial condition tg_ic[i].

      • Else, assumes and integrate an ensemble of n_tg_traj initial condition of the linear ODEs for each initial condition of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\).

    • 3D: An array of shape (n_traj, n_tg_traj, n_dim) which provide an ensemble of n_tg_ic initial conditions specific to each of the n_traj initial conditions of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\).

    If None, use the identity matrix as initial condition, returning the fundamental matrix of solutions of the linear ODEs. Default to None. If the forward argument is False, it specifies final conditions.

  • forward (bool, optional) – Whether to integrate the ODEs forward or backward in time. In case of backward integration, the initial condition ic becomes a final condition. Default to forward integration.

  • adjoint (bool, optional) – Wheter to integrate the tangent \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\) or the adjoint linear model \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}^T(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\). Integrate the tangent model by default.

  • inverse (bool, optional) – Wheter or not to invert the Jacobian matrix \(\boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \rightarrow \boldsymbol{\mathrm{J}}^{-1}(t, \boldsymbol{x})\). False by default.

  • boundary (None or callable, optional) – Allow to add a inhomogeneous term to linear ODEs: \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x} + \Psi(t, \boldsymbol{x})\). The boundary \(\Psi\) should have the same signature as \(\boldsymbol{\mathrm{J}}\), i.e. func(t, x). If None, don’t add anything (homogeneous case). None by default.

  • write_steps (int, optional) – Save the state of the integration in memory every write_steps steps. The other intermediary steps are lost. It determines the size of the returned objects. Default is 1. Set to 0 to return only the final state.

  • b (None or ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • c (None or ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • a (None or ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

Returns

time, traj, tg_traj – The result of the integration:

  • time: Time at which the state of the system was saved. Array of shape (n_step,) where n_step is the number of saved states of the integration.

  • traj: Saved states of the ODEs. 3D array of shape (n_traj, n_dim, n_steps). If n_traj = 1, a 2D array of shape (n_dim, n_steps) is returned instead.

  • tg_traj: Saved states of the linear ODEs. Depending on the input initial conditions of both ODEs, it is at maximum a 4D array of shape (n_traj, n_tg_traj `n_dim, n_steps). If one of the dimension is 1, it is squeezed.

Return type

ndarray

Examples

>>> from numba import njit
>>> import numpy as np
>>> from qgs.integrators.integrate import integrate_runge_kutta_tgls
>>> a = 0.25
>>> F = 16.
>>> G = 3.
>>> b = 6.
>>> # Lorenz 84 example
>>> @njit
... def fL84(t, x):
...     xx = -x[1] ** 2 - x[2] ** 2 - a * x[0] + a * F
...     yy = x[0] * x[1] - b * x[0] * x[2] - x[1] + G
...     zz = b * x[0] * x[1] + x[0] * x[2] - x[2]
...     return np.array([xx, yy, zz])
>>> @njit
... def DfL84(t, x):
...    return np.array([[     -a        , -2. * x[1], -2. * x[2]],
...                      [x[1] - b * x[2], -1. + x[0], -b * x[0]],
...                      [b * x[1] + x[2],  b * x[0], -1. + x[0]]])
>>> # 4 ic, no tg_ic (fundamental matrix computation of an ensemble of ic)
>>> ic = 0.1 * np.random.randn(4, 3)
>>> tt, traj, dtraj = integrate_runge_kutta_tgls(fL84, DfL84, t0=0., t=10., dt=0.1,
...                                              ic=ic, write_steps=1) # 101 steps
>>> print(ic.shape)
(4, 3)
>>> print(traj.shape)
(4, 3, 101)
>>> print(dtraj.shape)
(4, 3, 3, 101)
>>> # 1 ic, 1 tg_ic (one ic and its tg_ic)
>>> ic = 0.1 * np.random.randn(3)
>>> tg_ic = 0.001 * np.random.randn(3)
>>> tt, traj, dtraj = integrate_runge_kutta_tgls(fL84, DfL84, t0=0., t=10., dt=0.1,
...                                              ic=ic, tg_ic=tg_ic) # 101 steps
>>> print(ic.shape)
(3,)
>>> print(tg_ic.shape)
(3,)
>>> print(traj.shape)
(3, 101)
>>> print(dtraj.shape)
(3, 101)
>>> # 4 ic, 1 same tg_ic (an ensemble of ic with the same tg_ic)
>>> ic = 0.1 * np.random.randn(4, 3)
>>> tt, traj, dtraj = integrate_runge_kutta_tgls(fL84, DfL84, t0=0., t=10., dt=0.1,
...                                              ic=ic, tg_ic=tg_ic) # 101 steps
>>> print(ic.shape)
(4, 3)
>>> print(tg_ic.shape)
(3,)
>>> print(traj.shape)
(4, 3, 101)
>>> print(dtraj.shape)
(4, 3, 101)
>>> # 1 ic, 4 tg_ic (an ic with an ensemble of tg_ic in its tangent space)
>>> ic = 0.1 * np.random.randn(3)
>>> tg_ic = 0.001 * np.random.randn(4, 3)
>>> tt, traj, dtraj = integrate_runge_kutta_tgls(fL84, DfL84, t0=0., t=10., dt=0.1,
...                                              ic=ic, tg_ic=tg_ic) # 101 steps
>>> print(ic.shape)
(3,)
>>> print(tg_ic.shape)
(4, 3)
>>> print(traj.shape)
(3, 101)
>>> print(dtraj.shape)
(4, 3, 101)
>>> # 2 ic, same 4 tg_ic (an ensemble of 2 ic, both with the same ensemble
>>> # of tg_ic in their tangent space)
>>> ic = 0.1 * np.random.randn(2, 3)
>>> tg_ic = 0.001 * np.random.randn(4, 3)
>>> tt, traj, dtraj = integrate_runge_kutta_tgls(fL84, DfL84, t0=0., t=10., dt=0.1,
...                                              ic=ic, tg_ic=tg_ic) # 101 steps
>>> print(ic.shape)
(2, 3)
>>> print(tg_ic.shape)
(4, 3)
>>> print(traj.shape)
(2, 3, 101)
>>> print(dtraj.shape)
(2, 4, 3, 101)
>>> # 2 ic, 4 different tg_ic (an ensemble of 2 ic, with different ensemble
>>> # of tg_ic in their tangent space)
>>> ic = 0.1 * np.random.randn(2, 3)
>>> tg_ic = 0.001 * np.random.randn(2, 4, 3)
>>> tt, traj, dtraj = integrate_runge_kutta_tgls(fL84, DfL84, t0=0., t=10., dt=0.1,
...                                              ic=ic, tg_ic=tg_ic) # 101 steps
>>> print(ic.shape)
(2, 3)
>>> print(tg_ic.shape)
(2, 4, 3)
>>> print(traj.shape)
(2, 3, 101)
>>> print(dtraj.shape)
(2, 4, 3, 101)

Integrator module

Module with the classes of integrators to multi-thread the integration of an ordinary differential equations

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

of the model and its linearized version.

Module classes

class qgs.integrators.integrator.RungeKuttaIntegrator(num_threads=None, b=None, c=None, a=None, number_of_dimensions=None)[source]

Bases: object

Class to integrate the ordinary differential equations (ODEs)

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

with a set of TrajectoryProcess and a specified Runge-Kutta method.

Parameters

  • num_threads (None or int, optional) – Number of TrajectoryProcess workers (threads) to use. If None, use the number of machine’s cores available. Default to None.

  • b (None or ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • c (None or ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • a (None or ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • number_of_dimensions (None or int, optional) – Allow to hardcode the dynamical system dimension. If None, evaluate the dimension from the callable func. Default to None.

num_threads

Number of TrajectoryProcess workers (threads) to use.

Type

int

b

Vector of coefficients \(b_i\) of the Runge-Kutta method .

Type

ndarray

c

Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method .

Type

ndarray

a

Vector of coefficients \(a_i\) of the Runge-Kutta method .

Type

ndarray

n_dim

Dynamical system dimension.

Type

int

n_traj

The number of trajectories (initial conditions) computed at the last integration performed by the integrator.

Type

int

n_records

The number of saved states of the last integration performed by the integrator.

Type

int

ic

Store the integrator initial conditions.

Type

ndarray

func

Last function \(\boldsymbol{f}\) used by the integrator to integrate.

Type

callable

get_ic()[source]

Returns the initial conditions stored in the integrator.

Returns

The initial conditions.

Return type

ndarray

get_trajectories()[source]

Returns the result of the previous integrator integration.

Returns

time, traj – The result of the integration:

Return type

ndarray

initialize(convergence_time, dt, pert_size=0.01, reconvergence_time=None, forward=True, number_of_trajectories=1, ic=None, reconverge=False)[source]

Initialize the integration on an attractor by running it for a transient time, For an ensemble of initial conditions, can do the same transient time for each, or the convergence_time for the first one, and a smaller reconvergence_time for the subsequent ones. This results into initial conditions on the attractor, stored in ic.

Parameters

  • convergence_time (float) – Transient time needed to converge to the attractor.

  • dt (float) – Timestep of the transient integration.

  • pert_size (float, optional) – If the reconvergence is activated, size of the perturbation to add to the previous ic to find the next one. Default to 0.01 .

  • reconvergence_time (None or float, optional) – Transient time for the subsequent trajectories after the first long transient_time.

  • forward (bool, optional) – Whether to integrate the ODEs forward or backward in time. In case of backward integration, the initial condition ic becomes a final condition. Default to forward integration.

  • number_of_trajectories (int) – Number of initial conditions to find. Default to 1. Inactive if ic is provided.

  • ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the system. Can be a 1D or a 2D array:

    • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

    If None, use number_trajectories random initial conditions. Default to None. If the forward argument is False, it specifies final conditions.

  • reconverge (bool) – Use or not the smaller transient time reconvergence with a perturbation after the first initial conditions have been computed. If activated, only use the num_threads first initial conditions of the ic arguments. Default to False.

integrate(t0, t, dt, ic=None, forward=True, write_steps=1)[source]

Integrate the ordinary differential equations (ODEs)

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

with a specified Runge-Kutta method and workers. The function \(\boldsymbol{f}\) is the Numba jitted function stored in func. The result of the integration can be obtained afterward by calling get_trajectories().

Parameters

  • t0 (float) – Initial time of the time integration. Corresponds to the initial condition’s ic time. Important if the ODEs are non-autonomous.

  • t (float) – Final time of the time integration. Corresponds to the final condition. Important if the ODEs are non-autonomous.

  • dt (float) – Timestep of the integration.

  • ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the system. Can be a 1D or a 2D array:

    • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

    If None, use the initial conditions stored in ic. If then ic is None, use a zero initial condition. Default to None. If the forward argument is False, it specifies final conditions.

  • forward (bool, optional) – Whether to integrate the ODEs forward or backward in time. In case of backward integration, the initial condition ic becomes a final condition. Default to forward integration.

  • write_steps (int, optional) – Save the state of the integration in memory every write_steps steps. The other intermediary steps are lost. It determines the size of the returned objects. Default is 1. Set to 0 to return only the final state.

set_bca(b=None, c=None, a=None, ic_init=True)[source]

Set the coefficients of the Runge-Kutta method and restart the integrator. s

Parameters

  • b (None or ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method . If None, does not reinitialize these coefficients.

  • c (None or ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method . If None, does not reinitialize these coefficients.

  • a (None or ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method . If None, does not reinitialize these coefficients.

  • ic_init (bool, optional) – Re-initialize or not the initial conditions of the integrator. Default to True.

set_func(f, ic_init=True)[source]

Set the Numba-jitted function \(\boldsymbol{f}\) to integrate.

Parameters

  • f (callable) – The Numba-jitted function \(\boldsymbol{f}\). Should have the signature f(t, x) where x is the state value and t is the time.

  • ic_init (bool, optional) – Re-initialize or not the initial conditions of the integrator. Default to True.

Warning

This function restarts the integrator!

set_ic(ic)[source]

Direct setter for the integrator’s initial conditions

Parameters

ic (ndarray(float)) –

Initial condition of the system. Can be a 1D or a 2D array:

  • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

  • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

start()[source]

Start or restart the workers (threads) of the integrator.

Warning

If the integrator was not previously terminated, it will be terminated first in the case of a restart.

terminate()[source]

Stop the workers (threads) and release the resources of the integrator.

class qgs.integrators.integrator.RungeKuttaTglsIntegrator(num_threads=None, b=None, c=None, a=None, number_of_dimensions=None)[source]

Bases: object

Class to integrate simultaneously the ordinary differential equations (ODEs)

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

and its tangent linear model, i.e. the linearized ODEs

\[\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\]

where \(\boldsymbol{\mathrm{J}} = \frac{\partial \boldsymbol{f}}{\partial \boldsymbol{x}}\) is the Jacobian matrix of \(\boldsymbol{f}\), with a specified Runge-Kutta method. To solve this equation, one has to integrate simultaneously both ODEs. This class does so with a set of TglsTrajectoryProcess workers.

The function \(\boldsymbol{f}\) and \(\boldsymbol{J}\) should be Numba jitted functions. These functions must have a signature f(t, x) and J(t, x) where x is the state value and t is the time.

Parameters

  • num_threads (None or int, optional) – Number of TrajectoryProcess workers (threads) to use. If None, use the number of machine’s cores available. Default to None.

  • b (None or ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • c (None or ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • a (None or ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method . If None, use the classic RK4 method coefficients. Default to None.

  • number_of_dimensions (None or int, optional) – Allow to hardcode the dynamical system dimension. If None, evaluate the dimension from the callable func. Default to None.

num_threads

Number of TrajectoryProcess workers (threads) to use.

Type

int

b

Vector of coefficients \(b_i\) of the Runge-Kutta method .

Type

ndarray

c

Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method .

Type

ndarray

a

Vector of coefficients \(a_i\) of the Runge-Kutta method .

Type

ndarray

n_dim

Dynamical system dimension.

Type

int

n_traj

The number of trajectories (initial conditions) of the non-linear ODEs computed at the last integration performed by the integrator.

Type

int

n_tg_traj

The number of trajectories (initial conditions) the linear ODEs computed at the last integration performed by the integrator.

Type

int

n_records

The number of saved states of the last integration performed by the integrator.

Type

int

ic

Store the integrator non-linear ODEs initial conditions.

Type

ndarray

tg_ic

Store the integrator linear ODEs initial conditions.

Type

ndarray

func

Last function \(\boldsymbol{f}\) used by the integrator to integrate.

Type

callable

func_jac

Last Jacobian matrix function \(\boldsymbol{J}\) used by the integrator to integrate.

Type

callable

get_ic()[source]

Returns the initial conditions of the non-linear ODEs stored in the integrator.

Returns

The initial conditions.

Return type

ndarray

get_tg_ic()[source]

Returns the initial conditions of the linear ODEs stored in the integrator.

Returns

The initial conditions.

Return type

ndarray

get_trajectories()[source]

Returns the result of the previous integrator integration.

Returns

time, traj, tg_traj – The result of the integration:

  • time: time at which the state of the system was saved. Array of shape (n_records,).

  • traj: Saved dynamical system states. 3D array of shape (n_traj, n_dim, n_records). If n_traj = 1, a 2D array of shape (n_dim, n_records) is returned instead.

  • tg_traj: Saved states of the linear ODEs. Depending on the input initial conditions of both ODEs, it is at maximum a 4D array of shape (n_traj, n_tg_traj, n_dim, n_records). If one of the dimension is 1, it is squeezed.

Return type

ndarray

initialize(convergence_time, dt, pert_size=0.01, reconvergence_time=None, forward=True, number_of_trajectories=1, ic=None, reconverge=None)[source]

Initialize the integration on an attractor by running it for a transient time, For an ensemble of initial conditions, can do the same transient time for each, or the convergence_time for the first one, and a smaller reconvergence_time for the subsequent ones. This results into initial conditions on the attractor, stored in ic.

Parameters

  • convergence_time (float) – Transient time needed to converge to the attractor.

  • dt (float) – Timestep of the transient integration.

  • pert_size (float, optional) – If the reconvergence is activated, size of the perturbation to add to the previous ic to find the next one. Default to 0.01 .

  • reconvergence_time (None or float, optional) – Transient time for the subsequent trajectories after the first long transient_time.

  • forward (bool, optional) – If true, integrate the ODEs forward in time, else, integrate backward in time. In case of backward integration, the initial condition ic becomes a final condition. Default to forward integration.

  • number_of_trajectories (int) – Number of initial conditions to find. Default to 1. Inactive if ic is provided.

  • ic (None or ndarray(float), optional) –

    Initial condition of the system. Can be a 1D or a 2D array:

    • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

    If None, use number_trajectories random initial conditions. Default to None.

  • reconverge (bool) – Use or not the smaller transient time reconvergence with a perturbation after the first initial conditions have been computed. If activated, only use the num_threads first initial conditions of the ic arguments. Default to False.

integrate(t0, t, dt, ic=None, tg_ic=None, forward=True, adjoint=False, inverse=False, boundary=None, write_steps=1)[source]

Integrate simultaneously the non-linear and linearized ordinary differential equations (ODEs)

\[\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\]

and

\[\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\]

with a specified Runge-Kutta method and workers. The function \(\boldsymbol{f}\) is the Numba jitted function stored in func. The function \(\boldsymbol{J}\) is the Numba jitted function stored in func_jac. The result of the integration can be obtained afterward by calling get_trajectories().

Parameters

  • t0 (float) – Initial time of the time integration. Corresponds to the initial condition.

  • t (float) – Final time of the time integration. Corresponds to the final condition.

  • dt (float) – Timestep of the integration.

  • ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the system. Can be a 1D or a 2D array:

    • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

    If None, use the initial conditions stored in ic. If then ic is None, use a zero initial condition. Default to None. If the forward argument is False, it specifies final conditions.

  • tg_ic (None or ndarray(float), optional) –

    Initial (or final) conditions of the linear ODEs \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\).

    Can be a 1D, a 2D or a 3D array:

    • 1D: Provide a single initial condition. This initial condition of the linear ODEs will be the same used for each initial condition ic of the ODEs \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\) Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

    • 2D: Two sub-cases:

      • If tg_ic.shape[0]`=`ic.shape[0], assumes that each initial condition ic[i] of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\), correspond to a different initial condition tg_ic[i].

      • Else, assumes and integrate an ensemble of n_tg_traj initial condition of the linear ODEs for each initial condition of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\).

    • 3D: An array of shape (n_traj, n_tg_traj, n_dim) which provide an ensemble of n_tg_ic initial conditions specific to each of the n_traj initial conditions of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\).

    If None, use the identity matrix as initial condition, returning the fundamental matrix of solutions of the linear ODEs. Default to None. If the forward argument is False, it specifies final conditions.

  • forward (bool, optional) – If true, integrate the ODEs forward in time, else, integrate backward in time. In case of backward integration, the initial condition ic becomes a final condition. Default to forward integration.

  • adjoint (bool, optional) – If true, integrate the tangent \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\) , else, integrate the adjoint linear model \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}^T(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\). Integrate the tangent model by default.

  • inverse (bool, optional) – Wheter or not to invert the Jacobian matrix \(\boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \rightarrow \boldsymbol{\mathrm{J}}^{-1}(t, \boldsymbol{x})\). False by default.

  • boundary (None or callable, optional) – Allow to add a inhomogeneous term to linear ODEs: \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x} + \Psi(t, \boldsymbol{x})\). The boundary \(\Psi\) should have the same signature as \(\boldsymbol{\mathrm{J}}\), i.e. func(t, x). If None, don’t add anything (homogeneous case). None by default.

  • write_steps (int, optional) – Save the state of the integration in memory every write_steps steps. The other intermediary steps are lost. It determines the size of the returned objects. Default is 1. Set to 0 to return only the final state.

set_bca(b=None, c=None, a=None, ic_init=True)[source]

Set the coefficients of the Runge-Kutta method and restart the integrator. s

Parameters

  • b (None or ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method . If None, does not reinitialize these coefficients.

  • c (None or ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method . If None, does not reinitialize these coefficients.

  • a (None or ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method . If None, does not reinitialize these coefficients.

  • ic_init (bool, optional) – Re-initialize or not the initial conditions of the integrator. Default to True.

set_func(f, fjac, ic_init=True)[source]

Set the Numba-jitted function \(\boldsymbol{f}\) and Jacobian matrix function \(\boldsymbol{\mathrm{J}}\) to integrate.

Parameters

  • f (callable) – The Numba-jitted function \(\boldsymbol{f}\). Should have the signature f(t, x) where x is the state value and t is the time.

  • fjac (callable) – The Numba-jitted Jacobian matrix function \(\boldsymbol{J}\). Should have the signature J(t, x) where x is the state value and t is the time.

  • ic_init (bool, optional) – Re-initialize or not the initial conditions of the integrator. Default to True.

Warning

This function restarts the integrator!

set_ic(ic)[source]

Direct setter for the integrator’s non-linear ODEs initial conditions

Parameters

ic (ndarray(float)) –

Initial condition of the system. Can be a 1D or a 2D array:

  • 1D: Provide a single initial condition. Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

  • 2D: Provide an ensemble of initial condition. Should be of shape (n_traj, n_dim) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\), and where n_traj is the number of initial conditions.

set_tg_ic(tg_ic)[source]

Direct setter for the integrator’s linear ODEs initial conditions

Parameters

tg_ic (ndarray(float)) –

Initial condition of the linear ODEs \(\dot{\boldsymbol{\delta x}} = \boldsymbol{\mathrm{J}}(t, \boldsymbol{x}) \cdot \boldsymbol{\delta x}\).

Can be a 1D, a 2D or a 3D array:

  • 1D: Provide a single initial condition. This initial condition of the linear ODEs will be the same used for each initial condition ic of the ODEs \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\) Should be of shape (n_dim,) where n_dim = \(\mathrm{dim}(\boldsymbol{x})\).

  • 2D: Two sub-cases:

    • If tg_ic.shape[0]`=`ic.shape[0], assumes that each initial condition ic[i] of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\), correspond to a different initial condition tg_ic[i].

    • Else, assumes and integrate an ensemble of n_tg_traj initial condition of the linear ODEs for each initial condition of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\).

  • 3D: An array of shape (n_traj, n_tg_traj, n_dim) which provide an ensemble of n_tg_ic initial conditions specific to each of the n_traj initial conditions of \(\dot{\boldsymbol{x}} = \boldsymbol{f}(t, \boldsymbol{x})\).

start()[source]

Start or restart the workers (threads) of the integrator.

Warning

If the integrator was not previously terminated, it will be terminated first in the case of a restart.

terminate()[source]

Stop the workers (threads) and release the resources of the integrator.

class qgs.integrators.integrator.TglsTrajectoryProcess(processID, func, func_jac, b, c, a, ics_queue, traj_queue)[source]

Bases: Process

RungeKuttaTglsIntegrator’s workers class. Allows to multi-thread time integration.

Parameters

  • processID (int) – Number identifying the worker.

  • func (callable) – Numba-jitted function to integrate assigned to the worker.

  • func_jac (callable) – Numba-jitted Jacobian matrix function to integrate assigned to the worker.

  • b (ndarray, optional) – Vector of coefficients \(b_i\) of the Runge-Kutta method .

  • c (ndarray, optional) – Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method .

  • a (ndarray, optional) – Vector of coefficients \(a_i\) of the Runge-Kutta method .

  • ics_queue (multiprocessing.JoinableQueue) – Queue to which the worker ask for initial conditions input.

  • traj_queue (multiprocessing.Queue) – Queue to which the worker returns the integration results.

processID

Number identifying the worker.

Type

int

func

Numba-jitted function to integrate assigned to the worker.

Type

callable

func_jac

Numba-jitted Jacobian matrix function to integrate assigned to the worker.

Type

callable

b

Vector of coefficients \(b_i\) of the Runge-Kutta method .

Type

ndarray

c

Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method .

Type

ndarray

a

Vector of coefficients \(a_i\) of the Runge-Kutta method .

Type

ndarray

run()[source]

Main worker computing routine. Perform the time integration with the fetched initial conditions and parameters.

class qgs.integrators.integrator.TrajectoryProcess(processID, func, b, c, a, ics_queue, traj_queue)[source]

Bases: Process

RungeKuttaIntegrator’s workers class. Allows to multi-thread time integration.

Parameters
processID

Number identifying the worker.

Type

int

func

Numba-jitted function to integrate assigned to the worker.

Type

callable

b

Vector of coefficients \(b_i\) of the Runge-Kutta method .

Type

ndarray

c

Matrix of coefficients \(c_{i,j}\) of the Runge-Kutta method .

Type

ndarray

a

Vector of coefficients \(a_i\) of the Runge-Kutta method .

Type

ndarray

run()[source]

Main worker computing routine. Perform the time integration with the fetched initial conditions and parameters.