Usage guide

This page walks through every CLI workflow with example commands and their expected outputs.

Full pipeline (quick mode)

chaotic-pfc run all --no-display --quick-sweep

Runs every experiment in sequence using a reduced Lyapunov grid (seconds of compute time rather than hours). Produces attractor portraits, SDIC visualisation, communication figures, Lyapunov CSV tables, sweep .npz checkpoints, and classification maps.

Tip

Use --quick-sweep for smoke testing. Remove it to execute the full-resolution sweep (~40 orders × 100 cutoffs × 25 ICs × 3000 iterations each).

Single experiments

Attractors

chaotic-pfc run attractors

Generates three phase-space portraits (standard, generalised, and filtered Hénon maps). The \(x\)-axis shows the first state variable; the \(y\)-axis shows the second.

chaotic-pfc run attractors --save --lang en

Saves SVG figures with English titles to the figures/ directory.

Sensitivity (SDIC)

chaotic-pfc run sensitivity

Overlays two Hénon trajectories with initial conditions separated by \(10^{-4}\) to visualise exponential divergence: the hallmark of chaotic dynamics.

Communication pipeline

Three channel types are available for the full transmit-channel-receive chain:

chaotic-pfc run comm-ideal       # noiseless pass-through channel
chaotic-pfc run comm-fir         # FIR low-pass band-limited channel
chaotic-pfc run comm-order-n     # order-N Hénon + FIR channel

Each produces a \(4 \times 2\) grid of time-domain and PSD plots for the message, carrier, received signal, and recovered message.

Add --save to write figures to figures/. Use --lang pt for Portuguese figure labels.

Lyapunov spectra

chaotic-pfc run lyapunov

Computes Lyapunov exponents for 2-D and 4-D systems in four parts:

  • (A) 2-D Hénon: single initial condition.

  • (B) 4-D pole-filtered Hénon: single IC.

  • (C) 2-D Hénon: ensemble protocol with \(N_{\text{CI}}\) ICs.

  • (D) 4-D pole-filtered Hénon: ensemble protocol with \(N_{\text{CI}}\) ICs.

chaotic-pfc run lyapunov --save --n-ci 50

Saves per-IC CSV tables with 50 initial conditions to data/lyapunov/.

Sweep compute

Runs the 2-D (filter order, cutoff frequency) Lyapunov sweep:

chaotic-pfc run sweep compute --window hamming --filter lowpass

Results are saved as data/sweeps/<display-name>/variables_lyapunov.npz.

# Quick mode (~seconds, reduced grid) for smoke testing
chaotic-pfc run sweep compute --window hamming --filter lowpass --quick

# Run all window×filter combinations
chaotic-pfc run sweep compute --all

# Kaiser window with custom beta and bandpass bandwidth
chaotic-pfc run sweep compute --window kaiser --filter bandpass \
    --kaiser-beta 8.0 --bandwidth 0.3

# Adaptive early-stop: 3-4× speedup with negligible accuracy loss
chaotic-pfc run sweep compute --window hamming --filter lowpass \
    --adaptive --Nmap-min 500 --tol 1e-3

Sweep plot

Generates classification figures from saved .npz checkpoints:

# Plot all window×filter combinations in data/sweeps/
chaotic-pfc run sweep plot --all

# Plot only one combination
chaotic-pfc run sweep plot --window hamming --filter lowpass

# Specify output directory
chaotic-pfc run sweep plot --all --figures-dir figures/custom/

# Save figures without displaying
chaotic-pfc run sweep plot --all --save --no-display

Produces (per combination):

  • Heatmap: continuous \(\lambda_{\max}\) over \((N_z, \omega_c / \pi)\).

  • Classification interleaved: discrete map: periodic (blue), chaotic (red), unbounded (grey).

  • Difficulty map: adaptive iteration count per grid point (only for adaptive sweeps).

  • Beta curves: \(\lambda_{\max}\) evolution across Kaiser \(\beta\) values (only for Kaiser sweeps).

