Metadata-Version: 2.4
Name: oscillatools
Version: 0.1.0
Summary: Differentiable, control-oriented toolkit for coupled-phase-oscillator (Kuramoto) dynamics
Project-URL: Homepage, https://github.com/anulum/scpn-quantum-control
Project-URL: Repository, https://github.com/anulum/scpn-quantum-control
Project-URL: Issues, https://github.com/anulum/scpn-quantum-control/issues
Project-URL: Changelog, https://github.com/anulum/scpn-quantum-control/blob/main/oscillatools/CHANGELOG.md
Project-URL: Documentation, https://anulum.github.io/scpn-quantum-control/oscillatools/
Author-email: Miroslav Šotek <protoscience@anulum.li>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE.md
Keywords: control,coupled oscillators,differentiable simulation,dynamical systems,kuramoto,phase dynamics,synchronisation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: scipy<2.0,>=1.10
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.0; extra == 'dev'
Requires-Dist: hypothesis<7.0,>=6.155.2; extra == 'dev'
Requires-Dist: mypy<3.0,>=1.0; extra == 'dev'
Requires-Dist: networkx<4.0,>=3.0; extra == 'dev'
Requires-Dist: pytest-cov<8.0,>=4.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=7.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.4; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10.0,>=9.0; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]<2.0,>=0.24; extra == 'docs'
Requires-Dist: pymdown-extensions<12.0,>=10.0; extra == 'docs'
Provides-Extra: jax
Requires-Dist: jax>=0.4.30; extra == 'jax'
Provides-Extra: julia
Requires-Dist: juliacall<2,>=0.9; extra == 'julia'
Provides-Extra: rust
Requires-Dist: scpn-quantum-engine>=0.2.0; extra == 'rust'
Provides-Extra: sklearn
Requires-Dist: scikit-learn<2.0,>=1.3; extra == 'sklearn'
Provides-Extra: torch
Requires-Dist: torch<3.0,>=2.2; extra == 'torch'
Provides-Extra: viz
Requires-Dist: matplotlib<4.0,>=3.5; extra == 'viz'
Description-Content-Type: text/markdown

<!--
SPDX-License-Identifier: AGPL-3.0-or-later
Commercial license available
© Concepts 1996–2026 Miroslav Šotek. All rights reserved.
© Code 2020–2026 Miroslav Šotek. All rights reserved.
ORCID: 0009-0009-3560-0851
Contact: www.anulum.li | protoscience@anulum.li
-->

# oscillatools

A differentiable, control-oriented toolkit for coupled-phase-oscillator (Kuramoto)
dynamics. It provides the model family, integrators, exact mean-field reductions,
stability and continuation analysis, differentiation, and control primitives as a
light, standalone distribution whose only hard dependencies are **NumPy** and
**SciPy**. Every acceleration or interoperability tier (a Rust engine, Julia, JAX,
PyTorch, matplotlib, scikit-learn) is an optional extra; the pure-Python NumPy
floor always runs.

`oscillatools` is extracted from
[`scpn-quantum-control`](https://github.com/anulum/scpn-quantum-control), where the
toolkit originated, so that the coupled-oscillator surface can be installed without
that project's quantum-provider dependency stack.

## Installation

```bash
pip install oscillatools                 # NumPy + SciPy floor
pip install "oscillatools[rust]"         # optional Rust acceleration engine
pip install "oscillatools[jax]"          # JAX autodiff backend
pip install "oscillatools[torch]"        # PyTorch neural-operator surrogate
pip install "oscillatools[sklearn]"      # scikit-learn estimator interface
pip install "oscillatools[viz]"          # matplotlib renderers
pip install "oscillatools[julia]"        # Julia acceleration tier
```

## Capabilities

- **Model family** — classical, higher-order (hyperedge/simplicial force),
  time-delayed, noisy, inertial (second-order), adaptive-coupling, Sakaguchi,
  Winfree, Stuart–Landau, networked/multiplex, and next-generation QIF neural-mass
  Kuramoto dynamics.
- **Integrators** — explicit Euler, RK4, DOPRI adaptive step, symplectic (inertial),
  method-of-steps (delayed), and Euler–Maruyama (stochastic).
- **Exact reductions** — Ott–Antonsen and Watanabe–Strogatz manifolds, and the
  noisy/finite-width mean-field order-parameter theory.
- **Analysis** — order parameters and Daido harmonics, linear-stability spectra,
  Lyapunov exponents, pseudo-arclength continuation, saddle-node/fold location, and
  basin-stability estimation.
- **Differentiation** — a hand-written reverse-mode adjoint and forward sensitivity
  over the integrators (NumPy and, optionally, JAX), for gradient-based design.
- **Control** — optimal coupling design, pinning control, coordinated reset,
  SDRE/receding-horizon control, and system identification.
- **Interoperability** — a scikit-learn-style estimator interface and a
  NumPy-array-first API.

A generated capability handbook and manifest enumerate the full public surface.

## Optional acceleration and interoperability

The Rust acceleration engine ships as the separate
[`scpn-quantum-engine`](https://pypi.org/project/scpn-quantum-engine/) wheel and is
used automatically when installed (`[rust]` extra). Without it, the dispatchers fall
through to the NumPy implementation. Measured tier selection is reported per call.

## Licensing

`oscillatools` is dual-licensed under AGPL-3.0-or-later with a commercial license
available. See [`NOTICE.md`](NOTICE.md) and
[`LICENSES/AGPL-3.0-or-later.txt`](LICENSES/AGPL-3.0-or-later.txt). For commercial
licensing: protoscience@anulum.li.

## Citation

If you use `oscillatools`, please cite it using the metadata in
[`CITATION.cff`](CITATION.cff).
