chaotic_pfc.analysis.sweep

Parameter-sweep computation of Lyapunov exponents for the Henon map with an internal FIR filter.

This module sweeps the 2-D grid of filter orders N_s in {2, ..., 41} against normalised cutoffs omega_c in (0, 1) and estimates the largest Lyapunov exponent lambda_max at each grid point.

All hot paths are JIT-compiled with Numba. The outer 2-D loop is flattened into a single prange so every grid point is a task available to the thread pool.

The public API is small:

class chaotic_pfc.analysis.sweep.SweepResult(h, h_std, orders, cutoffs, window, filter_type, n_iters_used=None, metadata=<factory>)[source]

Bases: object

Result of a single (window, filter) sweep.

Parameters:
h

Mean of lambda_max across n_initial random ICs, per grid point. NaN where the trajectory diverged for all ICs.

Type:

ndarray, shape (Ncoef, Ncut)

h_std

Standard deviation of lambda_max samples at each grid point.

Type:

ndarray, shape (Ncoef, Ncut)

orders

Filter orders N_s actually swept.

Type:

ndarray, shape (Ncoef,)

cutoffs

Normalised cutoff frequencies omega_c in (0, 1) swept.

Type:

ndarray, shape (Ncut,)

window

FIR window used (lower-case, e.g. "hamming").

Type:

str

filter_type

Filter pass-zero configuration.

Type:

{“lowpass”, “highpass”, “bandpass”, “bandstop”}

n_iters_used

Average number of Lyapunov iterations actually used per grid point (across non-divergent ICs). In non-adaptive sweeps every finite cell equals Nmap; in adaptive sweeps it ranges from Nmap_min to Nmap, providing a “difficulty map” of the parameter space. None when loaded from a legacy .npz without this field.

Type:

ndarray, shape (Ncoef, Ncut), optional

metadata

Free-form metadata (simulation parameters, timing, etc.).

Type:

dict

h: ndarray[tuple[Any, ...], dtype[_ScalarT]]
h_std: ndarray[tuple[Any, ...], dtype[_ScalarT]]
orders: ndarray[tuple[Any, ...], dtype[_ScalarT]]
cutoffs: ndarray[tuple[Any, ...], dtype[_ScalarT]]
window: str
filter_type: str
n_iters_used: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None
metadata: dict
property display_name: str

Human-readable name used for output directories.

chaotic_pfc.analysis.sweep.load_sweep(path)[source]

Load a sweep from .npz produced by save_sweep().

Parameters:

path (str | Path)

Return type:

SweepResult

chaotic_pfc.analysis.sweep.precompute_fir_bank(orders, cutoffs, filter_type, window, *, kaiser_beta=5.0, bandwidth=0.05)[source]

Build the FIR coefficient tensor and gain matrix for a sweep.

Parameters:

  • orders (Sequence[int] | ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Filter orders to sweep. Values will be cast to int.

  • cutoffs (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Normalised cutoff frequencies in (0, 1).

  • filter_type (str) – "lowpass", "highpass", "bandpass", or "bandstop".

  • window (str) – Window name in WINDOWS.

  • kaiser_beta (float) – Shape parameter of the Kaiser window. Ignored unless window == "kaiser". Must be >= 0.

  • bandwidth (float) – Width of the pass/stop band when filter_type is "bandpass" or "bandstop". Ignored for lowpass and highpass. Clamped so edges stay inside (0, 1).

Returns:

  • fir_bank (ndarray, shape (Ncoef, Ncut, max_order)) – fir_bank[i, j, :order_i] holds the FIR coefficients for the (order_i, cutoff_j) pair, zero-padded on the right.

  • gains (ndarray, shape (Ncoef, Ncut)) – DC gain (sum of coefficients) of each filter.

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]]]

chaotic_pfc.analysis.sweep.quick_sweep_params()[source]

Return the (orders_lp, orders_hp, cutoffs, params) for quick-sweep mode.

These are small grids suitable for testing and CI smoke runs.

Return type:

tuple[ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]], ndarray[tuple[Any, …], dtype[_ScalarT]], dict[str, float | int]]

chaotic_pfc.analysis.sweep.run_sweep(window='hamming', filter_type='lowpass', *, orders=None, cutoffs=None, Nitera=500, Nmap=3000, n_initial=25, alpha=1.4, beta=0.3, seed=42, warmup=True, kaiser_beta=5.0, bandwidth=0.05, adaptive=False, Nmap_min=500, tol=0.001)[source]

Run a full Lyapunov sweep for one (window, filter) combination.

Parameters:

  • window (str) – FIR configuration (see WINDOWS, FILTER_TYPES).

  • filter_type (str) – FIR configuration (see WINDOWS, FILTER_TYPES).

  • orders (Sequence[int] | ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Filter orders to sweep. Defaults to np.arange(2, 42) for lowpass and np.arange(3, 43, 2) for highpass (which requires odd tap counts).

  • cutoffs (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Cutoff frequencies. Defaults to 100 points linearly spaced in (0, 1).

  • Nitera (int) – Burn-in iterations applied to the map before starting the Lyapunov accumulation.

  • Nmap (int) – Maximum number of iterations used to estimate each Lyapunov exponent. Also the exact iteration count when adaptive=False.

  • bandwidth (float) – Width of the pass/stop band for bandpass/bandstop filters.

  • n_initial (int) – Number of random initial conditions averaged per grid point.

  • alpha (float) – Henon parameters (alpha, beta).

  • beta (float) – Henon parameters (alpha, beta).

  • seed (int | None) – Seed for the RNG used to shuffle initial conditions. None leaves the RNG state untouched.

  • warmup (bool) – Run a tiny sweep first to trigger Numba JIT compilation.

  • kaiser_beta (float) – Shape parameter of the Kaiser window.

  • adaptive (bool) – When True, enable adaptive early-stop in the Lyapunov kernels.

  • Nmap_min (int) – Minimum iterations before the adaptive criterion may fire.

  • tol (float) – Convergence tolerance for the adaptive criterion.

Returns:

Full result object.

Return type:

SweepResult

See also

Parameter sweep architecture : Parallel architecture and divergence handling.

chaotic_pfc.analysis.sweep.save_sweep(result, path)[source]

Save a SweepResult to a compressed .npz.

Parameters:
Return type:

Path