scpn-quantum-control

Evidence-governed Kuramoto-XY quantum control and differentiable computation for coupled oscillator networks, with a hardware evidence ledger separating theory, simulator, unmitigated hardware, mitigated hardware, and noise-limited claims.

Positioning and purpose

scpn-quantum-control is an evidence-first platform for teams turning coupled-oscillator models into reproducible computational evidence. It is aimed at research groups, hardware operators, control engineers, and product teams that need a clearer path from model statement to auditable result than ad-hoc notebooks can provide.

In practice, this means:

• explicit problem-to-experiment boundaries (K_nm, omega, solver surface);
• separation of simulator and hardware evidence classes;
• stable public interfaces for integration;
• explicit, non-silenced boundaries on unsupported or blocked modes.

Start Here

If you are new to the repository, read these pages in order:

1. Onboarding — what the software is, who it serves, what is mature, and what remains claim-bound.
2. Solutions and Market Value — credible application, pilot, adoption, and commercial routes without inflated claims.
3. Quickstart — run a local no-credential Kuramoto-XY simulation.
4. Tutorials — follow the learning path from first simulation to research workflow.
5. Stable Facades API — use supported public entry points before advanced internals.
6. Hardware Status Ledger — understand which hardware and scientific claims are promoted, bounded, or blocked.

The short version: provide a coupling matrix K_nm and natural frequencies omega; the package validates the problem, compiles the XY Hamiltonian, builds circuits, runs local or provider-backed execution when allowed, and analyses synchronisation, entanglement, topology, and control observables under explicit evidence boundaries.

Product Map

Lane	What users get now	Why it matters
Physics compiler	A reproducible K_nm/omega to XY-Hamiltonian path with simulator execution and classical references.	Researchers can compare oscillator-network hypotheses without rewriting the quantum stack.
Differentiable optimisation	Parameter-shift VQE, composed phase objectives, gradient evidence, and bounded compiler/program AD kernels.	Optimisation and ML users can see when gradients are exact, approximate, blocked, or still roadmap.
Hardware governance	Provider capability records, raw-count ledgers, result packs, and release gates.	Hardware claims stay auditable and safe to cite.
Integration surface	Stable facades, notebooks, tutorials, API maps, and Rust acceleration hooks.	External projects can adopt supported entry points without depending on internal layout.

Adoption value

Organisation need	Repository surface	Review output
Reduce quantum R&D uncertainty	Simulator-first Kuramoto-XY workflows and classical baselines.	A repeatable local result before hardware spend.
Prepare a hardware campaign	Provider readiness, hardware result packs, and no-QPU gates.	Evidence classes that are clear before submission.
Build an optimisation pilot	Parameter-shift, finite-shot, framework-agreement, and compiler-AD routes.	Gradient evidence with explicit unsupported scenarios.
Assess commercial fit	Stable facades, AGPL/commercial boundary, release-readiness pages, and API maps.	A concrete route from research code to governed integration.

Use Differentiable Tutorials, Differentiable Programming, and Quantum Gradients when the central question is whether a workflow can be trained or optimised. Use Hardware Status Ledger when the central question is whether a result can be promoted as hardware evidence.

Status Snapshot — 2026-07-29

Area	Public status
Package line	Version 1.1.0, Python >=3.11, Qiskit >=2.2,<3.0.
Generic compiler surface	scpn_quantum_control.kuramoto_core validates arbitrary K_nm/omega inputs and compiles Hamiltonians, dense matrices, Trotter circuits, order-parameter measurements, and Kuramoto variant trajectories.
Stable integration surfaces	QRNG streaming, ML-DSA/PQC trigger signing, UltraScale+ HLS pulse emission, realtime telemetry, NV magnetometry, FRC pulsed-shot QAOA scheduling, and Studio federation manifest/evidence-bundle emission are documented from API, tutorial, and example routes.
Hardware evidence	Promoted raw-count campaigns: ibm_kingston DLA parity Phase 1, selected Phase 2 A+G/B-C/popcount controls, and the SCPN/FIM negative/falsification result for the tested digital circuit family. Legacy ibm_fez rows require artefact-level citation.
Claim source	Hardware Status Ledger.

What this package does

The classical Kuramoto model for coupled oscillators maps directly to the quantum XY spin Hamiltonian. Superconducting qubits are native simulators of this physics: each qubit is an oscillator on the Bloch sphere, and the XX+YY coupling between qubits reproduces the $\sin(\theta_j - \theta_i)$ interaction of the Kuramoto model.

