Versioning

Understand the project version boundaries, legacy Version 1 research, and active Version 2 library surfaces.

To preserve academic reproducibility while supporting clean refactoring and modern API expansion, this repository divides its codebase into two distinct surfaces: Version 1 (Legacy Research) and Version 2 (Active Library).

Version 1 (Legacy Research)

The directory version_1/ represents the historical phase of the repository. It contains long, unrefactored root scripts and generated run outputs used in historical papers.

We restrict updates to Version 1 to:

Reproducing previous publication runs exactly.
Fixing minor bugs that prevent executing a historical result.
Creating minor compatibility wrappers that bridge to a Version 2 implementation.

Do not add new analysis, systems, or examples to Version 1.

Version 2 (Active Library)

The directory version_2/ is the active, packaged library surface. All forward-facing development belongs here:

Examples: New user examples belong in version_2/examples/.
Core Modules: Reusable library functions belong in their respective package folders under hidden_attractors/ (e.g., analysis, workflows, models, native, basins).
CLI Wrappers: New CLI wrappers belong in tools/cli/ and are mapped in pyproject.toml.

Migration Workflow

When a Version 1 script begins to duplicate code or requires library upgrades:

Extract: Move the reusable calculation logic into the packaged hidden_attractors/ namespace.
Expose: Create a clean CLI wrapper under tools/cli/ if a command-line script is needed.
Document: Add a minimal, runnable example under examples/ and register the corresponding mathematical documentation under docs/.
Isolate: Keep new numerical output artifacts separate under outputs/.