DEV Community: Miroslav Šotek

Coordinating multiple AI coding agents on one repo or multiple in your own ecosystem — without git worktrees

Miroslav Šotek — Mon, 22 Jun 2026 18:22:18 +0000

If you have run more than one AI coding agent at once, you have met the failure
mode: agent A is editing src/auth.py while agent B rewrites the same file. One of them loses. The usual fixes are real, but they both dodge the actual problem.

The two usual answers, and what they dodge

Git worktrees. Give each agent its own checkout sharing one .git. They cannot collide on disk, and conflicts surface at merge time. This is isolation — it keeps agents apart so they never have to coordinate. Great until the merges fight.

Agent frameworks (LangGraph, CrewAI, AutoGen). You write the agents and their control flow in one process; one orchestrator spawns sub-agents. Powerful, but it assumes you are building the agents. If you are running off-the-shelf terminal assistants from different vendors, that is not your situation.

Neither lets several independent agents coordinate in real time on a shared tree:
claim work, see a shared plan, talk to each other. That layer — call it a
coordination bus — is what was missing for us, so we built one: SYNAPSE CHANNEL, a local-first WebSocket hub. One dependency, runs on your machine.

pip install synapse-channel
synapse hub --port 8876 --db ./synapse.db   # the coordination hub (crash-safe)

1. Claim before you edit

The core primitive is an advisory file-scope claim. An agent leases a task and declares the paths it will touch; the hub refuses an overlapping claim. The hub never reads your filesystem — the globs are agent-declared.

from synapse_channel import SynapseAgent

agent = SynapseAgent("backend", uri="ws://localhost:8876")
# ... after connect():
await agent.claim("auth-refactor", paths=["src/auth.py", "src/session.py"])
# A second agent claiming any overlapping path is denied — they never touch
# the same file. Leases expire and carry an epoch, so a crashed agent never
# holds a claim forever.

No central orchestrator decides this. Each agent claims for itself; the hub is the single arbiter of overlap.

2. A shared plan, on the command line

There is a dual-ledger blackboard — tasks and progress, with dependencies — that you can drive without writing a client:

synapse task declare BUILD --title "compile" 
synapse task declare TEST --title "run tests" --depends-on BUILD
synapse task update BUILD --status done      # unblocks TEST
synapse board                                # print the shared plan

A held task can be handed off atomically to another agent (scope, status, and context preserved), and an LLM-free supervisor re-offers work that stalls.

3. The interesting bit: waking a turn-based agent

Here is the problem nobody talks about. A turn-based assistant (the kind in your terminal) cannot hold a socket open between turns. So how does it learn a message arrived without burning turns polling?

SYNAPSE turns it into a push. synapse wait blocks on the connection and exits the instant a message addressed to you arrives. You run it as a background task; when it exits, your harness re-invokes the agent. No message → it costs nothing.

# backgrounded: exits + wakes the agent the moment a directed message lands synapse wait --name backend-rx --for backend --directed-only

# from anywhere — message one agent, a project group, or everyone
synapse send --target backend "rebased main, re-pull"
synapse send --target "quantum/*" "freeze, I'm tagging"
synapse send --target all --priority "[deploy] prod is green"

--directed-only keeps routine broadcasts from waking you, while priority messages still get through. Serialise the things that must not overlap — commits above all — by wrapping them in a lease:

synapse lock myrepo:git -- git push   # holds the lease while pushing; others wait

4. It survives a restart

Every claim, release, task, and checkpoint goes into an append-only SQLite log and is replayed on start-up, so a hub restart resumes live leases instead of dropping them. A lapsed claim keeps its checkpoint, so the next agent to take the task resumes rather than restarts. The same log doubles as a cross-agent audit trail — who claimed what, when, and who handed off to whom.

The honest part

We did not design this in the abstract. SYNAPSE coordinates the agents that develop SYNAPSE, every day. Most of the rough edges in the changelog — a missed wake, a waiter that hung after a restart, a ghost connection blocking a re-arm — were problems we hit using it, fixed the same day because they annoyed us directly. A tool its authors depend on gets sharp quickly.

It is local-first by design: a loopback hub, single owner, no cloud. Licence is AGPL-3.0 (free for OSS / research / personal); a pay-what-you-want commercial licence from CHF 9.99 covers closed-source and SaaS use.
Also, you still can buy me a coffee :)

pip install synapse-channel
synapse team   # hub + a couple of local workers, to kick the tyres

Source: https://github.com/anulum/synapse-channel
Docs: https://anulum.github.io/synapse-channel/
Product page: https://anulum.li/synapse/

If you coordinate parallel agents some other way, I would like to hear it — what breaks at three agents? At ten?

We Built a Universal Language for Synchrony — And It Might Be Too Ambitious

Miroslav Šotek — Mon, 08 Jun 2026 12:54:31 +0000

How SCPN Phase Orchestrator v0.8.0 turns Kuramoto dynamics into a domain-agnostic control compiler, why we verify math across five languages, and the honest truth about building a Boeing 747 when most people need a bicycle.

The $5.2 Billion Blackout That Started This

On August 14, 2003, a cascading failure in the US Northeast power grid left 55 million people without electricity. The final report cited something deceptively simple: synchrony loss. A generation unit in Ohio drifted out of phase. The protective relays, designed to prevent damage, tripped in sequence. One desynchronized oscillator triggered a cascade that propagated across 265 power plants in nine minutes.

The grid had controllers. It had models. What it lacked was a shared, reviewable language for coherence — a way to ask, in real time: "Is this synchrony valuable or dangerous? And if I touch this knob, can I prove what will happen before the electrons move?"

That question is why I built SCPN Phase Orchestrator.

It is not a Kuramoto simulator. It is a coherence control compiler — a system that takes any cyclic process (power waves, cloud retries, neural spikes, traffic signals) and compiles it into a unified phase space where synchrony can be observed, classified, and modified with bounded, auditable, replayable actions.

Version 0.8.0 just shipped. It includes something I have not seen in any other open-source oscillator library: cross-language mathematical parity verification and Lean proof obligations for safety-critical control chains. This post is the honest story of why we built it, how it works, and where we might have gone too far.

The Fragmentation Problem

If you work on synchrony in 2026, you live in silos.

Power engineers use PSS/E or PowerFactory with swing-equation models.
Cloud operators use Airflow, Kestra, or Temporal for workflow orchestration — none of which understand phase dynamics.
Neuroscientists use FieldTrip or MNE-Python for EEG phase analysis, but the tools stop at visualization; they do not close the loop.
Roboticists write custom Vicsek models for swarm consensus.
Plasma physicists maintain separate MHD codes for tokamak control.

Every domain has its own vocabulary, its own numerics, its own safety culture. When a power engineer and a cloud architect talk about "retry storms," they are describing the same underlying phenomenon — coupled oscillators with delayed feedback — but they have no shared formalism to prove it.

SCPN Phase Orchestrator (SPO) is an attempt to build that shared formalism without forcing anyone to abandon their domain expertise.

The Core Insight: Phase as a Universal Compiler Target

The Kuramoto model is usually taught as a toy system: N oscillators, sine coupling, an order parameter R. But Strogatz and Acebr\u00f3n showed something deeper in the early 2000s: the Kuramoto model is a mean-field reduction of almost any weakly coupled limit-cycle system. If your system has repeating behavior and weak coupling, it is secretly a Kuramoto network.

SPO treats that insight literally. We built a pipeline that compiles domain-specific cycles into a universal phase space:

Domain Binder -> Oscillator Extractors (P/I/S) -> UPDE Engine -> Supervisor -> Actuation Mapper

The Three Channels

Not all cycles look like sine waves. SPO separates extraction into three channels:

Channel	Source	Phase Extraction
Physical (P)	Continuous waveforms	Hilbert transform, zero-crossing
Informational (I)	Event/decision streams	Event-phase from message timing
Symbolic (S)	Discrete state sequences	Ring-phase $\theta = 2\pi s / N$, graph-walk

