scpn-quantum-control 0.9.5

NISQ quantum simulation of coupled Kuramoto oscillator networks via XY Hamiltonian mapping

scpn-quantum-control

Active Development — scpn-quantum-control is under intensive development. The quantum simulation engine, all 17 subpackages (165 modules), and the full pipeline (K_nm coupling → Hamiltonian → Trotter/VQE → IBM hardware → analysis) are fully functional, tested (2,813+ passing tests, 95% coverage), and validated on IBM Heron r2 hardware. We are currently pushing coverage toward 100%, preparing the arXiv preprint, and awaiting IBM Quantum Credits allocation. APIs may evolve as this work progresses.

Version: 0.9.5 Status: 165 Python Modules + 22 Rust Functions | 47 Notebooks | 21 Examples | 95% Coverage | IBM Hardware Validated

---

Quick Start

pip install scpn-quantum-control

import numpy as np
from scpn_quantum_control.phase.xy_kuramoto import QuantumKuramotoSolver

# 8 oscillators, exponential-decay coupling, heterogeneous frequencies
N = 8
K = 0.5 * np.exp(-0.3 * np.abs(np.subtract.outer(range(N), range(N))))
omega = np.linspace(0.8, 1.2, N)

# Simulate: Trotter evolution → order parameter R(t)
solver = QuantumKuramotoSolver(N, K, omega)
result = solver.run(t_max=1.0, dt=0.1)
print(f"Final R = {result['R'][-1]:.3f}")
# → R rises from ~0.3 (incoherent) toward 1.0 (synchronised)

No IBM credentials needed — runs on local statevector simulator. Pass any coupling matrix; the built-in SCPN benchmark is just one example.

---

What This Package Does

To our knowledge, the first quantum hardware demonstration of coupled-oscillator synchronisation with heterogeneous natural frequencies — validated on IBM's ibm_fez (Heron r2, 156 qubits) with Bell inequality violation (S=2.165), sub-threshold QKD error rates (5.5%), and 16-qubit Kuramoto dynamics.

The package provides:

1. A Kuramoto-to-quantum compiler — any coupling matrix K_nm and natural frequencies omega compile directly into executable Qiskit circuits for IBM hardware. Rust-accelerated Hamiltonian construction (5,401× faster than Qiskit).

2. 33 research modules ("gems") probing the synchronisation phase transition — synchronisation witnesses, OTOC scrambling, Krylov complexity, persistent homology, DLA parity theorem, and more. ~4 are novel constructions (witness formalism, Knm ansatz, FIM sector protection); ~8 are first applications of existing tools to Kuramoto-XY; the rest are standard many-body diagnostics applied to this system.

3. Hardware-validated results — 20/20 experiments completed on ibm_fez, 176,000+ shots, 16 publication figures, 3 papers on GitHub Pages.

Think of it as a quantum microscope for synchronisation: classical Kuramoto tells you when oscillators lock in step; this package tells you what the quantum state looks like at the transition, how entangled it is, how fast information scrambles, and whether the system thermalises.

Advanced benchmark: The built-in SCPN 16-layer coupling matrix (Paper 27) provides a heterogeneous-frequency benchmark from the Sentient-Consciousness Projection Network framework, where synchronisation models consciousness dynamics across ontological layers. See SCPN Foundations.

Key Results

Hardware (IBM ibm_fez, Heron r2, 156 qubits)

Result	Value
Bell inequality (CHSH)	S = 2.165 (>8σ above classical limit)
QKD bit error rate	5.5% (below BB84 threshold of 11%)
State preparation fidelity	94.6%
16-qubit UPDE	13/16 qubits with |⟨Z⟩| > 0.3
ZNE stability	<2% variation across fold levels 1–9
Experiments completed	20/20 (22 jobs, 176K+ shots)

Simulation

Result	Value
Critical coupling K_c(∞)	≈ 2.2 (BKT finite-size scaling)
DTC with heterogeneous ω	15/15 amplitudes show subharmonic response
OTOC scrambling	4× faster at K=4 vs K=1 (n=8)
Schmidt gap transition	K = 3.44 (n=8, 60-point resolution)
DLA dimension formula	2^(2N-1) − 2 (exact, all N)

Software

Metric	Value
Rust engine functions	22 (5,401× faster Hamiltonian construction)
Research modules	33 (~4 novel constructions, ~8 first-application)
Python modules	165 + Rust crate (1,170 lines)
Publication figures	14 (simulation + hardware)
Test suite	2,813 passing

