Discrete Dynamical System API

Bases: object

Class for defining, iterating, and analyzing discrete-time dynamical systems.

This class represents maps of the form

u_{n+1} = F(u_n; parameters),

where u_n is the state at iteration n and F is the discrete-time mapping. A system can be created either from one of the built-in models or from a user-supplied mapping, with optional Jacobian and backward mapping.

The class provides tools for orbit generation and nonlinear-dynamics analysis, including bifurcation diagrams, Lyapunov exponents, covariant Lyapunov vectors (CLVs), SALI, LDI, GALI, recurrence-based diagnostics, Hurst exponent estimation, periodic orbits, invariant manifolds, transport, escape analysis, rotation numbers, weighted Birkhoff averages, and related discrete-time observables.

Parameters

modelstr or None, optional: Name of a built-in discrete-time model.
mappingcallable or None, optional: User-defined mapping with signature F(u, parameters) -> NDArray[np.float64].
jacobiancallable or None, optional: Jacobian of the mapping with signature J(u, parameters) -> NDArray[np.float64].
backwards_mappingcallable or None, optional: Inverse or backward mapping associated with the system.
system_dimensionint or None, optional: Dimension of the state space for a custom mapping.
parametersarray_like or None, optional: Parameter vector for the system.
number_of_parametersint or None, optional: Number of parameters expected by the custom mapping.

Notes

A system can be created either from a built-in model or from a custom mapping, but not both at the same time.
The Jacobian is optional for orbit-level computations, but it is required for Lyapunov exponents, CLVs, SALI, LDI, GALI, and other tangent-space diagnostics.
A backward mapping is only needed for analyses that explicitly require inverse iteration, such as certain manifold computations.
Built-in models and supported analyses can be queried with the corresponding class methods.

See Also

ContinuousDynamicalSystem : Class for continuous-time systems. HamiltonianSystem : Class for separable Hamiltonian systems.

classmethod available_models() → List[str][source]: Return a list of available models.

property info: Dict[str, Any]: Return a dictionary with information about the current model.

set_parameters(parameters: ndarray[tuple[int, ...], dtype[float64]] | Sequence[float] | float) → None[source]

Set the parameter vector of the dynamical system.

This method validates and stores the model parameters. The input can be a scalar, a sequence of floats, or a NumPy array. It is internally converted into a float64 NumPy array of the appropriate size.

Parameters

parametersfloat or sequence of float or ndarray of shape (P,): The parameter set to be used by the system.

Returns

None

get_parameters() → ndarray[tuple[int, ...], dtype[float64]] | None[source]

Return the current parameter vector of the dynamical system.

Returns

ndarray of float64, shape (P,): The parameter vector currently stored in the system.

Perform one step in the mapping evolution

Parameters

uUnion[NDArray[np.float64], Sequence[float], float]: Initial condition(s): - Single IC: 1D array of shape (d,) where d is the system dimension - Ensemble: 2D array of shape (n, d) for n initial conditions - Also accepts sequence types that will be converted to numpy arrays - Scalar
parametersUnion[NDArray[np.float64], Sequence[float], float], optional: Parameters of the dynamical system, shape (p,) where p is the number of parameters

Returns

NDArray[np.float64]: The next step of the given initial condition with the same shape as u.

Raises

ValueError

If u is not a scalar, 1D, or 2D array, or if its shape does not match the expected system dimension.
If u is a 1D array but its length does not match the system dimension, or if u is a 2D array but does not match the expected shape for an ensemble.
If parameters is not None and does not match the expected number of parameters.
If parameters is None but the system expects parameters.
If parameters is a scalar or array-like but not 1D.

TypeError

If u is not a scalar or array-like type.
If parameters is not a scalar or array-like type.

Examples

>>> from pynamicalsys import DiscreteDynamicalSystem as dds
>>> ds = dds(model="standard map")
>>> # Single initial condition
>>> u = [0.2, 0.5]
>>> ds.step(u, parameters=1.5)
[[0.92704802 0.72704802]]
>>> # Multiple initial conditions
>>> u = np.array([[0.2, 0.5], [0.2, 0.3], [0.2, 0.6]])
>>> ds.step(u, paramters=1.5)
array([[0.92704802, 0.72704802],
       [0.72704802, 0.52704802],
       [0.02704802, 0.82704802]])

Generate a trajectory from a single initial condition or from an ensemble of initial conditions.

If u is one-dimensional, the trajectory of a single initial condition is returned. If u is two-dimensional, trajectories are computed for all initial conditions in the ensemble and returned in concatenated form.

Parameters

unumeric_like_t

Initial condition or ensemble of initial conditions.

Single initial condition: shape (system_dimension,)
Ensemble of initial conditions: shape (num_initial_conditions, system_dimension)

total_timeint_t

Total number of iterations used to generate the trajectory.

parametersnumeric_like_t | None, optional

System parameters passed to the mapping function. If None, the stored system parameters are used.

transient_timeint_t | None, optional

Number of initial iterations discarded before storing the trajectory. If provided, it must satisfy 0 <= transient_time < total_time.

Returns

NDArray[np.float64]

Trajectory array.

Single initial condition: shape (sample_size, system_dimension)
Ensemble of initial conditions: shape (num_initial_conditions * sample_size, system_dimension)

where sample_size = total_time - transient_time if a transient is used, and sample_size = total_time otherwise.

For one-dimensional systems with a single initial condition, the output is returned as a one-dimensional array of shape (sample_size,).

Raises

ValueError

If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is not positive.
If transient_time is invalid.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.

Notes

For ensembles, trajectories are concatenated along the first axis. To recover the individual trajectories, reshape the output as (num_initial_conditions, sample_size, system_dimension).

Examples

>>> u0 = np.array([0.1, 0.2])
>>> ts = system.trajectory(u0, 5000, parameters=[0.5, 1.0])

>>> ics = np.random.rand(100, 2)
>>> ts = system.trajectory(ics, 10000, parameters=[1.0, 0.1], transient_time=1000)
>>> ts = ts.reshape(100, 9000, 2)

