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.

DCSK comparison

chaotic-pfc run dcsk

Generates a BER-vs-SNR plot comparing three modulation schemes over an FIR-filtered Hénon map with AWGN:

  • Pecora-Carroll synchronisation (coherent)

  • Classical DCSK (non-coherent, half bit rate)

  • EF-DCSK (non-coherent, full bit rate)

Options:

chaotic-pfc run dcsk --snr-min -10 --snr-max 20 --snr-step 2
chaotic-pfc run dcsk --save --no-display
chaotic-pfc run dcsk --lang pt  # Portuguese labels

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

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, dcsk, and run all.

Further reading