Metadata-Version: 2.4
Name: scpn-phase-orchestrator
Version: 0.6.5
Summary: Domain-agnostic coherence control compiler built on SCPN's Kuramoto/UPDE framework
Author-email: Miroslav Sotek <protoscience@anulum.li>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/anulum/scpn-phase-orchestrator
Project-URL: Repository, https://github.com/anulum/scpn-phase-orchestrator
Project-URL: Issues, https://github.com/anulum/scpn-phase-orchestrator/issues
Project-URL: Documentation, https://anulum.github.io/scpn-phase-orchestrator/
Project-URL: Changelog, https://github.com/anulum/scpn-phase-orchestrator/blob/main/CHANGELOG.md
Project-URL: Discussions, https://github.com/anulum/scpn-phase-orchestrator/discussions
Keywords: kuramoto,phase-dynamics,coherence-control,UPDE,synchrony
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: scipy<2.0,>=1.11
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: click<9.0,>=8.1
Requires-Dist: protobuf<8.0,>=6.33.5
Requires-Dist: urllib3<3.0,>=2.7
Provides-Extra: rust
Requires-Dist: spo-kernel>=0.2.0; extra == "rust"
Provides-Extra: quantum
Requires-Dist: scpn-quantum-control>=0.1.0; extra == "quantum"
Provides-Extra: plasma
Requires-Dist: scpn-control>=0.1.0; extra == "plasma"
Provides-Extra: fusion
Requires-Dist: scpn-fusion-core>=3.9.0; extra == "fusion"
Provides-Extra: scpn-all
Requires-Dist: spo-kernel>=0.2.0; extra == "scpn-all"
Requires-Dist: scpn-quantum-control>=0.1.0; extra == "scpn-all"
Requires-Dist: scpn-control>=0.1.0; extra == "scpn-all"
Requires-Dist: scpn-fusion-core>=3.9.0; extra == "scpn-all"
Provides-Extra: queuewaves
Requires-Dist: fastapi<1.0,>=0.110; extra == "queuewaves"
Requires-Dist: uvicorn[standard]<1.0,>=0.27; extra == "queuewaves"
Requires-Dist: httpx<1.0,>=0.27; extra == "queuewaves"
Requires-Dist: websockets<17.0,>=12.0; extra == "queuewaves"
Provides-Extra: studio
Requires-Dist: streamlit<2.0,>=1.36; extra == "studio"
Provides-Extra: nn
Requires-Dist: jax<1.0,>=0.4; extra == "nn"
Requires-Dist: equinox<1.0,>=0.11; extra == "nn"
Requires-Dist: optax<1.0,>=0.2; extra == "nn"
Provides-Extra: nengo
Provides-Extra: lava
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2.0,>=1.20; extra == "otel"
Requires-Dist: opentelemetry-sdk<2.0,>=1.20; extra == "otel"
Provides-Extra: plot
Requires-Dist: matplotlib<4.0,>=3.7; extra == "plot"
Provides-Extra: notebook
Requires-Dist: jupyter<2.0,>=1.0; extra == "notebook"
Requires-Dist: jupyterlab<5.0,>=4.5.7; extra == "notebook"
Requires-Dist: notebook<8.0,>=7.5.6; extra == "notebook"
Requires-Dist: nbconvert<8.0,>=7.0; extra == "notebook"
Requires-Dist: matplotlib<4.0,>=3.7; extra == "notebook"
Provides-Extra: full
Requires-Dist: neurolib<1.0,>=0.6; extra == "full"
Requires-Dist: grpcio<2.0,>=1.60; extra == "full"
Requires-Dist: grpcio-tools<2.0,>=1.60; extra == "full"
Requires-Dist: pymodbus<4.0,>=3.5; extra == "full"
Requires-Dist: jax<1.0,>=0.4; extra == "full"
Requires-Dist: diffrax<1.0,>=0.5; extra == "full"
Requires-Dist: rtamt<1.0,>=0.3; extra == "full"
Requires-Dist: ripser<1.0,>=0.6; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest<10.0,>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio<2.0,>=0.23; extra == "dev"
Requires-Dist: pytest-cov<8.0,>=4.1; extra == "dev"
Requires-Dist: hypothesis<7.0,>=6.82; extra == "dev"
Requires-Dist: fastapi<1.0,>=0.110; extra == "dev"
Requires-Dist: uvicorn[standard]<1.0,>=0.27; extra == "dev"
Requires-Dist: httpx<1.0,>=0.27; extra == "dev"
Requires-Dist: websockets<17.0,>=12.0; extra == "dev"
Requires-Dist: coverage[toml]<8.0,>=7.3; extra == "dev"
Requires-Dist: ruff==0.15.15; extra == "dev"
Requires-Dist: mypy<3.0,>=1.19.1; extra == "dev"
Requires-Dist: types-protobuf<8.0,>=6.30; extra == "dev"
Requires-Dist: types-PyYAML<7.0,>=6.0; extra == "dev"
Requires-Dist: bandit==1.9.4; extra == "dev"
Requires-Dist: mistune>=3.2.1; extra == "dev"
Requires-Dist: mkdocs-material<10.0,>=9.5; extra == "dev"
Requires-Dist: mkdocstrings[python]<2.0,>=0.24; extra == "dev"
Requires-Dist: pymdown-extensions<11.0,>=10.21.3; extra == "dev"
Requires-Dist: pygments<2.21,>=2.20; extra == "dev"
Requires-Dist: pre-commit<5.0,>=3.5; extra == "dev"
Requires-Dist: twine<7.0,>=6.2; extra == "dev"
Requires-Dist: pytest-benchmark<6.0,>=5.0; extra == "dev"
Dynamic: license-file