Compute a bifurcation diagram by varying one system parameter and recording a scalar observable along the resulting trajectories.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
param_indexint_t: Index of the parameter to be varied.
param_rangeNDArray[np.float64] | tuple[float, float, int]: Parameter values used in the sweep. It can be either: - a 1D array of parameter values, or - a tuple (start, stop, num_points) passed to numpy.linspace.
total_timeint_t: Number of iterations computed for each parameter value.
parametersnumeric_like_t | None, optional: Base parameter array. The entry at param_index is overwritten during the sweep.
transient_timeint_t, optional: Number of initial iterations discarded for each parameter value. Default is 0.
continuationbool, optional: If True, use the final state from the previous parameter value as the initial condition for the next one.
return_last_statebool, optional: If True, also return the final state obtained at the last parameter value.
observable_indexint_t, optional: Index of the state coordinate used as the observable in the bifurcation diagram. Default is 0.

Returns

tuple

If return_last_state is False:: (param_values, results)
If return_last_state is True:: (param_values, results, last_state)

Here: - param_values has shape (num_points,) - results has shape (num_points, sample_size) - last_state has shape (system_dimension,)

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If param_index is out of bounds.
If observable_index is out of bounds.
If total_time is negative.
If transient_time is invalid.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If param_index, observable_index, total_time, or transient_time are not integers.
If continuation or return_last_state are not booleans.

Notes

The varied parameter is always stored in the full parameter array passed to the low-level routine. If the system has stored parameters and parameters is not provided, the stored array is used as the base parameter vector.

Estimate the period of an orbit from state recurrences.

The method searches for repeated returns of the trajectory to its initial post-transient state within a prescribed tolerance. A candidate period is accepted only after repeated consistent detections.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
max_timeint_t, optional: Maximum number of iterations used in the search.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
transient_timeint_t | None, optional: Number of initial iterations discarded before the search.
tolerancenumeric_t, optional: Absolute tolerance used to detect recurrences.
min_periodint, optional: Minimum admissible period.
max_periodint, optional: Maximum admissible period.
stability_checksint, optional: Number of identical consecutive detections required before accepting a period.

Returns

int

Detected period.

A positive integer indicates a periodic orbit.
1 indicates a fixed point.
-1 indicates that no valid period was detected within the search window.

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If max_time is negative.
If transient_time is invalid.
If tolerance <= 0.
If min_period < 1.
If max_period < 1.
If max_period < min_period.
If stability_checks < 1.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If max_time is not an integer.
If transient_time is not an integer.
If min_period, max_period, or stability_checks are not integers.

Notes

For reliable detection, max_time should be significantly larger than the expected period.

Check whether an initial condition belongs to a periodic orbit of a given period.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
periodint: Period to test.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
tolerancenumeric_t, optional: Absolute tolerance used in the periodicity check.
transient_timeint_t | None, optional: Number of initial iterations discarded before testing periodicity.

Returns

bool: True if the orbit returns to the same state after period iterations, within the specified tolerance. False otherwise.

Find a periodic orbit through iterative grid refinement.

Parameters

grid_pointsnumeric_like_t

Initial search set.

If symmetry_line is None, it must be a 3D array of shape (grid_size_x, grid_size_y, 2).
If symmetry_line is not None, it must be a 1D array containing the coordinates sampled along the chosen symmetry parametrization.

periodint

Period of the orbit to search for.

parametersnumeric_like_t | None, optional

System parameters passed to the mapping function. If None, the stored system parameters are used.

tolerancenumeric_t, optional

Initial periodicity tolerance.

max_iterint_t, optional

Maximum number of refinement iterations.

convergence_thresholdnumeric_t, optional

Convergence threshold for orbit displacement and search-box size.

tolerance_decay_factornumeric_t, optional

Multiplicative factor used to reduce the tolerance after each iteration. Must satisfy 0 < tolerance_decay_factor < 1.

verbosebool, optional

If True, print iteration diagnostics.

symmetry_lineCallable[…, NDArray[np.float64]] | None, optional

Symmetry-line or symmetry-curve function. If provided, the search is restricted to that line or curve.

axisint | None, optional

Axis convention for the symmetry-line search. Must be 0 or 1 when symmetry_line is provided.

transient_timeint_t | None, optional

Number of initial iterations discarded before testing periodicity.

Returns

NDArray[np.float64]: Approximation of the periodic orbit.

Raises

ValueError

If the system dimension is not 2.
If grid_points has invalid shape.
If period < 1.
If tolerance <= 0.
If max_iter < 1.
If convergence_threshold <= 0.
If tolerance_decay_factor is not in (0, 1).
If symmetry_line is provided and axis is missing.
If axis is not 0 or 1.
If transient_time is negative.

TypeError

If grid_points cannot be interpreted as an array.
If parameters is not a scalar or array-like numeric object.
If symmetry_line is not callable.
If period, max_iter, or axis are not integers.

Compute the eigenvalues and eigenvectors of the monodromy matrix of a periodic orbit of this discrete-time system.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
periodint_t: Period of the orbit.
parametersnumeric_like_t | None, optional: System parameters. If None, the stored system parameters are used.
normalizebool, optional: If True, normalize the returned eigenvectors to unit Euclidean norm.
sort_by_magnitudebool, optional: If True, sort the eigenpairs by decreasing eigenvalue magnitude.

Returns

tuple[NDArray[np.complex128], NDArray[np.complex128]]

A tuple (eigenvalues, eigenvectors) where

eigenvalues has shape (system_dimension,)
eigenvectors has shape (system_dimension, system_dimension)

Each column of eigenvectors is an eigenvector associated with the eigenvalue in the same position.

Raises

ValueError

If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If period is not positive.
If the system does not provide a Jacobian.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If period is not an integer.
If normalize is not a boolean.
If sort_by_magnitude is not a boolean.

Classify the local linear stability of a 2D periodic orbit of this discrete-time system.

Parameters