Beta sweep

Runs the Lyapunov sweep for a range of Kaiser \(\beta\) values:

chaotic-pfc run sweep beta-sweep --beta-min 2.0 --beta-max 10.0 --beta-step 0.5

Runs sweeps for every \(\beta\) in the interval for each filter type under the Kaiser window. Results go to data/sweeps/kaiser/.

# Adaptive mode saves significant time on beta-sweeps
chaotic-pfc run sweep beta-sweep --beta-min 2.0 --beta-max 10.0 \
    --beta-step 0.5 --adaptive --tol 1e-3

3-D visualisation (requires plotly)

pip install -e ".[viz3d]"
chaotic-pfc run sweep plot-3d --all

Opens an interactive 3-D Plotly volume stacking all \(\beta\) surfaces, with configurable camera angle and colour scale.

Statistical analysis

chaotic-pfc run analysis

Prints a comprehensive 10-section report summarising all sweep results found under data/sweeps/:

  1. Summary table: one row per sweep with chaotic/periodic/divergent percentages.

  2. Filter-type comparison: aggregates per filter type (lowpass, highpass, bandpass, bandstop).

  3. Best chaos-preserving filters: ranked by chaotic coverage.

  4. Lambda-max distribution: histogram with skewness statistics.

  5. Transition boundaries: first chaotic cutoff per filter order.

  6. Spectral robustness (chaos margin): width of the chaotic region.

  7. Spearman correlation: (order, cutoff) vs. \(\lambda_{\max}\).

  8. Bootstrap 95% CI: confidence intervals for chaotic proportion.

  9. Optimal parameters: (order, cutoff) pairs yielding the highest \(\lambda_{\max}\).

  10. Kaiser beta evolution: \(\lambda_{\max}\) as function of \(\beta\).

# Export the summary table as JSON
chaotic-pfc run analysis --json data/analysis_summary.json

# Analyse a specific sweep directory
 chaotic-pfc run analysis --data-dir data/sweeps

Export tables for PFC/article

Generate publication-ready LaTeX tables with bilingual support:

chaotic-pfc run analysis export-tables

Produces 8 .tex files per language under data/analysis_output/tables/{pt,en}/:

  • tab_top_k.tex — Top-3 windows per filter type (chaotic area).

  • tab_top_k_extended.tex — Top-3 with \(\lambda_{\max}\) statistics and 95% CI.

  • tab_full_ranking.tex — Full 124-entry ranking (longtable).

  • tab_sweet_spots.tex — Grid point with highest \(\lambda_{\max}\) per filter.

  • tab_consolidated_top_k.tex — Top-3 with Kaiser collapsed to best \(\beta\).

  • tab_consolidated_extended.tex — Extended stats, Kaiser consolidated.

  • tab_consolidated_full_ranking.tex — Full ranking (28 entries), balanced.

  • tab_kaiser_beta_optimal.tex — Optimal \(\beta\) per filter type.

# Single language
chaotic-pfc run analysis export-tables --lang en

# Custom directories
chaotic-pfc run analysis export-tables \
    --sweep-dir data/sweeps \
    --output-dir tables_for_overleaf

# Reproducible bootstrap seed
chaotic-pfc run analysis export-tables --bootstrap-seed 42

All tables use booktabs rules and inline LaTeX math. Captions, column headers, and filter names are resolved via the i18n system.

Language support

The CLI supports bilingual figure labels via the --lang flag or the CHAOTIC_PFC_LANG environment variable:

# English labels (default)
chaotic-pfc run attractors --lang en

# Portuguese (Brazil) labels
chaotic-pfc run attractors --lang pt

# Set default language via environment variable
export CHAOTIC_PFC_LANG=pt
chaotic-pfc run attractors

The flag is supported by attractors, sensitivity, comm-ideal, comm-fir, comm-order-n, and run all.

Further reading