Skip to content

Frequently Asked Questions

What is the Kuramoto model?

A system of \(N\) coupled phase oscillators: \(\dot{\theta}_i = \omega_i + \frac{K}{N} \sum_j \sin(\theta_j - \theta_i)\). Above a critical coupling \(K_c\), oscillators spontaneously synchronize.

What does "domain-agnostic" mean?

The orchestrator separates topology from physics. A binding_spec.yaml declares oscillator names, frequencies, coupling templates, and policy rules without referencing any particular domain. The same solver handles plasma stability, neural coherence, or microservice health.

Do I need Rust?

No. Pure Python works out of the box. Build the optional spo_kernel extension for the active interpreter with python tools/install_spo_kernel.py --release. Selected UPDE, coupling, monitor, oscillator, and supervisor hot paths delegate to Rust when their bindings are available; unsupported paths retain the Python implementation. Performance varies by operation, size, build, and host, so use the dated measurements in the Rust FFI guide as local regression evidence rather than a deployment guarantee.

What Python versions are supported?

Python 3.11–3.13. The package metadata and CI matrix enforce that range.

How do I add a new domain?

Run spo scaffold <name> to generate starter files, then follow the New Domain Checklist tutorial. If you have a configured LLM gateway, spo scaffold <name> --llm --description "..." can generate a reviewable binding proposal; without provider configuration it fails closed and writes nothing.

What is R_good vs R_bad?

Dual-objective coherence control. R_good is the order parameter for oscillators that should synchronize (e.g., EEG gamma band). R_bad is the order parameter for oscillators that should remain desynchronized (e.g., pathological seizure coupling). The supervisor tries to maximise R_good while minimising R_bad.

How does the Petri net relate to regimes?

The Petri net is a formal finite-state machine for multi-phase protocols. Each Place corresponds to a regime (e.g., BASELINE, ENTRAINMENT, RECOVERY). Guard expressions on transitions evaluate phase metrics (R_global, boundary violations) to decide when regime changes fire. PetriNetAdapter wraps RegimeManager with this FSM layer.

What is Stuart-Landau mode?

The standard Kuramoto model tracks only phase. StuartLandauEngine extends this to phase+amplitude coupling via the Stuart-Landau ODE: \(\dot{z}_i = (\mu_i + i\omega_i)z_i - |z_i|^2 z_i + K \sum_j A_{ij}(z_j - z_i)\). Use it when amplitude dynamics matter (e.g., neural oscillation power, oscillation death).

How does deterministic replay work?

AuditLogger writes a SHA256-chained JSONL file. Each line hashes the previous line's hash plus the current payload. ReplayEngine rebuilds the full engine from the header record, re-runs every step, and compares state vectors within tolerance (atol=1e-6 by default). The hash chain independently validates log integrity — a single tampered byte breaks the chain.

What is QueueWaves?

A research cascade-monitoring application that maps microservice queue depth and latency metrics onto Kuramoto oscillators. It emits a phase-coherence alert when configured metrics cross their thresholds. The repository does not yet establish prospective lead time or superiority over ordinary service alerts. See the QueueWaves guide.

How do I integrate with Prometheus?

Runtime observability is enabled by default. The HTTP runtime exposes /api/metrics as Prometheus text with spo_r_global, spo_stability_proxy, spo_pac_max, spo_latency_ms, spo_step, and per-layer gauges through scpn_phase_orchestrator.runtime.observability.

OpenTelemetry remains an optional export backend: OTelExporter validates spans and metric records even when the OTel extra is not installed, then emits them when scpn-phase-orchestrator[otel] is available. Historical adapter imports remain compatibility aliases.

How are runtime requests rate-limited?

Runtime network security uses token-bucket limiting. Each key accrues tokens at the configured per-minute rate up to a bounded burst capacity; a caller can only send a burst while tokens remain. This prevents a client from consuming an entire fixed-window allowance at the start of a minute.

How are Petri-net guard contexts validated?

Petri-net guards evaluate only declared metric names. Unknown context keys, non-numeric values, and non-finite values are rejected before transition evaluation. This keeps guard decisions tied to the binding or adapter contract instead of accepting arbitrary runtime dictionary content.

What is PAC?

Phase-Amplitude Coupling, quantified by the Modulation Index (Tort et al., 2010). scpn_phase_orchestrator.upde.pac.modulation_index computes MI between a low-frequency phase signal and a high-frequency amplitude envelope. High MI indicates cross-frequency coupling.

What are the four control knobs?

Knob Symbol Effect
Coupling strength \(K\) How strongly oscillators pull each other
Phase lag \(\alpha\) Sakaguchi lag shifts the coupling function
Driver amplitude \(\zeta\) Strength of external forcing
Target phase \(\Psi\) Desired phase offset for entrainment

Policy rules adjust these knobs in response to regime transitions and boundary violations.

What is the nn/ module?