unumeric_like_t: Initial condition of shape (2,).
periodint_t: Period of the orbit.
parametersnumeric_like_t | None, optional: System parameters. If None, the stored system parameters are used.
thresholdnumeric_t, optional: Reference radius used to separate contracting and expanding multipliers. For standard discrete-time stability analysis this should usually remain equal to 1.0.
tolnumeric_t, optional: Numerical tolerance used when deciding whether a multiplier lies on the threshold.

Returns

dict[str, str | NDArray[np.complex128]]

Dictionary with keys

“classification” : stability label
“eigenvalues” : Floquet multipliers
“eigenvectors” : corresponding eigenvectors

Raises

ValueError

If the system dimension is not 2.
If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If period is not positive.
If threshold is negative.
If tol is negative.
If the system does not provide a Jacobian.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If period is not an integer.
If threshold is not numeric.
If tol is not numeric.

Compute the two branches of the stable or unstable manifold of a 2D saddle periodic orbit.

Parameters

unumeric_like_t: Initial condition on the periodic orbit, with shape (2,).
periodint: Period of the orbit.
parametersnumeric_like_t | None, optional: System parameters. If None, the stored system parameters are used.
deltanumeric_t, optional: Initial displacement magnitude used to seed the manifold branches.
n_pointsint | tuple[int, int], optional: Number of seed points used on each manifold branch. If an integer is given, the same value is used for both branches.
iter_timeint_t | tuple[int_t, int_t], optional: Number of iterations used to evolve each branch. If an integer is given, the same value is used for both branches.
stability{“stable”, “unstable”}, optional: Which invariant manifold to compute.

Returns

tuple[NDArray[np.float64], NDArray[np.float64]]: Two arrays containing the + and - manifold branches.

Raises

ValueError

If the system is not 2-dimensional.
If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If period is not positive.
If delta is not positive.
If n_points is not a positive integer or a tuple of two positive integers.
If iter_time is not a positive integer or a tuple of two positive integers.
If stability is invalid.

RuntimeError

If stability=”stable” but no backward mapping is available.
If no Jacobian is available.

Notes

This method is only implemented for 2D systems and requires the selected periodic orbit to be a saddle.

Compute the rotation number of a trajectory.

The rotation number is estimated as the time average of the wrapped increment of the first coordinate modulo mod.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Number of iterations used in the average.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
modnumeric_t, optional: Period used to wrap the increment of the first coordinate. Must be positive. The default is 1.0.

Returns

float: Estimated rotation number.

Raises

ValueError

If the system dimension is less than 1.
If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is not positive.
If mod is not positive.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If mod is not a real number.

Notes

This wrapper validates the inputs and forwards the computation to the low-level rotation_number routine.

Compute the escape index and escape time for a single trajectory.

Parameters

unumeric_like_t

Initial condition of shape (system_dimension,).

max_timeint_t

Maximum number of iterations.

exitsNDArray[np.float64] | Sequence[Sequence[float]] | Sequence[NDArray[np.float64]]

Exit specification.

If escape == “entering”:: Exit centers, with shape (n_exits, system_dimension) or (system_dimension,) for a single exit center. Hyperrectangular holes are built around each center using hole_size.
If escape == “exiting”:: A bounded region of shape (system_dimension, 2), where each row is [lower, upper] for one coordinate.

parametersnumeric_like_t | None, optional

System parameters. If None, stored system parameters are used.

escapestr, optional

Escape mode. Must be either “entering” or “exiting”.

hole_sizenumeric_t | None, optional

Side length of the hyperrectangular holes used when escape == “entering”.

Returns

Tuple[int, int]

If escape == “entering”:: (exit_index, escape_time)
If escape == “exiting”:: (face_index, escape_time)

Raises

ValueError

If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If max_time <= 0.
If escape is not “entering” or “exiting”.
If hole_size is missing or not positive when escape == “entering”.
If exits has an invalid shape.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If max_time is not an integer.

survival_probability(escape_times: ndarray[tuple[int, ...], dtype[integer]] | Sequence[int], max_time: int | integer, min_time: int | integer = 1, time_step: int | integer = 1) → Tuple[ndarray[tuple[int, ...], dtype[int64]], ndarray[tuple[int, ...], dtype[float64]]][source]

Compute the survival probability from an array of escape times.

Parameters

escape_timesNDArray[np.integer] | Sequence[int]: Escape times for an ensemble of trajectories.
max_timeint_t: Maximum evaluation time.
min_timeint_t, optional: Minimum evaluation time. Default is 1.
time_stepint_t, optional: Step between consecutive evaluation times. Default is 1.

Returns

Tuple[NDArray[np.int64], NDArray[np.float64]]

Tuple (t_values, survival_probs), where:

t_values contains the evaluation times,
survival_probs contains the corresponding survival probabilities.

Raises

ValueError

If escape_times is not one-dimensional.
If any escape time is smaller than 1.
If max_time <= min_time.
If time_step <= 0.

TypeError

If escape_times cannot be converted to an integer NumPy array.
If max_time, min_time, or time_step are not integers.

Compute the diffusion coefficient from an ensemble of trajectories.

Parameters

unumeric_like_t: Ensemble of initial conditions with shape (num_ic, system_dimension).
total_timeint_t: Number of iterations used in the transport estimate.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
axisint, optional: Coordinate index used in the displacement calculation.

Returns

np.float64: Estimated diffusion coefficient.

Raises

ValueError: If u is not a 2D array of valid initial conditions. If parameters does not match the expected number of parameters. If total_time is negative. If axis is not a valid coordinate index.
TypeError: If u, parameters, total_time, or axis have invalid types.

Compute the ensemble average of one coordinate as a function of time.

Parameters

unumeric_like_t: Ensemble of initial conditions with shape (num_ic, system_dimension).
total_timeint_t: Total number of iterations.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
sample_timesNDArray[np.int32] | Sequence[int] | None, optional: Sampling times at which the average is recorded. If None, all times from 1 to total_time are used.
axisint, optional: Coordinate index whose ensemble average is computed.

Returns

NDArray[np.float64]: Ensemble-average time series.

Compute the cumulative ensemble average of one coordinate as a function of time.

Parameters

