Onboarding

This page is the shortest route to understanding what scpn-quantum-control is, what it is useful for, and where the claim boundaries sit.

Why this exists

The package is intended for teams that cannot treat every quantum workflow as equivalent. It separates:

• simulation science (fast iteration),
• method verification (reproducible checks and baselines),
• hardware evidence (raw-count-backed claims), and
• commercial readiness (stable facades, release gates, and deployment boundaries).

The goal is a single path from idea to auditable outcome, where every higher-cost route has a defined evidence burden. A useful result in this repository is not only a plot or a notebook output; it is a result with inputs, code path, dependency context, claim class, and promotion rule.

The full set of claim classes, ledgers, preregistration records, and runtime contracts is gathered behind one entry point — see Methodology. You do not need it to run the examples.

One-Sentence Description

scpn-quantum-control is a quantum-control and differentiable-computation workbench for coupled oscillator networks, centred on the Kuramoto-XY mapping and backed by simulator workflows, Rust acceleration, hardware-result ledgers, release gates, and explicit scientific claim boundaries.

Who this helps in practice

Role	Outcome
Researcher	turn coupled-oscillator models into structured comparisons with clear limits
Hardware operator	run campaign planning and raw-count review without mixing simulator and hardware claims
Product engineer	adopt stable facades and migrate into integrations with low risk
Compliance reviewer	inspect explicit claim classes and verify promotion rules before release
Commercial evaluator	see which parts are ready for pilots, which are research-only, and where a commercial licence is required

What Problem It Solves

Many physical and engineered systems are networks of coupled oscillators: electrical grids, plasma control loops, Josephson arrays, brain rhythms, chemical oscillators, and synchronising control systems. The software provides a common route for those systems:

1. express the coupling topology as a matrix K_nm;
2. express oscillator detuning or local drive as omega;
3. compile the corresponding XY Hamiltonian and circuits;
4. run local simulation or provider-backed execution when permitted;
5. measure synchronisation, entanglement, topology, and control observables;
6. preserve raw evidence and claim boundaries for papers, releases, and downstream integration.

Core Capabilities

Capability	What it means	Production route
Kuramoto-XY compiler	Converts arbitrary K_nm and omega into Hamiltonians, dense matrices, circuits, and order-parameter measurements.	scpn_quantum_control.kuramoto_core
Hardware evidence ledger	Separates theory, simulator output, raw-count hardware evidence, mitigated evidence, and unpromoted artefacts.	docs/hardware_status_ledger.md
Rust acceleration	Speeds up selected Hamiltonian, expectation, pulse, symmetry, and compiler-AD hot paths.	scpn-quantum-engine
Differentiable programming	Provides parameter-shift VQE building blocks, supported scalar/vector/matrix AD primitives, native lowering reports, and fail-closed unsupported boundaries.	scpn_quantum_control.phase.param_shift, scpn_quantum_control.compiler.mlir, and scpn_quantum_control.differentiable
Release gates	Make public release decisions repeatable instead of process-only statements.	tools/audit_release_readiness.py and scpn-bench gates

Adoption Checklist

Before using the package in a paper, product prototype, or integration, make these decisions explicit:

Question	Recommended answer path
Is my system naturally represented as coupled oscillators?	Start with K_nm, omega, and Physics-First Kuramoto-XY.
Do I need gradients?	Start with Differentiable Tutorials, then use Differentiable Programming and the gradient support matrix for route decisions.
Am I citing hardware?	Use only rows named in Hardware Status Ledger and committed raw-count artefacts.
Am I building a closed product or service?	Review the AGPL/commercial licence boundary before distribution or network use.
Am I using SCPN-specific biological or consciousness language?	Keep it source-bounded unless external validation artefacts exist.

Recommended First Paths

Goal	Path
Run the first local experiment	Quickstart
Understand the learning sequence	Tutorials
Use the stable API	Stable Facades API
Bring a custom oscillator network	Physics-First Kuramoto-XY
Train or inspect gradients	Differentiable Tutorials, Differentiable Programming, Quantum Gradients, and Differentiable API
Reproduce framework parity	Build the CPU-only framework overlay, run the external comparison suite, and inspect the claim ledger.
Inspect notebooks	Interactive Notebooks
Build or install the Rust engine	Rust Engine
Evaluate release readiness	Release Readiness Gate
Understand claim limits	Hardware Status Ledger and Falsification

Application Lanes

The framework is designed for application lanes where synchronisation and coupled dynamics matter:

