chaotic_pfc.analysis.sweep_plotting

sweep_plotting.py

Figures for Lyapunov classification maps produced by chaotic_pfc.sweep.

Three plot types are provided:

  1. plot_heatmap_continuous() — raw λ_max heatmap.

  2. plot_classification_interleaved() — publication-style discrete classification (periodic / chaotic / unbounded) with gaps between orders.

  3. 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_classification_interleaved([result, h, ...])

Publication-style layout with gaps between adjacent orders.

plot_difficulty_map(result, *[, save_path, cmap])

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)[source]

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

Parameters:
Return type:

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:
Return type:

Figure

chaotic_pfc.analysis.sweep_plotting.plot_difficulty_map(result, *, save_path=None, cmap='viridis')[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.

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.

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_all(result, out_dir, *, fmt='png', close_figures=True, lang='pt')[source]

Generate the standard figures for a sweep and save them to out_dir/<fig>.{fmt}. Returns the list of written paths.

Always produces the two classification figures listed in FIGURE_FILENAMES. Additionally produces fig3_difficulty_map.{fmt} (see DIFFICULTY_FIGURE_FILENAME) when result was generated with adaptive=True: the figure is silently skipped for non-adaptive sweeps because it would be monochromatic and therefore uninformative.

The output directory is created if it does not exist.

Parameters:
Return type:

list[Path]