unumeric_like_t: Ensemble of initial conditions with shape (num_ic, system_dimension).
total_timeint_t: Total number of iterations.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
sample_timesNDArray[np.int32] | Sequence[int] | None, optional: Sampling times at which the cumulative average is recorded. If None, all times from 1 to total_time are used.
axisint, optional: Coordinate index whose cumulative ensemble average is computed.

Returns

NDArray[np.float64]: Cumulative ensemble-average time series.

Compute the root-mean-squared value of one coordinate as a function of time.

Parameters

unumeric_like_t: Ensemble of initial conditions with shape (num_ic, system_dimension).
total_timeint_t: Total number of iterations.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
sample_timesNDArray[np.int32] | Sequence[int] | None, optional: Sampling times at which the RMS value is recorded. If None, all times from 1 to total_time are used.
axisint, optional: Coordinate index whose RMS value is computed.

Returns

NDArray[np.float64]: RMS time series.

Compute the mean squared displacement of one coordinate as a function of time.

Parameters

unumeric_like_t: Ensemble of initial conditions with shape (num_ic, system_dimension).
total_timeint_t: Total number of iterations.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
sample_timesNDArray[np.int32] | Sequence[int] | None, optional: Sampling times at which the MSD is recorded. If None, all times from 1 to total_time are used.
axisint, optional: Coordinate index used in the displacement calculation.

Returns

NDArray[np.float64]: Mean-squared-displacement time series.

Compute the centered time average for each trajectory in an ensemble.

Parameters

unumeric_like_t: Ensemble of initial conditions with shape (num_ic, system_dimension).
total_timeint_t: Total number of iterations.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
axisint, optional: Coordinate index used in the time average.

Returns

NDArray[np.float64]: One centered time-average value for each initial condition.

Compute recurrence times to an eps-neighborhood of the reference point.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Total number of iterations used to detect recurrences.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
epsnumeric_t, optional: Side length of the recurrence neighborhood.
transient_timeint_t | None, optional: Number of initial iterations discarded before defining the recurrence box.

Returns

NDArray[np.float64]: Array containing the recurrence times between successive returns to the eps-neighborhood.

Compute the number of correct decimal digits in the convergence of a weighted Birkhoff average.

This diagnostic compares weighted Birkhoff averages computed over two consecutive halves of the trajectory. Larger values indicate better convergence of the observable average and are typically associated with more regular dynamics.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Total number of iterations used in the computation. If an odd value is provided, it is increased by one internally so that the trajectory can be split into two equal halves.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
funcobservable_t, optional: Observable function applied to the generated trajectory. It must accept a 2D array of shape (n, system_dimension) and return either: - a 1D array of shape (n,), or - a scalar value. The default observable is cos(2π x_0).
transient_timeint_t | None, optional: Number of initial iterations discarded before the computation.

Returns

float: Weighted-Birkhoff convergence indicator defined as -log10(|WB_0 - WB_1|), where WB_0 and WB_1 are the weighted Birkhoff averages over the first and second halves of the trajectory.

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If transient_time is invalid.
If func does not return either a scalar or a 1D array.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.
If func is not callable.

Notes

The computation uses a weighted Birkhoff average on two consecutive trajectory segments of equal length. The observable is evaluated on the generated trajectory after the transient, if any.

Examples

>>> x_obs = lambda X: np.cos(X[:, 0])
>>> value = system.dig(u0, 1000, parameters=params, func=x_obs)

>>> value = system.dig(
...     u0,
...     1000,
...     parameters=params,
...     func=lambda X: np.sin(X[:, 0] + X[:, 1]),
... )

>>> value = system.dig(
...     u0,
...     2000,
...     parameters=params,
...     func=x_obs,
...     transient_time=500,
... )

Compute Lyapunov exponents using specified numerical method.

Parameters

uUnion[NDArray[np.float64], Sequence[float]]: Initial condition(s) of shape (d,) or (n, d) where d is system dimension
total_timeint: Total iterations to compute (default 10000, must be ≥ 1)
parametersUnion[None, float, Sequence[np.float64], NDArray[np.float64]], optional: System parameters of shape (p,) passed to mapping function
methodstr, optional: Computation method: - “ER”: Analytical QR decomposition, after Eckmann and Ruelle [1]. Only for 2d systems - “QR”: QR decomposition (modifed Gram-Schmidt) - “QR_HH”: Householder QR (more stable, uses np.linalg.qr)
return_historybool, optional: If True, returns convergence history (default False)
sample_timesOptional[Union[NDArray[np.float64], Sequence[int]]], optional: Specific times to sample when return_history=True
transient_timeOptional[int], optional: Initial iterations to discard
num_exponentsOptional[int], optional: Number of Lyapunov exponents to compute, by default None. If None, compute the whole spectrum.
log_basefloat, optional (default np.e): Logarithm base for exponents (e.g. e, 2, or 10)

Returns

Union[Tuple[NDArray[np.float64], NDArray[np.float64]],

Tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]]

If return_history=False: exponents
If return_history=True: history

Raises

ValueError

If u is not a scalar, or 1D array, or if its shape does not match the expected system dimension.
If parameters is not None and does not match the expected number of parameters.
If parameters is None but the system expects parameters.
If parameters is a scalar or array-like but not 1D.
If total_time is negative.
If trasient_time is negative.
If transient_time is greater than or equal to total_time.
If method is not “QR” or “QR_HH”.
If sample_times is not a 1D array of integers.
If log_base is not positive.
If num_exponents is larger then the system’s dimension.

TypeError

If u is not a scalar or array-like type.
If parameters is not a scalar or array-like type.
If total_time is not int.
If transient_time is not int.
If log_base is not float.
If num_exponents is not an positive integer.
If sample_times cannot be converted to a 1D array of integers.
If method is not a string.

Notes

Sample times are automatically sorted and deduplicated

References

[1] Eckmann & Ruelle, Rev. Mod. Phys 57, 617 (1985) [2] Wolf et al., Physica 16D 285-317 (1985)

Examples

>>> # Basic 2D system with ER method
>>> u0 = np.array([0.1, 0.2])
>>> params = np.array([0.5, 1.0])
>>> lyapunov_exponents = system.lyapunov(u0, 10000,
...         parameters=params)

