API Reference¶
Auto-generated from source docstrings via
mkdocstrings.
Python classes auto-delegate to Rust when the spo_kernel extension is
available; the public interface is identical in both backends.
What this index is for¶
This index is the operational entrypoint for implementation teams. It is organized by what users are trying to do (run, validate, control, prove, report), not by internal file layout.
Use it in this order when starting from a requirement:
- Pick a goal in the API by Job section.
- Follow the corresponding guide or tutorial for domain, adapter, and benchmark context.
- Move to the Minimal Imports by Task section before any exploratory refactor.
- Confirm review requirements via the PHA-C acceptance evidence chain and the matching benchmark lane.
This keeps navigation aligned with production outcomes instead of code structure.
How to use this map in execution planning¶
Use this page as the first gate in implementation planning:
- choose one operational objective in API by Job,
- move to the supporting guide or tutorial for context,
- use the linked API entrypoints only with a specific test scope,
- confirm the related evidence contracts before moving into deployment flow.
This order keeps review scope stable. The link graph is complete enough for single-path decisions, and it avoids parallel API exploration that can create hidden dependency risk.
If you are still deciding what SPO is for, start with the Use Cases and Value Map. This API index is organised for implementation work after the domain, data source, and safety boundary are known.
How this API boundary is intended to be used¶
The index is not a complete replacement for the pipeline pages. It is the implementation anchor for readers who already know:
- which domain assumption is being modelled,
- what decision boundary defines acceptable intervention,
- and which replay or audit checks are mandatory before exposure to actuators.
Use this page to confirm "which API surface can be used under which safety assumption" before changing imports, defaults, or policy rules.
API by Job¶
| Job | Primary API | Supporting docs | Typical output |
|---|---|---|---|
| Run a reviewed binding from Python | Python Facade | Quickstart | OrchestratorState with phases, coupling, frequencies, and order parameter |
| Validate and resolve domain assumptions | Binding | New Domain Checklist | accepted binding spec or explicit diagnostics |
| Extract phase from data | Oscillators | From Raw Sources to Run | physical, informational, or symbolic phase series |
| Describe reactor phase meaning | Reactor Semantics | New Domain Checklist | versioned context, observable, phase, relation, and review-only regime records |
| Simulate coupled dynamics | UPDE | UPDE Numerics | phase trajectory, order parameters, and backend evidence |
| Infer or build coupling | Coupling | Build K_nm Templates | K_nm, lag, topology, or causal-coupling evidence |
| Detect coherence and instability | Monitor | Analysis Toolkit | R, PLV, PAC, Lyapunov, entropy, recurrence, and safety signals |
| Detect phase-space merge readiness | Merge Window | UPDE Moving Frame | consecutive phase-plus-position lock evidence |
| Emit review-only PHA-C event state | PHA-C Handoff | Merge Window | hashed non-actuating handoff record for replay, MIF, or Studio review |
| Emit review-only PHA-C event timeline | PHA-C Event Timeline | PHA-C Handoff | first lock, lock loss, reset counts, and trajectory hash evidence |
| Gate the full PHA-C chain | PHA-C Acceptance Chain | PHA-C Event Timeline | end-to-end spatial, Doppler, moving-frame, merge, handoff, timeline, and formal-obligation evidence |
| Bind PHA-C runtime evidence to Lean | PHA-C Lean Proof Obligation | PHA-C Acceptance Chain | fixed-point KinematicBounds.acceptanceCertificate discharge plus continuous-envelope manifest and formal certificate hash |
| Propose bounded control | Supervisor and Actuation | Production Guide | rate-limited review proposals, not unreviewed hardware writes |
| Replay and audit decisions | Audit | Deterministic Replay | hash-linked evidence that can be verified later |
| Optimise differentiable oscillator models | nn API | Differentiable Kuramoto | differentiable loss, trained coupling, or topology proposal |
Minimal Imports by Task¶
| Task | Import first | Escalate when |
|---|---|---|
| Run a local binding | from scpn import Orchestrator |
you need amplitude, delay, stochastic, or hardware-adjacent adapters |
| Inspect final coherence | OrchestratorState.order_parameter |
you need per-layer, PLV, PAC, Lyapunov, or transfer-entropy monitors |
| Build a domainpack | load_binding_spec, validate_binding_spec |
you need auto-binding proposals or generated scaffolds |
| Optimise coupling | scpn_phase_orchestrator.nn.functional |
you need Equinox layers, SAF loss, or inverse coupling |
| Review evidence | AuditLogger and replay APIs |
you need deterministic comparison across environments |
| Exchange reactor semantics | ReactorContext, ObservableDescriptor, PhaseSemanticRecord |
you need compatible relations or review-only regime estimates |
API by Reader¶
| Reader | Minimal surface | When to go deeper |
|---|---|---|
| Notebook user | Python Facade | use engine APIs when amplitude, delay, stochastic, or simplicial dynamics are required |
| Domainpack author | Binding, Oscillators, Coupling | use supervisor APIs after sources and boundaries validate |
| Operator or platform engineer | QueueWaves, Audit, Reporting, Studio | use distributed sync and adapters only after audit replay is stable |
| ML researcher | nn API, Autotune | use SAF, inverse coupling, and replay learners after reproducible seeds are fixed |
| Release reviewer | Documentation Coverage, CLI, Artifacts | compare the public API manifest, changelog, and release hygiene before tagging |
PHA-C acceptance evidence chain¶
PHA-C records are review-only evidence surfaces. They never actuate hardware, mutate a supervisor, or change coupling policy. Use them when a downstream MIF/FRC lane, release reviewer, benchmark gate, or operator dashboard needs auditable proof that the accelerator-facing physics chain stayed inside its declared phase, spatial, and kinematic envelopes.
| Surface | Evidence boundary | Formal or replay guarantee |
|---|---|---|
| PHA-C Handoff | one moving-frame sample plus merge-window margins | canonical non-actuating record hash and signed-margin replay |
| PHA-C Event Timeline | complete phase/position trajectory | first-lock, lock-loss, reset, transition-hash, and timeline-hash replay |
| PHA-C Acceptance Chain | spatial modulation, Doppler correction, moving-frame propagation, merge evidence, handoff, timeline, and aggregate subgate evidence | final-position, maximum-velocity, path-length, signed-margin, schedule, trajectory, and acceptance-hash replay |
| PHA-C Lean Proof Obligation | fixed-point manifest derived from a verified acceptance record | KinematicBounds.acceptanceCertificate plus acceptance_certificate_discharges_runtime_preconditions binding spatial budget, phase budget, and acceptance equation replay |
The acceptance benchmark row preserves this same chain across Rust, Go, Julia, Mojo, and Python source-contract slots. Local committed benchmark JSON is a regression snapshot only; production timing claims require the documented benchmark-isolation protocol.
Public API entry point¶
from scpn_phase_orchestrator import (
AuditLogger,
BifurcationDiagram,
BindingSpec,
BoundaryObserver,
ControlAction,
CouplingBuilder,
Orchestrator,
OrchestratorState,
ObservableDescriptor,
PhaseRelation,
PhaseExtractor,
PhaseSemanticRecord,
PhaseState,
QPUDataArtifact,
ReactorContext,
RegimeEstimate,
RegimeManager,
SPOError,
SparseUPDEEngine,
SheafUPDEEngine,
StuartLandauEngine,
SupervisorPolicy,
UPDEEngine,
compile_domain_to_qpu_artifact,
emit_qpu_data_artifact,
find_critical_coupling,
lyapunov_spectrum,
trace_sync_transition,
validate_qpu_data_artifact,
)
The frozen top-level manifest is tracked in
public_api_manifest.txt. Any change to
scpn_phase_orchestrator.__all__ must update that manifest, this import block,
and release notes in the same change so semantic-versioning review can classify
the compatibility impact.
Module index¶
| Module | Description |
|---|---|
| Python Facade | High-level local simulation API for notebooks and applications |
| Core & Exceptions | Exception hierarchy, Rust/Python compat constants |
| Binding | Configuration loading and validation for binding specs |
| Reactor Semantics | Reactor-family-neutral context, observables, typed phase meaning, compatible relations, and review-only regimes |
| UPDE Engine | Kuramoto ODE, Stuart-Landau amplitude ODE, metrics, PAC |
| UPDE — PHA-C Handoff | Review-only event/state bridge from moving-frame samples and merge-window evidence |
| UPDE — PHA-C Event Timeline | Review-only trajectory evidence for first lock, lock loss, resets, and timeline hashes |
| UPDE — PHA-C Acceptance Chain | End-to-end review gate spanning spatial coupling, Doppler, moving-frame dynamics, merge evidence, handoff, timeline hashes, and Lean-facing formal-obligation evidence |
| UPDE — PHA-C Lean Proof Obligation | Fixed-point Lean KinematicBounds.acceptanceCertificate, SPOFormal.Continuous, and phase-budget proof-obligation manifest derived from a verified PHA-C acceptance record |
| Oscillators | Phase extraction: Physical, Informational, Symbolic channels |
| Coupling | K_nm matrix construction, geometry constraints, lag estimation |
| Supervisor | Regime management, policy engine, Petri net FSM, event bus |
| Monitor | Boundary violation detection, coherence monitoring |
| Monitor — Merge Window | PHA-C phase-plus-position merge lock gate with consecutive-sample evidence |
| Actuation | Control output mapping, action projection |
| Imprint | History-dependent coupling modulation |
| Drivers | External forcing functions (Physical, Informational, Symbolic) |
| Audit | SHA256-chained audit logging and deterministic replay |
| Reporting | Matplotlib coherence visualizations |
| Artifacts | Portable run artifacts and QPU data packaging/validation |
| Distributed Sync | Transport-neutral phase-vector gossip protocol for UPDE nodes |
| Scaffold | Domainpack scaffolding, including fail-closed LLM-guided proposals |
| Visualization | Real-time WebXR/network/torus visualization surfaces |
| Adapters | Bridges to SCPN ecosystem, observability, SNN controllers |
| Plugins | Extension manifests and compatibility checks |
| QueueWaves | Real-time cascade failure detector for microservices |
| SSGF | Self-Stabilizing Gauge Field: geometry carrier, ethical cost, PGBO, the topological-integration observable |
| Autotune | Auto-calibration: SINDy, coupling estimation, phase extraction, frequency ID, reward evaluation, replay policy search |
| Meta-Transfer | Replay-backed cross-domain initial policy proposals |
| CLI | spo command-line interface |