Classical vs Quantum Wall-Time

No quantum advantage at n ≤ 16. Classical ODE is faster for all accessible sizes. The value of the quantum approach is characterisation (entanglement, MBL, witnesses), not speed.

Method	n=4	n=8	n=12	n=16
Classical Kuramoto ODE (scipy)	0.4 ms	1.4 ms	2.8 ms	~11 ms
Exact diagonalisation (numpy eigh)	0.1 ms	164 ms	26.8 s	OOM (32 GB)
Qiskit statevector	~50 ms	~2 s	~minutes	impractical
Rust Hamiltonian + numpy eigh	0.02 ms	30 ms	~5 s	~2 min (est.)
IBM hardware (per-job, 4000 shots)	~5 s	~10 s	~20 s	~40 s

Measured on Ubuntu 24.04, AMD Ryzen, 32 GB RAM. Rust speedup applies to Hamiltonian construction only; the eigh bottleneck is LAPACK in all cases.

Publications

• Preprint: Quantum Kuramoto-XY on 156-qubit processor
• Paper: Synchronisation Witness Operators (novel NISQ-ready formalism)
• Paper: DLA Parity Theorem (exact closed-form)

Background: Kuramoto → XY Mapping

Any network of N coupled Kuramoto oscillators can be mapped to a quantum XY Hamiltonian. The built-in SCPN example uses 16 oscillators with a coupling matrix K_nm:

K_nm = K_base * exp(-alpha * |n - m|)

with K_base = 0.45, alpha = 0.3, and empirical calibration anchors (K[1,2] = 0.302, K[2,3] = 0.201, K[3,4] = 0.252, K[4,5] = 0.154). Cross-hierarchy boosts link distant layers (L1-L16 = 0.05, L5-L7 = 0.15). See docs/equations.md for the full parameter set.

The 16×16 K_nm coupling matrix. White annotations: calibration anchors from Paper 27 Table 2. Cyan annotations: cross-hierarchy boosts (L1↔L16, L5↔L7). Exponential decay with distance is visible along the diagonal.

The classical dynamics follow the Kuramoto ODE:

d(theta_i)/dt = omega_i + sum_j K_ij sin(theta_j - theta_i)

The core isomorphism: this ODE maps to the quantum XY Hamiltonian

H = -sum_{i<j} K_ij (X_i X_j + Y_i Y_j) - sum_i omega_i Z_i

where X, Y, Z are Pauli operators. Superconducting transmon qubits implement XX+YY interactions natively through controlled-Z gates, making quantum hardware a natural simulator for Kuramoto phase dynamics. The order parameter R — a measure of global synchronization — is extracted from qubit expectations: R = (1/N)|sum_i (<X_i> + i<Y_i>)|.

Coherence R as a function of coupling strength K_base across 16 SCPN layers. Strongly-coupled layers (L3, L4, L10) synchronize first; weakly-coupled L12 lags behind, consistent with the exponential decay in K_nm.

Reference: M. Sotek, Self-Consistent Phenomenological Network: Layer Dynamics and Coupling Structure, Working Paper 27 (2025). Manuscript in preparation.

Hardware Results (ibm_fez, February 2026)

Experiment	Qubits	Depth	Hardware	Exact	Error
VQE ground state	4	12 CZ	-6.2998	-6.3030	0.05%
Kuramoto XY (1 rep)	4	85	R=0.743	R=0.802	7.3%
Qubit scaling	6	147	R=0.482	R=0.532	9.3%
UPDE-16 snapshot	16	770	R=0.332	R=0.615	46%
QAOA-MPC (p=2)	4	--	-0.514	0.250	--

Full results with all 12 decoherence data points: results/HARDWARE_RESULTS.md

Key findings:

• VQE with K_nm-informed ansatz achieves 0.05% error on 4-qubit subsystem
• Coherence wall at depth 250-400 on Heron r2 — shallow Trotter (1 rep) beats deep Trotter on NISQ devices

More Trotter repetitions improve mathematical accuracy but increase circuit depth. On NISQ hardware, decoherence from the extra gates outweighs the Trotter error reduction. Optimal strategy: fewest reps that capture the physics.

• 16-layer UPDE snapshot on real hardware — per-layer structure partially tracks coupling topology (L12 collapse, L3 resilience at the extremes; Spearman rho = -0.13 across all layers)

Per-layer X-basis expectations from the 16-qubit UPDE snapshot on ibm_fez. L12 (most weakly coupled) shows near-complete decoherence; strongly-coupled layers (L3, L4, L10) maintain coherence.

