Rust FFI Acceleration

The spo-kernel Rust workspace accelerates selected paths across the engine, coupling, supervisor, SSGF, monitor, extraction, and autotune surfaces. Recorded local speedups vary substantially by operation, size, build, and host. Python classes auto-detect the compiled spo_kernel module and delegate transparently—no application-code change is needed.

For runtime selection across Rust, Python, JAX, and auxiliary research backends, see Backend Fallback Chain.

Prerequisites

• Rust 1.83+ (workspace MSRV)
• maturin (pip install maturin)

Building

Use the repository helper so maturin runs through the Python interpreter that owns the target environment:

python tools/install_spo_kernel.py --release

This compiles all Rust crates and installs spo_kernel into the active Python environment. To target the repository virtual environment explicitly:

.venv/bin/python tools/install_spo_kernel.py --release

Verify the selected environment:

python tools/install_spo_kernel.py --check-only

The equivalent raw maturin command is:

python -m maturin develop --release -m spo-kernel/crates/spo-ffi/Cargo.toml

Using python -m maturin is intentional: it prevents a globally installed maturin executable from building into a different interpreter than the one used by spo run, tests, or notebooks.

You can inspect the command without compiling Rust:

python tools/install_spo_kernel.py --dry-run --json

After installation, direct import should work:

import spo_kernel
print(spo_kernel.PyUPDEStepper)

Auto-Delegation

Python classes check for spo_kernel at construction time. If present, hot paths delegate to Rust with no API change:

from scpn_phase_orchestrator import UPDEEngine

engine = UPDEEngine(n_oscillators=64, dt=0.01, method="rk4")
# engine._rust is a PyUPDEStepper if spo_kernel is installed
# engine._rust is None otherwise (pure numpy fallback)

The _compat.HAS_RUST flag controls delegation globally. Set it to False in benchmarks to force the Python path.

Accelerated Modules

Python Class / Function	Rust FFI Class	Hot path
UPDEEngine	PyUPDEStepper	step(), run()
StuartLandauEngine	PyStuartLandauStepper	step(), run()
CouplingBuilder	PyCouplingBuilder	build(), project()
ImprintModel	PyImprintModel	update(), modulate_coupling(), modulate_lag()
compute_order_parameter	order_parameter	single call
compute_plv	plv	single call
modulation_index	pac_modulation_index	single call
pac_matrix	pac_matrix_compute	full NxN
CoherenceMonitor	PyCoherenceMonitor	compute_r_good(), compute_r_bad(), detect_phase_lock()
RegimeManager	PyRegimeManager	evaluate(), transition()
ActionProjector	PyActionProjector	project()
BoundaryObserver	PyBoundaryObserver	observe()
SupervisorPolicy	PySupervisorPolicy	decide()
PhaseQualityScorer	PyPhaseQualityScorer	score(), is_collapsed()
LagModel	PyLagModel	estimate()
NeurocoreBridge	PyLIFEnsemble	step() (LIF ensemble, 325x at N=10000)
Physical extractor	physical_extract	analytic signal extraction
Symbolic extractors	ring_phase, graph_walk_phase, transition_quality	single call
Informational extractor	event_phase	timestamp analysis
SimplicialEngine	simplicial_run	3-body coupling run()
HypergraphEngine	hypergraph_run	k-body coupling run()
GeometricEngine	geometric_run	SO(2) exp map run()
extract_envelope	envelope_rms_rust	cumulative-sum RMS
OttAntonsenReduction	oa_run_rust	run(), steady_state_R(), predict_from_oscillators()
SplittingEngine	splitting_run_rust	Strang split run()
te_adapt_coupling	te_adapt_coupling_rust	TE-directed coupling update
UniversalPrior.log_probability	prior_log_probability_rust	Bayesian log-density
load_hcp_connectome	load_hcp_connectome_rust	synthetic connectome generation
GeometryCarrier.decode	carrier_decode_rust	softplus(A·z) decode
compute_ethical_cost	compute_ethical_cost_rust	SEC + CBF ethical cost
classify_sleep_stage	classify_sleep_stage_rust	AASM stage classification
EVSMonitor._frequency_specificity	frequency_specificity_rust	target/control ITPC ratio
PhaseSINDy.fit	sindy_fit_rust	STLSQ sparse regression
estimate_coupling	(disabled)	normal equations (3x slower than LAPACK)
extract_phases	(disabled)	naive DFT (60x slower than SciPy FFT)

