SCPN Phase Orchestrator¶
Many systems succeed or fail on timing. A retry storm that synchronises takes down a cluster; generators that drift out of step trip a power grid; neurons firing in lockstep look like a seizure; fusion-plasma modes that phase-lock disrupt the reactor. Different domains, one underlying problem: coupled rhythms drifting into — or out of — sync.
SCPN Phase Orchestrator (SPO) is a Python library and CLI for that problem. It takes the repeating signals a system already produces — waveforms, event streams, state changes — turns them into a shared language of phase, and tells you what is locking together, how close the system is to a regime change, and which single bounded knob can steer it back. Every proposed change is bounded, rate-limited, and audit-logged for human review before it reaches hardware. The same engine maps onto plasma, cloud infrastructure, traffic, power grids, factories, and biology, because underneath they are all coupled-cycle systems.
For specialists, in one line: a domain-agnostic synchronisation-analysis and honest-evaluation toolkit built on Kuramoto/UPDE phase dynamics, with a review-only control-proposal surface — bind signals, extract oscillator phases, run coupled dynamics, measure coherence, classify regimes, and emit bounded review artefacts.
What is validated — and what is not¶
SPO's most defensible asset is not a magic detector; it is honesty under a controlled false-alarm rate. Stated plainly:
- One externally-validated detection niche: grid modal damping. On the IEEE-39 and Kundur systems, SPO's estimate of the dominant electromechanical mode's growth rate tracks the small-signal eigenvalue computed by the ANDES simulator (Spearman ρ up to 0.87) — a checkable physical quantity, not a proxy. See the early-warning study.
- Generic early-warning detection is at chance on real data, and SPO reports that. Across five real modalities (grid, EEG, ecological/climate, molecular), generic tipping-point indicators at an honest operating point perform at chance under a permutation-controlled test. SPO does not claim to predict tipping points in these domains; the grid is the one exception, where the signature is a physically deterministic growing mode.
- A shipped tool to check any early-warning claim: the honest auditor. The
scpn_phase_orchestrator.evaluationpackage and thespo audit-detectorCLI score any detector's event-vs-null skill at a matched false-alarm rate, with a label-permutation p-value and a hash-sealed record — the SCPN suite, an AR(1)/Kendall-τ baseline, or a black-box classifier, on identical footing. Turning "most detectors are at chance" from an embarrassment into a measurement is the point.
Everything else — the 36 domain packs, the control-proposal surface, the assurance bundle — is a reusable scaffold or a review-only artefact, not a validated claim. That evidence discipline runs through the whole toolkit; the fact-based overview separates the validated from the not.
What this project is for¶
The software is intended for teams that must make control decisions from time-structured signals where phase relationships carry operational value. That includes systems where:
- instability grows from delayed feedback loops,
- oscillatory phases drift across regions or services,
- and operators need evidence of both safety and effectiveness before actuation.
In practical terms, SPO gives teams a repeatable path from raw signals to a logged control decision:
- identify phase-bearing signals and build a binding specification,
- choose a validated backend with explicit evidence thresholds,
- run bounded simulation and replay checks,
- promote only actions that pass policy and audit gates,
- keep all decisions reconstructible from JSONL records.
It is designed for both R&D proving-ground use and production services that require explicit review boundaries between proposal, validation, and actuation.
Why it is different from generic monitoring¶
Standard observability systems report symptoms. SPO turns symptoms into phase-aligned state models before proposing changes. That makes it suitable when:
- the same telemetry appears in multiple domains (service queues, power loads, rhythms),
- operators need synchronized evidence across simulation, policy, and audit lanes,
- and teams need a hard stop on unsafe actions when replay or policy checks fail.
This does not replace existing controllers. It standardizes what is being controlled and how that control is justified before it reaches any actuator surface.
For evaluation, start with the practical question: does the target system have waves, cycles, retries, stages, rotations, or event loops whose timing matters? If yes, SPO can express those sources as phase, test coupling hypotheses, separate useful from harmful synchrony, and preserve a replayable control review record.
Current Release Boundary¶
Version 1.4.3 is the current release candidate. Public availability must be
verified through PyPI and an immutable exact-tag release receipt; a source-tree
version alone is not publication evidence. Version 1.0.0 established the
stable API baseline: the public names exported from
scpn_phase_orchestrator.__all__ are covered by semantic-versioning guarantees.
This release consolidates the operator, evaluation, assurance, native-kernel,
and documentation surfaces built through the 0.12.0 line. The public docs
route readers from use-case selection through Python APIs, tutorials, notebooks,
benchmark snapshots, real-data validation evidence, and release hygiene without
requiring them to reverse-engineer the source tree.
| Reader concern | Where the release answers it |
|---|---|
| What problem does SPO solve? | Use Cases and Value Map and Executive Overview |
| How do I run it? | Quickstart, Hello World, and From Raw Sources to Run |
| How do I embed it? | Python Facade API and API Overview |
| What evidence supports PHA-C? | PHA-C Acceptance Chain, PHA-C Lean Proof Obligation, and Reference Benchmark Snapshot |
| What remains review-only? | Public Roadmap, Adapters, and Release Hygiene |
The benchmark snapshot remains local regression evidence unless the raw run records CPU/core isolation and host-load controls. Live hardware writes remain adapter-scoped and disabled by default.
What This Means in Practice¶
SPO gives a team one reviewable path from raw operational traces to bounded control evidence:
| Stage | Practical output | Why it matters |
|---|---|---|
| Bind | binding_spec.yaml with sources, channels, boundaries, and assumptions |
domain knowledge becomes inspectable instead of living in notebooks |
| Extract | physical, informational, and symbolic phases on one timeline | waves, events, and states can be compared mathematically |
| Simulate | Kuramoto, UPDE, Stuart-Landau, delay, stochastic, simplicial, or inertial dynamics | teams can test synchronisation and desynchronisation hypotheses before deployment |
| Supervise | regimes, Petri nets, value guards, and bounded action proposals | unsafe or unsupported control paths stay behind review gates |
| Audit | hash-linked logs, deterministic replay, benchmark snapshots, and Studio panels | decisions can be reproduced, rejected, or promoted with evidence |
| If you are asking... | Start here |
|---|---|
| What is this software for? | Use Cases and Value Map |
| What is the business/operator value? | Executive Overview |
| How do I run something in five minutes? | Quickstart |
| How do I decide what counts as an oscillator? | Oscillator Hunt Sheet |
| How do I move from raw data to a run? | End-to-End From Raw Sources |
| How do I use it from Python? | Python Facade API |
| How do I understand notebooks and demos? | Notebooks and Demos |
| What is implemented versus still open? | Public Roadmap |
First Evaluation Path¶
- Read the Use Cases and Value Map.
- Run
spo demo --domain minimal_domain --steps 20. - Validate one binding spec with
spo validate. - Replay one audited run with
spo replay --verify. - Use the API Reference only after choosing the relevant surface.
Architecture¶
Domain Binder ─► Oscillators (P/I/S) ─► UPDE Engine (9 variants) ─► Supervisor ─► Actuation
│ │ │ │ │
binding_spec.yaml 3-channel Kuramoto, Stuart-Landau, Policy DSL ControlAction
extraction Inertial, Market, Swarmalator + Petri Net + Projector
(Physical / Stochastic, Geometric, Delay + Regime FSM
Informational / Simplicial + Ott-Antonsen + MPC
Symbolic) + Rust FFI / JAX GPU
Features¶
-
Honest Early-Warning Auditor
Score any detector's event-vs-null skill at a matched false-alarm rate, with a label-permutation p-value and a hash-sealed record — the SCPN suite, an AR(1)/Kendall-τ baseline, or a black-box classifier, on identical footing.
spo audit-detector. -
36 Domainpacks (scaffolds)
Plug-and-play domain bindings: plasma control, power grids, traffic flow, cardiac rhythm, neuroscience EEG, swarm robotics, queuewaves, brain connectome, sleep architecture, and 27 more — reusable scaffolds, with the power grid the one externally-validated niche.
-
3-Channel Model (P/I/S)
Physical, Informational, and Symbolic oscillator extraction. Each domain signal decomposes into one or more channels with dedicated extractors (Hilbert, wavelet, zero-crossing, event, ring, graph).
-
Rust-Accelerated
spo-kernelFFI via PyO3/maturin, with dated local benchmark and parity evidence. Pure-Python fallback ships by default; timings are not deployment guarantees. -
Stuart-Landau
Phase + amplitude coupled ODEs. Subcritical bifurcation detection, PAC (phase-amplitude coupling) metrics, and amplitude-aware supervision.
-
Policy DSL
YAML-based declarative supervisor rules. Condition-action pairs triggered by regime state and metric thresholds. Rate-limited, TTL-aware, projector-clipped.
-
Petri Net FSM
Multi-phase protocol sequencing via place/transition nets with guard expressions. Regime-place mapping drives supervisor decisions through protocol stages.
-
QueueWaves
Real-time cascade failure detector for microservice architectures. Scrapes queue depths, extracts phases, detects desynchronization before cascading failures propagate.
-
Deterministic Replay
SHA256-chained audit trail in JSONL format. Every simulation step is hash-linked and re-executable. Tolerance-based replay verification (atol=1e-6) plus hash-chain integrity check.
-
Differentiable (JAX)
nn/module: KuramotoLayer, StuartLandauLayer, simplicial 3-body, BOLD, reservoir, UDE, inverse pipeline, OIM. All JIT-compilable, vmap-compatible, GPU-ready. -
9 ODE Engines
Standard Kuramoto, Stuart-Landau, inertial (power grids), market (finance), swarmalator (robotics), stochastic, geometric, delay, simplicial. Plus Ott-Antonsen mean-field reduction.
-
15 Monitors
Chimera detection, EVS entrainment, Lyapunov exponents, entropy production, PAC, PID, transfer entropy, winding numbers, ITPC, sleep staging, STL safety. Beyond R alone.
-
Inverse Kuramoto
Infer coupling matrix K and frequencies ω from observed data (EEG, sensors, markets) by backpropagating through the ODE solver. L1 sparsity discovers network topology.
Quick Install¶
Installation Quickstart Onboarding
Navigation¶
| Section | Description |
|---|---|
| Getting Started | Executive overview, onboarding, install, quickstart, hello world tutorial |
| Concepts | System overview, oscillators, control knobs, imprint model |
| Guides | Stuart-Landau, QueueWaves, Rust FFI, adapters, production |
| Specifications | Binding schema, UPDE numerics, policy DSL, all contracts |
| Tutorials | New domain checklist, oscillator hunt sheet, Knm templates |
| API Reference | Full Python API docs (mkdocstrings) |
| Polyglot API Artifacts | Native Rust, Go, Julia, and Mojo documentation outputs |
| Gallery | All 36 domainpacks, notebooks, examples, and demos |
The current documentation inventory and API-reference guardrails are tracked in Documentation Coverage.
Contact: protoscience@anulum.li | GitHub Discussions | www.anulum.li
Developed by ANULUM / Fortis Studio
License: AGPL-3.0-or-later | Commercial licensing available
© 1996–2026 Miroslav Šotek. All rights reserved.