This package provides five things:

1. A compiler that takes any coupling matrix $K_{nm}$ and natural frequencies $\omega_i$ and produces executable Qiskit circuits for IBM hardware.

2. 35 research modules probing the synchronization phase transition — synchronization witnesses, topological diagnostics, chaos measures, computational complexity bounds, and open-system dynamics. ~4 are novel constructions; ~8 are first applications of existing tools to Kuramoto-XY; the rest are standard many-body diagnostics.

3. The SCPN 16-layer network as a built-in benchmark — the coupling matrix from the Scale-Coupled Phase Network framework, a 16-layer generalised-Kuramoto model whose synchronisation across scales provides a structured, reproducible test problem.

4. A differentiable computation lane for supported scalar, vector, and matrix primitive kernels, including compiler-AD metadata and native Rust backend parity for selected primitives. Supported scalar program traces also expose native lowering reports before LLVM/JIT compilation, with strict no-tie native selection lowering for np.where, maximum, minimum, and clip, plus scalar 2x2/3x3/4x4/5x5 expression determinant, helper-backed 6x6 through 19x19 determinant, static square/rectangular trace, static diagonal gather/scatter, static dense inverse through 7x7, static vector and matrix-RHS solve through 7x7, and 2x2 product lowering. The native linalg support contract is introspectable before compilation, and wide determinant helpers are regression-tested on non-diagonal dense matrices. Unsupported compiler and program-AD paths fail closed rather than silently fabricating gradients.

5. A documented quantum-gradient route that starts from parameter-shift VQE and extends toward backend-aware gradient planning, gradient tapes, framework adapters, QNN/QGNN/QSNN workflows, analog oscillator mapping, open-system gradients, and benchmark evidence. Current capabilities and planned surfaces are separated in the support documentation.

Think of it as a quantum microscope for synchronization. Classical Kuramoto tells you when oscillators lock in step. This package tells you what the quantum state looks like at the transition, how hard it is to prepare, what its topology reveals, and where classical simulation fails.

Key results

