Step 2: Detect Orbits From The Converged Attractors

This notebook reads the attractor table generated in Step 1 and groups the converged attractor samples into orbit labels.

Two parquet files are produced:

• outputs/orbits.parquet with attractor and orbit metadata,

• outputs/sim_orbit.parquet mapping each simulation to one orbit label.

from pathlib import Path

import polars as pl

from kinamax.integration.core import detect_orbits
from kinamax.integration.models import H46_EM_Problem

problem_class = H46_EM_Problem

Load The Batched Simulation Table

This file is the output of Step 1. The attractor-state labels are the original state names with an a suffix because they correspond to attractor samples rather than initial conditions.

example_dir = Path(__file__).resolve().parent if "__file__" in globals() else Path.cwd()
working_dir = example_dir / "outputs"

simulations = pl.read_parquet(working_dir / "simulations.parquet")
state_vec_labels = problem_class.state_vector_labels
attractor_state_vec_labels = [f"{k}a" for k in state_vec_labels]
ode_params_labels = problem_class.params_labels

Cluster Attractors Into Orbits

detect_orbits(...) groups simulations that converge to the same attractor sequence, up to cyclic permutation along the orbit.

attractors, sim_orbit = detect_orbits(
    problem_class=problem_class,
    simulations=simulations,
    ode_params_labels=ode_params_labels,
    attractor_state_vec_labels=attractor_state_vec_labels,
    state_vec_labels=state_vec_labels,
)

Clean The Energy-Like States And Save

Orbit detection focuses on the dynamical variables. The accumulated energy states are therefore reset to zero before storing the orbit representatives.

attractors = attractors.with_columns(
    Ev=pl.lit(0.0),
    Eh=pl.lit(0.0),
)
attractors.write_parquet(working_dir / "orbits.parquet")
sim_orbit.write_parquet(working_dir / "sim_orbit.parquet")

attractors.head()

shape: (5, 19)

x	dotx	v	Ev	Eh	xw	w0	Ad	Q	fd	alpha	C0	R	L	M	detected_subharmonic	attractor_label	orbit_label	target_frequency
f64	f64	f64	f64	f64	f64	f64	f64	f64	f64	f64	f64	f64	f64	f64	i64	i64	i64	f64
-0.000265	0.293995	-3.101933	0.0	0.0	0.0005	121.0	2.5	87.0	35.0	0.068	0.000001	7830.0	0.025	0.0173	1	0	0	35.0
0.000683	0.050324	0.622915	0.0	0.0	0.0005	121.0	2.5	87.0	44.0	0.068	0.000001	7830.0	0.025	0.0173	3	1	1	44.0
0.000031	-0.068758	-0.651765	0.0	0.0	0.0005	121.0	2.5	87.0	44.0	0.068	0.000001	7830.0	0.025	0.0173	3	2	1	44.0
-0.00075	0.044738	0.006936	0.0	0.0	0.0005	121.0	2.5	87.0	44.0	0.068	0.000001	7830.0	0.025	0.0173	3	3	1	44.0
-0.000499	-0.009333	0.024962	0.0	0.0	0.0005	121.0	2.5	87.0	50.0	0.068	0.000001	7830.0	0.025	0.0173	1	4	2	50.0