Trajectory Metrics

Geometric summaries and robustness calculations.

When an integration completes without diverging, it generates a massive point cloud in phase space (often tens of thousands of rows). The trajectory_metrics module reduces this massive array into a compact geometric summary.

Cloud Summary

The cloud_summary() function computes three key metrics:

  1. Bounding Box: The minimum and maximum extent of the trajectory along each axis.
  2. Centroid: The mean position of the trajectory points.
  3. Spread: The standard deviation along each axis, representing the “thickness” or “volume” of the attractor.
from hidden_attractors.analysis import cloud_summary
import numpy as np

# Simulate a trajectory (e.g., 10000 points in 3D)
x = np.random.randn(10000, 3) 

summary = cloud_summary(x)

print("Bounding Box (X):", summary["bounding_box"][0])
print("Centroid:", summary["centroid"])
print("Spread:", summary["spread"])

These metrics are essential for distinguishing between point attractors (spread ≈0\approx 0), limit cycles (spread >0> 0 but 1D structure), and strange attractors (spread >0> 0 in multiple dimensions).

Robustness Cases

A hidden attractor is defined by having a basin of attraction that does not intersect with the neighborhoods of unstable equilibria. But what happens if the attractor physically “touches” or gets extremely close to an equilibrium?

The robustness_cases() function calculates the minimum Euclidean distance between the trajectory cloud and a given set of equilibria.

from hidden_attractors.analysis import robustness_cases

# Assuming 'eq' is a dictionary of equilibria coordinates
cases = robustness_cases(x, eq)

for label, distance in cases:
    print(f"Distance to {label}: {distance:.4f}")

Interpretation

  • Distance > 0.5: The attractor is robustly separated from the equilibrium. Strong hidden candidate.
  • Distance ≈\approx 0.01: The attractor grazes the equilibrium. This is a “fragile” hidden attractor, or potentially a self-excited attractor with a very narrow basin connection that wasn’t caught by the seed grid. Requires high-accuracy ABM integration to verify.