First Simulation

A step-by-step tutorial running the unified Chua workflow from scratch.

In this tutorial, we will use the Unified Chua Workflow to automatically locate and classify attractors in the fractional-order Chua system. This workflow combines seed generation, fractional-order integration, and basin classification into a single pipeline.

1. The Goal

We want to analyze the non-smooth Chua circuit, whose characteristic is linear by pieces, at a fractional order of $q = 0.98$ . Our objective is to find whether the system exhibits a self-excited attractor or a hidden attractor.

2. Using the CLI

The easiest way to run the workflow is via the command-line interface. Open your terminal and run:

hidden-attractors-unified-chua \
  --q 0.98 \
  --dt 0.01 \
  --t-transient 100 \
  --t-sim 100 \
  --memory 500 \
  --n-classical 50 \
  --output ./chua_results

Understanding the parameters:

--q 0.98: Sets the fractional order of the derivative.
--dt 0.01: Integration time step.
--t-transient 100: Time to integrate before we start recording the trajectory (allows the system to settle).
--t-sim 100: Time to record the actual trajectory.
--memory 500: The memory window length for the Caputo derivative (used by EFORK or ABM).
--n-classical 50: Generate 50 initial conditions randomly distributed around the equilibria.
--output ./chua_results: Directory where logs and JSON summaries will be saved.

3. Running via Python API

If you prefer to integrate this into your own scripts or Jupyter notebooks, you can use the Python API directly.

Create a file named first_simulation.py:

import os
from hidden_attractors.workflows.unified_chua import main as unified_chua_main

output_dir = "./chua_results"
os.makedirs(output_dir, exist_ok=True)

# Define the configuration arguments as a list of strings
args = [
    "--q", "0.98",
    "--dt", "0.01",
    "--t-transient", "100",
    "--t-sim", "100",
    "--memory", "500",
    "--n-classical", "50",
    "--output", output_dir
]

# Run the workflow
print("Starting unified Chua workflow...")
unified_chua_main(args)
print(f"Done! Results saved to {output_dir}")

Run the script:

python first_simulation.py

4. What happens under the hood?

When you run this workflow, the library performs several automated steps:

Parameter Setup: Loads the default Chua non-smooth parameters.
Equilibria Calculation: Finds the equilibria ( $O_+$ , $O_-$ , $O_0$ ).
Seed Generation: Generates 50 classical initial conditions near the equilibria.
Integration: Uses the EFORK solver (compiled C backend if available, otherwise Python fallback) to integrate the system for each seed.
Classification: For each trajectory, analyzes the final point and the trajectory cloud to determine if it converged to an equilibrium, diverged, or formed an attractor. If an attractor is formed, it checks the distance to all equilibria to classify it as Self-Excited or a Hidden Candidate.
Reporting: Saves the summary to a JSON file in the output directory.

5. Reviewing the Output

After the simulation completes, check the ./chua_results directory. You will find a JSON file containing the full summary of the run.

In the next section, we will look at how to interpret this JSON file and understand the basin classification results.

Quick Start

Understanding Results