A power grid voltage trace goes through P. A microservice retry log goes through I. A traffic light state machine goes through S. All three land in the same phase space.

The Four Knobs

Once in phase space, every control problem reduces to four parameters:

Knob	Meaning
K	Coupling strength (K_nm matrix)
alpha	Phase lag (transport/actuator delays)
zeta	Driver strength (external forcing)
Psi	Reference phase (control target)

This is not abstraction for abstraction's sake. It is a contract. When a supervisor proposes a control action, it proposes a bounded change to one of these four knobs. The action is reviewable because the contract is universal.

R_good vs. R_bad

The most important design decision in SPO: coherence is not one scalar.

Most tools give you an order parameter $R$ and assume higher is better. SPO splits the objective:

R_good: Coherence you want to maintain (actuator locked to target phase)
R_bad: Coherence you want to suppress (harmful mode-locking, retry storms, epileptic seizure rhythms)

A power grid wants high R_good between generators and the grid frequency, but it wants R_bad near zero for inter-area oscillations that can trigger cascading failures. A cloud system wants high R_good for cache coherence, but R_bad near zero for thundering-herd retry patterns.

No other oscillator library makes this distinction explicit.

Show Me the Code

SPO is on PyPI. You can install it and run a deterministic simulation in under a minute:

pip install scpn-phase-orchestrator

The high-level facade does not require understanding the theory:

from scpn import Orchestrator

orch = Orchestrator.from_yaml("domainpacks/minimal_domain/binding_spec.yaml")
state = orch.run(steps=100, seed=42)
print(state.order_parameter)

For ML researchers, the nn/ module exposes JAX/equinox layers that are JIT-compilable, vmap-compatible, and fully differentiable:

from scpn_phase_orchestrator.nn import (
    KuramotoLayer,
    jax_runtime_info,
    require_accelerator,
)

print(jax_runtime_info())
device = require_accelerator()  # fails fast on CPU-only runtimes

layer = KuramotoLayer(n_oscillators=64)
# K and omega are learnable. Use SAF spectral loss for topology optimization.

The upde/ module provides advanced dynamics for researchers who need more than the standard Kuramoto model:

Inertial Kuramoto: Second-order swing equations for power grid stability
Market Kuramoto: Financial regime detection via Hilbert phase
Swarmalator: Coupled spatial + phase dynamics
Simplicial Engine: 3-body higher-order coupling (Gambuzza 2023)
Ott-Antonsen: Exact mean-field reduction for $O(1)$ prediction
Delay Engine: Time-delayed coupling with circular buffers
Stochastic Engine: Euler-Maruyama with auto-tuned optimal noise

What v0.8.0 Actually Adds (And Why It Is Not Just Features)

The jump from 0.6.4 to 0.8.0 was not incremental. It introduced the PHA-C downstream accelerator chain — a formal-acceptance pipeline for moving-frame merge safety.

Polyglot Parity Gates

Here is something I have not found in any other open-source project: SPO now verifies that identical mathematical behavior is produced across five languages.

For every release, the benchmark suite checks parity across Rust, Go, Julia, Mojo, and Python for:

Chimera detection (Kuramoto-Battogtokh local-order vector)
ITPC (Lachaux inter-trial phase-coherence)
Spectral analysis (D\u00f6rfler-Bullo combinatorial graph Laplacian)
Hodge decomposition (gradient / curl / harmonic split)
Transfer entropy (Schreiber histogram estimator)
Entropy production (Acebr\u00f3n overdamped-Kuramoto dissipation)
PHA-C handoff, timeline, and acceptance (moving-frame merge safety)

Why? Because if you are going to propose a control action for a power grid or a medical device, you need to know that the math is the same in the language running on the FPGA, the language running in the browser, and the language running in the Python notebook.

The benchmark snapshot (dated 2026-06-05) records the evidence. The PHA-C acceptance gate runs at ~29 steps/s — slow, because it is doing formal verification at runtime, not just simulation.

Lean Proof Obligations

The PHA-C chain now targets SPOFormal.Kinematic.KinematicBounds and SPOFormal.Continuous with Lean proofs. This means:

Kinematic residuals are bounded by Gronwall envelopes
Phase budgets are discharged by fixed-point certificates
Acceptance records carry proof metadata that must agree with arithmetic discharge before the row passes

This is review-only for now. The quantum, neuromorphic, PLC, and medical actuation adapters remain disabled until a separate operator-approved hardware evidence chain exists. We are not claiming live formal verification on hardware yet. We are claiming that the review artefacts are formally structured.

Audit Trails That Can Be Replayed

Every run produces a SHA256-chained JSONL log. In v0.8.0, the PHA-C chain adds hash-replay validation: tampered scalar evidence or unsafe claim-boundary edits are rejected without needing the original raw arrays.

spo run domainpacks/queuewaves/binding_spec.yaml --steps 1000 --audit audit.jsonl
spo replay audit.jsonl --output report.json --verify

This is not logging. This is deterministic evidence. If a regulator asks "why did the controller propose $K = 0.3$ at $t = 147$?", you can replay the exact numerical path, the supervisor state, and the regime classification.

The Honest Truth: It Might Be Too Much

I need to say this clearly, because dev.to readers deserve honesty: SCPN Phase Orchestrator is over-engineered for most users.

The repository has 492 Python modules, 93 Rust files, 544 tests, 186 documentation pages, and a formal-methods backend that most developers will never touch. The polyglot parity gates run at 3–29 steps/s. The Lean proof obligations require understanding fixed-point arithmetic and Gronwall bounds.

If you just want to simulate 64 Kuramoto oscillators on your laptop, use fabridamicelli/kuramoto. It is mature, simple, and has 100+ stars. If you want pure JAX speed, use jaxkuramoto. If you want neuroscience-specific pipelines, use neurolib.

SPO is for a different use case: systems where the cost of a wrong control action is measured in millions of dollars or human lives, and where the control proposal must be explainable before it reaches hardware.

That is a narrow gate. We know. We are not trying to replace every oscillator library. We are trying to build the one you use when the other libraries stop.

Security Posture: What We Patch and What We Do Not

Because this is a control framework, security is not an afterthought. A few specifics:

CVE-2026-48710 (BadHost): We patched the Starlette Host-header validation boundary in the QueueWaves FastAPI deployment. If you run SPO behind a reverse proxy, validate the Host header at the proxy layer. We pin starlette>=1.0.1.
Hardware adapters: Real hardware access is adapter-scoped and opt-in. Modbus/TLS SCADA requires mutual TLS client certs. Plain Modbus TCP is explicitly restricted to lab networks. BrainFlow sensor input is read-only with no actuation writes.
Quantum/neuromorphic: Compiler outputs are handoff artefacts only. Execution and hardware writes remain disabled until a verified external pipeline is attached.
YAML sandboxing: binding_spec.yaml files are schema-validated but not yet fully sandboxed. Do not load untrusted domainpacks without review.

We run CodeQL, dependency scanning, secret scanning, and Rust audit in CI. We generate capability inventories automatically rather than editing them by hand. But we do not yet generate SBOMs or hash-pin all dependencies — that is on the near-term roadmap.

The Roadmap: Where This Goes

The next six months are about lowering the floor without lowering the ceiling.

SPO Core vs. SPO Formal: We are splitting the project into two tracks. SPO Core will be a simplified, fast, easy-to-use Kuramoto library with closed-loop control. SPO Formal will contain the PHA-C chain, Lean proofs, and polyglot consensus. Same API, different depth.
Auto-coupling discovery: Extend our transfer entropy module to infer $K$ from observational data and validate it against the binding spec. Most users do not know their coupling topology. We should discover it.
Real-time edge bridges: ROS2 connector, MQTT for industrial IoT, OPC-UA for process control. The digital twin domainpack is interesting, but it needs to actually connect to hardware.
Web playground: Expand the WebAssembly module into a full interactive simulator. Drag coupling sliders. Watch phase portraits update in real time. No installation required.
Neuromorphic compilation: Move from review artefacts to actual compilation targets (Intel Loihi, IBM TrueNorth, SpiNNaker). The FPGA kernel (Zynq-7020, sub-15$\mu$s latency) proves we can do hardware targets.
Polyglot consensus control: Run the same control loop in Python, Rust, and Julia simultaneously. Require 2/3 agreement before actuation. Byzantine-fault-tolerant control for oscillator networks.

