Metadata-Version: 2.4
Name: hidden-attractors-fo
Version: 1.2.1
Summary: Hidden-attractor localization and independent dynamical-system and time-series characterization.
Author-email: Hidden Attractors Fractional Order project <xerkkun@fyskode.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Xerkkun/Hidden-Attractors-Localization/tree/main/version_2
Project-URL: Documentation, https://github.com/Xerkkun/Hidden-Attractors-Localization/tree/main/version_2/docs
Project-URL: Repository, https://github.com/Xerkkun/Hidden-Attractors-Localization
Project-URL: Issues, https://github.com/Xerkkun/Hidden-Attractors-Localization/issues
Project-URL: Archive, https://doi.org/10.17605/OSF.IO/ZGK74
Keywords: fractional-order systems,hidden attractors,Lyapunov exponents,time series,dynamical systems,Chua,Caputo,EFORK
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: matplotlib>=3.8
Requires-Dist: scipy>=1.12
Requires-Dist: numba>=0.63.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: packaging>=24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: check-manifest>=0.49; extra == "dev"
Provides-Extra: analysis
Requires-Dist: antropy>=0.1.6; extra == "analysis"
Requires-Dist: nolds<0.6.3,>=0.6.2; python_version < "3.12" and extra == "analysis"
Requires-Dist: nolds<0.7,>=0.6.3; python_version >= "3.12" and extra == "analysis"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Provides-Extra: pydstool
Requires-Dist: PyDSTool; extra == "pydstool"
Dynamic: license-file

# hidden-attractors-fo

[![PyPI](https://img.shields.io/pypi/v/hidden-attractors-fo)](https://pypi.org/project/hidden-attractors-fo/)
[![CI](https://github.com/Xerkkun/Hidden-Attractors-Localization/actions/workflows/ci.yml/badge.svg)](https://github.com/Xerkkun/Hidden-Attractors-Localization/actions/workflows/ci.yml)

`hidden-attractors-fo` provides reproducible numerical components for
integer-order and commensurate Caputo fractional-order Lur'e-compatible
systems. The installed surface includes system definitions, integer and
fractional integrators, seed construction, continuation, finite-time
diagnostics, sampled-neighborhood verification, plotting, and a unified CLI.

This public distribution documents implemented software and completed
validation only. It does not ship exploratory runs, internal study notes,
project plans, or unvalidated parameter searches.

## Install

```bash
python -m pip install hidden-attractors-fo
```

```python
import hidden_attractors
```

```bash
hidden-attractors --help
hidden-attractors inspect systems
```

Check for a stable PyPI update without changing the active environment:

```bash
hidden-attractors update --check
```

Use `hidden-attractors update --yes` only when you intend to upgrade the active
Python environment. Prereleases are excluded by default, and a local version
newer than PyPI is never downgraded.

An active Windows `hidden-attractors.exe` does not replace itself. It prints
the exact `sys.executable -m pip ...` command to run from a new prompt after the
launcher exits; `hidden-attractors update --check` remains available normally.

For development from this directory:

```bash
python -m pip install -e ".[dev,analysis,docs]"
```

## Independent dynamical characterization

The library can characterize supplied systems, trajectories, and scalar time
series without running a hidden-attractor search. Public analysis entry points
cover generic trajectory and boundedness metrics, FFT/PSD, Poincare sections,
the 0-1 statistic, bifurcation post-processing, and equation-based Lyapunov
spectra.

The installed surface includes Lyapunov estimation from a uniformly sampled
scalar time series. The structured result combines Rosenstein's largest
exponent, an Eckmann reconstructed spectrum, and a Kaplan--Yorke dimension
with units, estimator parameters, backend provenance, fit diagnostics, memory
guards, and finite-data warnings:

```bash
python -m pip install "hidden-attractors-fo[analysis]"
```

```python
from hidden_attractors import estimate_time_series_lyapunov

result = estimate_time_series_lyapunov(
    signal,
    sample_interval=0.01,
    time_unit="s",
    observable="x",
)
print(result.largest_exponent)
print(result.spectrum)
print(result.kaplan_yorke_dimension)
```

These calculations return finite numerical characteristics; they do not by
themselves certify chaos or hiddenness.

## Validated end-to-end example

From `version_2/`:

```bash
python examples/chua_integer_lure_reference/run_example.py --quick
```

The example executes seed construction, continuation, integration, sampled
equilibrium-neighborhood controls, and structured JSON/CSV output. It is an
integer-order software reference/control. Its finite numerical result is not a
global proof of hiddenness.

Programmatic starting points:

```python
from hidden_attractors import get_system
from hidden_attractors.integrations.selector import integrate
from hidden_attractors.workflows.config_loader import load_config
```

## Scientific Scope

The supported scope and evidence boundaries are summarized in
[`docs/scientific_scope.md`](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/docs/scientific_scope.md).

Describing-function and Nyquist calculations construct seeds. Continuation
transports those seeds. Phase portraits, spectra, Poincare sections, 0-1
statistics, and Lyapunov estimates are finite-time diagnostics. None of these
operations alone establishes hiddenness.

A hiddenness label requires the declared sampled-neighborhood or basin
contract, including all relevant equilibria, recorded solver settings, and
reproducible classifier thresholds. Such a label remains finite numerical
evidence rather than a global mathematical proof.

## Runtime paths

By default, generated outputs are written under `./outputs`. Override this
with `HIDDEN_ATTRACTORS_OUTPUT_DIR`. Runtime caches use the operating system
user-cache location or `HIDDEN_ATTRACTORS_CACHE_DIR`. The library does not
write into its installed `site-packages` directory.

## Validation and distribution

The wheel contains the importable library and its supported configuration
resources. The source distribution additionally contains the manual set and
the validated integer example. Full validation manifests and reproducibility
records live in the tagged repository and the archived DOI snapshot, not in
the installed package.

Maintainer checks:

```bash
python -m pytest -q -m "hygiene or release_readiness"
python -m build
python -m twine check dist/*
python tools/release/validate_wheel_install.py
```

The canonical freeze record is `validation/freeze_audit/`.

## Documentation

- [User Manual](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/USER_MANUAL.md)
- [Installation](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/docs/installation.md)
- [Quick Start](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/docs/quick_start.md)
- [API Stability](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/docs/api_stability.md)
- [Scientific Scope](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/docs/scientific_scope.md)
- [Citation](https://github.com/Xerkkun/Hidden-Attractors-Localization/blob/main/version_2/docs/citation.md)

## Citation and license

Archived DOI: `10.17605/OSF.IO/ZGK74`.

The software is licensed under the MIT License.