# SCPN Phase Orchestrator

Domain-agnostic coherence control compiler built on Kuramoto/UPDE phase dynamics.

> **Active Development** — SCPN Phase Orchestrator is under intensive development. The core UPDE engine, 3-channel oscillator extraction (P/I/S), supervisor with regime management, and Rust FFI acceleration are functional and guarded by local and CI verification gates. Public capability counts are generated from the manifest below rather than maintained by hand. APIs may evolve as this work progresses.

**Version:** 0.6.5
**Status:** active development; public inventory is generated below.

## Why This Exists

SPO is for systems where cyclic processes either need to lock together or must
be kept from locking together: power grids, fusion plasmas, cloud retry storms,
industrial machines, biological rhythms, traffic networks, robotic swarms,
digital twins, and differentiable oscillator research. It gives those systems a
shared language of phase, coupling, coherence, regime, and bounded control.

The product value is not only simulation. The repository combines domain
binding specs, physical/informational/symbolic phase extraction,
Kuramoto/UPDE dynamics, supervisor and audit surfaces, optional Rust
acceleration, bounded adapter bridges, and differentiable JAX layers for
topology and coupling optimisation.

SPO is therefore useful in four commercial situations:

| Situation | What SPO adds |
|-----------|---------------|
| A plant, grid, service, or biological system has repeated behaviour | converts raw cycles, events, and states into comparable phase variables |
| Synchrony is valuable in one subsystem and dangerous in another | separates `R_good` from `R_bad` instead of treating coherence as one scalar |
| Control proposals must be explainable before they reach hardware | emits bounded, rate-limited, replayable review artefacts rather than hidden automation |
| A team needs one language across physics, software, and operations | represents coupling, lag, forcing, and target phase with the same `K`, `alpha`, `zeta`, and `Psi` contract |

Start with the [Use Cases and Value Map](docs/getting-started/use_cases.md) if
you need to understand what the software is for before choosing an API.

For a compact business, operator, and technical orientation, read the
[Executive Overview](docs/getting-started/executive_overview.md). It explains
where SPO creates value, how the pieces fit together, which surfaces are
execution-ready, and which frontier tracks remain review-only until external
evidence is attached.

## Reader Map

| Reader | What to read first | Why |
|--------|--------------------|-----|
| Domain expert | [Use Cases and Value Map](docs/getting-started/use_cases.md) | decide whether the system has real phase/coherence structure |
| Operator or buyer | [Executive Overview](docs/getting-started/executive_overview.md) | understand value, risk boundaries, and deployment posture |
| Engineer | [Quickstart](docs/getting-started/quickstart.md) | validate a domainpack and run a deterministic simulation |
| Python integrator | [Python Facade API](docs/reference/api/api.md) | embed reviewed local simulation without shelling out to Click |
| ML researcher | [Differentiable Kuramoto](docs/guide/differentiable_kuramoto.md) | use JAX layers, SAF loss, inverse coupling, and accelerator checks |
| Reviewer | [Release Hygiene](docs/RELEASE_HYGIENE.md) | verify docs, benchmarks, CI, security, and release evidence |

