Adapting New Systems

Register custom mathematical models in the ChaoticSystem registry and define reproducible numerical experiments.

The hidden-attractors-fo library is designed to be fully generic. While Chua and Danca are the primary verified baseline systems, you can register any custom integer-order or fractional-order chaotic system.

Adding a new system involves two explicit layers:

  1. ChaoticSystem: Defines the mathematical model (vector field, equilibria, Jacobian).
  2. WorkflowInputSpec: Defines the numerical experiment (solvers, classifiers, sweeps, grid scales).

Registering a Custom System

Built-in Systems

For built-in models, the definitions are declared natively in the package source:

hidden_attractors/systems/builtins.py

External / User Systems

To register a new system from a custom script, use the public package capabilities:

from hidden_attractors.systems import ChaoticSystem, register_system

register_system(
    ChaoticSystem(
        name="custom-system-id",
        dimension=3,
        rhs=my_vector_field_func,
        equilibria=my_equilibria_func,
        parameters={"parameter_1": 1.0},
        description="Detailed description of my custom chaotic model."
    ),
    replace=True
)

Required Fields for Verification

Every registered system should ideally provide:

  • name: Stable, lowercase identifier (e.g. fractional-rossler).
  • dimension: State dimension.
  • rhs(state, parameters): Evaluates the vector field f(x,p)f(x, p).
  • parameters: Default numerical parameter map.
  • equilibria(parameters): Dict of named equilibria locations.
  • jacobian(state, parameters): Analytic regional Jacobians (crucial for Matignon stability analysis).
  • lure: Manual Lur’e decomposition split (required only if describing-function Nyquist sweeps are requested).

Workflow Input Spec

To run automated CLI scripts or workflows on your custom system, declare your experiment configurations in a WorkflowInputSpec file (or build it dynamically in Python).

The spec records:

  • IntegratorSpec: Solver choice (efork or abm), order q, step size h, transient burn-in, and Caputo memory length Lm.
  • DestinationClassifierSpec: Pixel thresholds to classify coordinate points as divergent, stable, target attractor, or unknown.
  • SphereControlSpec: Concentric radii and coordinates for sampling neighborhood hiddenness grids.
  • StrictRefinementSpec: Tolerance parameters for cross-solver trajectory comparisons.

Checking System Requirements

You can inspect whether a system meets all requirements for a specific workflow from the command line:

# General help
hidden-attractors-workflow-requirements --help

# Check if a custom system meets sphere control requirements
hidden-attractors-workflow-requirements --workflow sphere-controls --system custom-system-id