Metadata-Version: 2.4
Name: scpn-phase-orchestrator
Version: 0.6.3
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.3
**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.

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.

<!-- 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.3 |
| 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 | 522 |
| Public documentation pages | 175 |
| GitHub Actions workflows | 10 |

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)

![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.

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
```

### 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

```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).

## 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>