>>> # With convergence history
>>> lyapunov_exponents = system.lyapunov(u0, 10000,
...         parameters=params, return_history=True)
>>> # Using Householder QR for better stability
>>> lyapunov_exponents = system.lyapunov(u0, 10000,
...         parameters=params, method="QR_HH", return_history=True)
>>> # With transient time and logarithm base 10
>>> lyapunov_exponents = system.lyapunov(u0, 10000,
...         parameters=params, transient_time=1000,
...         log_base=10.0, return_history=True)

finite_time_lyapunov(u: ndarray[tuple[int, ...], dtype[float64]] | Sequence[float] | float, total_time: int, finite_time: int, parameters: None | float | Sequence[float64] | ndarray[tuple[int, ...], dtype[float64]] = None, num_exponents: int | None = None, method: str = 'QR', transient_time: int | None = None, log_base: float = 2.718281828459045, return_points: bool = False) → ndarray[tuple[int, ...], dtype[float64]] | Tuple[ndarray[tuple[int, ...], dtype[float64]], ndarray[tuple[int, ...], dtype[float64]]][source]

Compute finite-time Lyapunov exponents (FTLE) along trajectory.

Parameters

uUnion[NDArray[np.float64], Sequence[float]]: Initial condition of shape (d,) where d is system dimension
total_timeint: Total simulation time steps (must be > finite_time, default 10000)
finite_timeint: Averaging window size in time steps (default 100)
parametersUnion[None, float, Sequence[np.float64], NDArray[np.float64]], optional: System parameters of shape (p,) passed to mapping function
methodstr, optional: Computation method: - “ER”: Eckmann-Ruelle (optimal for 2D systems) - “QR”: Gram-Schmidt QR decomposition - “QR_HH”: Householder QR (more stable)
transient_timeOptional[int], optional: Initial burn-in period to discard (default None → finite_time)

Returns

NDArray[np.float64]

FTLE matrix of shape (n_windows, d) where:

n_windows = (total_time - transient_time) // finite_time
Each row contains exponents for one time window
Columns are ordered by decreasing exponent magnitude

Raises

ValueError

If u is not a scalar, or 1D array, or if its shape does not match the expected system dimension.
If parameters is not None and does not match the expected number of parameters.
If parameters is None but the system expects parameters.
If parameters is a scalar or array-like but not 1D.
If total_time is negative.
If finite_time is negative or zero.
If trasient_time is negative.
If transient_time is greater than or equal to total_time.
If method is not “QR” or “QR_HH”.
If log_base is not positive

TypeError

If u is not a scalar or array-like type.
If parameters is not a scalar or array-like type.
If total_time is not int.
If transient_time is not int.
If log_base is not float.
If method is not a string.
If return_points is not a boolean.

Notes

FTLE measure local stretching rates over finite intervals
For chaotic systems, FTLE → true exponents as finite_time → ∞
ER method is faster but limited to 2D systems
Results are more reliable when:
finite_time >> 1
(total_time - transient_time) // finite_time >> 1

Examples

>>> # Basic usage with defaults
>>> u0 = np.array([0.1, 0.2])
>>> params = np.array([0.5, 1.0])
>>> ftle = system.finite_time_lyapunov_exponents(u0, params)

>>> # With custom parameters
>>> ftle = system.finite_time_lyapunov_exponents(
...     u0, params,
...     total_time=5000,
...     finite_time=50,
...     method="GS"
... )

Compute covariant Lyapunov vectors (CLVs) along a trajectory of this discrete-time system.

The CLVs form a covariant basis of tangent space that transforms under the Jacobian consistently with the dynamics. The i-th CLV is associated with the i-th Lyapunov exponent, ordered from the most expanding to the most contracting direction.

This method uses a Ginelli-style algorithm consisting of: 1. transient evolution 2. forward QR warm-up 3. forward storage of orthonormal bases and triangular factors 4. backward initialization 5. backward recursion yielding the CLVs

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Number of map iterations for which CLVs are returned.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
num_clvsint | None, optional: Number of CLVs to compute. If None, all CLVs are computed.
transient_timeint_t, optional: Number of initial iterations discarded before the CLV computation.
warmup_timeint_t, optional: Number of forward QR warm-up iterations used before storing the orthonormal bases.
tail_timeint_t, optional: Number of additional forward QR iterations used to initialize the backward recursion.
seedint, optional: Seed used to initialize the random upper-triangular matrix in the backward stage.

Returns

Tuple[NDArray[np.float64], NDArray[np.float64]]

clvs: array of shape (total_time + 1, system_dimension, num_clvs) containing the CLVs along the trajectory
traj: array of shape (total_time + 1, system_dimension) containing the corresponding trajectory

Raises

ValueError

If the system dimension is less than 2.
If total_time is negative.
If transient_time is invalid.
If warmup_time is negative.
If tail_time is negative.
If num_clvs is not in the interval [1, system_dimension].

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time, transient_time, warmup_time, or tail_time are not integers.
If seed is not an integer.

Notes

The quality of the computed CLVs depends on the choices of warmup_time and tail_time. In weakly hyperbolic or nearly tangent regimes, larger values may be necessary.

References

F. Ginelli et al., Characterizing dynamics with covariant Lyapunov vectors, Phys. Rev. Lett. 99, 130601 (2007).

Compute angle diagnostics derived from covariant Lyapunov vectors (CLVs).

This method computes CLVs along a trajectory and returns either the full time series of requested angles or window-averaged angle diagnostics.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Number of map iterations used for the angle diagnostics.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
subspacesSequence[Tuple[Sequence[int], Sequence[int]]] | None, optional: Pairs of CLV index sets defining subspaces whose minimum principal angles are to be computed.
pairsSequence[Tuple[int, int]] | None, optional: Pairs of CLV indices whose mutual angles are to be computed.
window_timeint_t | None, optional: If None, the full time series of angles is returned. Otherwise, angles are computed in consecutive windows and averaged over each window.
transient_timeint_t, optional: Number of initial iterations discarded before the computation.
warmup_timeint_t, optional: Forward QR warm-up length passed to the CLV computation.
tail_timeint_t, optional: Backward-recursion convergence length passed to the CLV computation.
seedint, optional: Seed forwarded to the CLV computation.
use_absbool, optional: If True, use the absolute value of the cosine before applying arccos.