• 12-point decoherence curve from depth 5 to 770 with exponential decay fit

Hardware-to-exact ratio R_hw/R_exact vs circuit depth. The three regimes: near-perfect readout (depth < 25), linear decoherence (85-400), and noise-dominated (> 400).

Package Map

graph TD
    subgraph Foundation
        bridge["bridge/ (11)\nK_nm → Hamiltonian\ncross-repo adapters"]
    end

    subgraph "Core Physics"
        phase["phase/ (14)\nTrotter, VQE, ADAPT-VQE\nVarQITE, Floquet DTC"]
        analysis["analysis/ (41)\nWitnesses, QFI, PH\nOTOC, Krylov, magic"]
    end

    subgraph "Applications"
        control["control/ (5)\nQAOA-MPC, VQLS-GS\nPetri nets, ITER"]
        qsnn["qsnn/ (5)\nQuantum spiking\nneural networks"]
        apps["applications/ (10)\nFMO, power grid\nJosephson, EEG, ITER"]
    end

    subgraph "Hardware & QEC"
        hw["hardware/ (9)\nIBM runner, trapped-ion\nGPU offload, cutting"]
        mit["mitigation/ (4)\nZNE, PEC, DD\nZ₂ post-selection"]
        qec["qec/ (4)\nToric code, surface code\nrep code, error budget"]
    end

    subgraph "Field Theory"
        gauge["gauge/ (5)\nWilson loops, vortices\nCFT, universality"]
        crypto["crypto/ (4)\nBB84, Bell tests\ntopology-auth QKD"]
    end

    bridge --> phase
    bridge --> analysis
    bridge --> control
    bridge --> qsnn
    phase --> analysis
    phase --> apps
    hw --> phase
    mit --> hw
    qec --> hw
    analysis --> gauge

    style bridge fill:#6929C4,color:#fff
    style analysis fill:#d4a017,color:#000
    style phase fill:#6929C4,color:#fff

Subpackage	Modules	Purpose
analysis	44	Synchronization probes: witnesses, QFI, PH, OTOC, Krylov, magic, BKT, DLA
phase	26	Time evolution: Trotter, VQE, ADAPT-VQE, VarQITE, AVQDS, QSVT, Floquet DTC, Lindblad
hardware	17	IBM Quantum runner, trapped-ion backend, GPU offload, circuit cutting, fast sparse
bridge	12	K_nm → Hamiltonian, cross-repo adapters (sc-neurocore, SSGF, orchestrator)
applications	11	FMO photosynthesis, power grid, Josephson array, EEG, ITER, quantum EVS
control	7	QAOA-MPC, VQLS Grad-Shafranov, Petri nets, ITER disruption, topological optimizer
mitigation	7	ZNE, PEC, dynamical decoupling, Z₂ parity, CPDR, symmetry verification
identity	6	VQE attractor, coherence budget, entanglement witness, fingerprint
qsnn	6	Quantum spiking neural networks (LIF, STDP, synapses, dynamic coupling, training)
crypto	6	BB84, Bell tests, topology-authenticated QKD, key hierarchy
gauge	5	U(1) Wilson loops, vortex detection, CFT, universality, confinement
qec	5	Toric code, repetition code UPDE, surface code, biological surface code, error budget
ssgf	4	SSGF quantum integration
benchmarks	4	Classical vs quantum scaling, MPS baseline, GPU baseline, AppQSim
tcbo	1	TCBO quantum observer
pgbo	1	PGBO quantum bridge
l16	1	Layer 16 quantum director

Quick Start

pip install scpn-quantum-control

Any coupling network — bring your own K and omega:

from scpn_quantum_control import QuantumKuramotoSolver, build_kuramoto_ring

K, omega = build_kuramoto_ring(6, coupling=0.5, rng_seed=42)
solver = QuantumKuramotoSolver(6, K, omega)
result = solver.run(t_max=1.0, dt=0.1, trotter_per_step=2)
print(f"R(t): {result['R']}")

Built-in SCPN network (16 oscillators from Paper 27):

from scpn_quantum_control import QuantumKuramotoSolver, build_knm_paper27, OMEGA_N_16

K = build_knm_paper27(L=4)
solver = QuantumKuramotoSolver(4, K, OMEGA_N_16[:4])
result = solver.run(t_max=0.5, dt=0.1, trotter_per_step=2)

Detect synchronization with witness operators:

