chaotic-pfc documentation

A scientific computing library implementing a complete chaos-based digital communication system using the Hénon map: providing physical-layer security through chaotic carriers.

The project models an end-to-end pipeline: message generation, chaotic modulation at the transmitter, propagation through ideal or FIR band-limited channels, and demodulation through chaos synchronisation at the receiver: backed by a rigorous Lyapunov-exponent analysis of the underlying nonlinear dynamics. The library also includes a full numerical study that classifies regions of the (filter order, cutoff frequency) parameter space as chaotic, periodic, or divergent.

Status

Undergraduate final project (PFC) in Engineering at FESA (Faculdade Engenheiro Salvador Arena), Brazil. Developed as part of the scientific article “Sistemas de comunicação baseados em mapas de Hénon utilizando filtro FIR” (2026).

Features

  • Hénon map variants: 2-D standard Hénon, generalised Hénon, filtered Hénon, and N-th order filtered Hénon maps as chaotic oscillators (chaotic_pfc.dynamics.maps).

  • Chaos-based communication: transmitter/receiver pair via Pecora-Carroll synchronisation (chaotic_pfc.comms.transmitter, chaotic_pfc.comms.receiver).

  • Channel models: ideal pass-through, FIR band-limited channels, AWGN, multipath propagation, and impulsive noise (chaotic_pfc.comms.channel).

  • Lyapunov exponent computation: single-IC and N-IC ensemble protocol using tangent-map method with Modified Gram-Schmidt re-orthonormalisation (chaotic_pfc.dynamics.lyapunov).

  • High-performance parameter sweep: deterministic parallel Lyapunov sweep across the (filter order, cutoff frequency) grid via Numba JIT compilation (chaotic_pfc.analysis.sweep).

  • Modulation: Pecora-Carroll chaos-based modulation via transmitter/receiver synchronisation (chaotic_pfc.comms.transmitter, chaotic_pfc.comms.receiver).

  • Statistical analysis suite: summary tables, filter-type comparison, transition boundaries, Spearman correlation, bootstrap confidence intervals, and optimal-parameter identification (chaotic_pfc.analysis.stats).

  • Publication-quality figures: SVG outputs with STIX fonts, attractor portraits, SDIC visualisation, 4×2 communication grids, and 3-D Plotly volumes (chaotic_pfc.plotting.figures).

  • Unified CLI: chaotic-pfc run <experiment> backed by importable submodules under chaotic_pfc.cli.

Installation

Requires Python 3.11+.

pip install -e ".[dev]"        # development tools (pytest, ruff, mypy)
pip install -e ".[dev,fast]"    # development + Numba JIT acceleration
pip install -e ".[viz3d]"       # 3-D visualisation with Plotly

The package imports and runs without Numba installed: kernels fall back to pure Python via chaotic_pfc._compat. Install the [fast] extra for 20–50× speedup on the parameter sweep.

Quick start

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

The --quick-sweep flag runs the full pipeline with a reduced Lyapunov grid: seconds of compute time rather than hours: sufficient to smoke-test every component. Remove it to execute the full-resolution sweep.

Key experiments

Attractors

Phase-space portraits of three Hénon variants: chaotic-pfc run attractors

Sensitivity (SDIC)

Exponential divergence visualisation: chaotic-pfc run sensitivity

Communication

Full pipeline over ideal/FIR channels: chaotic-pfc run comm-ideal

Lyapunov Spectra

Single-IC and ensemble protocols: chaotic-pfc run lyapunov

Parameter Sweep

High-resolution (order × cutoff) grid: chaotic-pfc run sweep compute