Try It

pip install scpn-phase-orchestrator
spo demo --domain minimal_domain --steps 20
spo validate domainpacks/queuewaves/binding_spec.yaml

The repository is AGPL-3.0. Commercial licensing is available. If you are working on power grids, fusion plasmas, cloud infrastructure, neuroscience, or any system where cyclic processes need to lock together (or must be kept apart), we would genuinely appreciate your feedback.

The code is at github.com/anulum/scpn-phase-orchestrator. The docs are built with MkDocs. The benchmarks are reproducible. The physics invariants are executable tests.

We know the project is not viral yet. We have done almost no marketing. This post is the beginning of that, but more importantly, it is an invitation: tell us where the friction is. We are updating constantly, and the most valuable input we can get is from people who try to use this for real problems and hit the walls we did not see.

We appreciate sharing, Likes, Contributions, Sponsoring / Donations to keep me going. We are open for collaboration.

Built by ANULUM Institute / Fortis Studio. If you have read this far, thank you. The project is ambitious, possibly too ambitious, but the problem it addresses — the lack of a shared, reviewable language for coherence — is real. We would rather be too ambitious than too narrow.

scpn-quantum-control: The Quantum Workbench for Coupled Oscillator Networks — and Why We Built It Differently

Miroslav Šotek — Mon, 08 Jun 2026 12:26:46 +0000

A fact-based look at v0.9.8, 9,139 tests, 15+ hardware backends, and the only quantum-native automatic differentiation engine for Kuramoto-XY Hamiltonians.

The Problem Nobody Was Solving

In 2024, I needed to run a specific experiment: simulate a network of 16 coupled Kuramoto oscillators on a 156-qubit IBM Heron r2 processor and prove whether quantum synchronisation witnesses could be measured on NISQ hardware.

I looked at the existing tools. Qiskit had the hardware access. PennyLane had the gradients. QuTiP had the dynamics. Cirq had the fine-grained control. But none of them could do what I actually needed:

Take an arbitrary coupling matrix K_nm, a frequency vector ω, and compile them into a quantum circuit that evolves an XY Hamiltonian on real hardware — then measure whether the resulting state exhibits synchronisation.

There was no off-the-shelf tool for this. So I built one.

Eleven months later, scpn-quantum-control is at v0.9.8. It is not a general-purpose quantum computing framework. It is a specialised workbench for a specific class of problems: quantum simulation of coupled oscillator networks. And it is built with a level of engineering discipline that I believe is rare in academic quantum software.

This article is an honest, fact-based account of what it does, how it works, and where it is going.

