chaotic_pfc.plotting.figures

figures.py

Publication-quality SVG figures with LaTeX-style labels.

Typography is configured via setup_rc(), which auto-detects whether a full LaTeX installation is available on the system:

  • If latex is found on $PATH, real LaTeX rendering is used (usetex=True, Computer Modern Roman).

  • Otherwise, mathtext with STIX fonts is used as a fallback that visually matches LaTeX output without any external dependency.

The detection can be overridden via the environment variable CHAOTIC_PFC_FORCE_LATEX (0 forces fallback, 1 forces real LaTeX). This is useful in CI environments or for debugging.

All text is converted to vector paths in SVG output so that figures render identically on any system.

Functions

latex_available()

Return True if LaTeX is available for figure rendering.

plot_attractor(X, Y[, title, xlabel, ...])

Plot a phase-space portrait of a 2-D trajectory.

plot_comm_grid(n, m, s, r, m_hat, omega, ...)

4×2 grid: left = time domain, right = PSD.

plot_sensitivity(n, X1, X2[, save_path, lang])

Overlay two Hénon trajectories to illustrate sensitivity to ICs.

setup_rc()

Configure matplotlib for publication-quality LaTeX-style SVG output.

Classes

PlotGridOptions([time_window, suptitle, ...])

Optional styling parameters for plot_comm_grid().
chaotic_pfc.plotting.figures.latex_available()[source]

Return True if LaTeX is available for figure rendering.

The return value is determined at import time by checking $PATH for the latex executable. Set the environment variable CHAOTIC_PFC_FORCE_LATEX=0 or 1 to override.

Return type:

bool

chaotic_pfc.plotting.figures.setup_rc()[source]

Configure matplotlib for publication-quality LaTeX-style SVG output.

Auto-detects whether a full LaTeX installation is available:

  • If latex is found on $PATH, uses real LaTeX rendering (usetex=True, Computer Modern Roman, amsmath + amssymb preamble).

  • Otherwise, falls back to mathtext with STIX fonts, which visually match LaTeX without external dependencies.

The detection can be overridden via CHAOTIC_PFC_FORCE_LATEX=0 or =1.

All text is converted to vector paths in SVG output.

chaotic_pfc.plotting.figures.plot_attractor(X, Y, title='', xlabel='$x_1[n]$', ylabel='$x_2[n]$', save_path=None)[source]

Plot a phase-space portrait of a 2-D trajectory.

Parameters:

  • X (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – State-variable trajectories, same length.

  • Y (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – State-variable trajectories, same length.

  • title (str) – Optional figure title. If empty, no title is drawn.

  • xlabel (str) – Axis labels. Defaults use LaTeX-style math for x_1 and x_2.

  • ylabel (str) – Axis labels. Defaults use LaTeX-style math for x_1 and x_2.

  • save_path (str | None) – If given, the figure is written to this path. The extension selects the format (.svg, .png, etc.).

Returns:

The matplotlib Figure object. Returned so callers can inspect or further annotate it before showing / closing.

Return type:

Figure

chaotic_pfc.plotting.figures.plot_sensitivity(n, X1, X2, save_path=None, lang='pt')[source]

Overlay two Hénon trajectories to illustrate sensitivity to ICs.

Plots two state trajectories that start from infinitesimally different initial conditions, making visually obvious how they diverge exponentially — the classic demonstration of chaos.

Parameters:

  • n (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Sample index axis, shape (N,).

  • X1 (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Two state trajectories evaluated on n. Typically differing only by x0_2 = x0_1 + 1e-4.

  • X2 (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Two state trajectories evaluated on n. Typically differing only by x0_2 = x0_1 + 1e-4.

  • save_path (str | None) – If given, the figure is written to this path.

  • lang (str) – Language code for the figure title ("pt" or "en").

Returns:

The matplotlib Figure object.

Return type:

Figure

class chaotic_pfc.plotting.figures.PlotGridOptions(time_window=<factory>, suptitle='', y_lim_msg=(-1.5, 1.5), y_lim_sig=(-2.5, 2.5), y_lim_mhat=None, h_channel=None, save_path=None)[source]

Bases: object

Optional styling parameters for plot_comm_grid().

All fields have sensible defaults; only override what you need.

Parameters:
time_window: slice
suptitle: str = ''
y_lim_msg: tuple[float, float] = (-1.5, 1.5)
y_lim_sig: tuple[float, float] = (-2.5, 2.5)
y_lim_mhat: tuple[float, float] | None = None
h_channel: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None
save_path: str | None = None
chaotic_pfc.plotting.figures.plot_comm_grid(n, m, s, r, m_hat, omega, psd_m, psd_s, psd_r, psd_mhat, *, opts=None, time_window=slice(0, 300, None), suptitle='', y_lim_msg=<object object>, y_lim_sig=<object object>, y_lim_mhat=<object object>, h_channel=None, save_path=None, lang='pt')[source]

4×2 grid: left = time domain, right = PSD. Rows: m[n], s[n], r[n], m̂[n]. If h_channel is provided, its frequency response is overlaid on PSD_s.

The opts dataclass overrides individual keyword arguments when both are provided. See PlotGridOptions for grouped defaults.

Parameters:

  • n (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Sample indices, shape (N,).

  • m (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Original message, shape (N,).

  • s (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Transmitted (modulated) signal, shape (N,).

  • r (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Received signal after the channel, shape (N,).

  • m_hat (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Recovered message estimate, shape (N,).

  • omega (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – Normalised frequency axis from psd_normalised().

  • psd_m (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – PSD of each signal (same length as omega).

  • psd_s (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – PSD of each signal (same length as omega).

  • psd_r (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – PSD of each signal (same length as omega).

  • psd_mhat (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – PSD of each signal (same length as omega).

  • opts (PlotGridOptions | None) – PlotGridOptions dataclass with default axis limits, time window, and title. Individual keyword arguments override the corresponding opts fields.

  • time_window (slice) – Python slice selecting which sample range to plot in the time-domain panels.

  • suptitle (str) – Figure-level title. Overrides opts.suptitle unless empty.

  • y_lim_msg (tuple[float, float]) – Y-axis limits for the time-domain panels. y_lim_mhat defaults to y_lim_msg unless explicitly set.

  • y_lim_sig (tuple[float, float]) – Y-axis limits for the time-domain panels. y_lim_mhat defaults to y_lim_msg unless explicitly set.

  • y_lim_mhat (tuple[float, float] | None) – Y-axis limits for the time-domain panels. y_lim_mhat defaults to y_lim_msg unless explicitly set.

  • h_channel (ndarray[tuple[Any, ...], dtype[_ScalarT]] | None) – FIR coefficients for overlaying the channel frequency response on PSD_s.

  • save_path (str | None) – If provided, the figure is saved to this path via _save().

  • lang (str) – Language for axis labels ("pt" or "en").

Return type:

matplotlib.figure.Figure