Returns

Tuple[NDArray[np.float64], NDArray[np.float64]]

If window_time is None:

angles: array of shape (T, M)
traj: trajectory of shape (T, system_dimension)

If window_time is not None:

avg_angles: array of shape (num_windows, M + 1), where the first column contains the window center time index
initial_conditions: array of shape (num_windows, system_dimension)

Raises

ValueError

If the system dimension is less than 2.
If total_time is negative.
If transient_time is invalid.
If warmup_time is negative.
If tail_time is negative.
If window_time is not None and is not positive.
If both subspaces and pairs are missing.
If subspaces or pairs contain invalid CLV indices.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time, transient_time, warmup_time, tail_time, or window_time are not integers.
If seed is not an integer.
If use_abs is not a boolean.

Notes

Small subspace angles indicate near-tangencies between invariant directions and are often the most informative hyperbolicity diagnostic. Pairwise CLV angles are more fine-grained but less geometrically complete than subspace angles.

Estimate the Hurst exponent of each component of a trajectory generated by the discrete-time system.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Total number of iterations used to generate the trajectory.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, stored parameters are used.
wminint, optional: Minimum window size used in the rescaled-range analysis. Must satisfy 2 <= wmin < effective_time // 2, where effective_time = total_time - transient_time.
transient_timeint_t | None, optional: Number of initial iterations discarded before generating the trajectory.

Returns

float | NDArray[np.float64]

If system_dimension == 1, returns a scalar Hurst exponent.
Otherwise, returns an array of shape (system_dimension,) containing one Hurst exponent per coordinate.

Raises

ValueError

If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If transient_time is invalid.
If wmin < 2.
If wmin is too large for the effective trajectory length.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.
If wmin is not an integer.

Notes

The Hurst exponent is estimated independently for each coordinate of the generated trajectory using the rescaled-range method.

Compute finite-time Hurst exponents along a trajectory.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Total number of iterations used in the computation.
finite_timeint_t: Length of each non-overlapping analysis window.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, stored parameters are used.
wminint, optional: Minimum window size used in the rescaled-range analysis within each finite-time window.
return_pointsbool, optional: If True, also return the final phase-space point of each window.

Returns

NDArray[np.float64] | tuple[NDArray[np.float64], NDArray[np.float64]]

If return_points=False, returns an array of shape (num_windows, system_dimension) containing the finite-time Hurst exponents.
If return_points=True, returns:
- h_values: shape (num_windows, system_dimension)
- phase_space_points: shape (num_windows, system_dimension)

Raises

ValueError

If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If finite_time is not positive.
If finite_time > total_time.
If wmin < 2.
If wmin >= finite_time // 2.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If finite_time is not an integer.
If wmin is not an integer.
If return_points is not a boolean.

Notes

The trajectory is divided into consecutive non-overlapping windows of length finite_time, and one Hurst exponent per coordinate is computed in each window.

Compute the Smallest Alignment Index (SALI) for a discrete dynamical system.

SALI measures the alignment of two deviation vectors evolved in tangent space. For chaotic trajectories, SALI typically decays rapidly toward zero, whereas for regular trajectories it remains bounded away from zero.

Parameters

unumeric_like_t: Initial condition of shape (d,), where d is the system dimension.
total_timeint_t: Total number of iterations used in the computation.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the parameters stored in the system are used.
return_historybool, optional: If True, return SALI evaluated at the requested sampling times. Otherwise, return only the final SALI value. Default is False.
sample_timesSequence[int_t] | NDArray[np.integer] | None, optional: Iteration times at which SALI is recorded when return_history=True. If None and return_history=True, SALI is recorded at every iteration after the transient.
tolnumeric_t, optional: Early stopping threshold. If SALI < tol, the computation is interrupted. Default is 1e-16.
transient_timeint_t | None, optional: Number of initial iterations to discard before starting the SALI computation. If None, no transient is discarded.
seedint_t, optional: Seed used to initialize the deviation vectors. Default is 1312.
return_last_statebool, optional: If True, also return the final state of the trajectory.

Returns

float or NDArray[np.float64] or tuple

If return_history=False and return_last_state=False, returns the final SALI value as a scalar.
If return_history=False and return_last_state=True, returns (final_sali, final_state).
If return_history=True and return_last_state=False, returns a 1D array containing the sampled SALI history.
If return_history=True and return_last_state=True, returns (sali_history, final_state).

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If transient_time is invalid.
If sample_times is not a valid 1D array of integers.
If tol is negative.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.
If tol is not numeric.
If seed is not an integer.

Notes

SALI tends to zero for chaotic trajectories and remains bounded away from zero for regular trajectories. Sample times are automatically sorted and deduplicated.

Examples

>>> u0 = np.array([0.1, 0.2])
>>> params = np.array([0.5, 1.0])

>>> sali = system.SALI(u0, 10000, parameters=params)

>>> sali_hist = system.SALI(
...     u0, 10000, parameters=params, return_history=True
... )

>>> times = np.array([100, 1000, 5000])
>>> sali_samples, final_state = system.SALI(
...     u0,
...     10000,
...     parameters=params,
...     sample_times=times,
...     return_history=True,
...     return_last_state=True,
... )

Compute the Linear Dependence Index (LDI_k) for a discrete dynamical system.

LDI_k is computed from the evolution of k deviation vectors in tangent space and is used to distinguish regular and chaotic motion.

Parameters