What It Actually Is (and Isn't)

Let's be precise. scpn-quantum-control is not trying to be the next Qiskit, PennyLane, or Cirq. Those are general-purpose frameworks with millions of users and billions in corporate backing. They own the general quantum computing space.

What scpn-quantum-control does is own a narrow, deep slice of that space:

Kuramoto-XY compiler: Converts arbitrary coupling matrices K_nm and frequency vectors ω into quantum circuits evolving H = Σ K_nm (X_n X_m + Y_n Y_m) + Σ ω_n Z_n
Synchronisation analysis: Measures order parameters R(t), entanglement entropy, Schmidt gaps, and OTOC scrambling on those circuits
Hardware validation: Runs on IBM Heron r2 (156 qubits), IonQ, AWS Braket, Azure Quantum, Quantinuum, Rigetti, QuEra, IQM, Pasqal, OQC, D-Wave, qBraid, Quandela, and local simulators
Evidence ledger: Every hardware claim is classified, traceable, and falsifiable

The codebase is substantial: 767 Python modules, 1,501 public classes, 55 Rust bindings, 27 Rust source files, 98 Jupyter notebooks, 23 examples, and 9,139 tests maintaining 97%+ coverage.

It is maintained by one person (me). It is licensed under AGPL-3.0-or-later with a commercial dual-licensing option. Those are limitations, and I will discuss them honestly.

The Core Technical Stack

1. The Kuramoto-XY Compiler (Unique — No Other Framework Has This)

The heart of the system is the compiler that takes classical oscillator network specifications and produces quantum circuits.

from scpn_quantum_control import QuantumKuramotoSolver

# Define a 4-oscillator coupling matrix
K_nm = [
    [0.0, 1.2, 0.8, 0.0],
    [1.2, 0.0, 1.5, 0.9],
    [0.8, 1.5, 0.0, 1.1],
    [0.0, 0.9, 1.1, 0.0],
]

# Frequencies
omega = [1.0, 1.1, 0.9, 1.05]

# Compile to quantum circuit
solver = QuantumKuramotoSolver(
    K_nm=K_nm,
    omega=omega,
    reps=4,  # Trotter steps
    backend="qiskit_aer"
)

# Run and get order parameter trajectory
result = solver.run()
R_t = result.order_parameter()  # R(t) over time

Under the hood, this compiles to a Trotterised XY Hamiltonian with Ry rotations for frequencies and Rxx/Ryy gates for couplings. The circuit depth scales as O(reps × edges).

Why this matters: Most quantum simulation frameworks assume you already have a quantum circuit. This one assumes you have a classical network graph and builds the circuit for you. That is a different user, and a different problem.

2. Differentiable Programming (v0.9.8 — The Breakthrough)

Released June 1, 2026, v0.9.8 adds what I believe is the only quantum-native automatic differentiation engine for XY Hamiltonians.

from scpn_quantum_control.differentiable import parameter_shift_gradient
from scpn_quantum_control.differentiable import GradientTape

# Parameters: coupling strengths and frequencies
params = {"K_01": 1.2, "K_12": 1.5, "omega_0": 1.0}

with GradientTape() as tape:
    result = solver.run(params)
    energy = result.expectation_value()

# Exact quantum gradients via parameter-shift rule
grads = tape.gradient(energy, params)
# grads["K_01"] = ∂⟨H⟩/∂K_01 = ½[⟨H(K_01+π/2)⟩ − ⟨H(K_01−π/2)⟩]

This is not a toy wrapper. The implementation includes:

Backend-neutral parameter-shift: Works on simulators and hardware, not just Qiskit Aer
JAX bridging: Optional jax extra for JIT compilation and vectorised gradients
PennyLane adapter: Use PennyLane's optimisers with Kuramoto-XY circuits
QSNN trainer integration: Train quantum spiking neural networks with backprop
Reverse-mode AD for linear algebra: Compact reverse replay for det, inv, solve, trace, diag, and matrix chains — exact adjoints instead of scalar expansion

Why this matters: PennyLane has excellent general-purpose quantum AD, but it does not have native support for Kuramoto-XY Hamiltonians. Qiskit has EstimatorV2 primitives but lacks native auto-diff. This makes scpn-quantum-control the only tool where you can train the coupling matrix itself via gradient descent on quantum hardware.

3. The Hardware Evidence Ledger (Best-in-Class Reproducibility)

Every hardware run produces a HardwareResultPack with:

Claim classification: A (analytic), B (simulation), C (hardware), D (extrapolation)
Raw counts: IBM job IDs, measurement outcomes, calibration data
Provenance: capture_provenance() records Python version, dependency versions, git commit, environment
Falsification criteria: Every claim states what would prove it wrong

This is not just "we ran it on hardware." It is epistemic hygiene: a structured way to know what you know, how you know it, and what would change your mind.

The system is strict enough that it has a "release-readiness audit helper" that blocks version tags if hardware claims are not properly documented.

4. Rust Acceleration (5,401× Speedup)

The Hamiltonian construction bottleneck is written in Rust via PyO3:

// Rust: builds dense XY Hamiltonian matrix
pub fn build_kuramoto_hamiltonian(
    K_nm: &[f64],
    omega: &[f64],
    n: usize,
) -> Vec<<Complex64> {
    // O(n²) construction, memory-efficient
    // ...
}

Benchmarks on an M3 Max:

n=4: Classical ODE 0.4ms vs Rust 0.02ms
n=8: Classical ODE 1.4ms vs Rust 30ms
n=12: Classical ODE 2.8ms vs Rust 5,000ms
n=16: Classical ODE 11ms vs Rust ~2min

The Rust crate is not a thin wrapper. It is 27 source files with a Criterion benchmark harness and a deterministic test suite.

5. The Provider-Neutral HAL (15+ Backends)

v0.9.8 introduced a Hardware Abstraction Layer (HAL) with immutable backend profiles and metadata-only discovery for:

IBM Quantum, IonQ, AWS Braket, Azure Quantum, Quantinuum, Rigetti, QuEra/Bloqade, IQM, Pasqal, OQC, D-Wave, qBraid, Quandela, and local simulators.

The Qiskit adapter supports base64-QPY and OpenQASM 3 conversion, with an approval-gated Runtime adapter that requires explicit tokens for cloud submission. This is fail-closed by design.

Real Hardware Results

We have run circuits on IBM Heron r2 (156 qubits, Feb–May 2026). Here is what actually happened:

Experiment	Qubits	Depth	Raw Error	Claim Class
VQE ground state	4	12	0.05%	C
Kuramoto R(t)	4	85	7.3%	C
Kuramoto scaling	6	147	9.3%	C
UPDE (uniform)	16	770	46%	C

The 46% error at 16 qubits is not a failure. It is a measurement of the NISQ coherence wall at depth 250–400 on Heron r2. We are working on mitigation (ZNE, GUESS, DD), but the raw data is honest.

The DLA Parity Theorem — an exact closed-form result for the dimension of the dynamical Lie algebra of XY Hamiltonians — has been validated on hardware with 342 circuits across two phases.

Real-World Applications

This is not just theory. The framework has application plugins for:

Neuroscience: 109-subject EEGMMIDB baseline analysis, phase-locking value (PLV) computation on quantum hardware
Fusion energy: ITER disruption prediction bridge contract with classifier API and 11-feature ordering
Power grids: IEEE 5-bus and 14-bus measured-system coupling artefacts
Plasma physics: H-mode pedestal width prediction via quantum regression

These are not toy examples. The ITER contract includes tamper-evident digests and a downstream non-admission policy.

Engineering Discipline

I want to highlight the infrastructure because I think it matters:

9,139 tests with 97%+ coverage (measured, not estimated)
46 Hypothesis fuzz tests for property-based checking
Mutation testing via mutmut to verify test quality
Performance regression suite ensuring Rust stays ≥2× faster than Python
Cross-validation against QuTiP and Dynamiqs (43 tests)
SBOM generation for every release
Secret scanning with gitleaks and custom vault-pattern scanner
Structured logging via structlog
Capability manifest system generating JSON/Markdown inventory
Software Heritage archival (SWHID recorded)
Zenodo DOI: 10.5281/zenodo.18821930

This is the kind of engineering I would expect from a production SaaS product, not an academic quantum simulation tool.

Honest Limitations

I am not going to pretend this is perfect. Here are the real problems:

1. The License

The project is under AGPL-3.0-or-later with a commercial dual-licensing option (CHF 49–999/month). This is a legitimate choice for copyleft, but it creates adoption friction. Many enterprises have "no AGPL" policies. Startups may not afford the commercial license.

I am documenting a potential lightweight core split (Apache-2.0 for the compiler and AD engine, AGPL for hardware runners and application plugins), but this is not yet implemented. If you are a commercial user, you need to contact me.

2. Single Maintainer

This is a one-person project. I am the only committer, the only reviewer, and the only release manager. The bus factor is 1. With 767 Python modules, 1,501 public classes, and 55 Rust bindings, this is not sustainable.

I am actively looking for co-maintainers. If you understand quantum computing and want to work on something genuinely unique, reach out.

3. Paper 0 - In progress / But it bloats the ecosystem

466 of the 767 Python modules are generated source-accounting fixtures for an unpublished methodology paper (Paper 0). They are coverage-excluded and do not affect runtime, but they inflate the package size. I need to move these to an optional extra.

4. No Quantum Advantage (Yet)

At every scale we can access (n≤16), classical ODE integration beats quantum simulation in both accuracy and speed. The quantum approach is not yet faster or better. It is different — it measures quantum-specific observables (entanglement, OTOC scrambling) that classical simulation cannot. But we have not demonstrated quantum advantage.

The Roadmap

Here is what is coming:

v0.9.9–v0.10.0 (near term):

License core restructure (Apache-2.0 core + AGPL extensions)
Expanded AD test suite (finite-difference verification, JAX agreement tests)
Documentation tutorials for gradient-based training

v0.10.0–v0.11.0 (medium term):

Adaptive Trotter error compensation (auto-adjust reps via commutator norms)
Quantum Graph Neural Networks (QGNN) for learning optimal coupling structures
QSaaS API prototype (FastAPI REST for cloud synchronisation analysis)

v0.12.0+ (long term):

Real-time quantum feedback control (mid-circuit measurement → classical processing → parameter adjustment)
Symmetry-based error mitigation using DLA parity as real-time syndrome
Neuromorphic-quantum hybrid interface (bridge to sc-neurocore)

Who Should Use This?

You should consider scpn-quantum-control if:

You are simulating coupled oscillator networks (Kuramoto, XY, Heisenberg) on quantum hardware
You need exact quantum gradients for variational optimisation of coupling parameters
You are building quantum spiking neural networks (QSNN)
You require hardware evidence ledgers for reproducible NISQ experiments
You are working on quantum-classical co-simulation for complex systems (EEG, plasma, power grids)

You should probably use Qiskit or PennyLane if:

You need general-purpose quantum circuits (arbitrary gates, no network structure)
You are doing standard quantum ML (QAOA, VQE on molecular Hamiltonians)
You need a massive community and ecosystem (tutorials, Stack Overflow, enterprise support)

How to Try It

pip install scpn-quantum-control
# or with JAX support:
pip install scpn-quantum-control[jax]

The repository is at github.com/anulum/scpn-quantum-control. The documentation is at anulum.github.io/scpn-quantum-control.

For hardware access, you will need credentials for your chosen backend (IBM Quantum, AWS Braket, etc.). The framework supports local simulation out of the box via Qiskit Aer.

Final Thoughts

scpn-quantum-control is not trying to be everything to everyone. It is trying to do one thing exceptionally well: simulate coupled oscillator networks on quantum hardware with rigorous evidence and exact gradients.

The field of quantum computing has enough general frameworks. What it needs is specialised tools built with production-grade discipline for specific scientific domains. This is one of them.

If you work on quantum networks, synchronisation theory, or NISQ simulation, I would welcome your feedback, your bug reports, and ideally your contributions.

The code is there. The tests are there. The hardware evidence is there. The gradients are there.

Now we need to make it accessible.

I appreciate sharing, Likes, Contributions, Sponsoring / Donations to keep me going. We are open for collaboration.

Miroslav Šotek is the author of scpn-quantum-control and sc-neurocore. He works on quantum simulation of complex networks and neuromorphic computing. The project is archived on Software Heritage and indexed in the Qiskit Ecosystem Catalog.

License: AGPL-3.0-or-later / Commercial. DOI: 10.5281/zenodo.18821930

I Built a Tokamak Control System Alone. Here's What I Learned About Writing Software That Can't Fail.

Miroslav Šotek — Mon, 08 Jun 2026 12:06:41 +0000

What happens when you apply production-grade security, formal verification, and 3,300+ tests to a physics problem most people solve with MATLAB scripts.

The Audacity

A year ago, I started building SCPN-Control — a framework for controlling tokamak fusion reactors. By myself. As a solo developer.

If you know anything about fusion energy, you know this is absurd. Tokamak control is the domain of national labs, billion-dollar collaborations, and teams of fifty physicists. The DIII-D Plasma Control System has been in production for twenty years. RAPTOR at EPFL runs on actual hardware at TCV. OMFIT at General Atomics has a thousand users.

I have none of that. I have a laptop, workstation (former Minig Rig) and two rather old servers, a GitHub account, and an unhealthy tolerance for partial differential equations.

But I also have something those projects don't: a neuro-symbolic controller architecture with formal verification, end-to-end differentiable physics, and a safety-case infrastructure that treats a research codebase like flight software.

This post isn't a sales pitch. It's a technical autopsy of what happens when you build production-grade scientific software without a production team — and why the result might matter even if it never touches a real tokamak.

What It Actually Is

SCPN-Control is a multi-layered framework. At the bottom: physics kernels. At the top: a compiler that turns formal specifications into stochastic computing circuits. In between: everything.

Layer 1: The Physics Kernel

The core/ module solves the Grad-Shafranov equation — the elliptic PDE that describes magnetohydrodynamic equilibrium in a tokamak. This isn't a toy implementation. It supports:

Fixed and free-boundary solvers (SOR, multigrid, Anderson acceleration, Newton-Kantorovich)
H-mode pedestal profiles via the modified hyperbolic tangent (mtanh)
Coil optimization with shape, X-point, and divertor target constraints
Toroidal 1/R stencil (not the naive Cartesian Laplacian that most educational codes use)

The solver is written in Python with a Rust acceleration backend, but it falls back to Python gracefully if the native library isn't available. This matters because fusion researchers run code on everything from laptops to HPC clusters.

# From src/scpn_control/core/fusion_kernel.py
# The GS* operator — note the sign-corrected toroidal term
a_E = 1.0 / dR2 - 1.0 / (2.0 * R_safe * self.dR)   # East coefficient
a_W = 1.0 / dR2 + 1.0 / (2.0 * R_safe * self.dR)   # West coefficient
a_N = 1.0 / dZ2                                      # North
a_S = 1.0 / dZ2                                      # South
a_C = -2.0 * (1.0 / dR2 + 1.0 / dZ2)                # Center

The free-boundary solver is experimental and documented as such. The fixed-boundary solver is robust enough to generate equilibria for controller testing.

Layer 2: The Controller Stack

The control/ module implements five NMPC (Nonlinear Model Predictive Control) backends:

Internal — projected gradient descent (fallback, zero dependencies)
SciPy — SLSQP for general nonlinear problems
OSQP — first-order ADMM for sparse, real-time problems
CasADi — IPOPT with exact Hessian for research
acados — structure-exploiting SQP with HPIPM, the solver used in autonomous vehicles and robotics

The acados integration is the one I care about. It uses an augmented-state formulation for slew-rate constraints, validates dynamics residuals post-solve, and fails closed if the solver status isn't zero.

# From src/scpn_control/control/nmpc_controller.py
# Augmented state: [x_k, u_{k-1}] for slew-rate constraints
model.disc_dyn_expr = ca.vertcat(x_next, u)  # u becomes next u_last
model.con_h_expr = u - u_last                # slew-rate constraint

But the part that's actually unique is the transport gradient tuning. Using JAX, the controller can backpropagate through the gyrokinetic transport model to optimize source schedules. This means the MPC doesn't just optimize control actions — it optimizes the physics model it's using.

# JAX autodiff through transport — unique in fusion control
def tune_transport_coefficients_for_tracking(self, ...):
    # Gradient of tracking error w.r.t. transport coefficients
    # Finite-difference audit enforced by default

No other fusion control framework has end-to-end differentiable transport. This is either brilliant or insane, and I'm not sure which yet.

Layer 3: The Neuro-Symbolic Compiler

This is the part that makes SCPN-Control different from every other plasma control project.

The scpn/ module implements a Stochastic Petri Net compiler. You write a control policy as a Petri net — places, transitions, inhibitor arcs, timing delays — and the compiler turns it into a stochastic computing circuit that runs on deterministic bitstreams.

Why stochastic computing? Because it's inherently fault-tolerant. A bit-flip in a stochastic bitstream changes the probability by 1/N, not by orders of magnitude. For a fusion reactor where a controller failure means a $2 billion machine eats itself, this matters.

The compiler produces two paths:

Oracle path: standard floating-point arithmetic for debugging
Stochastic path: bitstream-based computation with antithetic variates

# From src/scpn_control/scpn/controller.py
# Antithetic variates for variance reduction
base = rng.random((n_pairs, self._nT))
low_hits = np.sum(base < p_fire[None, :], axis=0)
high_hits = np.sum(base > (1.0 - p_fire)[None, :], axis=0)
counts = low_hits + high_hits

The stochastic path is deterministic (seeded RNG), reproducible, and formally verifiable. Which brings me to the part I'm actually proud of.

The Security Story

Scientific software is usually terrible at security. Researchers write code that reads arbitrary files, executes shell commands, and exposes internal state over the network because "it's just for internal use."

I treated this like flight software from day one.

WebSocket Hardening

The phase/ module exposes tokamak state over WebSockets for real-time monitoring. The original implementation was an unauthenticated pipe. The current version has:

Bearer token + API key authentication
Token-bucket rate limiting (20 commands/sec per client)
TLS enforcement with loopback-only default
Browser origin allowlisting
Command allowlisting (set_psi, set_pac_gamma, reset, stop)
64KB payload caps
Timeout-based backpressure with explicit disconnect counters

# From src/scpn_control/phase/ws_phase_stream.py
def _bucket_rate_limited(self, buckets, key, now):
    capacity = float(self.command_rate_limit)
    refill_rate = capacity / self.command_rate_window_s
    updated_at, tokens = buckets.get(key, (now, capacity))
    elapsed = max(0.0, now - updated_at)
    tokens = min(capacity, tokens + elapsed * refill_rate)
    limited = tokens < 1.0
    if not limited:
        tokens -= 1.0
    buckets[key] = (now, tokens)
    return limited

C++ Compilation Sandbox

The Rust/C++ solver is compiled on-demand if the prebuilt binary isn't available. The compilation path now has:

SHA-256 source verification against a manifest
hmac.compare_digest for timing-safe comparison
Stack canaries (-fstack-protector-strong)
Full RELRO binding (-Wl,-z,relro -Wl,-z,now)
-mtune=generic instead of -march=native (CPU feature leak eliminated)
120-second compilation timeout
Minimal environment (only PATH, TMPDIR, SystemRoot preserved)

Fault Injection Gating

The stochastic controller has a bit-flip fault injection mode for testing. It requires two independent gates to enable:

# Double-gated — nuclear safety standard
if self._sc_bitflip_rate > 0.0 and not self._allow_fault_injection:
    raise ValueError("sc_bitflip_rate > 0 requires allow_fault_injection=True.")
if self._sc_bitflip_rate > 0.0 and os.environ.get("SCPN_ALLOW_CONTROLLER_FAULT_INJECTION") != "1":
    raise ValueError("sc_bitflip_rate > 0 requires SCPN_ALLOW_CONTROLLER_FAULT_INJECTION=1.")

This is how SCRAM systems work. You don't accidentally enable safety overrides.

Path Traversal Elimination

JSONL logging is constrained to a verified root directory with symlink protection:

def _resolve_jsonl_log_path(log_path, log_root):
    resolved = candidate.resolve(strict=False)
    try:
        resolved.relative_to(root)
    except ValueError as exc:
        raise ValueError("log_path must resolve under log_root.") from exc
    if resolved.suffix != ".jsonl":
        raise ValueError("log_path must use a .jsonl suffix.")

Is this overkill for a research project? Yes. But the discipline carries over. When you write every path resolution as if an attacker controls the input, you stop writing bugs even when no attacker exists.

The Formal Verification Layer

This is where I think SCPN-Control is genuinely ahead of the curve — not just for fusion, but for control systems in general.

The scpn/ module includes a Z3 bounded model checking integration for compiled Petri net controllers. It proves:

Place invariants: Markings never exceed bounds
Temporal response: If condition A fires, condition B responds within N steps
Recurrence: Certain states are always revisited
Exclusivity: Conflicting actions never fire simultaneously

Each proof produces a manifest with SHA-256 digests, schema versioning, and mandatory counterexample paths for failed proofs. The safety-case infrastructure requires:

Formal controller proof (Z3/SMT)
Audited differentiable-transport evidence (JAX + finite-difference validation)
Digital-twin update evidence (TRANSP/TSC backed)
All bound to a canonical controller artifact digest
Explicit readiness gate — blocked until all evidence is present

# Safety-case admission — fail-closed
if not manifest.has_all_required_evidence():
    raise SafetyCaseNotReadyError("Controller artifact lacks required evidence.")

This is 10 CFR 50 nuclear safety documentation standard. For a solo project. Written by one person.

I don't know if this makes me disciplined or delusional. But I know no other fusion control project has formal verification of controller logic.

The Honesty Problem

Here's where I stop talking about what's good and tell you what's broken.

49 out of 50 physics fidelity gaps are still open.

The ROADMAP explicitly states:

"Local-dispersion path overpredicts the GENE CBC reference"
"Latest 2000-step adiabatic run did not reach saturated chi_i"
"Do not publish a saturated CBC chi_i value until the longer campaign passes"
"Must not be presented as quantitative cross-code agreement"

The native TGLF-equivalent transport model exists. The nonlinear gyrokinetic solver exists. But they haven't been quantitatively compared against real TGLF or GENE runs. The infrastructure is there — interfaces to GACODE, GENE, GS2, CGYRO, QuaLiKiz — but the evidence isn't.

There is no real hardware timing evidence yet.

The E2E latency benchmark infrastructure is tamper-evident and schema-versioned, but all measurements are synthetic. I haven't run the control loop on a Raspberry Pi 4 or Jetson Nano and published p50/p95/p99 distributions. The <1ms real-time claim is theoretical.

The H-mode Newton Jacobian is incomplete.

The fixed-boundary Newton solver uses a Jacobian derived for L-mode linear profiles. For H-mode mtanh profiles, the Jacobian is wrong, which means convergence is unreliable for the most physically relevant regime.

I document all of this. The ROADMAP is 50+ entries of "not done yet." But documentation doesn't close gaps. Only work does.

What I Learned About Building Software Alone

If you're a solo developer building something ambitious, here's what actually matters:

1. Test Coverage Is a Forcing Function

I have 3,300+ tests and 99%+ coverage. Not because I'm a testing zealot, but because without a team to catch my mistakes, the tests are the team. The CI runs 25 jobs across Linux, Windows, and macOS. Every PR gate fails if coverage drops by 0.1%.

The ratchet effect is real: once you have 99% coverage, you can't justify a lazy commit that drops it to 98%. The number forces discipline.

2. Security Hardening Is Just Input Validation at Scale

Every security fix I implemented was fundamentally about validating assumptions:

Is this file path where I think it is?
Is this config value finite and positive?
Is this library the one I compiled?

When you write every function as if the caller is malicious, you write better code even for internal APIs. The WebSocket hardening made the streaming layer more robust against network partitions. The C++ compilation sandbox caught a -march=native portability bug. Security and correctness are the same thing viewed from different angles.

3. Type Hints Are Documentation That Doesn't Lie

The entire codebase uses from __future__ import annotations and strict type hints. Pydantic v2 models validate configs at the boundary. This isn't just for IDE autocomplete — it's for catching physics bugs.

When plasma_current_target is typed as float and validated as > 0, you can't accidentally pass a negative current or a string. In scientific computing where a sign error means the plasma goes the wrong way, this matters.

4. Honest Documentation Builds Trust Faster Than Hype

The ROADMAP says "49 open fidelity gaps." The README says "requires external resources for experimental validation." The code says raise ValueError("degenerate equilibrium") instead of silently returning NaN.

This is terrible marketing. It's excellent engineering. The fusion community is skeptical of unvalidated claims — with good reason. I'd rather have ten people trust the code because the limitations are explicit than a thousand people distrust it because I oversold.

5. The "Kitchen Sink" Problem Is Real (for now)

The project has 57+ modules. Equilibrium, transport, MHD, edge physics, neural nets, RL, stochastic computing, FPGA export, real-time control, federated learning, formal verification.

Each of these is a career. Together, they're a maintenance burden. The risk isn't that any single module is wrong — it's that the integration surface becomes too large to validate.

My current strategy: extract a scpn-core package with just the GS solver + basic controllers, and keep scpn-control as the full framework. The Unix philosophy applies even to tokamaks.

Where This Goes Next

The immediate priorities are unglamorous:

Hardware timing evidence. Run the E2E benchmark on a Raspberry Pi 4. Measure p50/p95/p99. Publish the results.
Close 5-10 physics fidelity gaps. Install GACODE. Run native TGLF-equivalent vs real TGLF. Document agreement.
Fix the H-mode Jacobian. Implement mtanh derivative for the Newton solver.

The medium-term goals are where the project gets interesting:

End-to-end differentiable scenario: Couple JAX GS solver → differentiable transport → NMPC. Gradient-through-equilibrium is genuinely unique — no one has this.
Certified neuro-symbolic control: Expand Z3 proofs to CTL/LTL specifications. Auto-generate safety certificates. This could be the basis for ITER safety documentation.
Cross-facility federated learning: Extend the FedAvg/FedProx disruption predictor with differential privacy guarantees. Multi-site learning without data sharing.

Why You Should Care (Even If You Don't Care About Fusion)

If you're a software engineer, SCPN-Control is a case study in what happens when you apply production discipline to a research problem. Most scientific code is written to produce a paper. This is written to produce a system.

If you're a physicist, the neuro-symbolic controller architecture is a genuinely new approach to safety-critical control. Stochastic computing + formal verification + differentiable physics is a combination that doesn't exist anywhere else.

If you're a solo developer wondering if you can build something that competes with teams of fifty people: you can. But you have to be more disciplined than they are. You don't have a colleague to catch your sign errors. You have tests, types, and the humility to document what you don't know.

The Code

SCPN-Control is open source under AGPL-3.0-or-later with commercial licensing available.

GitHub: github.com/anulum/scpn-control
Docs: README + ROADMAP (the ROADMAP is the most honest document I've ever written)
Tests: pytest with 3,300+ cases, 99%+ coverage
Install: pip install scpn-control (with optional dependencies for acados, JAX, etc.)

I'm not asking for stars (yet I don't mind them). I'm asking for scrutiny. If you know plasma physics, tear apart the transport solver. If you know control theory, break the NMPC. If you know security, find the holes I missed.

The project is only useful if it's correct. And it's only correct if people prove it wrong.

I appreciate sharing, Likes, Contributions, Sponsoring / Donations to keep me going, we are open for collaboration.

Miroslav Šotek builds software for problems that are supposed to require teams. He is usually wrong about how hard things are, but occasionally right about how to build them.

SCPN Fusion Core: A Control-First, Neuro-Symbolic Software Stack for Tokamak Plasma Control

Miroslav Šotek — Mon, 08 Jun 2026 11:28:57 +0000

SCPN-FUSION-CORE ON GITHUB

We built an open-source software laboratory that treats tokamak plasma control as a compiler problem. Control logic is expressed in formally verifiable Petri nets, compiled to spiking neural networks, and executed at sub-microsecond latencies against physics-informed plant models. It is not a replacement for billion-dollar physics solvers. It is a framework for building, validating, and hardening control algorithms before they touch billion-dollar hardware.

Why Fusion Control Needs a New Software Stack

Nuclear fusion is having a moment. SPARC is aiming for Q ≥ 10. ITER is commissioning its plasma control system. Dozens of private companies are racing toward net energy. But behind the headlines, a quieter crisis is unfolding: the software that controls these machines is not keeping up with the physics.

Tokamak control is a trilemma. You need:

Physical realism — the controller must respect magnetohydrodynamics, transport, and stability limits.
Real-time execution — plasma evolution happens in milliseconds; control loops must close in microseconds.
Auditable safety — when a plasma disrupts, the cost is measured in millions of dollars and months of downtime. The control logic must be inspectable, reproducible, and bounded.

Most existing tools optimize one vertex of this triangle and leave the others informal. Physics codes like GENE, CGYRO, or TRANSP solve the first problem brilliantly, but they run for hours on supercomputers. Control systems like the ITER Plasma Control System (PCS) solve the second and third, but they are bespoke, proprietary, and hard to test against realistic physics outside of the machine itself.

We started SCPN Fusion Core with a simple inversion: make control the primary artifact, and treat physics as the plant model it operates against.

The SCPN Approach: Three Unusual Bets

Bet 1: Control-First Architecture

Instead of solving transport equations and then "bolting on" a controller, we designed the stack from the control loop outward. The central abstraction is a stochastic Petri net — a graph of places, transitions, and contracts that encodes control logic in a formally inspectable way. This net compiles to a spiking neural network (SNN) of leaky integrate-and-fire (LIF) neurons, which executes at hardware-compatible latencies.

The pipeline looks like this:

Petri Net (places + transitions + safety contracts)
    |
    v  compiler.py — structure-preserving mapping
Stochastic LIF Network (neurons + synapses + thresholds)
    |
    v  controller.py — closed-loop execution
Real-Time Plasma Control (sub-millisecond, deterministic replay)
    |
    v  artifact.py — versioned, signed compilation artifact
Deployment Package (JSON + schema + git SHA)

This is not a metaphor. The compiler is implemented in Python, the real-time kernel is in Rust, and the compilation artifact is a signed, schema-versioned JSON bundle that can be audited before deployment.

Bet 2: Evidence-Bounded Claims

Fusion software has a credibility problem. It is easy to write a module called gyrokinetic_transport.py and imply that it replaces a $50M code. It is much harder to prove it.

We adopted a fail-closed validation philosophy. Every scientific claim in the repository is tracked in a machine-readable report with an explicit status:

Accepted: Same-case evidence exists, checksums match, thresholds pass.
Blocked: The claim is not yet supported by external reference data.

For example, our native nonlinear gyrokinetic solver has explicit invariant benchmarks and electromagnetic residual diagnostics, but its full-fidelity status is blocked until it produces same-case comparison artifacts against GENE, CGYRO, or GS2. The report is public, the debug traces are row-level, and the thresholds are declared in advance. We do not hide incomplete work in prose.

This makes the repository useful before plant deployment. It is a place to test controller architectures, benchmark kernel choices, and build the documentation discipline needed for later hardware-in-the-loop work.

Bet 3: Formal Verification in Lean 4

Real-time control of a burning plasma is a safety-critical problem. We believe that claims about safety properties should be machine-checkable, not just well-intentioned.

SCPN Fusion Core includes a committed Lean 4 proof surface. The first machine-checkable theorems prove that:

Invalid Grad-Shafranov case descriptions fail closed (validation errors propagate exactly).
PID saturation bounds are preserved under normalization and filtering.
Petri net reachability and token boundedness are preserved by the SNN compiler.

These are intentionally narrow boundaries — we are not claiming to have verified the full plasma solver. But they are a start, and no other open-source fusion project has them.

Architecture at a Glance

The repository is a polyglot workspace:

Layer	Technology	Role
Control Compiler	Python	Petri net → SNN compilation, contract checking, artifact packaging
Real-Time Kernels	Rust (11 crates)	PID, MPC, transport, ML inference, PyO3 bindings
Physics Models	Python + JAX	Grad-Shafranov, 1.5D transport, gyrokinetic operators, MHD stability
Validation	Python + Rust	Benchmark pipelines, reference data, report generation
Formal Proofs	Lean 4	Safety theorems, CI-checked

Key Numbers

0.52 µs — Rust PID kernel step latency (P50), measured via Criterion on an Intel i5-11600K.
10.5 µs — Closed-loop hardware-in-the-loop step latency (P50).
413 µs — Rust full-order Grad-Shafranov SOR solve (33×33).
~24 ns — QLKNN-10D neural transport surrogate per-point inference.
3,815 — Test functions (Hypothesis property-based tests in Python, proptest in Rust).
74 — Validation scripts producing tracked reports.

The Three-Path Gyrokinetic Design

We expose three gyrokinetic transport lanes with explicit fidelity limits:

Path	Fidelity	Speed	Module
A: External GK	Reference (when installed)	Minutes to CPU-hours	GENE, CGYRO, GS2, TGLF, QUALIKIZ adapters
B: Native GK	Linear + nonlinear 5D operator contracts	~0.3 s/surface linear	`gk_eigenvalue`, `gk_quasilinear`, `gk_nonlinear`
C: Hybrid Surrogate+GK	Adaptive	~24 ns/point	QLKNN + OOD detector + online corrector

The hybrid layer validates neural surrogates against GK spot-checks in real time. External adapters carry explicit metadata distinguishing linear from nonlinear electrostatic/electromagnetic models. We do not bundle or replace those solvers; we validate against them.

What We Built vs. What We Blocked

Honesty is cheaper than hype. Here is the current capability matrix with explicit blockers:

Built and validated (local contracts):

Neuro-symbolic SNN compiler with deterministic replay
Rust real-time PID/MPC kernels
1.5D coupled transport solver (JAX-differentiable)
QLKNN-10D and FNO neural surrogates
Native linear gyrokinetic eigenvalue solver
7-criterion MHD stability suite
Disruption chain (thermal quench → current quench → runaway → halo)
Lean 4 safety proofs for validation error propagation and PID boundedness

Blocked (waiting for same-case external parity):

Full nonlinear 5D gyrokinetic turbulence parity vs. GENE/CGYRO/GS2
Full kinetic runaway-electron distribution parity vs. DREAM
Charge-state-resolved impurity transport parity vs. Aurora/STRAHL
EFIT-grade free-boundary equilibrium reconstruction
Production-scale MPI/multi-GPU scaling evidence

The blocked items are not hidden. They are tracked in validation/reports/ with row-level debug traces, explicit threshold declarations, and deterministic CI behavior.

How It Compares

Capability	SCPN	TORAX	FUSE	FreeGSNKE	DREAM
Control-first architecture	Yes	No	No	No	No
Neuro-symbolic SNN compiler	Yes	No	No	No	No
Real-time kernel <1 µs	0.52 µs	No	No	No	No
Formal verification	Lean 4	No	No	No	No
JAX autodiff transport	Yes	Yes	No	No	No
1.5D coupled transport	Yes	Yes	Yes	No	No
Neural transport surrogate	QLKNN-10D	QLKNN-7/10D	No	No	No
Full GK turbulence	Blocked	TGLF only	TGLF only	No	No
Full kinetic runaway	Blocked	No	No	No	Yes
Free-boundary GS	Partial	No	No	Yes	No

The positioning: TORAX is a physics-first transport simulator with excellent JAX autodiff. FUSE is a reactor design framework with OpenMC neutronics. FreeGSNKE is an equilibrium reconstruction tool. DREAM is the runaway-electron gold standard. SCPN is the control layer that can interface with all of them. We are not trying to replace them. We are trying to make it possible to test control algorithms against them without a tokamak.

Who This Is For

Fusion control researchers who need a fast, differentiable plant model to prototype controllers.
Validation engineers who need reproducible benchmark pipelines with explicit fidelity gates.
Accelerator/GPU teams who need deterministic decomposition contracts for production scaling.
Formal methods contributors who want to extend machine-checkable safety proofs to physical systems.
Investors evaluating whether a fusion team's control software is reproducible before the team has a machine.

Try It

# Install (Python only, Rust optional)
pip install -e .

# Run a Grad-Shafranov equilibrium
scpn-fusion kernel

# Run the tokamak flight simulator
scpn-fusion flight

# Run the validation suite
pytest tests/ -x -q

# Run the Golden Base notebook
jupyter notebook examples/neuro_symbolic_control_demo_v2.ipynb

# Or spin up the Streamlit dashboard
docker compose up --build  # localhost:8501

The Rust backend is optional but recommended for real-time work:

cd scpn-fusion-rs
cargo build --release && cargo test
cargo bench  # Criterion benchmarks

The Road Ahead

The next milestones are narrow and specific:

One accepted full-fidelity artifact. We are working to produce a same-case nonlinear gyrokinetic comparison against GENE. One accepted row changes the narrative from "blocked" to "validated."
Hardware validation. We are seeking partnerships with university tokamaks to validate the SNN controller on real hardware. Even a single shot with a compiled Petri-net controller would be a landmark.
Extended formal proofs. The Lean surface will expand to cover SNN deterministic replay over seeded stochastic traces, and matrix-level incidence preservation against the Python compiler artifact.
Security hardening. We are adding a formal threat model, input fuzzing for GEQDSK/IMAS parsers, and a safety certification roadmap for industrial adoption.

License & Commercial Use

SCPN Fusion Core is released under AGPL-3.0. This keeps the open-source stack free and inspectable. For commercial use in proprietary plant software, a separate commercial license is available: protoscience@anulum.li.

Citation

@software{scpn_fusion_core,
  title   = {SCPN Fusion Core: Neuro-Symbolic Tokamak Control Suite},
  author  = {Sotek, Miroslav},
  year    = {2026},
  url     = {https://github.com/anulum/scpn-fusion-core},
  version = {3.9.9}
}

Join Us

Repository: github.com/anulum/scpn-fusion-core
Discussions: GitHub Discussions for Q&A and ideas
Documentation: anulum.github.io/scpn-fusion-core
Contact: protoscience@anulum.li

We are looking for contributors in Rust real-time systems, JAX differentiable physics, formal verification, and tokamak experimental physics. If you believe that control software for fusion should be open, inspectable, and evidence-bounded, we would like to hear from you.

The project is currently at version 3.9.9. It is not viral. It is not a startup. It is a software laboratory. We are building it because someone has to. We appreciate sharing, Likes, Contributions, Sponsoring / Donations to keep us going, we are open for collaboration.

Kindest Regards, Miroslav Šotek, lead researcher.

System Architecture: Deterministic Claim-Level Halting for LLM Hallucinations using Rust and Dual-Entropy Scoring

Miroslav Šotek — Mon, 08 Jun 2026 10:43:08 +0000

The current standard for LLM hallucination detection is a structural liability. In production enterprise environments, evaluating an output for factual coherence after the entire payload has been generated and transmitted is mathematically and operationally insufficient. In strictly regulated domains—such as financial analytics, compliance frameworks, or clinical data parsing—a single fabricated integer or hallucinated citation invalidates the entire downstream pipeline.

Auditing the error post-hoc is a failure state. The system must possess the capability to sever the generation in real-time.

To resolve this, I architected Director-AI (currently at stable release v3.14). It functions as a drop-in middleware circuit breaker that executes deterministic, token-level streaming halts using a dual-entropy scoring engine, powered by Rust-accelerated compute paths.

The Flaw in Post-Hoc Verification

Most "AI Safety" wrappers operate as parallel or sequential API calls. They wait for the primary LLM to complete its generation, pass the output to an evaluation model, and return a pass/fail boolean. This introduces three critical bottlenecks:

Massive Latency Overhead: Doubling the time-to-first-token (TTFT) and total generation time.

Compute Waste: Processing thousands of tokens in a sequence that was already corrupted at token 15.

Data Exposure: Allowing unverified, potentially non-compliant data to exist in memory or enter logging pipelines.

The Director-AI Solution: Real-Time Interception

Director-AI sits between the client and the LLM provider as an asynchronous streaming proxy. As tokens are generated, they are buffered in micro-batches and evaluated against a dual-entropy scoring algorithm before being forwarded to the client.

Dual-Entropy Scoring Mechanism

The core evaluation logic relies on two distinct axes of verification, combined to calculate a total system entropy state:

NLI (Natural Language Inference) Contradiction Detection: Evaluates if the current token sequence logically contradicts the established premise or prompt constraints using the 0.4B FactCG-DeBERTa model.

RAG (Retrieval-Augmented Generation) Fact-Checking: Cross-references the emerging semantic claim against a validated vector-database context.

If the combined entropy exceeds the defined safety threshold, Director-AI immediately terminates the TCP connection to the LLM and injects a standard exception to the client.

Rust-Accelerated Compute Paths

To execute this evaluation without degrading the user experience, the middleware overhead must remain negligible.

Director-AI shifts intensive operations away from the Python network layer. The v3.14 architecture implements 12 core compute paths natively written in Rust, delivering a 9.4× geometric mean speedup over equivalent Python code blocks. By avoiding garbage-collection pauses and parallelizing tensor evaluations directly on the incoming token stream, it enforces real-time validation. The codebase is backed by over 4,310+ passing tests, guaranteeing strict memory safety and predictable execution under peak API loads.

Cryptographic Auditability for Zero-Tolerance Domains

For banking infrastructure and financial analytics systems, simply halting an invalid output is not enough; the security event must be auditable without violating global data privacy laws.

Director-AI is explicitly architected to align with the EU AI Act, GDPR, and Swiss revDSG frameworks. It achieves this through a zero-knowledge audit pipeline.

Instead of writing plaintext queries to log files, the AuditLogger processes all telemetry into structured JSONL files, utilising one-way SHA-256 query hashing.

Operational Impact: System administrators can mathematically prove that a specific guardrail was active and triggered at a precise Unix timestamp, without ever storing, exposing, or caching the user's proprietary, high-sensitivity prompt data.

Deployment Mechanics

Director-AI operates as a framework-agnostic drop-in. It does not require modifying frontend applications or fine-tuning underlying models. You route your existing OpenAI, Anthropic, or local LLM API base URLs through the Director-AI port, and the middleware handles the token interception autonomously.

The system is deployed under a dual-licensing model (Apache-2.0 AND BUSL-1.1, v3.14→v3.16. open-core, with proprietary enterprise extensions).

Examine the open-core capability manifest, architecture diagrams, and deployment instructions on GitHub:

https://github.com/anulum/director-ai

I built an open-source real-time LLM hallucination guardrail — here are the benchmarks

Miroslav Šotek — Sun, 29 Mar 2026 01:17:47 +0000

What is Director-Class AI?

An open-source Python library that guards LLM output in real time. It watches tokens as they stream and halts generation the moment it detects a hallucination.

It uses NLI (Natural Language Inference via DeBERTa/FactCG) and optional RAG knowledge grounding to score each claim against source documents.

pip install director-ai

Two-line integration:

from director_ai import guard
client = guard(openai.OpenAI())  # wraps any OpenAI/Anthropic client

Benchmarks (measured, not aspirational)

Metric	Value	Conditions
Balanced accuracy	75.8%	FactCG on LLM-AggreFact (29,320 samples)
GPU latency	14.6ms/pair	GTX 1060, ONNX, batch=16
L40S latency	0.5ms/pair	FP16, batch=32
E2E catch rate	90.7%	Hybrid mode, 600 HaluEval traces
Rust BM25 speedup	10.2x	Over pure Python implementation

Framework Integrations

LangChain, LlamaIndex, LangGraph, CrewAI, Haystack, DSPy, Semantic Kernel, and SDK Guard (wraps OpenAI/Anthropic/Bedrock/Gemini/Cohere clients).

Honest Limitations

NLI-only scoring needs KB grounding for domain use (medical FPR=100% without KB)
ONNX CPU is slow (383ms/pair) — GPU recommended
Long documents need >=16GB VRAM
Summarisation accuracy weakest (AggreFact-CNN 68.8%)

Quality

3,545 tests, 91% coverage
Sigstore-signed releases, SLSA provenance
OpenSSF Best Practices: 100%
19 badges of CI/security health