chaotic_pfc.dynamics.lyapunov

lyapunov.py

Lyapunov exponent computation for the Hénon map (2-D) and the Hénon map with a pole filter (4-D).

4-D system:

x₁[n+1] = α − x₃[n]² + β·x₂[n] x₂[n+1] = x₁[n] x₃[n+1] = b₀·(α − x₃[n]² + β·x₂[n]) + a₁·x₃[n] + a₂·x₄[n] x₄[n+1] = x₃[n]

where b = [b₀, 0, 0] and a = −[1, −2r·cos(w₀), r²] (pole-filter coeffs).

2-D system:

x₁[n+1] = α − x₁[n]² + β·x₂[n] x₂[n+1] = x₁[n]

Two flavours of computation are provided:

  • lyapunov_max / lyapunov_henon2d — single perturbed initial condition, returning one estimate of the spectrum.

  • lyapunov_max_ensemble / lyapunov_henon2d_ensemble — full experimental protocol: sample N_ci initial conditions uniformly around the fixed point (±``perturbation``), compute the spectrum for each, and aggregate statistics. Results can be exported to CSV via EnsembleResult.to_csv().

Implementation note

The 2-D and 4-D variants share the same QR/Gram-Schmidt loop; the only differences are the iterate function, the Jacobian, and the dimension. Both single-IC and ensemble entry points delegate to the generic helpers _lyapunov_spectrum and _run_ensemble.

Functions

fixed_point_stability([alpha, beta, Gz, ...])

Quick check: fixed point, eigenvalues, stability (4-D filtered).

lyapunov_henon2d([alpha, beta, Nitera, ...])

Compute Lyapunov exponents for the standard 2-D Hénon map.

lyapunov_henon2d_ensemble([alpha, beta, ...])

Ensemble Lyapunov protocol for the standard 2-D Hénon map.

lyapunov_max([alpha, beta, Gz, pole_radius, ...])

Compute the maximum Lyapunov exponent of the 4-D pole-filtered Hénon map.

lyapunov_max_ensemble([alpha, beta, Gz, ...])

Ensemble Lyapunov protocol for the 4-D pole-filtered Hénon map.

Classes

EnsembleResult(fixed_point, eigenvalues, ...)

Outcome of the ensemble Lyapunov protocol.

FixedPointInfo

Result of fixed_point_stability() — fixed point, eigenvalues, stability.

LyapunovResult(lyapunov_max, all_exponents)

Result of a single-IC Lyapunov exponent computation (2-D or 4-D).
class chaotic_pfc.dynamics.lyapunov.FixedPointInfo[source]

Bases: TypedDict

Result of fixed_point_stability() — fixed point, eigenvalues, stability.

fixed_point: ndarray[tuple[Any, ...], dtype[_ScalarT]]
eigenvalues: ndarray[tuple[Any, ...], dtype[_ScalarT]]
stable: bool
class chaotic_pfc.dynamics.lyapunov.LyapunovResult(lyapunov_max, all_exponents, fixed_point=None, eigenvalues=None, stable=None, fixed_point_p=None, fixed_point_n=None, eigenvalues_p=None, eigenvalues_n=None, stable_p=None, stable_n=None)[source]

Bases: object

Result of a single-IC Lyapunov exponent computation (2-D or 4-D).

Fields populated by lyapunov_max() (4-D):

lyapunov_max, all_exponents, fixed_point, eigenvalues, stable

Fields populated by lyapunov_henon2d() (2-D):

lyapunov_max, all_exponents, fixed_point_p, fixed_point_n, eigenvalues_p, eigenvalues_n, stable_p, stable_n

Parameters:
lyapunov_max: float
all_exponents: ndarray
fixed_point: ndarray | None = None
eigenvalues: ndarray | None = None
stable: bool | None = None
fixed_point_p: ndarray | None = None
fixed_point_n: ndarray | None = None
eigenvalues_p: ndarray | None = None
eigenvalues_n: ndarray | None = None
stable_p: bool | None = None
stable_n: bool | None = None
chaotic_pfc.dynamics.lyapunov.lyapunov_max(alpha=1.4, beta=0.3, Gz=1.0, pole_radius=0.975, w0=0.0, Nitera=2000, Ndiscard=1000, perturbation=0.1, seed=42)[source]

Compute the maximum Lyapunov exponent of the 4-D pole-filtered Hénon map.