• Quantum algorithm research: XY Hamiltonians, VQE, Trotterisation, witness operators, topology, DLA parity, and mitigation workflows.
• Plasma and control systems: ITER disruption and control-facing benchmark contracts.
• Power systems: graph-coupled oscillator and IEEE-bus candidate workflows.
• EEG/MEG and biological rhythms: source-bounded synchronisation candidates with strict non-clinical claim boundaries.
• Quantum hardware operations: raw-count evidence packs, provider readiness, and no-QPU gates before new hardware spend.
• Differentiable computation: gradient-bearing primitive kernels used for optimisation, VQE training experiments, compiler-backed AD, CPU-only framework parity, and external ML-framework comparison rows.

Market-fit framing

The strongest adoption case is not a claim of near-term quantum advantage. The adoption case is governed uncertainty reduction for domains where coupled dynamics matter and where uncontrolled evidence would be expensive:

Market problem	Why this package matters
Quantum pilots are hard to compare	Common K_nm/omega contracts, classical references, and claim classes make pilots reviewable.
Hardware runs are costly and easy to overstate	No-QPU gates, provider readiness, and raw-count ledgers prevent simulator output from becoming hardware language.
Optimisation stacks hide fallback behaviour	Gradient support matrices and fail-closed routes make unsupported AD visible before integration.
Research notebooks do not become products cleanly	Stable facades, API docs, examples, and release gates provide a migration path from exploration to integration.

What Is Mature

• Local simulator workflows for Kuramoto-XY examples and notebooks.
• Stable facade route for first-path users.
• Public documentation for hardware evidence status and claim classes.
• Rust acceleration for selected hot paths.
• Release-readiness and hardware-result-pack gates.
• Supported differentiable scalar, vector, and matrix primitive surfaces, plus inspectable native program-AD lowering reports for supported scalar traces with strict no-tie native where/selection/clip support, 2x2/3x3/4x4/5x5 expression determinant native lowering, helper-backed 6x6 through 19x19 determinant native lowering, static square/rectangular trace native lowering, static diagonal gather/scatter native lowering, static dense inverse native lowering through 7x7, static vector and matrix-RHS solve native lowering through 7x7, 2x2 product native lowering, and an introspectable native linalg support contract for service gating.
• Parameter-shift gradient helpers for callable expectation objectives, gradient-descent VQE examples, provider-gradient readiness ledgers, and a unified differentiable-readiness audit for reviewer-facing support evidence.
• The Phase-QNode differentiable lane now has a reproducible CPU framework overlay profile, external comparison rows for JAX, PyTorch, TensorFlow, PennyLane, optional Enzyme/compiler AD runner evidence, and optional Catalyst qjit/MLIR/QIR runner evidence with strict JSON, timeout, toolchain, and correctness gates. Catalyst rows also carry a dedicated compiler-workflow profile for compiled differentiation, control flow, finite-shot limits, and unsupported provider routes, plus a claim ledger that requires artefact IDs before promotion.

What Remains Bounded

• Broad quantum advantage is not claimed.
• Clinical, biological, or consciousness claims are not externally validated.
• Hardware evidence must name committed raw-count artefacts and pass the relevant ledger gates before promotion.
• Phase-QNode performance remains a promotion candidate until a self-hosted isolated-benchmark CI runner uploads an isolated_affinity artefact; local and GitHub-hosted rows are diagnostic only, and CUDA/ROCm claims require explicit visible-device metadata rather than CPU fallback.
• General native MLIR/LLVM/JIT AD over arbitrary programs is still an open engineering frontier; supported primitives and supported scalar traces execute through bounded kernels, and unsupported paths report the blocked operation before failing closed.
• Native determinant traces at 20x20 and wider are intentionally fail-closed after a strict native verification failure at the current helper formulation.
• Native quotient-linalg full-output inverse, vector-solve, and matrix-RHS solve traces are supported through 7x7 for static matrices and at most four RHS columns. 5x5 through 7x7 reuse one partial-pivot factorisation helper per static matrix; 8x8 and wider full-output traces still fail closed until a larger verified factorisation helper passes the native correctness gate. This remaining limitation is useful research evidence, not a silent runtime fallback.
• Full gradient tape semantics, public JAX/PyTorch/TensorFlow adapters, PennyLane/Qiskit migration bridges, backend-aware hardware gradient planning, QNN/QGNN/QSNN production examples, and analog oscillator mapping are planned roadmap surfaces until their tests, docs, and support matrix entries are complete.

Commercial Route

The repository is AGPL-3.0-or-later with a commercial licence available. Open research, teaching, and AGPL-compatible redistribution use the public licence. Closed-source products, proprietary services, SaaS integrations, and embedded deployments require a commercial licence grant before distribution or network-service use.

Contact: protoscience@anulum.li.