Attractor Topology Toolkit (ATT)

Joint-vs-marginal persistent homology on Takens embeddings for coupling detection in dynamical systems.

pip install att-toolkit

---

ATT extracts, compares, and visualizes the topological structure of chaotic attractors from multivariate time series. Its core construction -- joint-vs-marginal persistent homology on Takens-embedded coupled systems -- isolates emergent coupling topology by comparing persistence diagrams of joint delay embeddings against their marginal counterparts. The library provides clean infrastructure for attractor reconstruction, persistent homology, cross-system binding detection, surrogate-tested statistics, and head-to-head benchmarks against transfer entropy, phase-amplitude coupling, and cross-recurrence quantification.

Domain of applicability: The binding score is selectively sensitive to coupling between systems with different intrinsic timescales (e.g., Rossler-Lorenz). It has zero power for same-timescale coupling (e.g., Lorenz-Lorenz). Always use z-score calibration against surrogates rather than raw scores. Validated on EEG (binocular rivalry), ECG (MIT-BIH arrhythmia), and LLM hidden states (Qwen2.5-1.5B, Phi-2, Pythia-1.4B, StableLM). See the preprint, Experiments 9-14.

Quick Start

Topological fingerprinting of a Lorenz attractor

from att.config import set_seed
from att.synthetic import lorenz_system
from att.embedding import TakensEmbedder
from att.topology import PersistenceAnalyzer

set_seed(42)

# Generate a Lorenz attractor
ts = lorenz_system(n_steps=10000, dt=0.01)

# Reconstruct phase space via Takens embedding
embedder = TakensEmbedder(delay="auto", dimension="auto")
cloud = embedder.fit_transform(ts[:, 0])

# Compute persistent homology
analyzer = PersistenceAnalyzer(max_dim=2)
diagrams = analyzer.fit_transform(cloud, subsample=1000)
analyzer.plot()

Binding detection in coupled systems

from att.config import set_seed
from att.synthetic import coupled_lorenz
from att.binding import BindingDetector

set_seed(42)

# Generate coupled Lorenz systems
ts_x, ts_y = coupled_lorenz(coupling=0.5)

# Detect emergent topology in the joint embedding
detector = BindingDetector(max_dim=1, method="persistence_image")
detector.fit(ts_x[:, 0], ts_y[:, 0])

print(f"Binding score: {detector.binding_score():.4f}")
print(f"Embedding quality: {detector.embedding_quality()}")
print(f"Significant: {detector.test_significance(n_surrogates=100)}")

CLI

# Run a coupling sweep from a YAML config
att benchmark run \
  --config configs/coupled_lorenz_sweep.yaml \
  --output results/sweep.csv \
  --plot results/sweep.png

Installation

pip install att-toolkit           # core
pip install att-toolkit[eeg]      # + MNE-Python for EEG/MEG
pip install att-toolkit[gudhi]    # + GUDHI backend (alpha/witness complexes)
pip install att-toolkit[zigzag]  # + Dionysus for zigzag persistence
pip install att-toolkit[all]      # everything

From source:

git clone https://github.com/musicofhel/att-docs.git
cd att-docs
pip install -e ".[dev]"

API Overview

Module	Description
att.config	Deterministic seeding, YAML experiment configs
att.synthetic	Lorenz, Rossler, Aizawa, Kuramoto, coupled oscillators, layered networks (all seeded)
att.embedding	Takens delay embedding, AMI delay estimation, FNN dimension estimation, SVD validation
att.topology	Persistent homology via Ripser/GUDHI, persistence images/landscapes
att.binding	Joint-vs-marginal persistence image subtraction with significance testing
att.transitions	Sliding-window topology with CUSUM/PELT changepoint detection
att.surrogates	Phase-randomized and time-shuffled surrogates
att.benchmarks	Transfer entropy, PAC, CRQA comparison framework
att.neuro	EEG/MEG loaders and preprocessing (requires mne)
att.cone	Directed cross-layer projection geometry (ConeDetector, availability profiles)
att.viz	Persistence diagrams, barcodes, Betti curves, 3D attractors, binding images
att.cli	Command-line interface for benchmark sweeps
att.llm	LLM hidden-state topology: layer-wise PH, CROCKER matrices, zigzag persistence, intrinsic dimension, attention-hidden binding

