Interface Overview

Core concepts and public Python interface of the library.

The hidden-attractors-fo Python library is designed around a modular interface. Rather than monolithic scripts, the functionality is divided into independent modules that can be composed to build custom workflows.

Architecture Map

The library consists of the following core modules:

  • models: Definitions of chaotic systems. Provides the right-hand side (RHS) functions, Jacobians, parameters, and equilibria solvers for built-in systems like Chua and Lorenz.
  • solvers: Numerical integrators. Contains EFORKSolver and ABMSolver for fractional-order systems, and RK4Solver for integer-order systems.
  • seed_generation: Functions to generate initial conditions. Includes classical spherical grids, biased random distributions, and describing-function (Machado branch) seeds.
  • basins: The classification engine. Contains the BasinLabel enum and the logic to categorize a trajectory based on its final state relative to equilibria.
  • analysis: Dynamical analysis tools. Includes trajectory metrics, spectral analysis (FFT), Poincaré sections, Lyapunov exponents, and recurrence quantification.
  • plotting: Matplotlib wrappers for consistent, publication-ready figures (2D/3D trajectories, basin grids, bifurcation diagrams).
  • io: Functions for saving and loading trajectory data and JSON summaries.
  • workflows: High-level orchestrators that combine the above modules into complete analytical pipelines (e.g., unified_chua).

Extensibility

The library features a System Registry. You are not limited to the built-in Chua or Lorenz models. You can define your own chaotic systems (RHS, Jacobian, equilibria) and register them. Once registered, your custom system can immediately use the fractional-order solvers, seed generators, and basin classification logic.

See Custom Systems for a tutorial.

Standard Workflow Pattern

Regardless of whether you use the CLI or Python API, most hidden attractor localization tasks follow this pattern:

  1. Setup: Load parameters and compute equilibria for the target system.
  2. Seed Generation: Create a set of initial conditions (often in a sphere around unstable equilibria).
  3. Integration: Evolve the system forward in time from each seed.
  4. Classification: Analyze the final points against the equilibria coordinates.
  5. Reporting: Aggregate the results, identify HIDDEN_CANDIDATE occurrences, and generate visualizations.

In the next sections, we will explore the Python APIs for each of these steps.