Benchmark Comparison

bench/run_benchmarks.py measures UPDEEngine.step() with RK4, averaged over 1000 steps after 50 warmup iterations. The table is a historical local snapshot. Re-run the benchmark and record host/build metadata before using a number for capacity planning.

N	Python (numpy)	Rust (spo_kernel)	Speedup
16	~25 us/step	7.3 us/step	3.4x
64	~180 us/step	28 us/step	6.4x
256	~2.8 ms/step	0.32 ms/step	8.7x
1024	~45 ms/step	8.6 ms/step	5.2x

The speedup saturates at large N because both paths are O(N^2) in coupling computation; the Rust advantage comes from avoiding Python interpreter overhead and numpy dispatch per operation.

LIF Ensemble (NeurocoreBridge)

The PyLIFEnsemble accelerates the neurocore bridge's spiking neuron simulation. Measured on Windows 11, Python 3.12, Rust 1.93.0 release build, N=10000 neurons (10 layers × 1000), 100 substeps:

Backend	Time	ns/neuron/substep	Speedup vs scalar
Rust (PyLIFEnsemble)	0.004 s	3-6 ns	325×
NumPy (vectorised)	0.014 s	14 ns	93×
Scalar (sc-neurocore per-neuron)	1.306 s	1,306 ns	1×

The recorded 4 ms per 100-substep result is local throughput evidence. It does not establish a 250 Hz control-loop deadline: end-to-end sensing, scheduling, transport, actuation, jitter, and worst-case latency were not measured.

Crate Structure

spo-kernel/
  Cargo.toml          # workspace root
  crates/
    spo-types/        # Shared types: UPDEState, LayerState, Regime, Knob, ControlAction
    spo-engine/       # 53 modules: UPDE (12 engines), coupling (11), monitors (14), SSGF (3), autotune (4), + support
    spo-oscillators/  # Physical, informational, symbolic, quality extractors
    spo-supervisor/   # Boundaries, coherence, policy, projector, regime manager
    spo-ffi/          # PyO3 bindings (this is what maturin builds)

All pure-logic crates (spo-types, spo-engine, spo-oscillators, spo-supervisor) have #![no_std] aspirations but currently use std for HashMap and Vec. Only spo-ffi depends on PyO3 and numpy.

FFI Numeric Precision Contract

The Python/Rust boundary is a float64 contract:

• Python passes contiguous numeric arrays after shape, finite-value, and domain validation.
• Rust kernels return float64-compatible values and Python revalidates shape, finiteness, and physical bounds before accepting the result.
• Phase outputs are normalised to [0, 2π) unless the documented monitor contract returns a unitless score or matrix.
• Fixed-point formal manifests are separate review artefacts; they do not change the runtime float64 solver contract.

Any new FFI path must add a module-specific parity test that compares Python and Rust on the same seeded input and documents the tolerated absolute or relative error. Safety-critical gates must fail closed when either backend emits NaN, infinity, shape drift, or a value outside the declared physical range.

Contributing Rust Code

Run all three before submitting:

cargo fmt --all
cargo clippy --workspace -- -D warnings
cargo test --workspace

The CI pipeline runs:

Job	Matrix	What
rust-check	3 OS (Linux, macOS, Windows)	cargo fmt --check, clippy -D warnings, cargo test
ffi-test	3 OS x 2 Python (3.11, 3.12)	maturin develop --release, pytest tests/
cargo-audit	Linux	cargo audit for known vulnerabilities
cargo-deny	Linux	RustSec advisories, banned wildcard dependencies, and source registry policy
rust-miri	Linux nightly	Miri smoke tests for pure-Rust type/supervisor crates
rust-msrv	Linux	Verify builds on Rust 1.83.0

Numerical Parity

The Rust and Python implementations produce identical results to float64 precision. The CI ffi-test job runs the full Python test suite with spo_kernel installed, confirming parity across all integration methods (euler, rk4, rk45) and both engines (UPDEEngine, StuartLandauEngine).