Result	Value
VQE ground-state row	0.05% (4-qubit, legacy ibm_fez artifact)
16-layer UPDE snapshot	46% error at depth 770 (NISQ-consistent)
Coherence wall	depth 250–400 (Heron r2)
DLA dimension formula	$2^{2N-1} - 2$(exact, all$N$)
Research modules	See generated capability inventory for current package counts
IBM hardware evidence	Legacy ibm_fez artifact rows + 342-circuit ibm_kingston Phase 1 DLA-parity raw-count dataset
DLA parity asymmetry (hardware)	$+10.8\,\%$ mean for depths $\ge 4$, peak $+17.5\,\%$ at depth 6, reproduced from data/phase1_dla_parity/
Test suite	CI-gated suite, 90% line gate; branch telemetry required and currently observational
Python modules	697 Python source modules + 1 Rust crate (177 PyO3 bindings) + Julia tier (accel/julia/*.jl)

Package map

Module counts change as governed capabilities land. The complete Python module and API catalog is generated from the current source tree and is the authoritative module inventory.

Subpackage	Inventory	Purpose
analysis	catalog	Synchronisation probes, witness discovery, QFI, topology, open-system, complexity, and governed research lanes
hardware	catalog	Provider-neutral capabilities, multi-provider adapters, result custody, feedback, layouts, cutting, and no-submit gates
phase	catalog	Time evolution, variational solvers, open systems, QNodes, framework bridges, and differentiable/gradient surfaces
bridge	catalog	$K_{nm}$ → Hamiltonian and cross-repository adapters
applications	catalog	Power-grid, plasma, EEG-like, Josephson, reservoir, kernel, and benchmark integrations with honesty boundaries
control and dla_topology_control	catalog	Bounded classical/quantum control objectives, constraints, topology derivatives, and evidence
compiler and root Program-AD modules	catalog	Static trace contracts, primitive derivatives, native lowering, parity evidence, and fail-closed unsupported routes
studio	catalog	Executive workflows, reproducible artefacts, scorecards, manifests, validation, and replay
crypto	9	Governed QKD, topology authentication, signing, QRNG integration, and key custody
Other domain families	catalog	Mitigation, QEC, QSNN, gauge, forecasting, thermodynamics, co-design, analog mapping, and benchmark harnesses

Quick example

Any coupling topology — 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']}")

Detect synchronization on hardware 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'}")

Limitations

• NISQ benchmarking only. Circuit depths >400 hit the coherence wall on Heron r2.
• SCPN coupling matrix is from unpublished work. The $K_{nm}$ parameterisation comes from Paper 27 (2025 working paper, no external citations). The Kuramoto→XY mapping is standard; the specific coupling structure is not independently validated.
• No quantum advantage at this scale. At $N=4$–16, classical exact diagonalisation is faster. Advantage requires $N \gg 20$ with error-corrected qubits.
• IBM hardware claim hygiene. The promoted raw-count dataset is Phase 1 DLA parity on ibm_kingston; legacy ibm_fez rows must cite their committed artifact path. V2/frontier/queued-job outputs are unpromoted.

Documentation

• Onboarding — project purpose, user routes, application value, and claim boundaries
• Solutions and Market Value — application portfolio, stakeholder value, pilot framework, and commercial routes
• Installation — pip install + all optional extras
• Quickstart — first experiment in 5 minutes
• Differentiable Tutorials — runnable gradient workflow with diagnostics, compiler report, and bounded QNN training
• Kuramoto Core Facade — stable K_nm/omega compiler entry point
• Stable Facades API — mkdocstrings reference for first-path public facades
• Physics-First Kuramoto-XY — start from arbitrary oscillator networks before SCPN-specific layers
• Sparse Kuramoto CPU Path — SciPy sparse force/Euler/RK4 route with 1M-node ring scaling evidence
• Kuramoto Standalone Package Decision — the oscillatools package split, CEO/IP-approved 2026-07-04
• Differentiable Tutorials — unified differentiable API workflow
• Differentiable Programming — current AD capabilities, boundaries, and user routes
• Quantum Gradients — parameter-shift gradients, VQE convergence route, and verification evidence
• Differentiable API — public scpn_quantum_control.differentiable namespace map
• Differentiable Roadmap — staged plan for framework adapters, advanced gradients, benchmarks, verification, and dashboards
• API Overview — stable facade route first, advanced module references second
• Complete Python Module and API Catalog — every source module and documented public module-level symbol
• Complete Documentation Catalog — every public guide, contract, protocol, and evidence page
• Campaign Artefacts — dated preregistration, readiness, manifest, and result notes
• Publication Operations — submission checklists, source packaging, and venue-readiness notes
• Release Readiness Gate — deterministic tag-readiness audit for version, licensing, coverage, behavioural quality, and claim-boundary artefacts
• Licensing FAQ — AGPL/commercial route, core-split boundary, and release gate for licence drift
• Research Gems — legacy curated Rounds 1–8 theory narratives
• Deep-analysis Research Lanes — governed maturity, differentiable-hook, claim-status, and inventory-gate catalogue
• RL Research Governance — disabled-by-default preregistration, seed, budget, deterministic-replay, and no-control gates
• Literature Catalogue — project-relevant literature surveys and citation-planning material
• Equations — every equation in the codebase
• Architecture — dependency graph + 20 subpackages
• Hardware Status Ledger — claim classes and campaign evidence paths
• Analysis API — advanced reference for the analysis modules
• Witness Discovery — Bayesian/bandit search over synchronisation witness candidates
• Application Benchmark Plugins — EEG, plasma, power-grid, and FEP datasets through the QPU artifact contract
• Domain Application Honesty Kits — typed synthetic/curated boundaries, forbidden claims, and packaged-data privacy audit
• Phase API — advanced reference for the phase evolution and gradient modules
• Kuramoto Variants — higher-order, monitored, and PT-symmetric trajectory APIs
• Classical Baselines — SciPy ODE, QuTiP Lindblad, and MPS TEBD provenance surfaces
• TN/MPS Baseline Design — CPU-first N=30-40 tensor-network baseline plan
• Hardware Guide — IBM Quantum setup
• Bridges — cross-repo integrations
• Tutorials — 4-level learning path, 14 tutorials
• Notebooks — curated learning sequence
• Complete Notebook Catalog — all 109 committed notebooks with category and claim posture
• Language Policy — Rust / Julia / Go / Mojo accel-chain rules
• Pipeline Performance — measured wall-times + multi-language benchmarks
• Methods Benchmark Dashboard — one-command artefact regeneration and paper-supporting benchmark provenance
• Issue Triage — label taxonomy, SLAs, routing
• Falsification — 8 named claims + falsifiers

---

Contact: protoscience@anulum.li | GitHub Discussions | www.anulum.li

    
Developed by ANULUM / Fortis Studio