Returns:

With fields: lyapunov_max, all_exponents, fixed_point, eigenvalues, stable.

Return type:

LyapunovResult

Parameters:
chaotic_pfc.dynamics.lyapunov.fixed_point_stability(alpha=1.4, beta=0.3, Gz=1.0, pole_radius=0.975, w0=0.0)[source]

Quick check: fixed point, eigenvalues, stability (4-D filtered).

Parameters:
Return type:

FixedPointInfo

chaotic_pfc.dynamics.lyapunov.lyapunov_henon2d(alpha=1.4, beta=0.3, Nitera=2000, Ndiscard=1000, perturbation=0.1, seed=42)[source]

Compute Lyapunov exponents for the standard 2-D Hénon map.

Returns:

With fields: lyapunov_max, all_exponents, fixed_point_p, fixed_point_n, eigenvalues_p, eigenvalues_n, stable_p, stable_n.

Return type:

LyapunovResult

Parameters:
class chaotic_pfc.dynamics.lyapunov.EnsembleResult(fixed_point, eigenvalues, stable, initial_conditions, exponents_per_ci, lmax_per_ci, mean_exponents, mean_lmax, max_lmax, n_chaotic, n_stable, metadata=<factory>)[source]

Bases: object

Outcome of the ensemble Lyapunov protocol.

Parameters:
fixed_point

Fixed point used as the sampling centre.

Type:

ndarray, shape (dim,)

eigenvalues

Eigenvalues of the Jacobian at fixed_point.

Type:

ndarray, shape (dim,)

stable

True iff all(|eigenvalues| < 1).

Type:

bool

initial_conditions

Initial conditions drawn for each run.

Type:

ndarray, shape (n_initial, dim)

exponents_per_ci

Full Lyapunov spectrum for each IC.

Type:

ndarray, shape (n_initial, dim)

lmax_per_ci

Largest Lyapunov exponent for each IC.

Type:

ndarray, shape (n_initial,)

mean_exponents

Per-component mean of exponents_per_ci.

Type:

ndarray, shape (dim,)

mean_lmax, max_lmax

Aggregates of lmax_per_ci.

Type:

float

n_chaotic, n_stable

Counts of ICs with λ_max > 0 and λ_max ≤ 0.

Type:

int

metadata

Free-form metadata (parameters used for the run).

Type:

dict

fixed_point: ndarray[tuple[Any, ...], dtype[_ScalarT]]
eigenvalues: ndarray[tuple[Any, ...], dtype[_ScalarT]]
stable: bool
initial_conditions: ndarray[tuple[Any, ...], dtype[_ScalarT]]
exponents_per_ci: ndarray[tuple[Any, ...], dtype[_ScalarT]]
lmax_per_ci: ndarray[tuple[Any, ...], dtype[_ScalarT]]
mean_exponents: ndarray[tuple[Any, ...], dtype[_ScalarT]]
mean_lmax: float
max_lmax: float
n_chaotic: int
n_stable: int
metadata: dict
to_csv(path)[source]

Write the per-IC table to CSV.

Columns: ci, x0_0, x0_1, ..., lambda_1, lambda_2, ..., lmax, status. Parent directories are created automatically.

Parameters:

path (str | Path)

Return type:

Path

chaotic_pfc.dynamics.lyapunov.lyapunov_max_ensemble(alpha=1.4, beta=0.3, Gz=1.0, pole_radius=0.975, w0=0.0, Nitera=2000, Ndiscard=1000, perturbation=0.1, n_initial=20, seed=42)[source]

Ensemble Lyapunov protocol for the 4-D pole-filtered Hénon map.

See EnsembleResult for the output schema. Samples n_initial initial conditions uniformly in a box of half-width perturbation around the fixed point, then runs the single-IC Gram-Schmidt Lyapunov estimator on each.

Parameters:
Return type:

EnsembleResult

chaotic_pfc.dynamics.lyapunov.lyapunov_henon2d_ensemble(alpha=1.4, beta=0.3, Nitera=2000, Ndiscard=1000, perturbation=0.1, n_initial=20, seed=42)[source]

Ensemble Lyapunov protocol for the standard 2-D Hénon map.

Samples around the positive fixed point (the one usually found in the strange attractor basin for α = 1.4, β = 0.3). See EnsembleResult for the output schema.

Parameters:
Return type:

EnsembleResult