unumeric_like_t: Initial condition of shape (d,), where d is the system dimension.
total_timeint_t: Total number of iterations used in the computation.
kint: Number of deviation vectors used in the computation.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the parameters stored in the system are used.
return_historybool, optional: If True, return LDI_k evaluated at the requested sampling times. Otherwise, return only the final LDI_k value. Default is False.
sample_timesSequence[int_t] | NDArray[np.integer] | None, optional: Iteration times at which LDI_k is recorded when return_history=True. If None and return_history=True, LDI_k is recorded at every iteration after the transient.
tolnumeric_t, optional: Early stopping threshold. If LDI_k < tol, the computation is interrupted. Default is 1e-16.
transient_timeint_t | None, optional: Number of initial iterations to discard before starting the LDI_k computation. If None, no transient is discarded.
seedint, optional: Seed used to initialize the deviation vectors. Default is 1312.
return_last_statebool, optional: If True, also return the final state of the trajectory.

Returns

float or NDArray[np.float64] or tuple

If return_history=False and return_last_state=False, returns the final LDI_k value as a scalar.
If return_history=False and return_last_state=True, returns (final_ldi, final_state).
If return_history=True and return_last_state=False, returns a 1D array containing the sampled LDI_k history.
If return_history=True and return_last_state=True, returns (ldi_history, final_state).

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If transient_time is invalid.
If sample_times is not a valid 1D array of integers.
If k is not in the interval [2, system_dimension].
If tol is negative.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.
If tol is not numeric.
If seed is not an integer.
If k is not an integer.

Notes

A set of k initially orthonormal deviation vectors is evolved with the

Jacobian and renormalized at each step. LDI_k is computed as the product of the singular values of the deviation-vector matrix.

The computation is terminated early if LDI_k < tol.

Examples

>>> u0 = np.array([0.1, 0.2, 0.0, 0.0])
>>> params = np.array([0.5, 1.0])

>>> ldi = system.LDI(u0, 10000, k=2, parameters=params)

>>> ldi_hist = system.LDI(
...     u0, 10000, k=3, parameters=params, return_history=True
... )

>>> times = np.array([100, 1000, 5000])
>>> ldi_samples, final_state = system.LDI(
...     u0,
...     10000,
...     k=2,
...     parameters=params,
...     sample_times=times,
...     return_history=True,
...     return_last_state=True,
... )

Compute the Generalized Alignment Index (GALI_k) for a discrete dynamical system.

GALI_k quantifies the degree of alignment of k deviation vectors evolved in tangent space. It measures the contraction of the k-dimensional volume spanned by these vectors and is used to distinguish regular and chaotic motion.

Parameters

unumeric_like_t

Initial condition of shape (d,), where d is the system dimension.

total_timeint_t

Total number of iterations used in the computation.

kint

Number of deviation vectors used in the computation.

parametersnumeric_like_t | None, optional

System parameters passed to the mapping function. If None, the parameters stored in the system are used.

return_historybool, optional

If True, return GALI_k evaluated at the requested sampling times. Otherwise, return only the final GALI_k value. Default is False.

sample_timesSequence[int_t] | NDArray[np.integer] | None, optional

Iteration times at which GALI_k is recorded when return_history=True. If None and return_history=True, GALI_k is recorded at every iteration after the transient.

methodstr, optional

Method used to compute GALI_k. Supported options are:

“DET”: Compute GALI_k from the Gram matrix G = V^T V, where V is the deviation-vector matrix, through GALI_k = sqrt(det(G)).
“QR”: Compute GALI_k from the diagonal of the triangular factor obtained from the custom QR decomposition routine qr, using GALI_k = prod_i |R_ii|.
“QR_HH”: Compute GALI_k from the diagonal of the triangular factor obtained from the Householder QR decomposition numpy.linalg.qr, again using GALI_k = prod_i |R_ii|.

Default is “QR”.

tolnumeric_t, optional

Early stopping threshold. If GALI_k < tol, the computation is interrupted. Default is 1e-16.

transient_timeint_t | None, optional

Number of initial iterations to discard before starting the GALI_k computation. If None, no transient is discarded.

seedint, optional

Seed used to initialize the deviation vectors. Default is 1312.

return_last_statebool, optional

If True, also return the final state of the trajectory.

Returns

float or NDArray[np.float64] or tuple

If return_history=False and return_last_state=False, returns the final GALI_k value as a scalar.
If return_history=False and return_last_state=True, returns (final_gali, final_state).
If return_history=True and return_last_state=False, returns a 1D array containing the sampled GALI_k history.
If return_history=True and return_last_state=True, returns (gali_history, final_state).

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If transient_time is invalid.
If sample_times is not a valid 1D array of integers.
If k is not in the interval [2, system_dimension].
If method is not “DET”, “QR”, or “QR_HH”.
If tol is negative.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.
If tol is not numeric.
If seed is not an integer.
If k is not an integer.
If method is not a string.

Notes

GALI_k can be written equivalently as

GALI_k = sqrt(det(V^T V))

where V is the deviation-vector matrix, or as

GALI_k = |det(R)| = prod_i |R_ii|

when V = Q R is a QR decomposition.

For chaotic trajectories, GALI_k typically decays rapidly toward zero due to the progressive alignment of deviation vectors. For regular trajectories, the decay is slower or GALI_k may remain bounded away from zero, depending on k and on the dimension of the invariant set.

The computation is terminated early if GALI_k < tol.

Examples

>>> u0 = np.array([0.1, 0.2, 0.0, 0.0])
>>> params = np.array([0.5, 1.0])

>>> gali = system.GALI(u0, 10000, k=2, parameters=params)

>>> gali_hist = system.GALI(
...     u0, 10000, k=3, parameters=params, return_history=True
... )

>>> times = np.array([100, 1000, 5000])
>>> gali_samples, final_state = system.GALI(
...     u0,
...     10000,
...     k=2,
...     parameters=params,
...     sample_times=times,
...     return_history=True,
...     return_last_state=True,
... )

recurrence_matrix(u: ndarray[tuple[int, ...], dtype[float64]] | Sequence[float], total_time: int, parameters: None | float | Sequence[float64] | ndarray[tuple[int, ...], dtype[float64]] = None, transient_time: int | None = None, **kwargs: Any) → ndarray[tuple[int, ...], dtype[uint8]][source]

Compute the recurrence matrix of a univariate or multivariate time series.

Parameters

