DEV Community

Cover image for scpn-quantum-control: The Quantum Workbench for Coupled Oscillator Networks — and Why We Built It Differently
Miroslav Šotek
Miroslav Šotek

Posted on

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

#quantumcomputing #opensource #differentiableprogramming #rust

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
Enter fullscreen mode Exit fullscreen mode

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)⟩]
Enter fullscreen mode Exit fullscreen mode

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
    // ...
}
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Top comments (0)