API Reference

July 7, 2026 · View on GitHub

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

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,
    PhaseExtractor,
    PhaseState,
    QPUDataArtifact,
    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
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