API Reference

Lyapunov Analysis

chaotax.lyapunov(stepper, *, rollout_steps=20000, warmup_steps=500, discard_steps=1000, dt=1)

Estimate the largest Lyapunov exponent of a dynamical system.

Return type:

Callable[[Inexact[Array, '*state_shape'], Inexact[Array, '*state_shape']], Float[Array, '']]

Parameters:

• stepper (Callable[[Inexact[Array, '*state_shape']], Inexact[Array, '*state_shape']])

• rollout_steps (int)

• warmup_steps (int)

• discard_steps (int)

• dt (float)

chaotax.lyapunov_spectrum(stepper, *, rollout_steps=20000, warmup_steps=500, discard_steps=1000, dt=1, num_exponents=None)

Estimate the Lyapunov spectrum of a dynamical system.

Returns a callable that computes Lyapunov exponents (in descending order) by tracking a matrix of perturbation vectors with QR re-orthonormalisation. When num_exponents is smaller than the number of degrees of freedom, only the leading exponents are computed at reduced cost (O(n_dof * num_exponents) per step instead of O(n_dof²)).

Return type:

Callable[[Inexact[Array, '*state_shape'], Inexact[Array, 'p *state_shape'] | None], Float[Array, 'p']]

Parameters:

• stepper (Callable[[Inexact[Array, '*state_shape']], Inexact[Array, '*state_shape']])

• rollout_steps (int)

• warmup_steps (int)

• discard_steps (int)

• dt (float)

• num_exponents (int | None)

Utilities

chaotax.rollout_growth(stepper, n)

Compute per-step tangent growth factors along a trajectory.

Rolls out the stepper for n steps while tracking how an initial perturbation vector grows under the linearised dynamics (via JVP). The perturbation is re-normalised after each step.

Parameters:

• stepper (Callable[[Inexact[Array, '*state_shape']], Inexact[Array, '*state_shape']]) – One-step state transition function.

• n (int) – Number of rollout steps.

Return type:

Callable[[Inexact[Array, '*state_shape'], Inexact[Array, '*state_shape']], Float[Array, 'n']]

Returns:

A function (u_0, eps_0) -> growth that returns the growth factor at each step.

chaotax.rollout_growth_spectrum(stepper, n)

Compute per-step growth factors for a set of perturbation vectors.

Like rollout_growth(), but tracks a matrix of perturbation directions simultaneously using QR re-orthonormalisation at each step. The perturbation matrix may have fewer rows than n_dof to compute only the leading exponents (cost per step is O(n_dof * p) instead of O(n_dof²) for the full spectrum).

Parameters:

• stepper (Callable[[Inexact[Array, '*state_shape']], Inexact[Array, '*state_shape']]) – One-step state transition function.

• n (int) – Number of rollout steps.

Return type:

Callable[[Inexact[Array, '*state_shape'], Inexact[Array, 'n_dof *state_shape']], Float[Array, 'n n_dof']]

Returns:

A function (u_0, eps_matrix_0) -> growth where growth has shape (n, p) containing the diagonal R-factor at each step.

chaotax.repeat(stepper, n)

Repeat application of a stepper function n times.

Parameters:

• stepper (Callable[[Shaped[Array, '?leaf_shape'], 'T']], Shaped[Array, '?leaf_shape'], 'T']]) – A function that takes in the current state and returns the next state.

• n (int) – Number of times to apply the stepper function.

Return type:

Callable[[Shaped[Array, '?leaf_shape'], 'T']], Shaped[Array, '?leaf_shape'], 'T']]

Returns:

A function that takes in the initial state and returns the state after n applications of the stepper.