from scpn_quantum_control.analysis.sync_witness import evaluate_all_witnesses

# After running X-basis and Y-basis circuits on IBM hardware:
results = evaluate_all_witnesses(x_counts, y_counts, n_qubits=4)
for name, w in results.items():
    print(f"{name}: {'SYNCHRONIZED' if w.is_synchronized else 'incoherent'}")

For development (editable install with test/lint tooling):

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v

Hardware execution (requires IBM Quantum credentials)

pip install -e ".[ibm]"
python run_hardware.py --experiment kuramoto --qubits 4 --shots 10000

Data Flow

The pipeline from coupling matrix to measurement follows a fixed sequence:

graph LR
    A["K_nm\ncoupling matrix"] --> B["knm_to_hamiltonian()\nSparsePauliOp"]
    B --> C["Trotter / VQE\nQuantumCircuit"]
    C --> D["Transpile\nnative gates"]
    D --> E["Execute\nAer / IBM"]
    E --> F["Parse counts\n⟨X⟩, ⟨Y⟩, ⟨Z⟩"]
    F --> G["Order parameter\nR(t)"]

    style A fill:#6929C4,color:#fff
    style G fill:#2ecc71,color:#000

Examples

21 standalone scripts in examples/:

#	Script	What it demonstrates
01	qlif_demo	Quantum LIF neuron: membrane → Ry rotation → spike
02	kuramoto_xy_demo	4-oscillator Kuramoto dynamics, R(t) trajectory
03	qaoa_mpc_demo	QAOA binary MPC: quadratic cost → Ising Hamiltonian
04	qpetri_demo	Quantum Petri net: tokens evolve in superposition
05	vqe_ansatz_comparison	Three ansatze benchmarked on 4-qubit Hamiltonian
06	zne_demo	Zero-noise extrapolation with unitary folding
07	crypto_bell_test	CHSH inequality violation certification
08	dynamical_decoupling	DD pulse sequence insertion (XY4, X2, CPMG)
09	classical_vs_quantum_benchmark	Scaling crossover analysis
10	identity_continuity_demo	VQE attractor basin stability
11	pec_demo	Probabilistic error cancellation
12	trapped_ion_demo	Ion trap noise model comparison
13	iter_disruption_demo	ITER plasma disruption classification
14	quantum_advantage_demo	Advantage threshold estimation
15	qsnn_training_demo	QSNN training loop with parameter-shift
16	fault_tolerant_demo	Repetition code UPDE
17	snn_ssgf_bridges_demo	Cross-repo bridge roundtrips
18	end_to_end_pipeline	Complete K_nm → IBM → analysis pipeline
19	sync_witness_operator	Synchronisation witness operator demo
20	quantum_persistent_homology	Persistent homology analysis
21	biological_qec_scpn16	Biological surface code on 16-layer SCPN

All examples run on statevector simulation (no QPU needed).

Notebooks

47 Jupyter notebooks in notebooks/ — 13 core tutorials plus 34 FIM investigation notebooks (NB14–47). Core notebooks:

#	Notebook	Level	Key Output
01	Kuramoto XY Dynamics	Beginner	R(t) trajectory, quantum-classical overlay
02	VQE Ground State	Beginner	Energy convergence, ansatz comparison
03	Error Mitigation	Intermediate	ZNE extrapolation plot
04	UPDE 16-Layer	Intermediate	Per-layer R bar chart
05	Crypto & Entanglement	Intermediate	CHSH S-parameter, QKD QBER
06	PEC Error Cancellation	Advanced	PEC vs ZNE, overhead scaling
07	Quantum Advantage	Advanced	Scaling crossover prediction
08	Identity Continuity	Advanced	Attractor basin, fingerprint
09	ITER Disruption	Domain	Feature distributions, accuracy
10	QSNN Training	Advanced	Loss curve, weight evolution
11	Surface Code Budget	Advanced	QEC resource estimation
12	Trapped Ion Comparison	Advanced	Noise model comparison
13	Cross-Repo Bridges	Integration	Phase roundtrip, adapter demos

All run on local AerSimulator. No IBM credentials needed.

Architecture