A differentiable Kuramoto backend built on JAX and equinox. It exposes oscillator dynamics as learnable neural network layers: KuramotoLayer, StuartLandauLayer, simplicial 3-body coupling, BOLD hemodynamic signal, reservoir computing, UDE-Kuramoto (physics + neural residual), inverse coupling inference, and an oscillator Ising machine (OIM) for combinatorial optimization. All functions are jax.jit-compilable and jax.vmap-compatible.

Install: pip install scpn-phase-orchestrator[nn]

See the Differentiable Kuramoto guide.

What are the UPDE engines?

SPO ships 18 phase-dynamics variants — the standard Kuramoto plus 17 extensions, reductions, and analysis engines (the homepage counts the 9 core time-stepping integrators; the list below adds the reductions and analysis tools):

  1. Standard Kuramoto — first-order phase coupling
  2. Stuart-Landau — phase + amplitude with Hopf bifurcation
  3. Inertial — second-order swing equation for power grids
  4. Market — financial regime detection via Hilbert phase
  5. Swarmalator — coupled spatial position + phase (robotics, biology)
  6. Stochastic — Euler-Maruyama with optimal noise D*
  7. Geometric — torus-preserving SO(2) exponential map integrator
  8. Delay — time-delayed coupling with circular buffer
  9. Simplicial — 3-body higher-order interactions (Gambuzza 2023)
  10. Splitting — Strang operator splitting (exact rotation + RK4 coupling)
  11. Hypergraph — k-body coupling with explicit edge lists
  12. Sparse — CSR-based O(N+E) integration for large networks
  13. Sheaf — multi-dimensional block coupling on cellular sheaves
  14. Ott-Antonsen — exact mean-field reduction for Lorentzian g(ω)
  15. Prediction — FEP-Kuramoto variational predictor
  16. Adjoint — gradient computation for K optimisation
  17. Bifurcation — continuation and critical point tracking
  18. Basin Stability — Monte Carlo stability analysis

See the Advanced Dynamics guide.

Can SPO detect market crashes?

The upde.market module extracts instantaneous phase from price/return time series via Hilbert transform, computes the Kuramoto order parameter R(t) across assets, and classifies synchronisation regimes. sync_warning() flags a configured threshold crossing. This is retrospective diagnostic machinery: SPO has not established out-of-sample crash prediction, trading utility, or lead time, and the literature examples are not validation of this package.

What is the SSGF?

The Self-Stabilizing Gauge Field is a free energy framework that maps Kuramoto dynamics to Friston's Free Energy Principle. The ssgf/ module implements the carrier field, Langevin noise injection, Boltzmann weighting, free energy closure, and the topological-integration observable (H1 persistent homology, p_h1) and PGBO (Phase Gradient Boundary Observer) constructs from the SSGF module.

Can SPO solve combinatorial optimization problems?

It can generate heuristic candidates. The nn.oim module implements an Oscillator Ising Machine that maps graph coloring, max-cut, and QUBO problems to Kuramoto phase clustering. Oscillators connected by graph edges repel from the same phase cluster. The dynamics can settle into candidate colourings, which callers must validate; hard instances can remain in local minima and no optimality guarantee is made. The implementation is differentiable via JAX for gradient-based energy minimisation.

What is inverse Kuramoto?

Given observed phase trajectories (from EEG, sensors, market data), the nn.inverse module infers the coupling matrix K and natural frequencies ω by backpropagating through the Kuramoto ODE solver. L1 sparsity penalty discovers network topology (which oscillators are actually coupled).

How does stochastic resonance work?

Counter-intuitively, adding noise at the optimal level D = K·R_det/2 increases synchronization. The upde.stochastic engine implements Euler-Maruyama integration with automatic D tuning. The effect is explained by the modified Bessel equation in the self-consistency condition (Acebrón et al. 2005).

What is the Ott-Antonsen reduction?

An exact analytical reduction of the N-oscillator Kuramoto system to a single complex ODE: dz/dt = -(Δ + iω₀)z + (K/2)(z - |z|²z). Valid for globally-coupled oscillators with Lorentzian frequency distribution. Used by the PredictiveSupervisor as a fast forward model for MPC (O(1) computation vs O(N) for full simulation).

How do I report a security vulnerability?

Follow the responsible disclosure process in SECURITY.md. Do not open a public issue.

How do I cite this project?

Use the metadata in CITATION.cff, which is machine-readable by Zenodo, GitHub, and most reference managers.

How to use this FAQ in evaluations

For technical reviews, this FAQ is best used as a route map:

  • read the domain or control question first,
  • confirm the implementation path in the linked guides,
  • verify the answer in a smoke command or replay output.

For procurement or operator review, pair each answer with one reproducible proof artifact (spo validate, replay log, benchmark command, or lockfile snapshot). That makes each response auditable instead of declarative.

For implementation review, prioritize links that map to explicit code paths and gated commands over broad capability descriptions.