chaotic_pfc.analysis.sweep_plotting¶

sweep_plotting.py¶

Figures for Lyapunov classification maps produced by chaotic_pfc.sweep.

Three plot types are provided:

plot_heatmap_continuous() — raw λ_max heatmap.
plot_classification_interleaved() — publication-style discrete classification (periodic / chaotic / unbounded) with gaps between orders.
plot_difficulty_map() — heatmap of the number of Lyapunov iterations actually used at each grid point. Only meaningful when the sweep was run with adaptive=True; shows where the spectrum converges quickly (light) vs. where it needs the full budget (dark) — a “difficulty map” of the parameter space.

All three accept a SweepResult (or its individual arrays for the first two) and optionally a save_path. They return the matplotlib.figure.Figure so callers can compose or display them. The module also re-uses the RC params from chaotic_pfc.plotting, so sweep figures look consistent with the rest of the pipeline.

Functions

`classify`(h)	Map raw λ_max values to discrete classes.
`plot_all`(result, out_dir, *[, fmt, ...])	Generate the standard figures for a sweep and save them to `out_dir/<fig>.{fmt}`.
`plot_chaotic_all`([sweep_dir, out_dir, ...])	Generate both cross-sweep chaotic figures and save to out_dir.
`plot_chaotic_density`([sweep_dir, save_path, ...])	Density map: how many window × filter configurations are chaotic.
`plot_chaotic_map`([sweep_dir, save_path, ...])	Binary union of chaotic regions across all window × filter sweeps.
`plot_classification_interleaved`([result, h, ...])	Publication-style layout with gaps between adjacent orders.
`plot_difficulty_map`(result, *[, save_path, ...])	Heatmap of Lyapunov iterations actually used at each grid point.
`plot_heatmap_continuous`([result, h, orders, ...])	Continuous λ_max heatmap over the (N_z, ω_c/π) plane.

chaotic_pfc.analysis.sweep_plotting.classify(h)[source]¶

Map raw λ_max values to discrete classes.

Returns an array with the same shape as h where each entry is:

-1 — periodic orbit (λ_max ≤ 0)
0 — chaotic orbit (λ_max > 0)
2 — unbounded / divergent (NaN in h)

The unusual integer codes match the matplotlib.colors.BoundaryNorm bins used below.

Parameters:: h (ndarray[tuple[Any, ...], dtype[_ScalarT]])
Return type:: ndarray[tuple[Any, …], dtype[_ScalarT]]

chaotic_pfc.analysis.sweep_plotting.plot_heatmap_continuous(result=None, *, h=None, orders=None, cutoffs=None, save_path=None, data_slots=3, gap_slots=1)[source]¶

Continuous λ_max heatmap over the (N_z, ω_c/π) plane.

Uses the same interleaved-column layout as plot_classification_interleaved() for visual consistency across the full figure set.

Parameters:

result (SweepResult | None) – SweepResult to plot. Mutually exclusive with the (h, orders, cutoffs) triple.
h (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Lyapunov grid, shape (len(orders), len(cutoffs)).
orders (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Filter orders (x-axis), shape (len(orders),).
cutoffs (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Cutoff frequencies (y-axis), shape (len(cutoffs),).
save_path (str | Path | None) – If provided, the figure is saved to this path via _save().
data_slots (int) – Interleaved-column parameters.
gap_slots (int) – Interleaved-column parameters.

Return type:

matplotlib.figure.Figure

chaotic_pfc.analysis.sweep_plotting.plot_classification_interleaved(result=None, *, h=None, orders=None, cutoffs=None, save_path=None, data_slots=3, gap_slots=1, lang='pt')[source]¶

Publication-style layout with gaps between adjacent orders.

Each order occupies data_slots columns of coloured data followed by gap_slots blank columns, producing the striped appearance used in Baptista et al.

Parameters:

result (SweepResult | None) – SweepResult to plot. Mutually exclusive with the (h, orders, cutoffs) triple.
h (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Lyapunov grid, shape (len(orders), len(cutoffs)).
orders (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Filter orders (x-axis), shape (len(orders),).
cutoffs (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – Cutoff frequencies (y-axis), shape (len(cutoffs),).
save_path (str | Path | None) – If provided, the figure is saved to this path via _save().
data_slots (int) – Number of colormap quantisation levels for chaotic/periodic.
gap_slots (int) – Number of white/yellow slots interleaved between classes.
lang (str) – Language for axis labels ("pt" or "en").

Return type:

matplotlib.figure.Figure

chaotic_pfc.analysis.sweep_plotting.plot_difficulty_map(result, *, save_path=None, cmap='viridis', data_slots=3, gap_slots=1)[source]¶

Heatmap of Lyapunov iterations actually used at each grid point.

A “difficulty map” of the parameter space: low values mean the spectrum estimate converged quickly (strongly chaotic or strongly stable points), high values mean the running estimate stayed within the convergence tolerance only after many iterations (typically fronteira points where |λ_max| ≈ 0). Diverged grid points are shown in the same light grey used for unbounded orbits in the classification figures, so the two layers can be visually overlaid.

Uses the same interleaved-column layout as plot_classification_interleaved().

Parameters:

result (SweepResult) – A SweepResult produced with adaptive=True. The function relies on result.n_iters_used and on result.metadata['Nmap_min'] / result.metadata['Nmap'] for the colour-bar limits.
save_path (str | Path | None) – Optional path to write the figure to.
cmap (str) – Sequential matplotlib colormap name. viridis is perceptually uniform and prints well in greyscale.
data_slots (int) – Interleaved-column parameters.
gap_slots (int) – Interleaved-column parameters.

Raises:

ValueError – If result was produced with adaptive=False (the heatmap would be a single colour, which is misleading rather than informative). The error message points the user to the adaptive=True flag in run_sweep().

Return type:

Figure

chaotic_pfc.analysis.sweep_plotting.plot_chaotic_map(sweep_dir='data/sweeps', *, save_path=None, color='red', data_slots=3, gap_slots=1, lang='pt')[source]¶

Binary union of chaotic regions across all window × filter sweeps.

At each grid point, if any sweep has λ_max > 0 the cell is coloured; otherwise it is white. The result is a single-colour silhouette of the full chaotic envelope. The interleaved-column layout matches plot_classification_interleaved().

Parameters:

sweep_dir (str | Path) – Root directory with <Window> (<ft>)/variables_lyapunov.npz subdirectories.
save_path (str | Path | None) – If provided, saved as both .svg and .png (bare stem).
color (str) – Matplotlib colour for chaotic cells (default: project red).
data_slots (int) – Interleaved-column parameters.
gap_slots (int) – Interleaved-column parameters.
lang (str) – Language for labels ("pt" or "en").

Return type:

matplotlib.figure.Figure