u: NDArray: Time series data. Can be 1D(shape: (N,)) or 2D(shape: (N, d)). If 1D, the array is reshaped to (N, 1) automatically.
total_time: int: Total number of iterations to simulate.
parameters: Union[None, float, Sequence[np.float64], NDArray[np.float64]], optional: Parameters passed to the mapping function.
transient_time: Optional[int], optional: Number of initial iterations to discard as transient(default None). If None, no transient is removed.
metric: {“supremum”, “euclidean”, “manhattan”}, default = “supremum”: Distance metric used for phase space reconstruction.
std_metric: {“supremum”, “euclidean”, “manhattan”}, default = “supremum”: Distance metric used for standard deviation calculation.
threshold: float, default = 0.1: Recurrence threshold(relative to data range).
threshold_std: bool, default = True: Whether to scale threshold by data standard deviation.

Returns

recmat: NDArray of shape(N, N), dtype = np.uint8: Binary recurrence matrix indicating whether each pair of points are within the threshold distance.

Raises

ValueError

If u is not an 1D array, or if its shape does not match the expected system dimension.
If parameters is not None and does not match the expected number of parameters.
If parameters is None but the system expects parameters.
If parameters is a scalar or array-like but not 1D.
If total_time is negative.
If trasient_time is negative.
If transient_time is greater than or equal to total_time.
If lmin is not a positive integer or is less than 1.
If metric or std_metric is not a valid string.
If threshold is not within [0, 1].

TypeError

If u is not a scalar or array-like type.
If parameters is not a scalar or array-like type.
If total_time is not int.
If transient_time is not int.
If metric or std_metric cannot be converted to a string.
If threshold is not a positive float.
If lmin is not an integer.

Compute the recurrence time entropy (RTE) of a trajectory.

Parameters

unumeric_like_t: Initial condition of shape (system_dimension,).
total_timeint_t: Total number of iterations used in the computation.
parametersnumeric_like_t | None, optional: System parameters passed to the mapping function. If None, the stored system parameters are used.
transient_timeint_t | None, optional: Number of initial iterations discarded before the computation.

Other Parameters

metric{“supremum”, “euclidean”, “manhattan”} or callable, optional: Pairwise metric used to construct the recurrence matrix.
std_metric{“supremum”, “euclidean”, “manhattan”} or callable, optional: Metric used in the standard-deviation-based threshold calculation.
thresholdfloat, optional: Threshold parameter. Its meaning depends on threshold_mode: - direct threshold if threshold_mode=”direct” - standard-deviation scale if threshold_mode=”std” - target recurrence rate if threshold_mode=”rr”
threshold_mode{“direct”, “std”, “rr”} | None, optional: Mode used to determine the recurrence threshold.
threshold_stdbool, optional: Deprecated legacy option. Kept for backward compatibility.
lminint, optional: Minimum white vertical line length used in the recurrence-time distribution.
return_final_statebool, optional: If True, include the final state of the trajectory in the output.
return_recmatbool, optional: If True, include the recurrence matrix in the output.
return_pbool, optional: If True, include the white-vertical-line distribution in the output.

Returns

float or tuple

If no optional outputs are requested, returns the scalar RTE value.
Otherwise returns a tuple whose first entry is the RTE value, followed by the requested outputs in this order:
1. final state, if return_final_state=True
2. recurrence matrix, if return_recmat=True
3. white-vertical-line distribution, if return_p=True

Raises

ValueError

If u is incompatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If transient_time is invalid.
If the RTE configuration is invalid.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If transient_time is not an integer.

Notes

Higher RTE values generally indicate more complex recurrence-time structure. Input validation is handled here; the low-level RTE routine assumes valid input.

Compute the finite-time recurrence time entropy (RTE) over consecutive non-overlapping windows of a trajectory.

Parameters

unumeric_like_t

Initial condition of shape (system_dimension,).

total_timeint_t

Total number of iterations used in the computation.

finite_timeint_t

Length of each non-overlapping analysis window.

parametersnumeric_like_t | None, optional

System parameters passed to the mapping function. If None, the stored system parameters are used.

return_pointsbool, optional

If True, also return the final phase-space point of each window.

**kwargsAny

Additional keyword arguments forwarded to RTE through finite_time_RTE. Supported options are:

metric{“supremum”, “euclidean”, “manhattan”} or callable, optional: Pairwise distance metric used to build the recurrence matrix.
std_metric{“supremum”, “euclidean”, “manhattan”} or callable, optional: Metric used in threshold estimation when threshold_mode="std".
thresholdfloat, optional: Recurrence threshold value, threshold scale, or target recurrence rate depending on threshold_mode.
threshold_mode{“direct”, “std”, “rr”}, optional: Strategy used to determine the recurrence threshold.
threshold_stdbool, optional: Deprecated legacy option. Retained for backward compatibility.
lminint, optional: Minimum white vertical line length used in the distribution.
return_final_statebool, optional: Ignored here. The finite-time wrapper manages final-state handling internally.
return_recmatbool, optional: Whether to include the recurrence matrix in the low-level RTE call.
return_pbool, optional: Whether to include the white-vertical-line distribution in the low-level RTE call.

Returns

NDArray[np.float64] | tuple[NDArray[np.float64], NDArray[np.float64]]

If return_points=False, returns an array of shape (num_windows,) containing the finite-time RTE values.
If return_points=True, returns:
- rte_values: array of shape (num_windows,)
- phase_space_points: array of shape (num_windows, system_dimension) containing the final point of each window

Raises

ValueError

If u is not compatible with the system dimension.
If parameters does not match the expected number of parameters.
If total_time is negative.
If finite_time is not positive.
If finite_time is larger than total_time or otherwise invalid.

TypeError

If u is not a scalar or array-like numeric object.
If parameters is not a scalar or array-like numeric object.
If total_time is not an integer.
If finite_time is not an integer.
If return_points is not a boolean.

Notes

The trajectory is split into consecutive non-overlapping windows of length finite_time. One RTE value is computed per window.

Examples

>>> ftrte = system.finite_time_recurrence_time_entropy(
...     u0,
...     total_time=50000,
...     finite_time=100,
...     parameters=params,
... )