What Makes ATT Different

ATT sits at the intersection of several existing research threads, none of which fully cover its construction:

Prior Work	What It Does	What ATT Adds
CCM (Sugihara et al.)	Joint delay embeddings for causal inference	Persistent homology on the joint manifold
R-Cross-Barcode / RTD-Lite	Cross-barcodes for graph comparison	Extension to VR complexes on Takens point clouds
Xi et al. (TE + directed PH)	PH on transfer entropy networks	PH on state-space embeddings, not derived networks
Giusti, Curto et al.	PH on neural correlation matrices	PH on time-evolving attractor dynamics
Sliding-window PH (Perea, Harer)	Topological time series analysis	Applied to bistable perception EEG (novel niche)

Experimental Results

ATT has been validated across synthetic, neural, cardiac, and LLM domains via 14 experiments (9 in the original preprint + 3 discovered by automated multi-agent search using CORAL + 2 extending ATT to transformer hidden states). CORAL is the experiment runner; ATT is the subject under test -- each CORAL agent writes scripts that call ATT's API (BindingDetector, TransitionDetector, PersistenceAnalyzer, TakensEmbedder) and independently discovers strategies that validate ATT's theoretical claims:

Experiment	Domain	Key Result	Preprint Section
Künneth confirmation	Reservoir computing	Inverted binding detects synchronization drift (F1=0.985)	Experiment 11
Perceptual switch detection	Binocular rivalry EEG	Adaptive TDA + alpha power achieves F1=1.0	Experiment 12
Cardiac arrhythmia	MIT-BIH ECG	Mixed TDA + signal features: AUROC=0.8014	Experiment 10
Vineyard tracking rescue	Reservoir degradation	Greedy top-K + SavGol: F1=1.0	coral_archive/
LLM hidden-state topology	Qwen2.5-1.5B MATH-500	Terminal-layer z=8.12; H1 non-monotonic entropy universal (4 models)	Experiment 13
Topo-confidence validation	Qwen2.5-1.5B MATH-500	Holdout AUROC=0.948 [0.898, 0.986]; orthogonal to entropy (r=0.062)	Experiment 14

LLM extension: Persistent homology on transformer hidden states predicts mathematical reasoning correctness with holdout AUROC=0.948. This signal is orthogonal to output entropy (r=0.062) -- topology captures whether the model "knows what it's doing" from a single forward pass, not output uncertainty. Standalone package: topo-confidence.

Key finding (Künneth confirmation): When coupled systems synchronize, the binding score drops (not rises) because the joint attractor collapses toward a product of marginals. This inverted behavior -- the Künneth cross-term prediction -- enables alarm-on-decrease detection of spectral radius drift. First direct experimental test of this theoretical interpretation.

Recall gap closed: The original preprint reported 94.1% precision but only 40.6% recall on binocular rivalry perceptual switches. An adaptive per-subject strategy (alpha power for dense-switching subjects, windowed TDA for sparse cases) achieves F1=1.0.

Full CORAL experiment artifacts (108 scored attempts, 53 agent notes): coral_archive/

Documentation

Full API reference and quickstart tutorial: musicofhel.github.io/att-docs

Blog post: Your Brain Is a Matrix of Chaos Attractors

Citation

If you use ATT in your research, please cite:

@software{att2026,
  title   = {Attractor Topology Toolkit: Joint-vs-Marginal Persistent
             Homology on Takens Embeddings},
  author  = {{ATT Contributors}},
  year    = {2026},
  url     = {https://github.com/musicofhel/att-docs},
}

Preprint (12 experiments spanning synthetic systems, binocular rivalry EEG, cardiac ECG, and reservoir computing): paper/preprint.pdf. Post-publication experiments 13-14 (LLM hidden-state topology): see experiments documentation.

License

MIT. See LICENSE for details.