scpn-phase-orchestrator 0.6.5

Domain-agnostic coherence control compiler built on SCPN's Kuramoto/UPDE framework

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 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. 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	decide whether the system has real phase/coherence structure
Operator or buyer	Executive Overview	understand value, risk boundaries, and deployment posture
Engineer	Quickstart	validate a domainpack and run a deterministic simulation
Python integrator	Python Facade API	embed reviewed local simulation without shelling out to Click
ML researcher	Differentiable Kuramoto	use JAX layers, SAF loss, inverse coupling, and accelerator checks
Reviewer	Release Hygiene	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.

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.

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.

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.

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

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

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:

PYTHONPATH=src python benchmarks/reference_suite.py

The snapshot is published at 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:

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. 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:

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. For the full notebook, example, and interactive demo inventory, see Notebooks & Demos. For market-facing and domain-facing orientation, see the Use Cases and Value Map.

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 for a full example exercising all three channels, imprint modulation, geometry projection, and policy-driven control. Spec format reference: binding_spec.schema.json.

Development

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 [e-mail].

Citation

See CITATION.cff.

---

    
Developed by ANULUM / Fortis Studio