## Value Chain

SPO is most useful when a team needs all four layers together:

| Layer | Question answered | Evidence produced |
|-------|-------------------|-------------------|
| Domain binding | What counts as an oscillator, boundary, driver, and objective? | reviewed `binding_spec.yaml` plus schema validation |
| Dynamics | How do phases, couplings, lags, and forcing evolve? | deterministic Kuramoto/UPDE trajectories and order metrics |
| Supervision | Which regime are we in, and which proposal is bounded? | policy, Petri, STL, projector, and audit records |
| Productisation | Can an operator reproduce, reject, or promote the result? | replay logs, benchmark snapshots, Studio panels, and docs routes |

The key product distinction is the combination of physics-grounded synchrony
models with review-first control surfaces. SPO does not hide control decisions
inside a dashboard or notebook; it turns them into inspectable artefacts.

<!-- capability-snapshot:start -->
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
<!-- Generated by tools/capability_manifest.py; do not edit counts by hand. -->

### SCPN Phase Orchestrator Capability Inventory

| Surface | Current inventory |
|---|---:|
| Package version | 0.6.5 |
| Public API exports | 24 |
| Python package modules | 447 |
| Core Engine modules | 224 |
| Runtime/Serving modules | 47 |
| Integration modules | 24 |
| Research/Experimental modules | 149 |
| Domainpack files | 36 |
| Rust kernel files | 91 |
| Optional extras | 15 |
| Python test files | 524 |
| Public documentation pages | 176 |
| GitHub Actions workflows | 12 |

Evidence boundary: this snapshot is a static inventory. Performance, coverage, hardware, and scientific-fidelity claims require their own committed evidence artifacts.
<!-- capability-snapshot:end -->

