Basin Grids

Visualize attraction basins of chaotic systems in 2D coordinate slices.

Attraction basins reveal which initial conditions (x0,y0,z0)(x_0, y_0, z_0) converge to a chaotic attractor, stable equilibria, or diverge to infinity. The library includes built-in APIs to render detailed 2D basin grids from your sweeps.

Conceptual Overview

In a typical 2D slice (e.g., the xyxy-plane at z=0z = 0):

  • Each pixel represents a simulated initial condition coordinate.
  • Pixels are color-coded based on the final classified trajectory status:
    • 🔴 Divergent (solutions escaping bounds)
    • 🟢 Self-Excited Attractor (solutions entering stable limit cycles or standard attractors)
    • 🔵 Hidden Attractor Candidate (solutions converging to a verified localized attractor isolated from equilibria)
    • ⚫ Stable Equilibrium (solutions collapsing into local stable points)
    • 🟡 Inconclusive/Unknown (unresolved grid cells requiring refinement)

Plotting via the API

You can generate basin plots using the public plotting module:

from hidden_attractors.plotting import plot_basin_grid
from hidden_attractors.io import load_basin_data

# 1. Load your completed basin grid coordinates and results
grid_data = load_basin_data("outputs/basin_sweeps_chua/basin_grid.json")

# 2. Render and save the 2D slice
plot_basin_grid(
    grid_data,
    output_path="outputs/basin_sweeps_chua/basin_xy_slice.png",
    plane="xy",
    z_slice=0.0,
    title="Non-smooth Chua Basin of Attraction"
)

Refined Basin Grids

When running refined classifications, you can generate overlay maps showing both the coarse grid and high-accuracy refined cells:

from hidden_attractors.plotting import plot_refined_basin_overlay

plot_refined_basin_overlay(
    coarse_grid_data,
    refined_grid_data,
    output_path="outputs/basin_sweeps_chua/basin_refined_overlay.png"
)