scpn_quantum_control/
├── analysis/       44 modules — synchronization probes
├── phase/          26 modules — time evolution + variational + Lindblad
├── hardware/       17 modules — IBM runner, trapped-ion, GPU, cutting, fast sparse
├── bridge/         12 modules — K_nm → quantum objects + cross-repo
├── applications/   11 modules — physical system benchmarks
├── control/         7 modules — QAOA-MPC, VQLS-GS, Petri, ITER, topological
├── mitigation/      7 modules — ZNE, PEC, DD, Z₂, CPDR, symmetry
├── identity/        6 modules — identity continuity analysis
├── qsnn/            6 modules — quantum spiking neural networks
├── crypto/          6 modules — QKD, Bell tests, key hierarchy
├── gauge/           5 modules — U(1) gauge theory probes
├── qec/             5 modules — error correction + biological surface code
├── ssgf/            4 modules — SSGF quantum integration
├── benchmarks/      4 modules — performance baselines
├── tcbo/            1 module  — TCBO quantum observer
├── pgbo/            1 module  — PGBO quantum bridge
├── l16/             1 module  — Layer 16 quantum director
└── scpn_quantum_engine/  Rust crate (PyO3 0.25, 22 functions)

Dependencies

Package	Version	Purpose
qiskit	>= 1.0.0	Circuit construction, transpilation
qiskit-aer	>= 0.14.0	Statevector + noise simulation
numpy	>= 1.24	Array operations
scipy	>= 1.10	Sparse linear algebra, optimisation
networkx	>= 3.0	Graph algorithms (QEC decoder)

Optional:

• matplotlib >= 3.5 for visualisation
• qiskit-ibm-runtime >= 0.20.0 for hardware execution
• cupy >= 12.0 for GPU-accelerated simulation

Limitations

• NISQ benchmarking only. Current hardware results are proof-of-concept. Circuit depths >400 hit the Heron r2 coherence wall; the 16-layer UPDE snapshot (46% error) confirms this. Real tokamak control requires <1 ms deterministic latency on radiation-hardened hardware — cloud QPUs cannot provide that.
• SCPN is an unpublished model. The 16-layer coupling structure comes from a 2025 working paper (Sotek, Paper 27) with no external citations yet. The Kuramoto→XY mapping is standard physics; the specific K_nm parameterisation is not independently validated.
• Small-scale advantage not demonstrated. At N=4-16 qubits, classical ODE solvers outperform quantum simulation in both speed and accuracy. Potential quantum advantage requires N>>20 with error-corrected qubits (post-2030 hardware).
• IBM hardware campaign complete. 20/20 experiments executed on real QPU (ibm_fez, Heron r2). 22 jobs, 176K+ shots. Job IDs and raw measurement counts in results/ibm_hardware_2026-03-{18,28}/. All results are from real quantum hardware, not simulator.

Documentation

Full docs at anulum.github.io/scpn-quantum-control:

• Installation — pip install + dev setup
• Quickstart — first experiment in 5 minutes
• Tutorials — 4-level learning path, 14 tutorials
• Research Gems — 33 analysis modules with theory and API
• Equations — every equation in the codebase
• Architecture — 107-module dependency graph
• Analysis API — 41 analysis modules
• Phase API — 14 evolution algorithms
• Hardware Guide — IBM Quantum setup
• Notebooks — 13 interactive notebooks
• Bridges — cross-repo integrations

Related Repositories

Repository	Description
sc-neurocore	Classical SCPN spiking neural network engine (v3.13.3, 2155+ tests)
scpn-fusion-core	Classical SCPN algorithms: Kuramoto solvers, coupling calibration, transport (v3.9.3, 3300+ tests)
scpn-phase-orchestrator	SCPN phase orchestration: regime detection, UPDE engine, Petri-net supervisor (v0.5.0, 2321 tests)
scpn-control	SCPN control systems: plasma MPC, disruption mitigation (v0.18.0, 3015 tests)

Citation

@software{scpn_quantum_control,
  title  = {scpn-quantum-control: Quantum-Native SCPN Phase Dynamics and Control},
  author = {Sotek, Miroslav},
  year   = {2026},
  url    = {https://github.com/anulum/scpn-quantum-control},
  doi    = {10.5281/zenodo.18821929}
}

License

AGPL-3.0-or-later — commercial license available.

Commercial Licensing

AGPL-3.0 requires derivative works to be open-sourced. If you need to integrate scpn-quantum-control into proprietary software without publishing your source code, a commercial license is available:

Tier	Price	Includes
Indie	CHF 49/month	Single developer, one product
Pro	CHF 199/month	Team up to 10, unlimited products
Perpetual	CHF 999 one-time	Permanent license, one major version
Enterprise	Custom	SLA, priority support, custom modules

Contact: [e-mail] | polar.sh/anulum

---

    
Developed by ANULUM / Fortis Studio