Refined Basin

Revisit unknown basin cells and classify them by comparing trajectory geometries against target references.

The Refined Basin workflow optimizes the classification of attraction basins. In large initial condition sweeps, many coordinates are classified as inconclusive or unknown due to short simulation times or complex transient states. This workflow systematically sweeps those unknown grid cells, runs longer integrations, and compares their geometric properties (bounding boxes, centroids) against known target attractor metrics.

How it works

1. Scan Existing Classification: Load a completed coarse basin grid from outputs/ or a database.
2. Filter Inconclusive Cells: Identify all coordinate cells marked as unknown or inconclusive.
3. Re-integrate: Run high-precision simulations on those specific coordinates with longer integration times ($t_{\rm final}$) and fine-grained steps ($h$).
4. Geometric Comparison: Calculate the Euclidean distance of the resulting orbit’s centroid and bounding box relative to target attractor metrics.
5. Classify: Re-label cells as self-excited, hidden-candidate, divergent, or stable-equilibrium based on the geometric convergence.

Usage via CLI

Run the refined basin script from the command line:

# Get help
hidden-attractors-refined-basin --help

# Refine an existing coarse basin directory
python tools/cli/refine_project_basin_classification.py --dir outputs/basin_coarse_01/ --t-final 100.0 --workers 4

Python API Usage

from hidden_attractors.workflows.refined_basin import RefinedBasinConfig, run_refined_basin

config = RefinedBasinConfig(
    grid_dir="outputs/basin_coarse_01",
    t_final=120.0,
    geometry_tolerance=0.05,
    workers=4
)

# Run classification refinement
run_refined_basin(config)