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[tuple[Any, ...], dtype[_ScalarT]])
fixed_point (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
eigenvalues (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
stable (bool | None)
fixed_point_p (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
fixed_point_n (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
eigenvalues_p (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
eigenvalues_n (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None)
stable_p (bool | None)
stable_n (bool | None)

lyapunov_max: float¶

all_exponents: ndarray[tuple[Any, ...], dtype[_ScalarT]]¶

fixed_point: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None¶

eigenvalues: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None¶

stable: bool | None = None¶

fixed_point_p: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None¶

fixed_point_n: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None¶

eigenvalues_p: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None¶

eigenvalues_n: ndarray[tuple[Any, ...], dtype[_ScalarT]] | 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.

Parameters:

alpha (float) – Hénon \(\alpha\) parameter.
beta (float) – Hénon \(\beta\) parameter.
Gz (float) – Pole-filter input gain. Governs the filter’s DC gain and the fixed-point location.
pole_radius (float) – Radius r of the pole in the z-domain. Must satisfy 0 ≤ r < 1 for a stable filter.
w0 (float) – Angular frequency ω₀ of the pole in radians/sample. w0 = 0 places both poles on the real axis.
Nitera (int) – Number of QR iterations (post-transient) over which the log-norm is accumulated.
Ndiscard (int) – Number of burn-in iterations discarded before the QR loop starts.
perturbation (float) – Half-width of the uniform sampling box around the fixed point, used to generate the initial condition. IC = xf · (1 + p · U) with U ∈ [-1, 1] per component.
seed (int) – RNG seed for the initial-condition perturbation.

Returns:

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

Return type:

LyapunovResult