[![CI](https://github.com/anulum/scpn-phase-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/anulum/scpn-phase-orchestrator/actions/workflows/ci.yml)
[![CodeQL](https://github.com/anulum/scpn-phase-orchestrator/actions/workflows/codeql.yml/badge.svg)](https://github.com/anulum/scpn-phase-orchestrator/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://github.com/anulum/scpn-phase-orchestrator/actions/workflows/scorecard.yml/badge.svg)](https://github.com/anulum/scpn-phase-orchestrator/actions/workflows/scorecard.yml)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12193/badge)](https://www.bestpractices.dev/projects/12193)
[![PyPI](https://img.shields.io/pypi/v/scpn-phase-orchestrator)](https://pypi.org/project/scpn-phase-orchestrator/)
[![Downloads](https://img.shields.io/pypi/dm/scpn-phase-orchestrator.svg)](https://pypi.org/project/scpn-phase-orchestrator/)
[![Total Downloads](https://static.pepy.tech/badge/scpn-phase-orchestrator)](https://pepy.tech/project/scpn-phase-orchestrator)
[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://anulum.github.io/scpn-phase-orchestrator/)
[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)](https://github.com/anulum/scpn-phase-orchestrator)
[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-purple)](https://github.com/anulum/scpn-phase-orchestrator/blob/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![Rust FFI](https://img.shields.io/badge/Rust-spo--kernel-orange)](https://github.com/anulum/scpn-phase-orchestrator/tree/main/spo-kernel)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/anulum/scpn-phase-orchestrator/blob/main/.pre-commit-config.yaml)
[![REUSE](https://img.shields.io/badge/REUSE-compliant-green)](https://reuse.software/)
[![Polar.sh](https://img.shields.io/badge/Fund-Polar.sh-blue)](https://polar.sh/anulum)

Badge notes: CI, CodeQL, Scorecard, docs, package, and coverage badges are
status pointers. Capability counts are generated by `tools/capability_manifest.py`;
benchmark, hardware, security, and release claims require their dedicated
evidence pages and GitHub run records.

![Synchronization Manifold](docs/assets/synchronization_manifold.png)

## What It Does

Treats Kuramoto phase dynamics as a universal synchrony state-space.
Any hierarchical coupled-cycle system — plasma, cloud infrastructure,
traffic, power grids, factories, biology — maps onto the same engine.

In plain terms: if a system has repeating behaviour, SPO helps determine
whether the repetitions are synchronising, whether that synchrony is useful or
dangerous, and which bounded intervention should be reviewed next.

SPO then separates three questions that are often mixed together:

1. **Observation:** what cycles, events, and states are present?
2. **Evidence:** which phase relationships are coherent, unstable, causal, or
   unsafe?
3. **Action:** which bounded knob could change the regime without bypassing
   review, safety tier, or replay evidence?

## Core Pipeline

```
Domain Binder → Oscillator Extractors (P/I/S) → UPDE Engine → Supervisor → Actuation Mapper
```

Each stage has a production reason to exist:

| Stage | Production purpose | Failure mode it prevents |
|-------|--------------------|--------------------------|
| Domain Binder | makes assumptions explicit before execution | hidden notebook logic and unreviewed signal mappings |
| Extractors | normalise waves, events, and states into phase | comparing incompatible telemetry directly |
| UPDE Engine | evolves coupled dynamics under reproducible numerics | hand-tuned synchrony claims without equations |
| Supervisor | classifies regimes and proposes bounded actions | uncontrolled changes to sensitive knobs |
| Actuation Mapper | translates proposals into reviewed adapter contracts | direct hardware writes without replay or rate limits |

### 3-Channel Oscillator Model

| Channel | Source | Phase Extraction |
|---------|--------|-----------------|
| **Physical (P)** | Continuous waveforms | Hilbert transform, zero-crossing |
| **Informational (I)** | Event/decision streams | Event-phase from message timing |
| **Symbolic (S)** | Discrete state sequences | Ring-phase θ=2πs/N, graph-walk |

### 4 Universal Control Knobs

| Knob | Meaning |
|------|---------|
| **K** | Coupling strength (Knm matrix) |
| **α** | Phase lag (transport/actuator delays) |
| **ζ** | Driver strength (external forcing) |
| **Ψ** | Reference phase (control target) |

### Dual Objective

- **R_good**: Coherence to maintain (actuator ↔ target phase-lock)
- **R_bad**: Coherence to suppress (harmful mode-locking)

## Capabilities

### GPU-First Differentiable Phase Dynamics (`nn/` module, JAX)

`nn/` is the primary API for ML users. It exposes JAX/equinox layers and
runtime checks directly from `scpn_phase_orchestrator.nn` so production
training jobs fail fast when no GPU/TPU backend is visible.

```python
from scpn_phase_orchestrator.nn import (
    KuramotoLayer,
    jax_runtime_info,
    require_accelerator,
)

print(jax_runtime_info())
device = require_accelerator()  # raises on CPU-only JAX runtimes
```

| Module | What it does |
|--------|-------------|
| KuramotoLayer | Phase-only oscillator layer (equinox), learnable K and ω |
| StuartLandauLayer | Phase + amplitude layer, bifurcation parameter μ |
| Simplicial Kuramoto | 3-body higher-order coupling (Gambuzza 2023) |
| BOLD Generator | Balloon-Windkessel hemodynamic model for fMRI |
| Reservoir Computing | Kuramoto network as nonlinear reservoir + ridge readout |
| SAF Spectral Loss | Topology optimization via Laplacian eigenstructure |
| UDE-Kuramoto | Physics backbone sin(Δθ) + learned neural residual |
| Inverse Pipeline | Infer coupling K and frequencies ω from observed data |
| OIM Graph Coloring | Oscillator Ising machine for combinatorial optimization |
| Differentiable Supervisor | Equinox policy for closed-loop `K`/`zeta` proposals with `ControlAction` adapter |

All functions are JIT-compilable, vmap-compatible, and differentiable.
Install: `pip install scpn-phase-orchestrator[nn]`
For CI and smoke tests on CPU-only hosts, use
`require_accelerator(allow_cpu=True)` explicitly.

### Advanced Dynamics (`upde/` module, NumPy)

| Module | What it does |
|--------|-------------|
| Inertial Kuramoto | Second-order swing equation for power grid stability |
| Market Kuramoto | Financial regime detection via Hilbert phase + order parameter |
| Swarmalator | Coupled spatial + phase dynamics (O'Keeffe 2017) |
| Simplicial Engine | 3-body coupling with explosive transitions |
| Stuart-Landau Engine | Amplitude dynamics with Hopf bifurcation |
| Stochastic Engine | Euler-Maruyama with optimal noise (D* auto-tuning) |
| Geometric Engine | Torus-preserving symplectic integrator |
| Delay Engine | Time-delayed coupling with circular buffer |
| Ott-Antonsen | Exact mean-field reduction (O(1) prediction) |

### Closed-Loop Control (unique — no other oscillator library has this)

| Module | What it does |
|--------|-------------|
| MPC Supervisor | Predicts R trajectory 10 steps ahead via OA reduction |
| Regime Manager | FSM with hysteresis (NOMINAL/DEGRADED/CRITICAL) |
| Petri Net FSM | Formal state machine with guard conditions |
| Plasticity | Three-factor Hebbian coupling adaptation |
| TE Adaptive | Transfer entropy-based causal coupling updates |
| Audit Trail | SHA256-chained JSONL for deterministic replay |

### Analysis Toolkit (15 monitors)

Order parameter, PLV, PAC (cross-frequency coupling), chimera detection,
EVS (entrainment verification), PID (redundancy/synergy), Lyapunov
exponent, entropy production, winding number, ITPC, coupling estimation
(including non-sinusoidal harmonics), HCP connectome generation.

### Hardware Deployment

| Target | Status |
|--------|--------|
| Rust FFI | 12 PyO3 bindings for native-speed core modules |
| FPGA | 16-oscillator Zynq-7020 kernel, sub-15μs latency |
| WebAssembly | Browser-based Kuramoto visualization, no server needed |
| JAX GPU | Transparent GPU acceleration via XLA |

See [Documentation Coverage](docs/reference/documentation_coverage.md) for the
current repo-wide documentation inventory and the enforced API-reference policy.

### Unique Analysis Capabilities

| Module | What it does |
|--------|-------------|
| Hodge Decomposition | Splits coupling K into gradient / curl / harmonic components |
| Transfer Entropy | Directed causal information flow between oscillators |
| Coupling Estimation | Infer K from data (least-squares + higher harmonics) |

## Quickstart

Use this path when evaluating the package for the first time. It keeps the
first run deterministic and reviewable before you move to a domain-specific
binding or hardware-adjacent adapter.

```bash
# Install from PyPI
pip install scpn-phase-orchestrator

# Or with optional extras
pip install scpn-phase-orchestrator[queuewaves]  # FastAPI cascade detector
pip install scpn-phase-orchestrator[plot]         # matplotlib visualisation
pip install scpn-phase-orchestrator[otel]         # OpenTelemetry export

# Scaffold a new domainpack
spo scaffold my_domain

# Scaffold from natural-language intent with a configured LLM provider
spo scaffold traffic_grid --llm \
  --description "I am modelling traffic lights in a 4-intersection grid"

# Validate a domain binding spec
spo validate domainpacks/minimal_domain/binding_spec.yaml

# Run a domain simulation
spo run domainpacks/queuewaves/binding_spec.yaml --steps 1000

# Run a real-data review demo from PhysioNet heart-rate-belt data
spo demo --dataset heartbeat.csv --target coherence --steps 100

# Replay from audit log
spo replay audit.jsonl --output report.json
```

Python applications can use the high-level facade without invoking Click:

```python
from scpn import Orchestrator

orch = Orchestrator.from_yaml("domainpacks/minimal_domain/binding_spec.yaml")
state = orch.run(steps=100, seed=42)
print(state.order_parameter)
```

## Reference Benchmarks

SPO keeps reference benchmarks as reproducible evidence, not as marketing
claims. The checked-in snapshot is dated `2026-05-20` and was generated with:

```bash
PYTHONPATH=src python benchmarks/reference_suite.py
```

The snapshot is published at
[`docs/galleries/reference_benchmark_snapshot.md`](docs/galleries/reference_benchmark_snapshot.md).
It records the command, Python/Numpy versions, platform metadata, acceptance
flags, and steps/s values for each suite. Selected reference suites:

| Suite | Reference contract | Snapshot steps/s |
|-------|--------------------|-----------------:|
| `kuramoto_reference_strogatz_2000` | Kuramoto/Strogatz synchronisation reference | `6941.27` |
| `stuart_landau_reference_pikovsky_2001` | Stuart-Landau limit-cycle reference | `3722.04` |
| `petri_net_reachability` | Petri-net reachability reference | `244900` |

Physics invariants are also executable as focused tests:

```bash
PYTHONPATH=src pytest tests/test_physics_benchmarks.py
```

Those tests cover Strogatz/Kuramoto synchronisation, weak-coupling
desynchronisation, coupling monotonicity, external-drive entrainment,
Stuart-Landau limit cycles, subcritical decay, amplitude consensus, and
zero-coupling independence.

## Hardware Integration Boundary

Real hardware access is adapter-scoped and opt-in:

| Surface | Status | Safety boundary |
|---------|--------|-----------------|
| BrainFlow sensor input | Optional real EEG/PPG/EMG read adapter | requires `brainflow`; no actuation writes |
| Modbus/TLS SCADA | Optional real PLC/DCS read/write adapter | mutual TLS client certs plus mandatory server verification |
| Plain Modbus TCP | Lab/isolated-network adapter | not for production writes across routable networks |
| Quantum/neuromorphic targets | Review artefact generation | execution and hardware writes remain disabled |

Hardware deployment details are documented in
[`docs/guide/adapters.md`](docs/guide/adapters.md). Quantum and neuromorphic
compiler outputs are intentionally handoff artefacts until a verified external
hardware execution pipeline is attached.

For development, clone the repo and install in editable mode:

```bash
git clone https://github.com/anulum/scpn-phase-orchestrator.git
cd scpn-phase-orchestrator
pip install -e ".[dev]"
```

For a role-based first-hour path, see the
[Onboarding Handbook](docs/getting-started/onboarding.md). For the full
notebook, example, and interactive demo inventory, see
[Notebooks & Demos](docs/galleries/notebooks_and_demos.md).
For market-facing and domain-facing orientation, see the
[Use Cases and Value Map](docs/getting-started/use_cases.md).

## Release and Evidence Posture

| Surface | Current posture | Where to verify |
|---------|-----------------|-----------------|
| Documentation | MkDocs public site with onboarding, tutorials, API references, guides, notebooks, and roadmap | `mkdocs build`, `docs/index.md`, and `mkdocs.yml` |
| Capability inventory | generated static counts, not edited by hand | `tools/capability_manifest.py` and `docs/_generated/` |
| Benchmarks | regression gate and dated reference snapshots | `bench/`, `benchmarks/`, and `docs/galleries/reference_benchmark_snapshot.md` |
| Security | CodeQL, dependency scanning, secret scanning, ingress hardening, and safe config loaders | GitHub Security tab and security docs |
| Release | semantic versioned package metadata and changelog | `pyproject.toml`, `CHANGELOG.md`, tags, and GitHub releases |

## Platform Support

| Platform | Python engine | Rust FFI (optional) |
|----------|--------------|---------------------|
| Linux | Full | Full |
| macOS | Full | Full |
| Windows | Full | Experimental (requires MSVC toolchain) |

The PyPI package is pure Python. Rust FFI provides optional acceleration
and is built from source via `maturin develop`.

## Domainpacks

| Pack | Domain | Purpose |
|------|--------|---------|
| `autonomous_vehicles` | Vehicles | Platoon phase-locking, leader-follower sync (3 layers, 8 oscillators) |
| `bio_stub` | Biology | Multi-scale biological oscillators (4 layers, 16 oscillators) |
| `cardiac_rhythm` | Cardiology | Gap-junction coupling, arrhythmia (4 layers, 10 oscillators) |
| `chemical_reactor` | Process control | Hopf bifurcation, Semenov limit (4 layers, 10 oscillators) |
| `circadian_biology` | Chronobiology | SCN clock-gene coupled oscillators (4 layers, 10 oscillators) |
| `digital_twin_nchannel` | Digital twins | Six-channel plant/twin residual profile with derived `TwinResidual` |
| `edge_consensus_nchannel` | Edge orchestration | Six-channel gossip consensus with load/trust coupling |
| `epidemic_sir` | Epidemiology | Epidemic wave synchronisation (3 layers, 8 oscillators) |
| `firefly_swarm` | Ecology | Flash synchronisation, Mirollo-Strogatz (2 layers, 8 oscillators) |
| `fusion_equilibrium` | Fusion equilibrium | Grad-Shafranov + FusionCoreBridge (6 layers, 12 oscillators) |
| `geometry_walk` | Graph systems | Random-walk phase coupling (2 layers, 8 oscillators) |
| `laser_array` | Photonics | Semiconductor laser phase-locking (3 layers, 8 oscillators) |
| `manufacturing_spc` | Manufacturing | Statistical process control (3 layers, 9 oscillators) |
| `metaphysics_demo` | P/I/S showcase | Imprint + geometry ablation (3 layers, 7 oscillators) |
| `minimal_domain` | Synthetic | Minimal-but-complete pipeline example (2 layers, 4 oscillators) |
| `network_security` | Cybersecurity | Traffic anomaly detection, DDoS suppression (3 layers, 8 oscillators) |
| `neuroscience_eeg` | Neuroscience | EEG band->phase, seizure detection (6 layers, 14 oscillators) |
| `plasma_control` | Tokamak plasma | MHD/transport multi-scale control (8 layers, 16 oscillators) |
| `pll_clock` | Telecommunications | PLL network clock synchronisation (3 layers, 8 oscillators) |
| `power_safety_nchannel` | Power systems | Six-channel grid safety profile with derived `Risk` |
| `power_grid` | Power systems | Swing equation = Kuramoto (5 layers, 12 oscillators) |
| `quantum_simulation` | Quantum computing | Qubit register phase coupling (3 layers, 8 oscillators) |
| `queuewaves` | Cloud/queues | Retry storm desynchronisation (3 layers, 6 oscillators) |
| `rotating_machinery` | Vibration | Harmonics, ISO 10816 boundaries (4 layers, 10 oscillators) |
| `satellite_constellation` | Aerospace | Orbital slot synchronisation, beam handover (3 layers, 8 oscillators) |
| `swarm_robotics` | Robotics | Vicsek collective motion (3 layers, 8 oscillators) |
| `traffic_flow` | Transportation | Signal coordination = phase sync (4 layers, 10 oscillators) |
| `financial_markets` | Finance | Stock synchronization, crash detection |
| `gene_oscillator` | Synthetic biology | Repressilator quorum coupling |
| `vortex_shedding` | Fluid dynamics | Wake station Stuart-Landau |
| `robotic_cpg` | Robotics | Joint CPG locomotion |
| `sleep_architecture` | Sleep medicine | AASM sleep staging from R |
| `musical_acoustics` | Acoustics | Consonance = R, groove = alpha |
| `brain_connectome` | Neuroscience | HCP-inspired coupling |
| `agent_coordination` | Multi-agent coordination | Heartbeat, task, and topic synchronisation |
| `digital_twin_nchannel` | Digital twins | Six-channel plant/twin residual profile |
| `edge_consensus_nchannel` | Edge orchestration | Six-channel gossip consensus |
| `power_safety_nchannel` | Power systems | Six-channel grid safety profile |
| `identity_coherence` | Consciousness | SSGF identity model (6 layers, 30 oscillators) |

### Adding a Domain

1. Create `domainpacks/<name>/binding_spec.yaml` declaring layers,
   oscillator families, coupling, drivers, objectives, and boundaries.
2. Optionally add `policy.yaml` for declarative supervisor rules.
3. Validate: `spo validate domainpacks/<name>/binding_spec.yaml`
4. Run: `spo run domainpacks/<name>/binding_spec.yaml --steps 1000`

See [`metaphysics_demo`](domainpacks/metaphysics_demo/) for a full
example exercising all three channels, imprint modulation, geometry
projection, and policy-driven control.  Spec format reference:
[binding_spec.schema.json](docs/specs/binding_spec.schema.json).

## Development

```bash
pip install -e ".[dev]"
ruff check src/ tests/
ruff format --check src/ tests/
pytest tests/ -v --tb=short
mkdocs build
```

## License

AGPL-3.0-or-later. Commercial licensing available — contact protoscience@anulum.li.

## Citation

See [CITATION.cff](CITATION.cff).

---

<p align="center">
  <a href="https://www.anulum.li">
    <img src="docs/assets/anulum_logo_company.jpg" width="180" alt="ANULUM">
  </a>
  &nbsp;&nbsp;&nbsp;&nbsp;
  <a href="https://www.anulum.li">
    <img src="docs/assets/fortis_studio_logo.jpg" width="180" alt="Fortis Studio">
  </a>
  <br>
  <em>Developed by <a href="https://www.anulum.li">ANULUM</a> / Fortis Studio</em>
</p>
