API Stability Tiers

Understand the library stability tiers: stable, experimental, internal, and legacy.

To guarantee reliable upgrades and communicate exactly which modules advanced users can safely import, hidden-attractors-fo defines four formal stability tiers.

Every sub-module declares its stability tier in its docstring header using Stability: <tier>, and public classes or functions carry __api_tier__ as an attribute.

The Four Stability Tiers

1. stable

Guarantee: Signatures and return types will not change between minor versions. If a breaking change is required, it will be preceded by a deprecation cycle.

Module	Contents
`hidden_attractors.models`	`ChuaParameters`, vector field evaluation, equilibria
`hidden_attractors.systems`	`ChaoticSystem`, `LureSystem`, registry contracts
`hidden_attractors.basins`	`CLASS_LABELS`, `class_label` classifications
`hidden_attractors.io`	Reader/writer helpers, `load_trajectory_csv`
`hidden_attractors.candidates`	`CandidateRecord`, loading candidate caches

2. experimental

Guarantee: The API is tested and stable, but function signatures may gain new optional keyword arguments. Positional arguments and return types will not change without a changelog entry.

Module	Contents
`hidden_attractors.analysis`	Lyapunov, spectral, Poincaré sections, cloud metrics
`hidden_attractors.seed_generation`	Harmonic-balance describing-function seed scanners
`hidden_attractors.solvers`	Solver contracts, EFORK-3 wrapper interfaces
`hidden_attractors.plotting`	Phase-space, time-series, and bifurcation diagrams
`hidden_attractors.workflows`	Workflow configs, continuation pipeline sweeps

3. internal

Guarantee: None beyond “it functions correctly for the included CLI commands”. Advance developers can import these modules, but signatures are subject to unannounced changes.

Module	Contents
`hidden_attractors.native`	`FractionalChuaBackend` (ctypes compilation wrappers)
`hidden_attractors.parallel`	OpenMP flags, process-pool and multi-processing handlers
`hidden_attractors.paths`	Internal system path constants

4. legacy

Guarantee: Frozen module. No new features will be added. Reusable calculations are gradually migrated into stable modules.

Module	Contents
`hidden_attractors.legacy`	Facade command mapping over `tools/legacy/` scripts

Checking Tiers Programmatically

You can introspect any class or function’s stability tier at runtime:

import hidden_attractors as ha

# Check a class annotation
print(ha.ChuaParameters.__api_tier__)   # 'stable'

# Get tier on any object safely
print(ha.get_tier(ha.ChuaParameters))   # 'stable'

# Assert a tier (raises AssertionError if the tier is lower)
ha.assert_tier(ha.ChuaParameters, ha.STABLE)