Auto-Generated API Reference¶

Generated from source docstrings via mkdocstrings.

This page is an advanced module index. It is useful for maintainers and subsystem authors who need direct access to implementation modules. First-path user workflows should start with Stable Facades API and Kuramoto Core Facade.

Stable Facades¶

`scpn_quantum_control.kuramoto_core` ¶

Small public facade for Kuramoto-XY problems.

`KuramotoProblem` `dataclass` ¶

Validated coupling matrix, frequencies, and serialisable metadata.

`n_oscillators` `property` ¶

Number of oscillators/qubits represented by the problem.

`K` `property` ¶

Alias for the validated coupling matrix.

`__post_init__()` ¶

Validate inputs and freeze defensive copies after construction.

`validate()` ¶

Re-run the public validation contract for this problem.

`to_metadata()` ¶

Return serialisable metadata for result artifacts.

`build_kuramoto_problem(K_nm, omega, metadata=None)` ¶

Create a validated Kuramoto-XY problem from arbitrary arrays.

`validate_kuramoto_inputs(K_nm, omega)` ¶

Validate and copy a symmetric Kuramoto coupling problem.

`compile_hamiltonian(problem)` ¶

Compile a Kuramoto problem into the XY SparsePauliOp Hamiltonian.

`compile_dense_hamiltonian(problem, *, max_dense_gib=None)` ¶

Compile a dense Hamiltonian, using the Rust engine when installed.

`compile_trotter_circuit(problem, time, trotter_steps=10, trotter_order=1)` ¶

Compile a Trotterised gate-model evolution circuit.

`compile_analog_program(problem, *, platform, duration, coupling_scale=1.0)` ¶

Compile a Kuramoto problem into a native analog hardware programme.

`compile_hybrid_program(problem, *, platform, duration, digital_time=None, max_analog_couplers=None, analog_threshold=0.0, trotter_steps=8, trotter_order=1)` ¶

Compile a split analog-native plus digital-residual programme.

`measure_order_parameter(problem, statevector)` ¶

Measure the Kuramoto order parameter from a statevector.

`simulate_variant_trajectory(problem, variant, *, dt, n_steps, theta0=None, hyperedges=None, hyper_weights=None, target_r=0.75, monitor_gain=0.8, measurement_strength=0.2, gain_loss=None, prefer_rust=True)` ¶

Run a higher-order, monitored, or PT-symmetric Kuramoto variant.

Advanced Module Reference¶

The sections below expose lower-level packages directly. Use them when extending or debugging a subsystem, not as the default path for tutorial code.

Bridge¶

`scpn_quantum_control.bridge.knm_hamiltonian` ¶

Knm coupling matrix -> Pauli Hamiltonian compiler.

Translates the 16x16 Knm coupling matrix + 16 natural frequencies from Paper 27 into a SparsePauliOp for quantum simulation.

Kuramoto <-> XY mapping: K[i,j]sin(theta_j - theta_i) <=> -J_ij(X_i X_j + Y_i Y_j) omega_i <=> -h_i * Z_i

`OMEGA_N_16 = np.array([1.329, 2.61, 0.844, 1.52, 0.71, 3.78, 1.055, 0.625, 2.21, 1.74, 0.48, 3.21, 0.915, 1.41, 2.83, 0.991], dtype=(np.float64))` `module-attribute` ¶

`omega_for_oscillators(n_oscillators)` ¶

Return deterministic natural frequencies for n_oscillators.

The first 16 entries are the canonical Paper 27 values in :data:OMEGA_N_16. Larger synthetic networks use a periodic extension of that measured table so scalable classical, co-simulation, and partitioned examples receive a full-length vector without fabricating new Paper 27 data.

Parameters¶

n_oscillators: Number of oscillator frequencies to return; must be at least one.

Returns¶

numpy.ndarray A fresh float64 vector of length n_oscillators.

Raises¶

TypeError If n_oscillators is not an integer. ValueError If n_oscillators is below one.

`build_knm_paper27(L=16, K_base=0.45, K_alpha=0.3)` ¶

Build the canonical Knm coupling matrix from Paper 27.

K[i,j] = K_base * exp(-K_alpha * |i - j|) (Paper 27, Eq. 3) with calibration anchors from Table 2 and cross-hierarchy boost constants.

`build_kuramoto_ring(n, coupling=1.0, omega=None, rng_seed=None)` ¶

Build a nearest-neighbour ring coupling matrix for n Kuramoto oscillators.

Returns (K, omega) ready for QuantumKuramotoSolver or knm_to_hamiltonian. If omega is None, draws from N(0,1) with the given seed.

`knm_to_hamiltonian(K, omega)` ¶

Convert Knm coupling matrix + natural frequencies to SparsePauliOp.

H = -sum_{i<j} K[i,j] * (X_i X_j + Y_i Y_j) - sum_i omega_i * Z_i

Uses Qiskit little-endian qubit ordering. Equivalent to knm_to_xxz_hamiltonian(K, omega, delta=0.0).

`knm_to_ansatz(K, reps=2, threshold=0.01)` ¶

Build physics-informed ansatz: CZ entanglement only between Knm-connected pairs.

Pattern from QUANTUM_LAB script 16 (PhysicsInformedAnsatz).

`scpn_quantum_control.bridge.qpu_data_artifact` ¶

QPU-ready oscillator artifact with provenance gates.

`QPUDataArtifact` `dataclass` ¶

A bounded QUANTUM-to-SPO knm.scpn-upde handoff.

The edge carries validated K_nm and omega arrays plus enough deterministic compiler metadata for SPO to rebuild its own review manifest. It never authorises QPU execution or actuation.

`n_oscillators` `property` ¶

Oscillator/qubit count carried by the edge.

`dt` `property` ¶

Implied per-step Trotter interval.

`__post_init__()` ¶

Validate and normalise the bounded federation payload fields.

`to_payload()` ¶

Return the JSON-compatible edge payload with an integrity digest.

`build_paper27_scpn_upde_edge(*, time=0.1, trotter_steps=1, trotter_order=1)` ¶

Return the 16-oscillator Paper-27 QUANTUM→SPO edge.

The emitted scope is deliberately limited to computational agreement; the Paper-27 coupling matrix remains provisional rather than canonical physics.

`build_scpn_upde_edge(K_nm, omega, *, time=0.1, trotter_steps=1, trotter_order=1, claim_boundary=PAPER27_PROVISIONAL_BOUNDARY)` ¶

Build a bounded knm.scpn-upde edge from Kuramoto inputs.

`validate_scpn_upde_edge_payload(payload)` ¶

Validate a knm.scpn-upde payload emitted by this module.

`scpn_quantum_control.bridge.snn_adapter` ¶

SNN <> quantum bridge: spike trains to rotation angles, measurements to currents.

Supports raw numpy spike arrays and optional sc-neurocore ArcaneNeuron integration.

`SNNQuantumBridge` ¶

Bidirectional bridge: spike trains -> quantum circuit -> input currents.

Orchestrates: firing rate -> Ry angles -> QuantumDenseLayer -> P(|1>) -> current. sc-neurocore is optional (pure numpy spike arrays accepted).

`forward(spike_history)` ¶

Full forward pass: spike history -> quantum -> output currents.

spike_history: (timesteps, n_inputs) binary spike array of any numeric dtype; integer spike trains are accepted and coerced to float64. Returns (n_neurons,) input currents for next SNN layer.

`ArcaneNeuronBridge` ¶

Bridge between sc-neurocore ArcaneNeuron and quantum layer.

Runs ArcaneNeuron for n_steps, collects spike history from v_fast threshold crossings, passes through quantum layer, feeds output currents back as ArcaneNeuron input.

Requires: pip install sc-neurocore

`step_neurons(currents)` ¶

Step all ArcaneNeurons, return binary spike vector.

`quantum_forward()` ¶

Pass accumulated spike history through quantum layer.

Returns (n_neurons,) output currents.

`step(external_currents)` ¶

Full cycle: step neurons -> quantum forward -> output.

Returns dict with spike vector, output currents, and neuron states.

`reset()` ¶

Reset neurons and spike history. v_deep persists (identity).

`spike_train_to_rotations(spikes, window=10)` ¶

Convert spike history to Ry rotation angles.

spikes: (timesteps, n_neurons) binary array of any numeric dtype; the integer spike trains an SNN produces are accepted and coerced to float64. Returns (n_neurons,) angles = firing_rate * pi, in [0, pi].

`quantum_measurement_to_current(values, scale=1.0)` ¶

Convert quantum output values to SNN input currents.

values: (n_neurons,) array — either P(|1>) probabilities in [0, 1] or binary spike indicators (0/1). Both are valid inputs. Returns (n_neurons,) input currents scaled by scale.

`scpn_quantum_control.bridge.ssgf_adapter` ¶

SSGF <> quantum bridge: geometry matrices to Hamiltonians, states to circuits.

Standalone functions work with numpy arrays. SSGFQuantumLoop provides optional integration with the live SSGFEngine from SCPN-CODEBASE.

`SSGFQuantumLoop` ¶

Quantum-in-the-loop wrapper for SSGFEngine.

Each step: read W and theta from SSGFEngine -> compile to Pauli Hamiltonian -> Trotter evolve on statevector -> extract phases -> write back to SSGFEngine.

Requires SCPN-CODEBASE on sys.path for SSGFEngine import.

`quantum_step()` ¶

One quantum-in-the-loop step.

Read W, theta from SSGFEngine
Compile W -> Pauli Hamiltonian
Encode theta -> quantum circuit
Trotter evolve
Extract new theta, R_global
Write theta back to SSGFEngine

`ssgf_w_to_hamiltonian(W, omega)` ¶

Convert SSGF geometry matrix W to Pauli Hamiltonian.

W has the same structure as K_nm (symmetric, non-negative, zero diagonal), so the existing knm_to_hamiltonian compiler applies directly.

`ssgf_state_to_quantum(state_dict)` ¶

Encode SSGF oscillator phases into qubit XY-plane rotations.

state_dict must contain 'theta': array of oscillator phases. Each qubit i gets Ry(pi/2)Rz(theta_i), producing (|0>+e^{itheta}|1>)/sqrt(2). This preserves phase in =cos(theta), =sin(theta) for roundtrip recovery.

`quantum_to_ssgf_state(sv, n_osc)` ¶

Extract oscillator phases and coherence from statevector.

Per-qubit: theta_i = atan2(, ). R_global = |mean(exp(i*theta))|.

Phase¶

`scpn_quantum_control.phase.xy_kuramoto` ¶

Quantum Kuramoto solver via XY spin Hamiltonian + Trotter evolution.

The Kuramoto model d(theta_i)/dt = omega_i + K*sum_j sin(theta_j - theta_i) is isomorphic to the XY spin Hamiltonian: H = -sum_{i<j} K_ij (X_iX_j + Y_iY_j) - sum_i omega_i Z_i

Quantum hardware simulates this natively via Trotterized time evolution.

`QuantumKuramotoSolver` ¶

Trotterized quantum simulation of Kuramoto oscillators.

Each oscillator maps to one qubit. The XY coupling simulates the sin(theta_j - theta_i) interaction natively.

`init(n_oscillators, K_coupling, omega_natural, trotter_order=None, evolution_config=None)` ¶

K_coupling: (n,n) coupling matrix, omega_natural: (n,) frequencies.

`build_hamiltonian()` ¶

Compile K + omega into SparsePauliOp. Called automatically by evolve().

`evolve(time, trotter_steps=None)` ¶

Build Trotterized evolution circuit U(t) = exp(-iHt).

Uses LieTrotter (order=1, O(t²/reps)) or SuzukiTrotter (order=2, O(t³/reps²)) depending on self.trotter_order.

`measure_order_parameter(sv)` ¶

Compute Kuramoto R from qubit X,Y expectations.

Rexp(ipsi) = (1/N) sum_j ( + i)

`run(t_max, dt, trotter_per_step=None, *, max_statevector_gib=None, deadline_monotonic=None, cancelled=None)` ¶

Time-stepped evolution returning R(t) and per-qubit expectations.

This local simulator path stores an exact dense statevector. Use max_statevector_gib to cap all declared live state, evolution, measurement and trajectory buffers before Qiskit allocation. History admission also includes the Python time list. Snapshot admission is not a bound on undeclared third-party workspaces. The local reservation serializes cooperating calls in this process. deadline_monotonic and cancelled are checked at evolution/history checkpoints; native calls already in progress are not forcibly terminated.

`energy_expectation(sv)` ¶

Compute for a given statevector.

`scpn_quantum_control.phase.kuramoto_variants` ¶

Higher-order, monitored, and PT-symmetric Kuramoto trajectories.

`KuramotoVariant` ¶

`scpn_quantum_control.phase.phase_vqe` ¶

VQE for Kuramoto/XY Hamiltonian ground state.

Finds the maximum synchronization configuration of the coupled oscillator system using a variational quantum eigensolver with physics-informed ansatz where entanglement topology matches Knm sparsity.

`PhaseVQE` ¶

VQE solver for the XY Kuramoto Hamiltonian ground state.

The ground state corresponds to maximum phase synchronization (minimum energy = strongest coupling alignment).

`init(K, omega, ansatz_reps=2, threshold=0.01)` ¶

Build Hamiltonian and K_nm-informed ansatz from coupling parameters.

`parameter_shift_gradient(params)` ¶

Return analytic parameter-shift gradients for the current ansatz.

`value_and_parameter_shift_gradient(params)` ¶

Return the VQE energy and structured parameter-shift gradient metadata.

`solve(optimizer='COBYLA', maxiter=200, seed=None, gradient_method=None)` ¶

Run VQE optimisation.

Returns dict with ground_energy, optimal_params, n_evals, and gradient metadata.

`ground_state()` ¶

Return the optimized ground state vector (call solve first).

`PhaseVQEResult` ¶

Bases: TypedDict

Structured result returned by :meth:PhaseVQE.solve.

`scpn_quantum_control.phase.coupling_learning` ¶

Parameter-shift coupling learning for oscillator observation models.

`CouplingGradientVerificationResult` `dataclass` ¶

Finite-difference agreement certificate for coupling-learning gradients.

`__post_init__()` ¶

Validate and defensively copy gradient-verification evidence.

`to_dict()` ¶

Return JSON-ready gradient-verification evidence.

`CouplingLearningResult` `dataclass` ¶

Auditable parameter-shift coupling-learning result.

`best_loss` `property` ¶

The best full-observation mean-squared loss.

`max_abs_residual` `property` ¶

The largest absolute observation residual.

`to_dict()` ¶

Return JSON-ready coupling-learning evidence.

`coupling_matrix_from_edge_vector(values, *, n_nodes, edges=None)` ¶

Build a symmetric zero-diagonal coupling matrix from edge parameters.

`learn_couplings_from_observations(observation_model, target_observations, initial_couplings, *, n_nodes=None, edges=None, backend='statevector', rule=None, learning_rate=0.1, max_steps=100, gradient_tolerance=1e-08, value_tolerance=None, target_loss_tolerance=1e-08, min_loss_decrease=None, allow_hardware=False)` ¶

Learn symmetric coupling parameters from differentiable observations.

The observation model must be a smooth, parameter-shift-compatible quantum expectation or sinusoidal surrogate over the supplied couplings. Arbitrary classical regressors are intentionally outside this claim boundary.

`verify_coupling_parameter_shift_gradient(observation_model, target_observations, couplings, *, n_nodes=None, edges=None, rule=None, finite_difference_step=1e-06, tolerance=1e-05)` ¶

`run_coupling_recovery_suite(cases=None)` ¶

Run the deterministic bounded coupling-recovery evidence suite.

`simulate_kuramoto_phase_time_series(couplings, omega, theta0, *, dt, n_steps)` ¶

Generate a fixed-step RK4 Kuramoto phase trajectory.

`simulate_xy_pair_energy_time_series(couplings, phases)` ¶

Generate synthetic edge-resolved XY pair-energy observations.

`scpn_quantum_control.phase.synchronisation_witness` ¶

Order-parameter and persistent-homology synchronisation witnesses.

Provides bounded synchronisation witnesses over synthetic phase clouds: harmonic Kuramoto order parameters, exact Vietoris--Rips persistent homology (Betti curves and persistence diagrams in dimensions 0 and 1) over geodesic phase distances, bootstrap uncertainty on the order parameter, and deterministic synchronised, desynchronised, and clustered reference regimes. The persistence computation is the standard reduction of the boundary matrix over GF(2) and is exact for the small phase clouds used here; it is not an accelerated timing kernel, hardware phase tomography, or high-dimensional manifold inference.

`SYNC_WITNESS_CLAIM_BOUNDARY = 'bounded synthetic phase-cloud synchronisation witnesses (harmonic Kuramoto order parameters and exact Vietoris-Rips persistent homology in dimensions 0 and 1 over geodesic phase distances) with known reference regimes; not hardware phase tomography, provider execution, isolated timing, or high-dimensional manifold inference'` `module-attribute` ¶

Claim boundary attached to synchronisation-witness records.

`SYNC_WITNESS_EVIDENCE_CLASS = 'functional_non_isolated'` `module-attribute` ¶

Evidence class for local synthetic synchronisation-witness runs.

Return fail-closed synchronisation-witness boundary rows.

`vietoris_rips_persistence(distance, *, max_dimension=1)` ¶

`run_differentiable_workflow_audit_suite(*, finite_shot_target_standard_error=0.02, coupling_learning_rate=0.35, coupling_max_steps=80, gradient_tolerance=1e-07)` ¶

Run the built-in cross-workflow differentiable-programming audit suite.

`run_finite_shot_gradient_uncertainty_audit(objective, initial_values, *, rule=None, plus_variances=0.04, minus_variances=0.04, target_standard_error=0.02, min_shots=64, max_shots_per_evaluation=None, confidence_level=0.95, confidence_z=1.959963984540054)` ¶

Audit finite-shot parameter-shift uncertainty propagation.

The shifted expectation values are evaluated deterministically, while the supplied variances and planned shots define the stochastic uncertainty envelope. This certifies propagation and containment semantics; it does not claim live hardware sampling correctness.

`run_known_phase_gradient_audit(initial_values=None, *, learning_rate=0.35, max_steps=80, finite_difference_step=1e-06, finite_difference_tolerance=1e-05, analytic_tolerance=1e-10, target_value_tolerance=1e-08)` ¶

Solve a regularised metric system fail-closed.

The returned direction is a preconditioned descent direction for minimisation steps of the form params - step_size * direction. Singular or ill-conditioned positive-semidefinite metrics receive the smallest diagonal shift required by the damping, eigenvalue-floor, and condition policy. Indefinite metrics fail closed instead of being silently repaired.

`parameter_shift_natural_gradient_descent(objective, initial_params, *, metric_tensor=None, parameters=None, rule=None, backend='statevector', learning_rate=0.1, max_steps=100, gradient_tolerance=1e-08, natural_gradient_tolerance=1e-08, value_tolerance=None, damping=1e-08, eigenvalue_floor=0.0, max_condition_number=1000000000000.0, degeneracy_tolerance=1e-10, sufficient_decrease=0.0001, backtracking_factor=0.5, max_backtracks=12, allow_hardware=False)` ¶

Minimise a phase objective with parameter-shift natural gradients.

The function composes native parameter-shift gradients with an explicit metric tensor supplied by the caller. The default identity metric is an auditable preconditioner baseline, not a claim of quantum Fisher metric extraction. Hardware backends remain fail-closed through the backend planner unless an explicit future policy enables them.

`validate_natural_gradient_training(result, *, gradient_tolerance=None, natural_gradient_tolerance=None, target_value=None, target_value_tolerance=None, min_decrease=None)` ¶

Validate natural-gradient descent provenance against explicit gates.

`scpn_quantum_control.phase.trainability` ¶

Barren-plateau diagnostics and finite-shot dry-run planning.

objective Scalar objective accepting a one-dimensional float64 parameter vector. sample_params Matrix of parameter vectors. At least two samples are required so the empirical gradient variance is defined. parameters Optional parameter metadata controlling names and trainable masks. rule Optional single- or multi-frequency parameter-shift rule. plus_variances, minus_variances Optional caller-supplied finite-shot measurement variances. When absent, the report derives a conservative variance tensor from sampled gradient variance and gradient_variance_threshold. target_standard_error Desired standard error for each trainable gradient component. gradient_variance_threshold Low-variance threshold and variance floor for derived shot allocation. gradient_norm_threshold Low-gradient-norm threshold for barren-plateau classification. min_shots Minimum shots for each plus/minus shifted evaluation. max_shots_per_evaluation Optional cap for each shifted evaluation. backend Backend name passed to the quantum-gradient planner. Hardware backends fail closed because this function never requests hardware approval. cost_per_shot Non-negative dry-run cost multiplier. cost_unit Non-empty label for estimated_cost.

Returns¶

BarrenPlateauTrainabilityReport Gradient-variance diagnostics and a zero-execution shot-allocation dry run.

Raises¶

ValueError If inputs are malformed or if the backend planner reports a fail-closed route.

The report samples parameter-shift gradients across caller-supplied parameter vectors, flags flat low-variance landscapes, and uses the existing finite-shot allocator to estimate shot counts before any backend execution.

`scpn_quantum_control.phase.optimizer_audit` ¶

Multi-start convergence evidence for parameter-shift phase optimizers.

`OptimizerConvergenceRecord` `dataclass` ¶

One optimizer result reduced to serialisable audit evidence.

`to_dict()` ¶

Return JSON-ready convergence evidence.

`OptimizerComparisonSuiteResult` `dataclass` ¶

Multi-start optimizer comparison with explicit claim boundaries.

`optimizers` `property` ¶

Optimizer names in first-seen order.

`certificate_failures` `property` ¶

Records whose convergence certificate failed.

`records_for_start(start_index)` ¶

Return all optimizer records for one start index.

`to_dict()` ¶

Return JSON-ready suite metadata.

`run_parameter_shift_optimizer_comparison(objective=None, starts=None, *, metric_tensor=None, parameters=None, rule=None, backend='statevector', learning_rate=0.4, max_steps=12, gradient_tolerance=1e-08, natural_gradient_tolerance=1e-08, certificate_gradient_tolerance=None, certificate_natural_gradient_tolerance=None, target_value=None, target_value_tolerance=None, min_decrease=0.0, comparison_tolerance=1e-10, require_natural_not_worse=True, allow_hardware=False)` ¶

Run a bounded multi-start optimizer comparison for phase objectives.

Scenarios that fail closed by plan or execution guard.

`failing_records` `property` ¶

Scenarios whose observed outcome did not match the expectation.

`to_dict()` ¶

Return JSON-ready provider-gradient audit metadata.

`default_provider_gradient_readiness_scenarios()` ¶

Return built-in provider-gradient support and fail-closed scenarios.

`run_provider_gradient_readiness_audit(scenarios=None, *, tolerance=1e-10)` ¶

Run executable provider-gradient readiness checks.

The audit intentionally mixes successful local callback routes with blocked hardware, unknown-backend, and malformed-sample routes. A passing audit means supported paths produce the expected gradients and unsupported paths refuse execution with explicit reasons; it is not a hardware execution claim.

`scpn_quantum_control.phase.trotter_upde` ¶

Quantum 16-layer UPDE solver: multi-site spin chain.

The 16-layer SCPN UPDE with Knm coupling becomes a 16-qubit system where each qubit encodes one layer's phase. Inter-layer coupling K[n,m] maps to XY interaction strength; natural frequencies Omega_n map to Z fields.

`QuantumUPDESolver` ¶

Full 16-layer UPDE as quantum spin chain.

Wraps QuantumKuramotoSolver with canonical SCPN parameters.

`init(K=None, omega=None, trotter_order=1)` ¶

Defaults to canonical 16-layer Paper 27 parameters if K/omega not given.

`step(dt=0.1, trotter_steps=5)` ¶

Single Trotter step, return per-layer expectations and global R.

`run(n_steps=50, dt=0.1, trotter_per_step=5)` ¶

Full trajectory returning R(t) over n_steps.

`reset()` ¶

Reset statevector so the next step() reinitialises from omega.

`hamiltonian()` ¶

Return the compiled XY Hamiltonian, or None if not yet built.

Studio¶

`scpn_quantum_control.studio.recompute_kernel` ¶

Recompute-verifiable Studio units for deterministic compile claims.

`XYCompileRecomputeUnit` `dataclass` ¶

Signed-unit payload for bit-exact XY compile recomputation.

`to_dict()` ¶

Return a JSON-ready recompute unit.

`build_xy_compile_recompute_unit(K_nm, omega, *, time, trotter_steps, trotter_order)` ¶

Build a bit-exact Studio recompute unit for an XY compile claim.

`canonical_xy_compile_input_bytes(K_nm, omega, *, time, trotter_steps, trotter_order)` ¶

Return the canonical binary input consumed by the WASM verifier kernel.

`verify_xy_compile_recompute_unit(unit)` ¶

Verify a recompute unit by comparing its claimed and recomputed digests.

`xy_compile_digest_python(input_bytes)` ¶

Return the Python reference digest for the WASM compile verifier input.

Control¶

`scpn_quantum_control.control.qaoa_mpc` ¶

QAOA for MPC trajectory optimisation.

Discretises the MPC action space to binary (coil on/off per timestep), maps the quadratic tracking cost to an Ising Hamiltonian, then solves via QAOA. The cost keeps the vector residual u_t * (B @ ones) - target; collapsing it to norms would discard the target's sign and its direction relative to B.

`QAOA_MPC` ¶

QAOA-based model predictive controller.

Cost: C = sum_t ||u_t * (B @ ones) - target||^2 with binary u_t in {0, 1}, one coil on/off decision per timestep. The residual stays a vector, so a sign flip or rotation of target changes the optimum. This quadratic-in-binary form is equivalent to an Ising Hamiltonian.

`init(B_matrix, target_state, horizon, p_layers=2)` ¶

Initialize the binary model-predictive controller.

Parameters¶

B_matrix Linear map from binary actions to the controlled state. target_state State vector used to construct the quadratic tracking cost. horizon Positive number of binary control timesteps and circuit qubits. p_layers Positive number of alternating QAOA cost and mixer layers.

Raises¶

ValueError If horizon or p_layers is not positive.

`build_cost_hamiltonian()` ¶

Map per-timestep quadratic binary cost to Ising Hamiltonian.

The tracking cost is C(u) = sum_t ||u_t * v - r||^2 with v = B @ ones and r the target. Using u_t^2 = u_t for binary u_t and u_t = (1 - Z_t)/2::

q  = ||v||^2 - 2 * (v . r)
C  = H*q/2 + H*||r||^2 - (q/2) * sum_t Z_t

so h_z = -q/2. There are no ZZ terms because the timesteps are independent; the coupling this mapping preserves is the v . r cross-term inside the norm, which a norm-only surrogate discards along with the target's sign.

Returns¶

qiskit.quantum_info.SparsePauliOp Diagonal identity-and-Z cost Hamiltonian for the control horizon.

`optimize(seed=None, *, max_dense_gib=None)` ¶

Run QAOA optimization, return binary action sequence.

The circuit is simulated densely, so the horizon sets a 2**horizon statevector. Admission is checked once here, before the optimiser runs, rather than inside the cost function that the optimiser calls up to two hundred times: a budget that cannot hold the state should refuse before any allocator is entered, not on the first iteration.

Two objects of the statevector's size are accounted for. The state itself is live throughout, and the expectation value against the cost Hamiltonian, and later probabilities(), each need a second array of the same dimension while the first is still held.

Parameters¶

seed Optional seed for the variational parameter initialization. max_dense_gib Optional dense-allocation budget in GiB. None uses the active process budget.

Returns¶

numpy.ndarray Integer array of zero/one actions shaped (horizon,).

Raises¶

DenseAllocationError If the statevector for horizon qubits exceeds the budget. RuntimeError If the cost Hamiltonian could not be constructed.

`scpn_quantum_control.control.q_disruption_iter` ¶

ITER-specific disruption classifier with 11 physics-based features.

Feature ranges from ITER Physics Basis, Nuclear Fusion 39 (12), 1999.

Integration with scpn-fusion-core: use from_fusion_core_shot() to load real tokamak disruption data from NPZ archives.

`ITERFeatureSpec` `dataclass` ¶

11 ITER disruption features with physical units and valid ranges.

`DisruptionBenchmark` ¶

ITER disruption classification benchmark using quantum circuit classifier.

`run(epochs=10, lr=0.1)` ¶

Train and evaluate. Returns accuracy + predictions.

`normalize_iter_features(raw, spec=None)` ¶

Min-max normalize using ITER physics ranges, clip to [0, 1].

`generate_synthetic_iter_data(n_samples, disruption_fraction=0.3, rng=None, *, allow_synthetic=False)` ¶

Synthetic ITER disruption data for classifier benchmarking.

Safe samples: drawn from normal distributions near ITER operational point. Disruption samples: shifted locked_mode up, q95 down, beta_N up. Returns (X, y) where X is (n_samples, 11) normalized, y is binary labels.

`from_fusion_core_shot(shot_data, *, allow_center_defaults=False, allow_density_proxy=False)` ¶

Convert a fusion-core NPZ disruption shot to ITER feature vector.

dict loaded from scpn_fusion.io.tokamak_disruption_archive

with keys like Ip_MA, q95, beta_N, locked_mode_amp, ne_1e19, is_disruption, disruption_time_idx.

Returns (features_11, label, warnings) where features are time-averaged scalars normalized to [0, 1], label is 0 (safe) or 1 (disruption), and warnings lists any explicitly allowed centre defaults.

ne_1e19 maps to the n_GW slot only when allow_density_proxy is true. For production Greenwald fraction input, provide n_GW directly.

`scpn_control_bridge_dependency_contract()` ¶

Return the SCPN-CONTROL disruption bridge dependency contract.

The contract is intentionally mirrored locally instead of importing SCPN-CONTROL, so this backend can be validated before CONTROL is installed.

`validate_scpn_control_bridge_dependency_contract(payload)` ¶

Validate the SCPN-CONTROL disruption bridge dependency contract.

QSNN¶

`scpn_quantum_control.qsnn.qlif` ¶

Quantum LIF neuron: Ry rotation + Z-basis measurement.

Maps the classical StochasticLIFNeuron membrane dynamics to a parameterized quantum circuit. Membrane voltage encodes as rotation angle; measurement produces spike/no-spike with probability matching classical firing rate.

`QuantumLIFNeuron` ¶

Single-qubit LIF neuron.

Membrane equation (Euler): v(t+1) = v(t) - (dt/tau)(v(t) - v_rest) + RIdt

Quantum mapping

theta = pi * clip((v - v_rest) / (v_threshold - v_rest), 0, 1) P(spike) = sin^2(theta/2) spike = 1 if P(|1>) > 0.5 (statevector mode)

`init(v_rest=0.0, v_threshold=1.0, tau_mem=20.0, dt=1.0, resistance=1.0, n_shots=100, rng=None)` ¶

n_shots=0 uses deterministic threshold; n_shots>0 uses stochastic sampling.

`step(input_current)` ¶

Update membrane, build Ry circuit, measure, return spike (0 or 1).

`get_circuit()` ¶

Return the last Ry circuit built by step(), or None.

`reset()` ¶

Reset membrane to v_rest.

`scpn_quantum_control.qsnn.qlayer` ¶

Quantum dense layer: multi-qubit entangled spiking network.

Maps sc-neurocore SCDenseLayer to a parameterized circuit

Input register: Ry-encoded input values
Synapse connections: CRy gates from input to neuron qubits
Entanglement: CX chain between neuron qubits
Readout: measure neuron register, threshold for spikes

`QuantumDenseLayer` ¶

Multi-qubit dense layer with entanglement between neurons.

n_qubits = n_inputs + n_neurons. Input qubits: [0, n_inputs) Neuron qubits: [n_inputs, n_inputs + n_neurons)

The layer encodes clipped inputs with Ry rotations, applies learned controlled rotations, entangles adjacent neuron qubits, and thresholds exact marginal probabilities into binary spikes.

`init(n_neurons, n_inputs, weights=None, spike_threshold=0.5, seed=None)` ¶

Initialize a quantum dense layer.

Parameters¶

n_neurons Number of output neuron qubits. n_inputs Number of input qubits. weights Synaptic weight matrix with shape (n_neurons, n_inputs). When omitted, weights are sampled uniformly from [0, 1]. spike_threshold Strict marginal-probability threshold used to emit a spike. seed Seed for random weight initialization when weights is omitted.

`forward(input_values, *, max_dense_gib=None)` ¶

Evolve the dense state in-place and threshold neuron probabilities.

Parameters¶

input_values Input vector with shape (n_inputs,). Values are clipped to [0, 1] before angle encoding. max_dense_gib Optional statevector budget in GiB; otherwise the current process budget applies. Checked before allocating the dense state.

Returns¶

NDArray[np.int64] Binary spike vector with shape (n_neurons,).

Raises¶

DenseAllocationError If the statevector exceeds the active budget.

`get_weights()` ¶

Return the synaptic weight matrix.

Returns¶

NDArray[np.float64] Weight matrix with shape (n_neurons, n_inputs).

`scpn_quantum_control.qsnn.training` ¶

Parameter-shift gradient training for QuantumDenseLayer.

Uses (f(w+pi/2) - f(w-pi/2)) / 2 per CRy angle on MSE loss.

`QSNNTrainer` ¶

Gradient-based trainer for QuantumDenseLayer via parameter-shift rule.

`init(layer, lr=0.01, *, max_dense_gib=None)` ¶

Bind a layer to the parameter-shift trainer.

Every forward pass simulates the layer densely, so the qubit count fixes a 2**n_qubits statevector. Admission is checked at construction and again before each forward-pass circuit is built, since the layer and active process budget may change. The saved explicit budget, when given, applies to later passes too. Two complex-vector equivalents account for the state and the real absolute-value/square probability buffers.

Parameters¶

layer Quantum dense layer to train. lr Learning rate for the descent optimiser. max_dense_gib Optional dense-allocation budget in GiB. None uses the active process budget.

Raises¶

DenseAllocationError If a forward-pass statevector for the layer exceeds the budget.

`parameter_shift_gradient(inputs, target)` ¶

Compute gradient of MSE loss w.r.t. all synapse angles.

Returns (n_neurons, n_inputs) gradient array.

`train_epoch(X, y)` ¶

One epoch over dataset. Returns mean loss.

`train(X, y, epochs=10)` ¶

Train for multiple epochs. Returns loss history.

`train_with_diagnostics(X, y, epochs=10)` ¶

Train and return structured convergence plus evaluation evidence.

`train_with_parameter_shift_descent(X, y, *, backend='statevector', max_steps=100, gradient_tolerance=1e-08, value_tolerance=None, target_loss=None, target_loss_tolerance=1e-08, min_loss_decrease=None, allow_hardware=False)` ¶

Return JSON-ready audit metadata.

`differentiable_circuit(objective, *, name='differentiable_circuit', parameter_names=(), gate='ry', observable='pauli_expectation', backend='statevector', transform='grad', adapter='native', gradient_method='parameter_shift', shot_policy=None, estimator_provenance=None)` ¶

Return a configured differentiable circuit facade for a scalar objective.

`jit_or_explain(function, *, backend='statevector', adapter='native')` ¶

Return a fail-closed JIT explanation for the canonical namespace.

The project currently exposes executable local gradients and compiler-AD evidence surfaces separately. This helper gives first-path users a stable JIT entry point that refuses unsupported compilation routes with actionable alternatives instead of silently falling back to eager execution.

`run_differentiable_circuit_contract_audit()` ¶

Run the executable audit through public diff namespace surfaces.

Returns¶

DifferentiableCircuitContractAuditResult Supported and fail-closed checks for call semantics, transform composition, backend capability metadata, and serialization provenance.

`supported_transforms()` ¶

Return the stable transform names exposed by the canonical namespace.

`namespace_metadata()` ¶

Return JSON-ready metadata for the canonical differentiable namespace.

`scpn_quantum_control.differentiable` ¶

Native differentiable-programming primitives for SCPN quantum objectives.

The base layer is backend-neutral parameter-shift differentiation for scalar objectives. Optional JAX support is exposed as an adapter without making JAX a runtime dependency of the core package.

`Parameter` `dataclass` ¶

One differentiable scalar parameter in an SCPN objective.

`__post_init__()` ¶

Validate parameter identity and trainability metadata.

`to_semantic_source()` ¶

Project native derivative-request identity and trainability.

Returns¶

dict[str, object] Name and mask bit without inventing a parameter value or unit.

`ParameterBounds` `dataclass` ¶

Closed interval constraint for one differentiable scalar parameter.

`__post_init__()` ¶

Validate finite interval and periodic-bound metadata.

`ParameterShiftRule` `dataclass` ¶

Symmetric parameter-shift rule for one- or multi-frequency generators.

`terms` `property` ¶

(shift, coefficient) terms for symmetric plus/minus probes.

`is_single_term` `property` ¶

Whether this rule is the legacy two-evaluation rule.

`__post_init__()` ¶

Validate and freeze explicit parameter-shift terms.

`ParameterShiftSampleRecord` `dataclass` ¶

One plus/minus shifted sample used in stochastic parameter-shift propagation.

`__post_init__()` ¶

Validate one finite-shot parameter-shift contribution record.

`to_dict()` ¶

Return JSON-ready shifted-sample provenance.

`DualNumber` `dataclass` ¶

Forward-mode automatic differentiation scalar with one tangent lane.

Parameters¶

primal Real primal scalar carried by the differentiable expression. tangent Real derivative with respect to the active scalar seed.

Attributes¶

primal Validated real primal scalar. tangent Validated real tangent scalar for the active derivative lane.

`__post_init__()` ¶

Validate the stored primal and tangent as real scalar values.

`coerce(value)` `staticmethod` ¶

Convert an operand into a forward-mode scalar.

Parameters¶

value Existing :class:DualNumber or real scalar operand.

Returns¶

DualNumber The original dual value, or a zero-tangent constant dual value.

Raises¶

ValueError If value is not a finite real scalar or dual value.

`add(other)` ¶

Return the forward-mode addition rule.

`radd(other)` ¶

Return reflected forward-mode addition.

`sub(other)` ¶

Return the forward-mode subtraction rule.

`rsub(other)` ¶

Return reflected forward-mode subtraction.

`mul(other)` ¶

Return the forward-mode product rule.

`rmul(other)` ¶

Return reflected forward-mode multiplication.

`truediv(other)` ¶

Return the forward-mode quotient rule.

`rtruediv(other)` ¶

Return reflected forward-mode division.

`neg()` ¶

Return the negated primal and tangent.

`pow(other)` ¶

Return the forward-mode scalar power rule.

`rpow(other)` ¶

Return reflected forward-mode scalar exponentiation.

`ReverseNode` ¶

Reverse-mode automatic differentiation scalar with local pullbacks.

Parameters¶

primal Real primal scalar represented by the node. parents Parent nodes paired with local derivative coefficients.

Attributes¶

primal Validated real primal scalar. parents Tuple of upstream nodes and pullback coefficients. adjoint Reverse accumulation slot seeded by a downstream traversal.

`coerce(value)` `staticmethod` ¶

Convert an operand into a reverse-mode node.

Parameters¶

value Existing :class:ReverseNode or real scalar operand.

Returns¶

ReverseNode The original node, or a constant node with no parents.

Raises¶

ValueError If value is not a finite real scalar or reverse node.

`add(other)` ¶

Return the reverse-mode addition pullback.

`radd(other)` ¶

Return reflected reverse-mode addition.

`sub(other)` ¶

Return the reverse-mode subtraction pullback.

`rsub(other)` ¶

Return reflected reverse-mode subtraction.

`mul(other)` ¶

Return the reverse-mode product pullback.

`rmul(other)` ¶

Return reflected reverse-mode multiplication.

`truediv(other)` ¶

Return the reverse-mode quotient pullback.

`rtruediv(other)` ¶

Return reflected reverse-mode division.

`neg()` ¶

Return the reverse-mode negation pullback.

`pow(other)` ¶

Return the reverse-mode scalar power pullback.

`rpow(other)` ¶

Return reflected reverse-mode scalar exponentiation.

`GradientResult` `dataclass` ¶

`__post_init__()` ¶

Validate bytecode offsets, operation name, and source line.

`WholeProgramBytecodeBasicBlock` `dataclass` ¶

One static Python-bytecode basic block for frontend planning.

The block is derived from normalized dis instructions without executing the objective. Successors are bytecode offsets only; they are a static control-flow skeleton for audits and later lowerings, not executable compiler evidence.

`__post_init__()` ¶

Validate block bounds, instructions, successors, and terminator.

Static semantics summary for whole-program AD graph capture.

`__post_init__()` ¶

Validate semantic flags and accepted or unsupported labels.

`WholeProgramCompilerFrontendReport` `dataclass` ¶

Static bytecode/source frontend report for whole-program AD objectives.

The report inspects Python bytecode and source-derived AST features without executing the objective. It is a compiler-frontend preflight artefact for accepted whole-program AD semantics, not executable Rust, LLVM, JIT, provider, hardware, or benchmark evidence.

Parameters¶

function_name: Python callable name used for diagnostics. bytecode_instructions: Normalised Python bytecode instruction rows from dis. bytecode_basic_blocks: Static control-flow block skeleton derived from the bytecode stream. source_ir_features: Source-level AST feature rows used by the Program AD frontend. source_regions: Static source-region graph derived from bounded AST constructs. source_bytecode_line_map: Static crosswalk from source lines to bytecode offsets, source regions, and source feature kinds. symbol_scope_entries: Static symbol-scope table derived from source names, bytecode operands, and function code-object scope metadata. unsupported_semantic_diagnostics: Static fail-closed diagnostics for unsupported Python constructs. semantics_report: Static semantics summary derived from bytecode and source features. source_available: Whether source text could be obtained through introspection. source_sha256: SHA-256 digest of the dedented source when available. source_start_line: Absolute file line where the inspected source snippet starts. source_end_line: Absolute file line where the inspected source snippet ends. bytecode_digest: SHA-256 digest over the normalised bytecode instruction stream. frontend_digest: SHA-256 digest over bytecode, source, source features, source regions, and semantic support metadata. ast_node_count: Number of AST nodes in the parsed source tree when available. hard_gaps: Named blockers that prevent the report from being accepted as a complete bytecode/source frontend preflight. claim_boundary: Boundary preventing this static report from becoming an execution or performance claim.

`bytecode_instruction_count` `property` ¶

The number of bytecode instructions in the frontend report.

`source_feature_count` `property` ¶

The number of source IR feature rows in the frontend report.

`frontend_ready` `property` ¶

Whether bytecode and source frontend metadata passed preflight.

`bytecode_basic_block_count` `property` ¶

The number of bytecode basic blocks in the frontend report.

`source_region_count` `property` ¶

The number of source regions in the frontend report.

`source_bytecode_line_map_count` `property` ¶

The number of source-bytecode crosswalk rows in the report.

`symbol_scope_entry_count` `property` ¶

The number of static symbol-scope entries in the report.

`unsupported_semantic_diagnostic_count` `property` ¶

The number of unsupported-semantics diagnostics in the report.

`__post_init__()` ¶

Validate all static frontend records, digests, and hard gaps.

`to_dict()` ¶

Return a JSON-ready compiler frontend report.

`ProgramADAdjointStep` `dataclass` ¶

One generated reverse-adjoint step over stabilized Program AD IR.

The step binds a primal SSA value and stabilized effect row to the local pullback inputs, finite incoming cotangent, local pullback coefficients, emitted contribution cotangents, effect ordering metadata, and any unambiguous runtime control/phi row used by reverse-mode adjoint generation. Non-executed phi inputs are recorded as blocked adjoints rather than replay contributions. It is an auditable generation plan over program_ad_effect_ir.v1 metadata; it does not add non-executed branch adjoints or executable compiler lowering.

`__post_init__()` ¶

Validate reverse-adjoint step metadata at construction time.

`to_dict()` ¶

Return a JSON-ready reverse-adjoint generation step.

`TraceADArray` ¶

Derivative-carrying ranked array for whole-program AD.

Parameters¶

items: Row-major scalar trace values carried by the array. shape: Static NumPy-compatible shape whose element count matches items. context: Trace context shared by every scalar item. source_indices: Optional original parameter slots retained through alias-preserving views; None entries identify constants or overwritten elements.

Notes¶

Supported NumPy functions dispatch through __array_function__ and supported ufuncs through __array_ufunc__. Raw ndarray coercion fails closed because it would discard derivative and alias metadata.

`ndim` `property` ¶

The rank of the derivative-carrying array.

`size` `property` ¶

The total number of derivative-carrying elements.

`T` `property` ¶

The NumPy-compatible reversed-axis transpose.

`len()` ¶

Return the leading-axis length of a ranked trace array.

`iter()` ¶

Iterate over trace scalars or rank-one row views.

`array(dtype=None, *, copy=None)` ¶

Reject ndarray coercion that would discard trace metadata.

Parameters¶

dtype Requested native dtype; conversion is refused for every dtype. copy Native NumPy copy request; no value authorizes derivative loss.

Raises¶

ValueError Trace values cannot become plain arrays without dropping derivatives.

`item()` ¶

Return the only scalar element, failing closed for non-scalar arrays.

`copy()` ¶

Return a derivative-preserving shallow array copy.

`reshape(*shape)` ¶

Return a derivative-preserving reshaped array view.

`ravel()` ¶

Return a flat view-preserving program AD array.

`flatten()` ¶

Return a flat copy-equivalent program AD array.

`repeat(repeats, axis=None)` ¶

Return a derivative-preserving array with repeated elements.

`squeeze(axis=None)` ¶

Return a derivative-preserving array with singleton axes removed.

`expand_dims(axis)` ¶

Return a derivative-preserving array with singleton axes inserted.

`swapaxes(axis1, axis2)` ¶

Return a derivative-preserving array with two axes exchanged.

`sum(axis=None)` ¶

Return a derivative-preserving sum over all elements or one axis.

`cumsum(axis=None)` ¶

Return a derivative-preserving cumulative sum.

`prod(axis=None)` ¶

Return a derivative-preserving product over all elements or one axis.

`cumprod(axis=None)` ¶

Return a derivative-preserving cumulative product.

`mean(axis=None)` ¶

Return a derivative-preserving arithmetic mean.

`var(axis=None, ddof=0)` ¶

Return a derivative-preserving variance with NumPy-compatible ddof.

`std(axis=None, ddof=0)` ¶

Return a derivative-preserving standard deviation.

`max(axis=None)` ¶

Return a derivative-preserving maximum with tie-safe semantics.

`min(axis=None)` ¶

Return a derivative-preserving minimum with tie-safe semantics.

`take(indices, axis=None, mode='raise')` ¶

Return derivative-preserving positional elements with fail-closed modes.

`argmax(axis=None)` ¶

Reject nondifferentiable maximum-index selection.

`argmin(axis=None)` ¶

Reject nondifferentiable minimum-index selection.

`getitem(index)` ¶

Return a derivative-preserving indexed scalar or array view.

`setitem(index, value)` ¶

Assign traced values while recording deterministic mutation metadata.

`__array_ufunc__(ufunc, method, *inputs, **kwargs)` ¶

Dispatch direct ufuncs or bounded unbuffered np.add.at mutations.

`__array_function__(func, types, args, kwargs)` ¶

Dispatch a supported NumPy function through fail-closed trace semantics.

`add(other)` ¶

Return the derivative-preserving elementwise sum.

`radd(other)` ¶

Return the derivative-preserving reflected elementwise sum.

`sub(other)` ¶

Return the derivative-preserving elementwise difference.

`rsub(other)` ¶

Return the derivative-preserving reflected elementwise difference.

`mul(other)` ¶

Return the derivative-preserving elementwise product.

`rmul(other)` ¶

Return the derivative-preserving reflected elementwise product.

`truediv(other)` ¶

Return the derivative-preserving elementwise quotient.

`rtruediv(other)` ¶

Return the derivative-preserving reflected elementwise quotient.

`pow(other)` ¶

Return the derivative-preserving elementwise power.

`rpow(other)` ¶

Return the derivative-preserving reflected elementwise power.

`neg()` ¶

Return the derivative-preserving elementwise additive inverse.

`matmul(other)` ¶

Return the derivative-preserving matrix product.

`rmatmul(other)` ¶

Return the derivative-preserving reflected matrix product.

`gt(other)` ¶

Return the traced elementwise strict-greater-than predicate.

`ge(other)` ¶

Return the traced elementwise greater-than-or-equal predicate.

`lt(other)` ¶

Return the traced elementwise strict-less-than predicate.

`le(other)` ¶

Return the traced elementwise less-than-or-equal predicate.

`eq(other)` ¶

Return the traced elementwise equality predicate.

`ne(other)` ¶

Return the traced elementwise inequality predicate.

`TraceADScalar` ¶

Operator-intercepted scalar for exact executed-path whole-program AD.

Parameters¶

primal: Finite real value carried by the trace. tangent: One-dimensional derivative vector aligned with the trace parameters. context: Trace context that owns the value and records derived operations. name: Stable SSA-style label used by trace and adjoint metadata.

Notes¶

Arithmetic, comparisons, and supported NumPy ufuncs preserve the owning context. Conversion to a Python float fails closed because it would discard derivative information.

`float()` ¶

Reject conversion that would discard derivative information.

`int()` ¶

Reject parameter-dependent integer conversion.

Raises¶

ValueError Integer conversion would discard the active derivative and could turn a traced parameter into an unqualified dynamic shape or index.

`index()` ¶

Reject using a traced parameter as an integer shape or index.

Raises¶

ValueError A derivative-carrying scalar has no static integer indexing contract.

`add(other)` ¶

Return the derivative-preserving scalar sum.

`radd(other)` ¶

Return the derivative-preserving reflected scalar sum.

`sub(other)` ¶

Return the derivative-preserving scalar difference.

`rsub(other)` ¶

Return the derivative-preserving reflected scalar difference.

`mul(other)` ¶

Return the derivative-preserving scalar product.

`rmul(other)` ¶

Return the derivative-preserving reflected scalar product.

`truediv(other)` ¶

Return the derivative-preserving scalar quotient.

`rtruediv(other)` ¶

Return the derivative-preserving reflected scalar quotient.

`pow(other)` ¶

Return the derivative-preserving scalar power.

`rpow(other)` ¶

Return the derivative-preserving reflected scalar power.

`neg()` ¶

Return the derivative-preserving additive inverse.

`abs()` ¶

Return the derivative-preserving absolute value.

`gt(other)` ¶

Return the traced strict-greater-than predicate.

`ge(other)` ¶

Return the traced greater-than-or-equal predicate.

`lt(other)` ¶

Return the traced strict-less-than predicate.

`le(other)` ¶

Return the traced less-than-or-equal predicate.

`eq(other)` ¶

Return the traced equality predicate.

`ne(other)` ¶

Return the traced inequality predicate.

`__array_ufunc__(ufunc, method, *inputs, **kwargs)` ¶

Dispatch a supported NumPy ufunc through scalar trace semantics.

`DifferentiableOptimizer` `dataclass` ¶

Native gradient-descent optimizer for differentiable parameters.

Parameters¶

learning_rate: Non-negative step size applied to trainable gradient components before optional bound projection.

`__post_init__()` ¶

Validate and canonicalize the optimizer step size.

`step(values, gradient_result, *, bounds=None, max_gradient_norm=None)` ¶

Return one projected gradient-descent update.

Parameters¶

values: Current real parameter vector. gradient_result: Gradient and trainable-mask metadata for the current point. bounds: Optional per-parameter box or periodic bounds. max_gradient_norm: Optional L2 clipping threshold applied to trainable components.

Returns¶

numpy.ndarray Updated real parameter vector after trainable-mask filtering and optional bound projection.

`minimize(objective, initial_values, *, parameters=None, rule=None, gradient_method='parameter_shift', finite_difference_step=1e-06, bounds=None, max_gradient_norm=None, max_steps=100, gradient_tolerance=1e-08, value_tolerance=None)` ¶

Run bounded gradient descent with native gradient backends.

Parameters¶

objective: Scalar-valued objective evaluated on real parameter vectors. initial_values: Initial real parameter vector before bound projection. parameters: Optional metadata controlling names and trainable masks. rule: Optional parameter-shift rule for the parameter-shift backend. gradient_method: Either "parameter_shift" or "finite_difference". finite_difference_step: Positive central-difference step used by the finite-difference backend. bounds: Optional per-parameter box or periodic bounds. max_gradient_norm: Optional L2 clipping threshold applied to trainable components. max_steps: Non-negative maximum number of descent steps. gradient_tolerance: Non-negative convergence tolerance for the trainable gradient norm. value_tolerance: Optional non-negative convergence tolerance for objective changes.

Returns¶

OptimizationResult Final values, gradient record, value history, convergence status, and best-observed iterate.

`dual_sin(value)` ¶

Evaluate the forward-mode sine primitive.

Parameters¶

value Existing :class:DualNumber or real scalar input.

Returns¶

DualNumber Sine value with tangent multiplied by cos(value).

Raises¶

ValueError If value cannot be represented as a real scalar dual value.

`dual_cos(value)` ¶

Evaluate the forward-mode cosine primitive.

Parameters¶

value Existing :class:DualNumber or real scalar input.

Returns¶

DualNumber Cosine value with tangent multiplied by -sin(value).

Raises¶

ValueError If value cannot be represented as a real scalar dual value.

`dual_exp(value)` ¶

Evaluate the forward-mode exponential primitive.

Parameters¶

value Existing :class:DualNumber or real scalar input.

Returns¶

DualNumber Exponential value with tangent multiplied by exp(value).

Raises¶

ValueError If value cannot be represented as a real scalar dual value.

`dual_log(value)` ¶

Evaluate the forward-mode natural-log primitive.

Parameters¶

value Existing :class:DualNumber or positive real scalar input.

Returns¶

DualNumber Natural-log value with tangent divided by the positive primal.

Raises¶

ValueError If value is not real or its primal is not strictly positive.

`reverse_sin(value)` ¶

Evaluate the reverse-mode sine primitive.

Parameters¶

value Existing :class:ReverseNode or real scalar input.

Returns¶

ReverseNode Sine node with local pullback coefficient cos(value).

Raises¶

ValueError If value cannot be represented as a real scalar reverse node.

`reverse_cos(value)` ¶

Evaluate the reverse-mode cosine primitive.

Parameters¶

value Existing :class:ReverseNode or real scalar input.

Returns¶

ReverseNode Cosine node with local pullback coefficient -sin(value).

Raises¶

ValueError If value cannot be represented as a real scalar reverse node.

`reverse_exp(value)` ¶

Evaluate the reverse-mode exponential primitive.

Parameters¶

value Existing :class:ReverseNode or real scalar input.

Returns¶

ReverseNode Exponential node with local pullback coefficient exp(value).

Raises¶

ValueError If value cannot be represented as a real scalar reverse node.

`reverse_log(value)` ¶

Evaluate the reverse-mode natural-log primitive.

Parameters¶

value Existing :class:ReverseNode or positive real scalar input.

Returns¶

ReverseNode Natural-log node with local pullback coefficient 1 / value.

Raises¶

ValueError If value is not real or its primal is not strictly positive.

`armijo_backtracking_line_search(objective, values, gradient_result, direction, *, bounds=None, initial_step=1.0, contraction=0.5, sufficient_decrease=0.0001, max_steps=20)` ¶

Return a bounded Armijo backtracking step for a scalar objective.

Parameters¶

objective Scalar objective evaluated at candidate parameter vectors. values Current parameter vector. gradient_result Gradient metadata at values. direction Candidate descent direction. Frozen parameter entries are masked out. bounds Optional closed-interval parameter bounds used to project candidates. initial_step Positive first trial step length. contraction Multiplicative step shrinkage in (0, 1). sufficient_decrease Armijo sufficient-decrease coefficient in (0, 1). max_steps Positive trial-step cap.

Returns¶

ArmijoLineSearchResult Accepted candidate or fail-closed rejection metadata.

`register_custom_derivative_rule(identity, rule, *, overwrite=False, registry=None)` ¶

Register a custom derivative rule in the selected or default registry.

Parameters¶

identity: Primitive identity object or canonical identity key. rule: Custom derivative rule to register. overwrite: Whether an existing different rule may be replaced. registry: Optional registry override; the default registry is used when omitted.

Returns¶

CustomDerivativeRule The registered rule.

Raises¶

ValueError If identity/rule validation fails or if a conflicting rule exists and overwrite is disabled.

`register_primitive_transform_rule(transform, *, overwrite=False, registry=None)` ¶

Register a combined derivative, batching, and lowering transform binding.

Parameters¶

transform: Primitive transform binding to register. overwrite: Whether an existing different transform may be replaced. registry: Optional registry override; the default registry is used when omitted.

Returns¶

PrimitiveTransformRule The registered transform binding.

Raises¶

ValueError If transform validation fails or if a conflicting transform exists and overwrite is disabled.

`register_primitive_batching_rule(identity, batching_rule, *, overwrite=False, registry=None)` ¶

Register a batching rule for an existing primitive derivative rule.

Parameters¶

identity: Primitive identity object or canonical identity key. batching_rule: Callable implementing batching for the primitive. overwrite: Whether an existing batching rule may be replaced. registry: Optional registry override; the default registry is used when omitted.

Returns¶

PrimitiveBatchingRule The registered batching rule.

Raises¶

ValueError If identity/rule validation fails, if no derivative rule exists, or if a batching rule already exists and overwrite is disabled.

`custom_derivative_rule_for(identity, *, registry=None)` ¶

Resolve a custom derivative rule for a primitive identity.

Parameters¶

identity: Primitive identity object or canonical identity key. registry: Optional registry override; the default registry is used when omitted.

Returns¶

CustomDerivativeRule Registered derivative rule.

Raises¶

ValueError If identity is malformed or no derivative rule is registered.

`registered_custom_jvp(identity, values, tangent, *, parameters=None, registry=None)` ¶

Return a JVP by resolving the primitive's registered custom rule.

`registered_custom_vjp(identity, values, cotangent, *, parameters=None, registry=None)` ¶

Return a VJP by resolving the primitive's registered custom rule.

`registered_custom_jacobian(identity, values, *, parameters=None, registry=None)` ¶

Return a dense Jacobian by resolving the primitive's registered custom rule.

`multi_frequency_parameter_shift_rule(frequencies, *, shifts=None, max_condition=10000000000.0)` ¶

Operator-intercepted forward-AD trace value classes and their operations.

This module holds the derivative-carrying value runtime for whole-program AD: :class:TraceADScalar and :class:TraceADArray and the trace-coupled helpers that implement their NumPy __array_function__ dispatch, ufunc application, shape/index/selection/reduction/linalg operations, and coercion. The value classes and their helpers are mutually recursive (operations build new trace values), so they form one cohesive runtime unit.

Static operand normalisation comes from :mod:~scpn_quantum_control.whole_program_trace_metadata, primal predicates from :mod:~scpn_quantum_control.whole_program_trace_predicates, the trace context and event recording from :mod:~scpn_quantum_control.whole_program_trace_runtime, and the per-primitive derivative rules from the program_ad_* primitive modules. The public reverse/forward-mode entry points (value_and_grad/grad/whole_program_value_and_grad and friends) are owned by focused API modules and re-exported by :mod:~scpn_quantum_control.differentiable for compatibility.

Module size note: this module is intentionally kept whole. Its top-level definitions form a single connected operator-intercepted forward-AD trace-value cluster, so it is sized by responsibility rather than line count. Its classes are mutually recursive, so splitting would introduce import cycles. See docs/architecture.md ("Module size and single-responsibility policy").

`TraceADScalar` ¶

Operator-intercepted scalar for exact executed-path whole-program AD.

Parameters¶

primal: Finite real value carried by the trace. tangent: One-dimensional derivative vector aligned with the trace parameters. context: Trace context that owns the value and records derived operations. name: Stable SSA-style label used by trace and adjoint metadata.

Notes¶

Arithmetic, comparisons, and supported NumPy ufuncs preserve the owning context. Conversion to a Python float fails closed because it would discard derivative information.

`float()` ¶

Reject conversion that would discard derivative information.

`int()` ¶

Reject parameter-dependent integer conversion.

Raises¶

ValueError Integer conversion would discard the active derivative and could turn a traced parameter into an unqualified dynamic shape or index.

`index()` ¶

Reject using a traced parameter as an integer shape or index.

Raises¶

ValueError A derivative-carrying scalar has no static integer indexing contract.

`add(other)` ¶

Return the derivative-preserving scalar sum.

`radd(other)` ¶

Return the derivative-preserving reflected scalar sum.

`sub(other)` ¶

Return the derivative-preserving scalar difference.

`rsub(other)` ¶

Return the derivative-preserving reflected scalar difference.

`mul(other)` ¶

Return the derivative-preserving scalar product.

`rmul(other)` ¶

Return the derivative-preserving reflected scalar product.

`truediv(other)` ¶

Return the derivative-preserving scalar quotient.

`rtruediv(other)` ¶

Return the derivative-preserving reflected scalar quotient.

`pow(other)` ¶

Return the derivative-preserving scalar power.

`rpow(other)` ¶

Return the derivative-preserving reflected scalar power.

`neg()` ¶

Return the derivative-preserving additive inverse.

`abs()` ¶

Return the derivative-preserving absolute value.

`gt(other)` ¶

Return the traced strict-greater-than predicate.

`ge(other)` ¶

Return the traced greater-than-or-equal predicate.

`lt(other)` ¶

Return the traced strict-less-than predicate.

`le(other)` ¶

Return the traced less-than-or-equal predicate.

`eq(other)` ¶

Return the traced equality predicate.

`ne(other)` ¶

Return the traced inequality predicate.

`__array_ufunc__(ufunc, method, *inputs, **kwargs)` ¶

Dispatch a supported NumPy ufunc through scalar trace semantics.

`TraceADArray` ¶

Derivative-carrying ranked array for whole-program AD.

Parameters¶

items: Row-major scalar trace values carried by the array. shape: Static NumPy-compatible shape whose element count matches items. context: Trace context shared by every scalar item. source_indices: Optional original parameter slots retained through alias-preserving views; None entries identify constants or overwritten elements.

Notes¶

Supported NumPy functions dispatch through __array_function__ and supported ufuncs through __array_ufunc__. Raw ndarray coercion fails closed because it would discard derivative and alias metadata.

`ndim` `property` ¶

The rank of the derivative-carrying array.

`size` `property` ¶

The total number of derivative-carrying elements.

`T` `property` ¶

The NumPy-compatible reversed-axis transpose.

`len()` ¶

Return the leading-axis length of a ranked trace array.

`iter()` ¶

Iterate over trace scalars or rank-one row views.

`array(dtype=None, *, copy=None)` ¶

Reject ndarray coercion that would discard trace metadata.

Parameters¶

dtype Requested native dtype; conversion is refused for every dtype. copy Native NumPy copy request; no value authorizes derivative loss.

Raises¶

ValueError Trace values cannot become plain arrays without dropping derivatives.

`item()` ¶

Return the only scalar element, failing closed for non-scalar arrays.

`copy()` ¶

Return a derivative-preserving shallow array copy.

`reshape(*shape)` ¶

Return a derivative-preserving reshaped array view.

`ravel()` ¶

Return a flat view-preserving program AD array.

`flatten()` ¶

Return a flat copy-equivalent program AD array.

`repeat(repeats, axis=None)` ¶

Return a derivative-preserving array with repeated elements.

`squeeze(axis=None)` ¶

Return a derivative-preserving array with singleton axes removed.

`expand_dims(axis)` ¶

Return a derivative-preserving array with singleton axes inserted.

`swapaxes(axis1, axis2)` ¶

Return a derivative-preserving array with two axes exchanged.

`sum(axis=None)` ¶

Return a derivative-preserving sum over all elements or one axis.

`cumsum(axis=None)` ¶

Return a derivative-preserving cumulative sum.

`prod(axis=None)` ¶

Return a derivative-preserving product over all elements or one axis.

`cumprod(axis=None)` ¶

Return a derivative-preserving cumulative product.

`mean(axis=None)` ¶

Return a derivative-preserving arithmetic mean.

`var(axis=None, ddof=0)` ¶

Return a derivative-preserving variance with NumPy-compatible ddof.

`std(axis=None, ddof=0)` ¶

Return a derivative-preserving standard deviation.

`max(axis=None)` ¶

Return a derivative-preserving maximum with tie-safe semantics.

`min(axis=None)` ¶

Return a derivative-preserving minimum with tie-safe semantics.

`take(indices, axis=None, mode='raise')` ¶

Return derivative-preserving positional elements with fail-closed modes.

`argmax(axis=None)` ¶

Reject nondifferentiable maximum-index selection.

`argmin(axis=None)` ¶

Reject nondifferentiable minimum-index selection.

`getitem(index)` ¶

Return a derivative-preserving indexed scalar or array view.

`setitem(index, value)` ¶

Assign traced values while recording deterministic mutation metadata.

`__array_ufunc__(ufunc, method, *inputs, **kwargs)` ¶

Dispatch direct ufuncs or bounded unbuffered np.add.at mutations.

`__array_function__(func, types, args, kwargs)` ¶

Dispatch a supported NumPy function through fail-closed trace semantics.

`add(other)` ¶

Return the derivative-preserving elementwise sum.

`radd(other)` ¶

Return the derivative-preserving reflected elementwise sum.

`sub(other)` ¶

Return the derivative-preserving elementwise difference.

`rsub(other)` ¶

Return the derivative-preserving reflected elementwise difference.

`mul(other)` ¶

Return the derivative-preserving elementwise product.

`rmul(other)` ¶

Return the derivative-preserving reflected elementwise product.

`truediv(other)` ¶

Return the derivative-preserving elementwise quotient.

`rtruediv(other)` ¶

Return the derivative-preserving reflected elementwise quotient.

`pow(other)` ¶

Return the derivative-preserving elementwise power.

`rpow(other)` ¶

Return the derivative-preserving reflected elementwise power.

`neg()` ¶

Return the derivative-preserving elementwise additive inverse.

`matmul(other)` ¶

Return the derivative-preserving matrix product.

`rmatmul(other)` ¶

Return the derivative-preserving reflected matrix product.

`gt(other)` ¶

Return the traced elementwise strict-greater-than predicate.

`ge(other)` ¶

Return the traced elementwise greater-than-or-equal predicate.

`lt(other)` ¶

Return the traced elementwise strict-less-than predicate.

`le(other)` ¶

Return the traced elementwise less-than-or-equal predicate.

`eq(other)` ¶

Return the traced elementwise equality predicate.

`ne(other)` ¶

Return the traced elementwise inequality predicate.

`scpn_quantum_control.differentiable_framework_overlay` ¶

Reproducible CPU-only overlay profile for optional AD frameworks.

`FrameworkOverlayManifest` `dataclass` ¶

CPU-only optional-framework overlay installation contract.

`__post_init__()` ¶

Validate the CPU-only manifest identity without coercion.

`to_dict()` ¶

Return a JSON-ready manifest payload.

`from_json(path)` `classmethod` ¶

Load a manifest from disk.

`FrameworkOverlayVerification` `dataclass` ¶

Verification result for a framework overlay manifest.

`to_dict()` ¶

Return JSON-ready verification metadata.

`build_framework_overlay_manifest(*, overlay_path=None, python_version=None, package_versions=None, verification_status='not_verified')` ¶

Build a CPU-wheel overlay manifest without performing installation.

`install_framework_overlay(overlay_path)` ¶

Install the CPU-only optional-framework overlay and return its manifest.

`verify_framework_overlay_path(overlay_path, *, pythonpath=None)` ¶

Verify that an overlay directory contains required package roots.

`main(argv=None)` ¶

Emit or verify the CPU-framework overlay manifest.

`scpn_quantum_control.differentiable_module_hardening_audit` ¶

Module coverage and diagnostic audit for differentiable-programming surfaces.

`DifferentiableModuleHardeningAuditResult` `dataclass` ¶

Audit result for the differentiable module hardening registry.

`to_dict()` ¶

Return JSON-ready audit evidence.

`DifferentiableModuleHardeningRecord` `dataclass` ¶

Hardening evidence for one differentiable-programming module.

`__post_init__()` ¶

Validate that every registry row contains concrete evidence paths.

`to_dict()` ¶

Return a JSON-ready module-hardening row.

`differentiable_module_hardening_registry()` ¶

Return the registered differentiable module hardening evidence map.

`run_differentiable_module_hardening_audit(*, repo_root=REPO_ROOT, registry=None)` ¶

Audit differentiable modules against registered tests and diagnostics.

`scpn_quantum_control.differentiable_transform_algebra` ¶

Metamorphic transform-algebra gate for differentiable local routes.

`TransformAlgebraAudit` `dataclass` ¶

Executable transform-algebra audit over supported and blocked routes.

`categories` `property` ¶

Sorted categories covered by this audit.

`missing_categories` `property` ¶

Required categories missing from the audit.

`passed_cases` `property` ¶

Cases whose executed residuals are within tolerance.

`failed_cases` `property` ¶

Cases whose executed residuals exceeded tolerance.

`blocked_cases` `property` ¶

Explicit fail-closed transform-algebra boundaries.

`support_matrix` `property` ¶

Support rows generated from executable and blocked cases.

`missing_support_rows` `property` ¶

Required support-matrix rows missing from the generated matrix.

`failed_support_rows` `property` ¶

Generated support rows whose source cases failed.

`passed` `property` ¶

Whether all executed checks passed and every category is covered.

`__post_init__()` ¶

Validate audit coverage and category uniqueness expectations.

`to_dict()` ¶

Return JSON-ready audit metadata.

`TransformAlgebraCase` `dataclass` ¶

One transform-algebra metamorphic or fail-closed boundary check.

`__post_init__()` ¶

Validate case metadata and pass/fail/block invariants.

`to_dict()` ¶

Return JSON-ready case metadata.

`run_transform_algebra_audit(*, tolerance=TRANSFORM_ALGEBRA_TOLERANCE)` ¶

Run the bounded transform-algebra metamorphic audit.

`assert_transform_algebra_audit_passes(audit=None)` ¶

Return the audit or raise with actionable failures.

`scpn_quantum_control.differentiable_benchmark_report` ¶

Claim-bounded local differentiable benchmark report builders.

`DifferentiableBenchmarkReport` `dataclass` ¶

Local conformance benchmark evidence for the unified differentiable API.

`__post_init__()` ¶

Validate that the report preserves claim-bounded benchmark semantics.

`to_dict()` ¶

Return a JSON-ready benchmark report payload.

`build_differentiable_benchmark_report()` ¶

Run local conformance suites and return bounded benchmark evidence.

`scpn_quantum_control.benchmarks.differentiable_evidence` ¶

CI-only benchmark evidence metadata and artefact writers.

`BenchmarkIsolationMetadata` `dataclass` ¶

Isolation metadata required before benchmark evidence can be promoted.

`from_ci_environment(env, *, command, cpu_affinity, isolation_method, load_before, load_after, governor, frequency_mhz, heavy_jobs_running, accelerator_metadata=None)` `classmethod` ¶

Classify a CI benchmark run from runner metadata.

`to_dict()` ¶

Return JSON-ready metadata.

`DifferentiableBenchmarkEvidenceBundle` `dataclass` ¶

Paths and metadata for one written differentiable benchmark bundle.

`capture_host_load()` ¶

Return host load averages when the platform exposes them.

`infer_heavy_jobs_running(load)` ¶

Infer whether current host load is too high for production promotion.

`read_cpu_frequency_mhz(cpu_index=0)` ¶

Read Linux CPU frequency metadata in MHz when available.

`read_cpu_governor(cpu_index=0)` ¶

Read Linux CPU frequency governor metadata when available.

`write_differentiable_benchmark_evidence_bundle(output_dir, *, metadata, timing_rows, artifact_id=None, external_artifact_ids=None)` ¶

Write raw JSON, CSV timing rows, and Markdown summary for benchmark evidence.

`scpn_quantum_control.benchmarks.differentiable_hardening_gate` ¶

Per-slice differentiable-programming hardening gate.

`DifferentiableBenchmarkClassificationCase` `dataclass` ¶

Expected benchmark-evidence classification for one runner scenario.

`passed` `property` ¶

Whether the observed classification matches the contract.

`to_dict()` ¶

Return JSON-ready benchmark classification evidence.

`DifferentiableHardeningGateCheck` `dataclass` ¶

One required verification surface for a differentiable hardening slice.

`__post_init__()` ¶

Validate that the verification row has executable evidence fields.

`to_dict()` ¶

Return a JSON-ready check row.

`DifferentiableHardeningSliceGateResult` `dataclass` ¶

Auditable verification checklist for one differentiable hardening slice.

`to_dict()` ¶

Return JSON-ready hardening-gate evidence.

`run_differentiable_hardening_slice_gate(*, module_specific_pytest_targets, changed_python_targets=(), claim_ledger_validation_target=DEFAULT_CLAIM_LEDGER_VALIDATION_TARGET, test_quality_audit_target=DEFAULT_TEST_QUALITY_AUDIT_TARGET)` ¶

`GROUND_STATE_OPTIMIZER_CONVERGENCE_SCHEMA = 'scpn_qc_ground_state_optimizer_convergence_v1'` `module-attribute` ¶

`GroundStateOptimizerConvergenceArtifact` `dataclass` ¶

Written ground-state optimizer convergence artefact metadata.

`to_dict()` ¶

Return JSON-ready artifact metadata.

`ground_state_optimizer_convergence_payload(suite=None, *, artifact_id='ground-state-optimizer-convergence-local')` ¶

Return the ground-state optimizer convergence artifact payload.

`render_ground_state_optimizer_convergence_markdown(payload)` ¶

Render optimizer convergence payload as bounded Markdown evidence.

`write_ground_state_optimizer_convergence_artifact(output_path, *, markdown_path=None, suite=None, artifact_id='ground-state-optimizer-convergence-local')` ¶

Write JSON and Markdown ground-state optimizer convergence artefacts.

`scpn_quantum_control.benchmarks.open_system_objective_evidence` ¶

Benchmark artefacts for bounded Lindblad and MCWF objectives.

`OPEN_SYSTEM_OBJECTIVE_EVIDENCE_SCHEMA = 'scpn_qc_open_system_objective_evidence_v1'` `module-attribute` ¶

`OpenSystemObjectiveEvidenceArtifact` `dataclass` ¶

Written open-system objective artifact metadata.

`to_dict()` ¶

Return JSON-ready artifact metadata.

`open_system_objective_evidence_payload(suite=None, *, artifact_id='open-system-objective-evidence-local')` ¶

Return the bounded open-system objective evidence payload.

`render_open_system_objective_evidence_markdown(payload)` ¶

Render the open-system objective payload as bounded Markdown evidence.

`write_open_system_objective_evidence_artifact(output_path, *, markdown_path=None, suite=None, artifact_id='open-system-objective-evidence-local')` ¶

Write JSON and Markdown open-system objective artefacts.

`scpn_quantum_control.benchmarks.differentiable_catalyst_comparison` ¶

Catalyst compiler-workflow evidence boundaries for differentiable comparisons.

Run or classify optional external comparison rows.

The SCPN analytic parameter-shift reference remains the source of truth. Missing optional tooling is recorded as hard-gap evidence instead of being silently omitted.

`run_identical_circuit_gradient_comparison_suite()` ¶

Run exact-state same-circuit gradient comparisons for Qiskit and PennyLane.

`write_differentiable_external_comparison(output_path, rows=None, *, artifact_id='differentiable-external-comparison-local')` ¶

Write external comparison rows as a bounded JSON evidence artefact.

`write_identical_circuit_gradient_comparison(output_path, rows=None, *, artifact_id='identical-circuit-gradient-comparison-local')` ¶

Write exact-state same-circuit comparison rows as JSON evidence.

`scpn_quantum_control.phase.pennylane_provider_plugin` ¶

PennyLane provider-plugin gradient artefacts and fail-closed route matrix.

`PennyLaneHardwarePluginExecutionArtifact` `dataclass` ¶

`validate_public_language_against_ledger(rows_or_ledger, public_texts)` ¶

Validate batch shape, provenance, backend, and normalized arrays.

`ExecutableWholeProgramADKernel` `dataclass` ¶

Executable replay kernel for a supported captured program AD trace.

The kernel is intentionally bounded: it replays the original Python objective through the supported operator-intercepted program AD IR, checks the one-dimensional parameter shape, checks the captured control/signature surface, and computes gradients through reverse-mode adjoint replay. It is executable and deterministic for the supported captured trace contract; it does not claim arbitrary source compilation or native LLVM/JIT lowering for arbitrary Python programs.

`__post_init__()` ¶

Validate replay provenance, parameters, signature, and claim boundary.

`value_and_grad(values)` ¶

Execute value replay and reverse-mode adjoint gradient replay.

`value(values)` ¶

Execute value replay for the captured program AD trace.

`gradient(values)` ¶

Execute reverse-mode adjoint replay for the captured program AD trace.

`batch_value_and_grad(values)` ¶

Execute same-branch batched value and reverse-adjoint gradient replay.

`batch_value(values)` ¶

Execute batched value replay for rows preserving the compiled branch path.

`batch_gradient(values)` ¶

Execute batched reverse-adjoint replay for rows preserving the branch path.

`NativeWholeProgramADKernel` `dataclass` ¶

Native LLVM/JIT kernel for a supported scalar program AD trace.

`__post_init__()` ¶

Validate the verified native kernel and all executable contracts.

`value(values)` ¶

Execute the native scalar value kernel.

`gradient(values)` ¶

Execute the native scalar-output gradient kernel.

`value_and_grad(values)` ¶

Execute native value and gradient kernels.

`jvp(values, tangent)` ¶

Execute the native scalar JVP kernel.

`vjp(values, cotangent)` ¶

Execute the native scalar VJP kernel.

`batch_value_and_grad(values)` ¶

Execute native value and gradient kernels over a two-dimensional batch.

`batch_value(values)` ¶

Execute native value kernels over a two-dimensional batch.

`batch_gradient(values)` ¶

Execute native gradient kernels over a two-dimensional batch.

`batch_jvp(values, tangents)` ¶

Execute the compiled native JVP kernel over a two-dimensional batch.

`batch_vjp(values, cotangents)` ¶

Execute the compiled native VJP kernel over a two-dimensional batch.

`MLIRModule` `dataclass` ¶

Textual MLIR module plus deterministic provenance.

`__post_init__()` ¶

Validate module text provenance and freeze mapping fields.

`compile_kuramoto_to_mlir(problem, config, omega=None)` ¶

Compile a Kuramoto problem into deterministic MLIR-style text.

problem may be a validated :class:KuramotoProblem or a raw coupling matrix when omega is supplied. Raw arrays are validated through the public Kuramoto facade before IR generation.

`compile_custom_derivative_rule_to_mlir(rule, values, config=None)` ¶

Lower an exact custom derivative rule to deterministic MLIR-style text.

This emits an auditable differentiable-primitive interchange artefact with value and Jacobian shape metadata. When numeric payloads are enabled, the current value and exact custom Jacobian are embedded as deterministic attributes. The function deliberately does not claim executable LLVM or JIT code generation.

`compile_custom_derivative_rule_to_executable(rule, sample_values, config=None, *, sample_tangent=None, sample_cotangent=None)` ¶

Compile a custom derivative rule into a verified executable AD kernel.

The executable backend is the dependency-free SCPN MLIR runtime adapter: it couples deterministic differentiable MLIR provenance with normalized runtime callables for value/JVP/VJP execution and verifies those kernels against the source custom derivative rule before returning. Native LLVM/JIT kernels use primitive-specific lowering entrypoints.

`compile_registered_primitive_to_executable(registry, identity, sample_values, config=None, *, sample_tangent=None, sample_cotangent=None)` ¶

Compile a registered primitive identity into an executable AD kernel.

`compile_whole_program_ad_trace_to_executable(objective, sample_values, parameters=None, config=None, *, trace=True)` ¶

Compile a supported captured program AD trace to an executable replay kernel.

This is the executable compiler boundary for whole-program AD today: it captures the supported scalar program IR, verifies reverse adjoint replay is available, emits deterministic MLIR provenance, then returns a fail-closed replay kernel. Shape drift, non-finite inputs, and branch/signature drift raise errors instead of silently changing the differentiated program.

`compile_whole_program_ad_trace_to_native_llvm_jit(objective, sample_values, parameters=None, config=None, *, trace=True)` ¶

Compile a supported scalar program AD trace to native LLVM/JIT kernels.

`compile_whole_program_ad_trace_to_mlir(result, config=None)` ¶

Lower a whole-program AD execution trace to MLIR-style interchange text.

The emitted module is an audit artefact for Python whole-program gradients and polyglot compiler planning. It deliberately records Rust and LLVM/JIT executable differentiation as blocked unless a real backend is provided.

Real-Time Runtime¶

`scpn_quantum_control.control.realtime_runtime` ¶

Deadline-aware realtime control runtime.

This is a deterministic software-control runtime for bounded feedback loops. It accounts for latency, jitter, and deadline misses around injected control steps. It is not an intra-shot hardware-latency claim.

`CycleSample` `dataclass` ¶

Sub-microsecond timing record for one outer-loop cycle.

`summarise_cycle_samples(start_ns, end_ns, deadline_ns, *, target_rate_hz=100000)` ¶

Summarise arrays of cycle timestamps in a single pass.

This is the batch path consumed by the throughput benchmark and by callers that buffer cycle timestamps and summarise them periodically. It computes the same jitter percentiles and deadline-miss count as :class:SubMicrosecondTracker over the full input.

Parameters¶

start_ns : numpy.ndarray or list[int] One-dimensional cycle-start timestamps in monotonic nanoseconds. end_ns : numpy.ndarray or list[int] One-dimensional cycle-finish timestamps in monotonic nanoseconds. deadline_ns : numpy.ndarray or list[int] One-dimensional absolute deadlines in monotonic nanoseconds. target_rate_hz : int Positive target cycle rate in hertz.

Returns¶

SubMicrosecondReport Full-window jitter percentiles and deadline-miss count.

Raises¶

TypeError If target_rate_hz is not a plain integer. ValueError If the rate is non-positive, arrays are not one-dimensional and equal length, no cycle is supplied, or a finish/deadline precedes its start.

Cloud-Native Deployment¶

`scpn_quantum_control.deployment.cloud_native` ¶

Deterministic cloud-native manifest generation.

The generator emits Kubernetes and Docker Compose manifests for offline SCPN workloads. It rejects secret-like environment variables and does not read local credentials, create clusters, or contact cloud APIs.

`ContainerResources` `dataclass` ¶

CPU and memory requests/limits for one SCPN container.

`__post_init__()` ¶

Validate the Kubernetes resource quantities.

`CloudDeploymentSpec` `dataclass` ¶

Cloud-native deployment request for an offline SCPN workload.

`__post_init__()` ¶

Validate and freeze the deployment request.

`CloudManifestBundle` `dataclass` ¶

Generated cloud-native manifest files plus provenance digest.

`__post_init__()` ¶

Validate the manifest digest and freeze the files.

`generate_cloud_manifests(spec)` ¶

Generate Kubernetes and Docker Compose manifests for spec.

Hardware Abstraction Layer¶

`scpn_quantum_control.hardware.backends` ¶

Plugin / backend extension API.

Closes audit item C10. Third parties may now register additional quantum backends without editing this repository by declaring an entry point in the scpn_quantum_control.backends group:

.. code-block:: toml

[project.entry-points."scpn_quantum_control.backends"]
acme_trapped_ion = "acme_plugin:AcmeBackend"
analog_kuramoto = "scpn_quantum_control.hardware.analog_kuramoto:analog_kuramoto_factory"
hybrid_digital_analog = "scpn_quantum_control.hardware.hybrid_digital_analog:hybrid_digital_analog_factory"

The entry-point target must be a zero-argument callable or a class that returns an object satisfying the :class:BackendProtocol interface when instantiated.

Internal backends (Qiskit runtime, PennyLane) register themselves via this repository's own pyproject.toml entry points; they are loaded the same way every third-party backend is, which means a broken plugin cannot take down the rest of the registry.

Discovery is lazy: call :func:discover_backends once per process. The module also exposes a manual :func:register_backend hatch for tests and notebooks that want to exercise a specific class without round-trip through entry points.

`QuantumBackendDescriptor` `dataclass` ¶

Provider-neutral execution contract for a quantum backend.

Registry lookup must never authenticate, touch the network, or queue paid work. This static descriptor gives routing code enough information to distinguish local simulation from approval-gated cloud submission before execution-specific adapters are invoked.

`describe_hal_backend_profile(backend_id)` ¶

Return selector metadata for one built-in HAL profile.

The descriptor is constructed from static HAL profile metadata only. It does not import provider SDKs, authenticate, inspect queues, or create any executable adapter. Runtime availability remains the responsibility of the injected adapter route.

`list_hal_backend_descriptors()` ¶

Return selector metadata for all built-in HAL profiles.

`describe_backend(name)` ¶

Return the provider-neutral descriptor for name.

Third-party backends that have not implemented descriptor() get a conservative descriptor: no advertised submit/simulator capability and explicit approval required before production routing.

`list_quantum_backends(*, auto_discover=True)` ¶

Return sorted provider-neutral descriptors for every known backend.

`scpn_quantum_control.hardware.provider_smoke` ¶

Metadata-only optional dependency smoke checks for HAL provider routes.

`AggregatorProviderOptionalDependencyRow` `dataclass` ¶

Offline dependency evidence for one aggregator/provider route.

`ProviderOptionalDependencyRow` `dataclass` ¶

Offline import-probe result for one built-in HAL backend route.

`aggregator_provider_optional_dependency_matrix(*, aggregator=None, provider=None, ir_format=None, route_id=None)` ¶

Return offline dependency evidence for aggregator/provider routes.

The matrix joins the declared aggregator/provider route table to the HAL optional-dependency probe. It remains no-network and no-authentication: import availability is measured through find_spec only.

`main(argv=None)` ¶

Print the offline provider optional-dependency matrix.

The command is intentionally metadata-only: it imports no provider SDK, reads no credentials, creates no clients, performs no authentication, and touches no network endpoint. Use --require-all in provider-pack CI lanes after installing scpn-quantum-control[providers].

`provider_optional_dependency_matrix()` ¶

Return metadata-only import availability for every built-in HAL route.

The probe uses importlib.util.find_spec only. It does not import provider SDKs, read credentials, create clients, authenticate, or touch the network.

`scpn_quantum_control.hardware.provider_capability_discovery` ¶

No-submit provider metadata adapters and compatibility facade.

Provider-neutral capability contracts, route assessment, and OpenPulse readiness live in :mod:.provider_capability_core. This module re-exports the exact core and provider-adapter objects for compatibility.

`ProviderCapabilitySnapshot` `dataclass` ¶

Provider target metadata collected without submitting a workload.

`__post_init__()` ¶

Validate the no-submit target metadata contract.

`ProviderCapabilityDecision` `dataclass` ¶

Readiness decision for one no-submit provider capability snapshot.

`to_dict()` ¶

Serialise the provider capability decision.

`assess_provider_capability_snapshot(snapshot, *, aggregator, provider, backend_id, route_id=None, required_ir_format=None, min_qubits=None, max_calibration_age_seconds=None, as_of=None)` ¶

Assess route metadata, optionally requiring a fresh calibration timestamp.

The caller supplies an explicit timezone-aware as_of with a finite, non-negative maximum age. A readiness result without this gate does not assert calibration freshness. This function never submits provider work.

`probe_aggregator_provider_capability(*, aggregator, provider, metadata_probe, ir_format=None, route_id=None, min_qubits=None, max_calibration_age_seconds=None, as_of=None)` ¶

Resolve and assess metadata without submission, with optional freshness gate.

`snapshot_from_azure_target(resolved, target)` ¶

Build a no-submit capability snapshot from Azure Quantum target metadata.

`snapshot_from_braket_device(resolved, device)` ¶

Build a no-submit capability snapshot from AWS Braket device metadata.

`snapshot_from_dwave_solver(resolved, solver)` ¶

Build a no-submit capability snapshot from direct D-Wave solver metadata.

`snapshot_from_iqm_backend(resolved, backend)` ¶

Build a no-submit capability snapshot from direct IQM backend metadata.

`snapshot_from_ionq_backend(resolved, backend)` ¶

Build a no-submit capability snapshot from direct IonQ backend metadata.

`snapshot_from_oqc_target(resolved, target)` ¶

Build a no-submit capability snapshot from direct OQC target metadata.

`snapshot_from_pasqal_target(resolved, target)` ¶

Build a no-submit capability snapshot from direct Pasqal target metadata.

`snapshot_from_qiskit_runtime_backend(resolved, backend)` ¶

Build a no-submit capability snapshot from IBM/Qiskit backend metadata.

`snapshot_from_qbraid_device(resolved, device)` ¶

Build a no-submit capability snapshot from qBraid device metadata.

`snapshot_from_quandela_processor(resolved, processor)` ¶

Build a no-submit capability snapshot from direct Quandela processor metadata.

`snapshot_from_quantinuum_backend(resolved, backend)` ¶

Build a no-submit capability snapshot from direct Quantinuum metadata.

`snapshot_from_quera_bloqade(resolved, target)` ¶

Build a no-submit capability snapshot from direct QuEra/Bloqade metadata.

`snapshot_from_rigetti_qcs(resolved, quantum_computer)` ¶

Build a no-submit capability snapshot from direct Rigetti QCS metadata.

`snapshot_from_strangeworks_backend(resolved, backend)` ¶

Build a no-submit capability snapshot from Strangeworks backend metadata.

`scpn_quantum_control.hardware.aggregators` ¶

First-class aggregator/provider route matrix for the hardware HAL.

`AggregatorProviderRoute` `dataclass` ¶

A declared aggregator/provider combination resolved to a HAL backend.

`__post_init__()` ¶

Validate route identifiers and freeze normalized note metadata.

`ResolvedAggregatorProviderRoute` `dataclass` ¶

Executable resolution of an aggregator/provider route.

`aggregator_provider_routes_for(*, aggregator=None, provider=None)` ¶

Return declared routes filtered by aggregator and/or provider.

`built_in_aggregator_provider_routes()` ¶

Return the metadata-only aggregator/provider coverage matrix.

`resolve_aggregator_provider_route(*, aggregator, provider, ir_format=None, route_id=None)` ¶

Resolve a broker/provider request to one executable HAL profile.

`scpn_quantum_control.hardware.hal` ¶

`QuantumBackend` ¶

Raises¶

ValueError If cancellation is unsupported or the response identity differs.

Notes¶

A rejected response does not undo the provider cancellation request.

`built_in_backend_profiles()` ¶

`cancel(job)` ¶

Request cancellation for a submitted backend job.

`rigetti_quil_workload(program, *, workload_id, n_qubits, shots, metadata=None)` ¶

Encode a Quil program as a HAL workload for direct pyQuil execution.

Identity¶

`scpn_quantum_control.identity.ground_state` ¶

Identity attractor basin via VQE ground state analysis.

Computes the ground state of an identity coupling Hamiltonian H(K_nm) and extracts the energy gap as a robustness metric. A large gap means the identity resists perturbation; a small gap means fragile coupling.

`IdentityAttractor` ¶

Characterize the attractor basin of an identity coupling topology.

Wraps PhaseVQE with identity-specific interpretation: the ground state is the natural resting configuration, and the energy gap to the first excited state quantifies robustness against perturbation.

`from_binding_spec(binding_spec, ansatz_reps=2)` `classmethod` ¶

Build from an scpn-phase-orchestrator binding spec.

`solve(maxiter=200, seed=None)` ¶

Find the ground state and compute robustness metrics.

Returns dict with ground_energy, exact_energy, energy_gap, relative_error_pct, robustness_gap, n_dispositions.

`robustness_gap()` ¶

Energy gap E_1 - E_0. Call solve() first.

`ground_state()` ¶

Return the VQE-optimized ground state vector.

`scpn_quantum_control.identity.coherence_budget` ¶

Coherence budget calculator for identity quantum circuits.

Estimates the maximum circuit depth at which fidelity remains above a given threshold, using the Heron r2 noise model calibration data. The coherence budget is the quantitative limit on how complex a quantum identity representation can be on NISQ hardware.

`coherence_budget(n_qubits, *, fidelity_threshold=0.5, max_depth=2000, t1_us=T1_US, t2_us=T2_US, cz_error=CZ_ERROR_RATE, readout_error=READOUT_ERROR_RATE, two_qubit_fraction=0.4)` ¶

Compute the maximum circuit depth before fidelity drops below threshold.

Parameters¶

n_qubits : int Number of qubits in the circuit. fidelity_threshold : float Minimum acceptable estimated fidelity, strictly between zero and one. max_depth : int Largest depth considered by the binary search and fidelity sampling. t1_us : float Qubit relaxation time in microseconds, reported with the result. t2_us : float Qubit dephasing time in microseconds. cz_error : float Error probability for each two-qubit gate. readout_error : float Error probability for each measured qubit. two_qubit_fraction : float Fraction of layers containing two-qubit gates.

Returns¶

dict[str, Any] Budget depth, fidelity at that depth, sampled fidelity curve, and hardware parameters.

Raises¶

ValueError If n_qubits is less than one or fidelity_threshold is outside the open interval (0, 1).

`fidelity_at_depth(depth, n_qubits, *, t1_us=T1_US, t2_us=T2_US, cz_error=CZ_ERROR_RATE, readout_error=READOUT_ERROR_RATE, two_qubit_fraction=0.4)` ¶

Estimate circuit fidelity at a given gate depth.

Model: F = F_gate^(n_gates) * F_readout^(n_qubits) * F_decoherence where F_decoherence = exp(-t_total / T2) approximately.

Parameters¶

depth : int Total number of gate layers. n_qubits : int Number of qubits in the circuit. t1_us : float Qubit relaxation time in microseconds, retained in the public hardware parameter contract. t2_us : float Qubit dephasing time in microseconds. cz_error : float Error probability for each two-qubit gate. readout_error : float Error probability for each measured qubit. two_qubit_fraction : float Fraction of layers containing two-qubit gates.

Returns¶

float Estimated fidelity in the interval [0, 1].

Raises¶

ValueError If depth is negative or n_qubits is less than one.

`scpn_quantum_control.identity.entanglement_witness` ¶

Entanglement witness for disposition pairs via CHSH inequality.

Measures the CHSH S-parameter for qubit pairs in a coupled identity state. S > 2 proves non-classical correlation between the corresponding dispositions — they cannot be described as independent states.

`chsh_from_statevector(sv, qubit_a, qubit_b)` ¶

Compute CHSH S-parameter for a qubit pair from a multi-qubit statevector.

Measures correlations E(a,b), E(a,b'), E(a',b), E(a',b') with optimal angles a=0, a'=pi/2, b=pi/4, b'=-pi/4 (Tsirelson bound: 2*sqrt(2)).

Returns S in [0, 2*sqrt(2)]. S > 2 certifies entanglement.

`disposition_entanglement_map(sv, disposition_labels=None)` ¶

Compute CHSH S-parameter for all qubit pairs.

Returns dict with 'pairs' (list of {qa, qb, S, entangled}), 'max_S', 'n_entangled', 'integration_metric' (mean S / Tsirelson bound).

`scpn_quantum_control.identity.identity_key` ¶

Quantum identity fingerprint from coupling topology.

Generates a cryptographic fingerprint from the identity K_nm matrix via VQE ground state correlations. The K_nm encodes the full history of disposition co-activation — different session histories produce different K_nm, therefore different quantum keys.

`identity_fingerprint(K, omega, *, ansatz_reps=2, maxiter=200)` ¶

Generate a quantum identity fingerprint from coupling topology.

Combines spectral fingerprint (public, topology-derived) with VQE ground state energy (quantum-derived). The spectral fingerprint can be published without revealing K_nm; the ground state energy serves as an additional consistency check.

Returns dict with spectral (public fingerprint), ground_energy, commitment (SHA-256 hash binding K_nm), and n_parameters (security).

`prove_identity(K, challenge)` ¶

Prove knowledge of K_nm without transmitting it.

`verify_identity(K, challenge, response)` ¶

Verify that a claimant holds the correct K_nm.

The verifier sends a random challenge; the claimant responds with HMAC(K_nm, challenge). Returns True iff the response matches.

`scpn_quantum_control.identity.binding_spec` ¶

Six-layer, 18-oscillator Arcane Sapience identity binding topology.

Quantum-side spec maps to the identity_coherence domainpack in scpn-phase-orchestrator (35 oscillators, 6 layers). The quantum spec uses 3 oscillators per layer as a reduced representation suitable for NISQ simulation; the orchestrator spec uses the full set.

ARCANE_SAPIENCE_SPEC = {'layers': [{'name': 'working_style', 'oscillator_ids': ['working_style_action_verification', 'working_style_delivery_preflight', 'working_style_single_task'], 'natural_frequency': 1.2}, {'name': 'reasoning', 'oscillator_ids': ['rs_0', 'rs_1', 'rs_2'], 'natural_frequency': 2.1}, {'name': 'relationship', 'oscillator_ids': ['rl_0', 'rl_1', 'rl_2'], 'natural_frequency': 0.8}, {'name': 'aesthetics', 'oscillator_ids': ['ae_0', 'ae_1', 'ae_2'], 'natural_frequency': 1.5}, {'name': 'domain_knowledge', 'oscillator_ids': ['dk_0', 'dk_1', 'dk_2'], 'natural_frequency': 3.0}, {'name': 'cross_project', 'oscillator_ids': ['cp_0', 'cp_1', 'cp_2'], 'natural_frequency': 0.9}], 'coupling': {'base_strength': 0.4, 'decay_alpha': 0.25, 'intra_layer': 0.6}} `module-attribute` ¶

ORCHESTRATOR_MAPPING = {'working_style_action_verification': ['ws_action_first', 'ws_verify_before_claim'], 'working_style_delivery_preflight': ['ws_commit_incremental', 'ws_preflight_push'], 'working_style_single_task': ['ws_one_at_a_time'], 'rs_0': ['rp_simplest_design', 'rp_verify_audits'], 'rs_1': ['rp_change_problem', 'rp_multi_signal'], 'rs_2': ['rp_measure_first'], 'rl_0': ['rel_autonomous', 'rel_milestones'], 'rl_1': ['rel_no_questions', 'rel_honesty'], 'rl_2': ['rel_money_clock'], 'ae_0': ['aes_antislop', 'aes_honest_naming'], 'ae_1': ['aes_terse', 'aes_spdx'], 'ae_2': ['aes_no_noqa'], 'dk_0': ['dk_director', 'dk_neurocore', 'dk_fusion'], 'dk_1': ['dk_control', 'dk_orchestrator'], 'dk_2': ['dk_ccw', 'dk_scpn', 'dk_quantum'], 'cp_0': ['cp_threshold_halt', 'cp_multi_signal', 'cp_retrieval_scoring'], 'cp_1': ['cp_state_preserve', 'cp_decompose_verify'], 'cp_2': ['cp_resolution', 'cp_claims_evidence']} `module-attribute` ¶

`build_identity_attractor(spec=None, ansatz_reps=2)` ¶

Build an identity attractor from a binding specification.

Parameters¶

spec : dict[str, Any] or None Binding specification. None selects ARCANE_SAPIENCE_SPEC. ansatz_reps : int Repetition count for the attractor ansatz.

Returns¶

IdentityAttractor Attractor compiled from the specification's coupling and frequency data.

`scpn_quantum_control.benchmarks.classical_baselines` ¶

Documented classical baselines for Kuramoto-XY workflows.

The functions here are deliberately small provenance surfaces:

SciPy ODE integrates the classical Kuramoto phase equations.
QuTiP Lindblad uses an independent density-matrix open-system solver.
quimb TEBD reuses the project MPS backend when the tensor extra is installed.

`ClassicalBaselineRun` `dataclass` ¶

Result envelope for one classical baseline run.

`r_final` `property` ¶

Final Kuramoto order parameter when the run is available.

`available_baselines()` ¶

Return which documented classical baselines are available now.

`scipy_ode_baseline(K, omega, *, t_max=1.0, dt=0.05, theta0=None, rtol=1e-08, atol=1e-10)` ¶

Integrate the classical Kuramoto ODE with SciPy solve_ivp.

The implemented equation is

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

`qutip_lindblad_baseline(K, omega, *, gamma=0.05, t_max=0.5, dt=0.1)` ¶

Run an optional QuTiP Lindblad density-matrix baseline.

If QuTiP is not installed, the returned result is marked unavailable instead of fabricating a numerical value.

`mps_tebd_baseline(K, omega, *, t_max=0.5, dt=0.1, bond_dim=32, cutoff=1e-10)` ¶

Run an optional quimb TEBD tensor-network baseline.

`run_documented_classical_baselines(K, omega, *, t_max=0.5, dt=0.1, include_optional=True)` ¶

Run the documented baseline suite for one Kuramoto problem.

`scpn_quantum_control.benchmarks.quantum_advantage` ¶

Quantum vs classical scaling benchmark for Kuramoto Hamiltonian simulation.

Measures wall-clock time for classical (exact diag + matrix exp) vs quantum (Trotter on statevector), then extrapolates scaling crossover.

`AdvantageResult` `dataclass` ¶

Scaling benchmark result for one system size.

`classical_benchmark(n, t_max=1.0, dt=0.1)` ¶

Time classical exact evolution of XY Hamiltonian.

For n > MAX_CLASSICAL_QUBITS, returns inf (matrix expm infeasible).

`quantum_benchmark(n, t_max=1.0, dt=0.1, trotter_reps=5)` ¶

Time Trotter evolution on statevector simulator.

`estimate_crossover(results)` ¶

Fit exponential scaling, extrapolate where quantum becomes faster.

Returns predicted qubit count at crossover, or None.

`run_scaling_benchmark(sizes=None, t_max=1.0, dt=0.1)` ¶

Full scaling benchmark across system sizes.

Default sizes=[4, 8, 12, 16, 20]. N=20 is ~8 MB statevector (quantum only). Classical exact evolution infeasible beyond n=14.

QEC¶

`scpn_quantum_control.qec.fault_tolerant` ¶

Repetition-code UPDE simulation with bit-flip protected logical qubits.

Proof-of-concept for QEC-protected Kuramoto dynamics. Uses distance-d repetition code (bit-flip only) per oscillator. Does NOT correct phase errors. SurfaceCodeUPDE supplies a separate X/Z ancilla-interaction and resource scaffold, not full protection or decoding. This module validates its repetition-code approach on statevector and is not executable on current hardware at useful noise levels.

`LogicalQubit` `dataclass` ¶

Repetition-code logical qubit.

`data_qubits` `property` ¶

Number of data qubits in the repetition-code logical qubit.

`RepetitionCodeUPDE` ¶

Repetition-code Kuramoto evolution (bit-flip protection only).

Each of n_osc oscillators is encoded into d physical qubits. Layout per oscillator: [d data qubits | d-1 ancilla qubits]. Total physical qubits = n_osc * (2d - 1).

`encode_logical(osc, qc)` ¶

Repetition-code encoding: Ry(theta) on first data qubit, CNOT fan-out.

`transversal_zz(osc_i, osc_j, angle, qc)` ¶

Transversal RZZ between logical qubits i and j.

Applies d pairwise RZZ gates between corresponding data qubits.

`syndrome_extract(osc, qc)` ¶

Parity checks between adjacent data qubits via ancillae.

`build_step_circuit(dt=0.1)` ¶

One Trotter step: encode -> Z rotations -> ZZ coupling -> syndrome.

`step_with_qec(dt=0.1, *, max_dense_gib=None)` ¶

Execute one QEC-protected Trotter step and extract syndromes.

The protected circuit carries both data and ancilla qubits, so the dense state is 2**physical_qubit_count(). Admission is checked before the circuit is built, so an inadmissible code distance refuses without entering the allocator. Two complex-vector equivalents cover the state and the real absolute-value/square buffers used to obtain probabilities.

Parameters¶

dt Trotter step size. max_dense_gib Optional dense-allocation budget in GiB. None uses the active process budget.

Returns¶

dict Per-oscillator syndromes and the detected-error count.

Raises¶

DenseAllocationError If the physical-qubit statevector exceeds the budget.

`physical_qubit_count()` ¶

Total physical qubits: n_osc * (d + d - 1).

`scpn_quantum_control.qec.surface_code_upde` ¶

Build a structural surface-code UPDE circuit and resource scaffold.

Each oscillator occupies a distance-d rotated-surface-code-shaped register (Horsman et al., NJP 14, 123011 (2012)). The generated circuit approximates encoding fan-out, distributed physical rotations, inter-patch couplings, and X/Z ancilla interactions for resource and depth analysis. It does not prepare a verified codespace, measure or reset ancillas, allocate classical syndrome bits, invoke a decoder, or demonstrate correction of either X or Z errors.

Physical qubit layout per oscillator: d² data + (d²-1) ancilla = 2d²-1. Total physical qubits: n_osc × (2d² - 1).

Structural operator proxies

distribute an Rz angle over every data qubit in one patch;
distribute pairwise RZZ angles across corresponding qubits in two patches;
append X- and Z-type ancilla-entangling networks without measurements.

Notes¶

correctable_errors is a code-distance resource label; this structural scaffold does not execute or verify that correction capability.

Mitigation¶

`scpn_quantum_control.mitigation.pec` ¶

Probabilistic Error Cancellation for local depolarizing channels.

Temme et al., PRL 119, 180509 (2017).

`PECResult` `dataclass` ¶

PEC estimation output.

`pauli_twirl_decompose(gate_error_rate, n_qubits=1)` ¶

Quasi-probability coefficients for depolarizing channel inverse.

Single-qubit: q_I = 1 + 3p/(4-4p), q_{X,Y,Z} = -p/(4-4p). Multi-qubit outputs are tensor products of the local inverse channel, ordered lexicographically over the local {I, X, Y, Z} basis. Temme et al., PRL 119, 180509 (2017), Eq. 4.

`pec_sample(circuit, gate_error_rate, n_samples, observable_qubit=0, rng=None)` ¶

Monte Carlo PEC: sample Paulis from quasi-probability distribution.

Estimates on observable_qubit by inserting Pauli corrections after each gate and accumulating signed expectations.

`scpn_quantum_control.mitigation.zne` ¶

Zero-Noise Extrapolation via global unitary folding.

Reference: Giurgica-Tiron et al., "Digital zero noise extrapolation for quantum error mitigation", IEEE QCE 2020.

`ZNEResult` `dataclass` ¶

Richardson extrapolation result: scales, raw values, and zero-noise estimate.

`gate_fold_circuit(circuit, scale)` ¶

Amplify noise by global unitary folding: G -> G (G^dag G)^((scale-1)/2).

The trailing measurement and barrier instructions are detached before folding and re-attached afterwards at their original qubit and clbit positions, so a partial, permuted or multi-register readout keeps the observable it started with. The returned circuit reuses the input's registers, bits, name, metadata and global phase; only the unitary body is repeated.

Parameters¶

circuit Circuit whose unitary body is folded. Classical operations may appear only in the trailing measurement/barrier block; a mid-circuit classical operation is rejected rather than silently dropped. scale Odd positive noise-scale factor. scale=1 returns an unchanged copy; scale=2k+1 appends k inverse-forward pairs.

Returns¶

qiskit.QuantumCircuit Folded circuit with the same measurement mapping as circuit.

Raises¶

ValueError If scale is not an odd positive integer, or if the circuit carries a classical operation outside its trailing measurement block.

References¶

Giurgica-Tiron et al., "Digital zero noise extrapolation for quantum error mitigation", IEEE QCE 2020.

`zne_extrapolate(noise_scales, expectation_values, order=1)` ¶

Richardson extrapolation to zero noise.

order controls polynomial degree: 1=linear, 2=quadratic. Scales must be distinct odd positive integers; booleans, floats and strings are rejected with ValueError without coercion, as in gate_fold_circuit.

Hardware¶

`scpn_quantum_control.hardware.trapped_ion` ¶

Representative trapped-ion noise model for cross-platform benchmarking.

Models all-to-all connectivity (no SWAP overhead) with depolarizing + thermal relaxation on MS gates. Multiqubit transpilation uses a CX-basis proxy for native MS/RXX-style entangling operations and must be explicitly enabled by the caller. Calibration values are representative order-of- magnitude QCCD benchmarks, not a specific device calibration.

`trapped_ion_noise_model(ms_error=MS_ERROR, t1_us=T1_US, t2_us=T2_US)` ¶

Noise model for QCCD trapped-ion hardware.

Single-qubit gates: thermal relaxation. MS gates: depolarizing + thermal relaxation (same pattern as heron_r2).

`transpile_for_trapped_ion(circuit, *, allow_proxy_basis=False)` ¶

Transpile with all-to-all connectivity (no SWAP insertion).

Multiqubit output is a {cx, ry, rz, sx, x, id} representative proxy for native trapped-ion MS/RXX-style gates, not a vendor-native compiler target. Callers must pass allow_proxy_basis=True to make that approximation explicit at call sites.

`scpn_quantum_control.hardware.fast_classical` ¶

High-performance sparse statevector engine.

Bypasses Qiskit circuit compilation and decomposition overheads to directly simulate Trotter or exact evolution using sparse matrix-vector multiplication (via scipy.sparse.linalg.expm_multiply).

Provides an order-of-magnitude speedup for large classical baselines (N >= 12) and enables simulation of N=20 systems on standard hardware in seconds.

`fast_sparse_evolution(K, omega, t_total, n_steps, initial_state=None, delta=0.0)` ¶

Evolve a statevector using fast sparse matrix exponentiation.

Parameters¶

K : ndarray of float Coupling matrix. omega : ndarray of float Natural frequencies. t_total : float Total evolution time. n_steps : int Number of intermediate time steps to return. initial_state : ndarray of complex, optional Initial statevector. Defaults to the all-zero computational basis state. delta : float XXZ anisotropy parameter. Zero selects the XY model.

Returns¶

dict[str, Any] Times, statevectors, qubit count, and final statevector.

`scpn_quantum_control.hardware.runner` ¶

IBM Quantum hardware runner.

Handles authentication, backend selection, transpilation, job submission, and result collection. Falls back to AerSimulator when no hardware available.

`HardwareRunner` ¶

Manages IBM Quantum backend lifecycle.

Usage

runner = HardwareRunner(token="...") # or token from saved account runner.connect() result = runner.run_sampler(circuit, shots=10000, name="my_experiment")

`backend` `property` ¶

Active Qiskit backend (None before connect()).

`backend_name` `property` ¶

Backend name string, or 'not_connected' before connect().

`backend_descriptor` `property` ¶

Provider-neutral descriptor for the connected execution route.

`init(token=None, channel='ibm_cloud', instance=None, backend_name=None, use_simulator=False, optimization_level=2, resilience_level=2, use_fractional_gates=True, results_dir='results', noise_model=None, max_dense_gib=None, seed_transpiler=20260718)` ¶

Configure runner. Call connect() before submitting jobs.

IBM Runtime error mitigation level.

0 = no mitigation 1 = TREX (readout error mitigation) 2 = PEA (probabilistic error amplification + noise learning + extrapolation) Default changed to 2 (PEA) for better accuracy on Heron r2+.

use_fractional_gates: Enable native RZZ on Heron r2+ (50-68% depth reduction). Requires Qiskit >= 1.3 and a backend that supports fractional gates. Falls back gracefully if the backend does not support them.

`connect()` ¶

Authenticate and select backend.

`calibration_snapshot()` ¶

Capture the connected backend's calibration for archival in a result pack.

Returns a JSON-serialisable snapshot (backend name, seed_transpiler, median T1/T2 and readout error, and the calibration date) so every run's result pack can carry the device state it was measured against, closing the "no archived calibration snapshot" reproducibility gap. Returns a {"available": False} record when the backend exposes no properties (e.g. a local simulator).

`transpile(circuit)` ¶

Transpile circuit for target backend.

`transpile_observable(obs, isa_circuit)` ¶

Map observable to transpiled circuit layout.

`circuit_stats(isa_circuit)` ¶

Return depth, gate counts, qubit count for transpiled circuit.

`retrieve_job(job_id)` ¶

Retrieve a previously submitted job by ID.

`run_sampler(circuits, shots=10000, name='experiment', timeout_s=600)` ¶

Submit circuits via SamplerV2, return counts.

`run_estimator(circuit, observables, parameter_values=None, name='experiment', timeout_s=600)` ¶

Submit circuit+observables via EstimatorV2, return expectation values.

`run_estimator_zne(circuit, observables, scales=None, order=1, name='zne_experiment')` ¶

Run ZNE: fold circuit at multiple noise scales, extrapolate to zero.

`transpile_with_dd(circuit, dd_sequence=None)` ¶

Transpile with Qiskit's PadDynamicalDecoupling pass.

Default sequence is XY4: [X, Y, X, Y].

`save_result(result, filename=None)` ¶

Save result(s) to JSON in results_dir with provenance.

A provenance block is embedded at the top level of the output document describing the git state, installed package versions, Python runtime, and host of the writer. Outsiders use it to trace published numbers back to a specific commit.

A calibration block records the device state (backend name, seed_transpiler, median T1/T2 and readout error, calibration date) the run was measured against, so every pack carries the calibration snapshot needed to reproduce it.

`save_token(token, instance=None, channel='ibm_cloud')` `staticmethod` ¶

Save IBM Quantum API token to disk (one-time setup).

`JobResult` `dataclass` ¶

Result from a single hardware or simulator job.

`to_dict()` ¶

Serialize to JSON-compatible dict.

Analysis¶

`scpn_quantum_control.analysis.sync_witness` ¶

Quantum synchronization witness operators.

A synchronization witness W is a Hermitian observable such that:

⟨W⟩ < 0  →  system is synchronised (collective phase coherence)
⟨W⟩ ≥ 0  →  system is incoherent

This is analogous to entanglement witnesses (Horodecki et al., 1996) but detects collective synchronization instead of quantum correlations.

Three witness constructions are provided:

Correlation witness W_corr = R_c·I - (1/N²)Σ_{ij}(X_iX_j + Y_iY_j) Threshold R_c separates synchronised from incoherent. Measurable with 2-qubit correlators (no tomography needed).
Fiedler witness W_F = λ₂_c·I - L̃(ρ) Based on the algebraic connectivity (2nd smallest eigenvalue of the quantum correlation Laplacian). λ₂ > 0 indicates connected synchronization; the witness fires when λ₂ exceeds threshold.
Topological witness W_top = p_c·I - P̂_H1 Based on persistent homology H1 cycle count. Fires when the fraction of persistent 1-cycles exceeds threshold, indicating vortex-free (synchronised) topology.

All three witnesses are: - Hermitian (self-adjoint) - Efficiently measurable on NISQ hardware - Calibratable against classical Kuramoto simulations

Reference: Prior quantum sync measures: Ameri et al., PRA 91, 012301 (2015); Ma et al., arXiv:2005.09001 (2020). Entanglement witnesses: Horodecki et al., PLA 223, 1 (1996). Sync-entanglement: Galve et al., Sci. Rep. 3, 1 (2013). This module's contribution: NISQ-hardware-ready witness trio with calibration.

`WitnessResult` `dataclass` ¶

Evaluation result of a synchronization witness.

`evaluate_all_witnesses(x_counts, y_counts, n_qubits, corr_threshold=0.0, fiedler_threshold=0.0, topo_threshold=0.5)` ¶

`to_json()` ¶

Serialise the discovery trace to compact JSON.

`WitnessSearchMode` ¶

Bases: StrEnum

Candidate proposal modes used by the discovery loop.

`discover_kuramoto_witnesses(K_nm, omega, *, theta0=None, spec=None, prefer_rust=True)` ¶

Run automated Kuramoto witness discovery.

The loop starts with a deterministic Latin-hypercube design, then combines an RBF Bayesian upper-confidence-bound acquisition with a bandit-style local exploration policy around the current best candidate.

`score_witness_candidates(K_nm, omega, candidates, *, theta0=None, spec=None, source=WitnessSearchMode.INITIAL, prefer_rust=True)` ¶

Score a fixed candidate batch through the witness objective.

`scpn_quantum_control.analysis.quantum_persistent_homology` ¶

Persistent homology on quantum measurement data.

Bridges quantum hardware → topological data analysis. Extracts a correlation distance matrix from measurement counts and computes persistent homology to detect the synchronization transition.

The classical version of this pipeline (PH on Kuramoto simulations) was published in Scientific Reports (2025), s41598-025-27083-w. The quantum version — PH on quantum measurement outcomes — is new.

Pipeline

Hardware measurement counts (X, Y bases) → correlation matrix
Correlation matrix → distance matrix d_ij = 1 - |C_ij|
Distance matrix → Vietoris-Rips persistent homology (ripser)
H1 persistence diagram → p_h1 (synchronization indicator)
Compare quantum p_h1 vs classical p_h1 at same parameters

When the system is synchronised

Correlation matrix is nearly rank-1 (all-to-all)
Distance matrix has small entries (close to 0)
Few persistent 1-cycles (vortices)
p_h1 ≈ 0

When the system is incoherent

Correlation matrix has partial structure
Distance matrix has varied entries
Many persistent 1-cycles
p_h1 > 0

`QuantumPHResult` `dataclass` ¶

Persistent homology result from quantum measurement data.

`quantum_persistent_homology(x_counts, y_counts, n_qubits, persistence_threshold=0.1)` ¶

Full pipeline: hardware counts → persistent homology.

Parameters¶

x_counts Measurement counts in the X basis. y_counts Measurement counts in the Y basis. n_qubits Number of measured qubits. persistence_threshold Minimum H1 lifetime counted as persistent.

Returns¶

QuantumPHResult Normalized H1 indicator, persistence data, and correlation/distance matrices.

Raises¶

ImportError If the optional ripser dependency is unavailable.

`ph_sync_scan(x_counts_list, y_counts_list, n_qubits, K_base_values, persistence_threshold=0.1)` ¶

Scan p_h1 across coupling strengths from hardware data.

Takes lists of measurement counts at different K_base values (from sync_threshold experiment or similar) and computes p_h1 at each coupling strength.

Parameters¶

x_counts_list X-basis count mappings aligned with the coupling scan. y_counts_list Y-basis count mappings aligned with the coupling scan. n_qubits Number of measured qubits. K_base_values Coupling strengths associated with the count pairs. persistence_threshold Minimum H1 lifetime counted as persistent.

Returns¶

dict[str, Any] Coupling values and aligned p_h1/persistent-H1 series.

`scpn_quantum_control.analysis.berry_phase` ¶

Finite-size Berry diagnostics for exact Kuramoto-XY ground-state scans.

The Berry (geometric) phase γ = -Im ∮ ⟨ψ(λ)|∂_λ ψ(λ)⟩ dλ measures the geometry of the ground-state manifold in parameter space. Along the one-dimensional open K scan used here, the accumulated connection is gauge-dependent; the fidelity and fidelity susceptibility are the primary gauge-invariant diagnostics.

Near a finite-size avoided crossing or transition proxy, the ground state can change character rapidly. This module reports exact dense finite-size diagnostics for that behaviour; it does not by itself prove an asymptotic BKT singularity or an exhaustive literature boundary.

We compute: 1. Berry connection A(K) = -Im⟨ψ(K)|∂_K ψ(K)⟩ (approximated as -Im⟨ψ(K)|ψ(K+dK)⟩/dK) 2. Berry curvature F(K) = dA/dK (derivative of connection) 3. Accumulated phase γ(K) = ∫_0^K A(K') dK' 4. Fidelity susceptibility χ_F = -2 ln|⟨ψ(K)|ψ(K+dK)⟩|/dK² (diverges at K_c, related to QFI)

Prior art includes geometric-phase probes, fidelity susceptibility, and quantum-synchronisation diagnostics. This module applies those finite-size diagnostics to the Kuramoto-XY Hamiltonian implemented in this package.

`BerryPhaseResult` `dataclass` ¶

Berry phase analysis across coupling strength.

`berry_phase_scan(omega, K_topology, k_range=None, *, max_dense_gib=None)` ¶

Compute Berry connection, curvature, and fidelity across K.

K_topology: normalized coupling matrix (max=1), scaled by k_range values. max_dense_gib: optional GiB budget for dense eigensolver and retained states.

`scpn_quantum_control.analysis.finite_size_scaling` ¶

Finite-size scaling for K_c extraction from small exact quantum systems.

Estimates the thermodynamic-limit K_c from small-N exact diagonalisation data. For BKT-motivated finite-size studies, one common ansatz uses logarithmic corrections:

K_c(N) = K_c(∞) + a / (log N)²

(standard BKT FSS ansatz, Nomura-Kitazawa 2002).

This module reports finite-size gap-minimum diagnostics: 1. Computes K_c(N) from gap minimum for N = 2, 3, 4, 5 qubits 2. Fits the BKT-motivated FSS ansatz to extrapolate K_c(∞) 3. Also fits power-law K_c(N) = K_c(∞) + b/N^ν for comparison

Methods: Nomura-Kitazawa level spectroscopy (2002), Hasenbusch-Pinn log-correction extrapolation.

`FSSFitDiagnostics` `dataclass` ¶

Least-squares diagnostics for one finite-size scaling ansatz.

Parameters¶

model: Stable identifier for the fitted ansatz. extrapolated_k_c: Intercept of the linearised finite-size model, interpreted as K_c(infinity) for the selected ansatz. correction_coefficient: Coefficient multiplying the finite-size correction coordinate. residuals: Pointwise residuals observed K_c(N) - fitted K_c(N) in the order of the input system sizes. residual_norm: Euclidean norm of the residual vector. max_abs_residual: Largest absolute residual across the fitted system sizes. design_condition: Condition number of the two-column linear design matrix. rank: Numerical rank reported by numpy.linalg.lstsq. n_points: Number of finite-size points used in the fit. claim_boundary: Claim boundary attached to the diagnostic evidence.

`to_dict()` ¶

Return JSON-ready finite-size fit diagnostics.

Returns¶

dict[str, object] Primitive mapping suitable for dashboards, documentation manifests, and persisted audit artifacts.

`FSSResult` `dataclass` ¶

Finite-size scaling result for dense local gap-minimum scans.

The legacy extrapolated values are kept beside richer fit diagnostics so existing callers can continue to read k_c_extrapolated_bkt and k_c_extrapolated_power while promotion gates can inspect residuals and fit conditioning.

Parameters¶

system_sizes: Qubit counts used in the local exact finite-size scan. k_c_values: Gap-minimum coupling estimates K_c(N) aligned with system_sizes. gap_min_values: Minimum spectral gap observed at each scanned system size. k_c_extrapolated_bkt: Legacy scalar intercept from the BKT logarithmic-correction ansatz, or None when fewer than two finite-size points are available or the linear solve fails. k_c_extrapolated_power: Legacy scalar intercept from the fixed-exponent inverse-size ansatz, or None when fewer than two finite-size points are available or the linear solve fails. bkt_fit: Full least-squares diagnostics for the BKT ansatz. power_fit: Full least-squares diagnostics for the inverse-size ansatz. claim_boundary: Claim boundary describing what this exact local scan does and does not establish.

`to_dict()` ¶

Return JSON-ready finite-size scaling evidence.

Returns¶

dict[str, Any] Mapping containing raw scan outputs, legacy scalar extrapolations, rich fit diagnostics, and the attached claim boundary.

`finite_size_scaling(system_sizes=None, k_range=None, *, max_dense_gib=None)` ¶

Extract K_c from multiple system sizes and extrapolate.

Uses ring topology with Paper 27 natural frequencies. max_dense_gib gates each exact dense gap scan before Hamiltonian/eigensolver allocation.

Parameters¶

system_sizes: Optional qubit counts to scan. Defaults to [2, 3, 4, 5]. k_range: Strictly increasing one-dimensional coupling grid. Defaults to a deterministic local scan from 0.3 to 6.0. max_dense_gib: Optional dense workspace limit applied before each Hamiltonian and eigensolver allocation.

Returns¶

FSSResult Local exact finite-size evidence with raw gap minima, extrapolated scalar fields, fit diagnostics, and claim boundaries.

`scpn_quantum_control.analysis.krylov_complexity` ¶

Krylov complexity at the synchronization transition.

Krylov complexity K(t) measures operator spreading in Hilbert space under Heisenberg evolution O(t) = e^{iHt} O e^{-iHt}. The Lanczos algorithm builds an orthonormal Krylov basis {|O_n)} from repeated application of the Liouvillian L = [H, ·]:

L|O_n) = b_{n+1}|O_{n+1}) + b_n|O_{n-1})

The Lanczos coefficients b_n encode the operator growth rate. Krylov complexity: K(t) = Σ_n n |φ_n(t)|²

For chaotic systems: K(t) grows exponentially then linearly. For integrable systems: K(t) grows polynomially.

At a QPT, b_n may show universal scaling. For second-order transitions: del Campo et al. (arXiv:2510.13947) established Kibble-Zurek scaling of Krylov cumulants. For BKT (infinite-order): the KZ mechanism breaks down due to the essential singularity in the correlation length. The Krylov complexity behaviour at BKT is completely open.

Prior art: Krylov + QPT for Ising (del Campo 2025), XXZ chaos (Afrasiar 2024). Krylov + BKT or synchronization: NONE.

`KrylovResult` `dataclass` ¶

Krylov complexity computation result.

`krylov_vs_coupling(omega, K_topology, k_range=None, t_max=10.0, n_times=50, max_lanczos=50, *, max_dense_gib=None)` ¶

Scan Krylov complexity diagnostics across coupling strength.

Uses Z_0 (first qubit Pauli-Z) as the probe operator.

`scpn_quantum_control.analysis.magic_nonstabilizerness` ¶

Exact small-system stabilizer Rényi-2 diagnostics.

Stabilizer Rényi Entropy M_n measures how far a state is from the set of stabilizer states (classically simulable via Clifford circuits).

M_2(|ψ⟩) = -log₂(Σ_P ⟨ψ|P|ψ⟩⁴ / 2^n) - n

where the sum is over all n-qubit Pauli strings P (4^n terms).

The implementation enumerates all 4**n Pauli strings and is therefore a bounded exact diagnostic. A maximum in a finite coupling scan is not, by itself, a critical-point estimator, a fault-tolerant resource-cost certificate, or evidence of classical hardness or quantum advantage.

`MagicResult` `dataclass` ¶

Single-coupling pure-state stabilizer Rényi-2 result.

`magic_vs_coupling(omega, K_topology, k_range=None, *, max_dense_gib=None)` ¶

Scan exact small-system non-stabilizerness on a finite coupling grid.

peak_K reports only the grid argmax. Interpreting it as a critical point requires a separate preregistered finite-size and uncertainty study.

`scpn_quantum_control.analysis.theory_hook_promotion` ¶

Evidence-gated promotion records for experimental theory hooks.

This module is the theory-hook boundary between an importable research routine and a promoted control or product capability. The registry covers quantum speed limits, Hamiltonian learning, the finite Koopman closure, the legacy quantum_phi mutual-information diagnostic, stabilizer Rényi entropy, and spectral form-factor diagnostics.

The registry is deliberately conservative. A passing local evidence probe shows that a bounded software route works on its stated synthetic fixture; it does not establish hardware validity, differentiability, critical scaling, quantum advantage, consciousness, or operational control authority. All records are immutable and JSON-ready. Evidence execution is local, deterministic, credential-free, and never submits provider work.

`TheoryHookTier` ¶

Bases: StrEnum

Evidence tier assigned to a theory hook.

BOUNDED identifies a small, testable research diagnostic with an explicit claim boundary. RESEARCH_ONLY identifies a route that must not be promoted beyond exploratory analysis under the current semantics.

`TheoryHookRole` ¶

Bases: StrEnum

Permitted role of a hook in the SCPN Quantum Control stack.

`TheoryHookStatus` ¶

`scpn_quantum_control.analysis.research_lane_registry` ¶

Governed catalogue of the package's analysis and gauge research lanes.

The research-lane registry makes the existing deep-analysis stack visible without promoting every importable module into a product or scientific claim. Each immutable row records the module's human-reviewed maturity, relevance to differentiable work, current claim status, optional promotion route, and evidence pointers.

The inventory gate is intentionally strict: every ordinary analysis or gauge module must have exactly one row. Package __init__ modules and this registry's own governance implementation are the only exclusions. A new module therefore fails :func:assert_research_lane_inventory until a reviewer classifies it explicitly.

Registry membership is catalogue evidence only. It grants no productisation, control, hardware, differentiability, advantage, criticality, topology, consciousness, clinical, or publication claim. Promotions remain governed by their own backlog and evidence packages.

`ResearchLaneMaturity` ¶

Bases: StrEnum

Human-reviewed implementation maturity.

RESEARCH marks exploratory scientific code. PROTOTYPE marks a bounded reusable diagnostic whose public contract or evidence is not yet a product gate. PRODUCT_CANDIDATE marks a stable candidate or a module already composed by a separately governed product; it is not a promotion by this registry.

`ResearchLaneDiffHook` ¶

Bases: StrEnum

Relationship between a lane and differentiable-control work.

`ResearchLaneClaimStatus` ¶

Bases: StrEnum

Strongest claim class currently carried by a lane's own evidence.

`ResearchLaneRecord` `dataclass` ¶

Immutable human classification for one importable research module.

Parameters¶

module Fully qualified module path under scpn_quantum_control.analysis or scpn_quantum_control.gauge. summary Narrow description of what the current implementation can provide. The summary is not a scientific validation claim. maturity Human-reviewed implementation maturity. diff_hook Relationship to separately governed differentiable-control work. claim_status Strongest claim class admitted by the module's current evidence. promotion_targets Backlog routes that may consume the lane. A route suffixed planned or deferred-owner-gate is explicitly not a completed promotion. evidence_refs Repository-relative evidence or governance pointers. Empty tuples are expected for research-only and diagnostic-only lanes.

Notes¶

PRODUCT_CANDIDATE and EVIDENCE_BOUNDED remain non-promotional here. Callers must consult the referenced product/evidence package before making any stronger claim.

`family` `property` ¶

Module family, either analysis or gauge.

`registry_grants_productisation` `property` ¶

Always false because catalogue membership is non-promotional.

`registry_grants_control` `property` ¶

Always false; catalogue membership grants no actuation authority.

`registry_grants_publication_claim` `property` ¶

Always false; catalogue membership is not publication evidence.

`__post_init__()` ¶

Reject blank, out-of-scope, duplicate, or permissive records.

`as_dict()` ¶

Return a deterministic JSON-ready row with explicit denials.

`ResearchLaneInventoryReport` `dataclass` ¶

`scpn_quantum_control.analysis.rl_research_governance` ¶

Fail-closed governance for witness-search and pulse-optimisation research.

RL-governance keeps reinforcement-learning-adjacent routes in a research extra. The existing witness discovery is a seeded static candidate search, not a Gym environment or a trained production policy. Its dense composite witness score is therefore named explicitly and evaluated through deterministic replay over multiple seeds. The pulse optimiser remains unimplemented and blocked behind the separately governed pulse-execution boundary.

Nothing in this module enables provider submission, hardware execution, production control, policy deployment, or a scientific performance claim.

`RLResearchLane` ¶

Bases: StrEnum

Governed RL-adjacent route.

`RLResearchGovernanceError` ¶

`as_dict()` ¶

Return the complete report as deterministic JSON-ready data.

`estimate_witness_evaluation_budget(spec)` ¶

Return a conservative candidate-evaluation upper bound for one seed.

The initial Latin-hypercube candidates consume n_initial evaluations. Each iteration proposes at most max(batch_size - 1, 1) Bayesian rows plus one seeded bandit row.

`assess_rl_research(policy, lane, *, spec=None)` ¶

Return a fail-closed admission decision for an RL-adjacent route.

Parameters¶

policy Explicit policy. None resolves to the disabled default. lane Witness discovery or pulse optimisation. spec Search specification used for budget checks. It is ignored for the pulse route, which is blocked in the current implementation.

`assert_rl_research_allowed(policy, lane, *, spec=None)` ¶

Return an allowed decision or raise :class:RLResearchGovernanceError.

`build_witness_seed_suite(policy, template)` ¶

Build one budget-checked witness specification per policy seed.

`run_governed_witness_seed_suite(K_nm, omega, *, policy, template, theta0=None, prefer_rust=False)` ¶

Run and replay each preregistered seed without hardware or deployment.

Each full seeded search is executed twice. Byte-identical serialized traces are required before a seed result can be constructed. This is reproducible software evidence across multiple seeds, not statistical significance for an operational policy or a claim that the dense score is ungameable.

`build_rl_research_evidence_report()` ¶

Run the frozen credential-free three-seed governance fixture.

`render_rl_research_evidence_markdown(report=None)` ¶

Render deterministic human-readable RL governance evidence.

Crypto¶

`scpn_quantum_control.crypto` ¶

Quantum cryptography research module.

Topology-authenticated QKD using SCPN coupling matrix K_nm as shared secret. The Kuramoto-XY isomorphism converts K_nm into an entangled ground state whose measurement statistics serve as correlated key material.

Research status: scaffolding only — no production crypto.

`MLDSASigner` ¶

ML-DSA-65 private-key signer satisfying the platform Signer protocol.

Construct via :meth:generate from a 32-byte seed rather than directly; the seed is the key's reproducible root and must come from the caller (a secure RNG or a key-management system), never from inside this module.

Parameters¶

key_id The stable identifier recorded in every envelope this signer seals, by convention "<studio>:<keyid>" (e.g. "scpn-quantum-control:2026-q2"). keypair An explicit pure-Python reference key pair. This compatibility path cannot promise memory zeroisation; production code uses :meth:generate.

Raises¶

ValueError If key_id is empty or whitespace.

`key_id` `property` ¶

The stable identifier recorded in the envelope.

`is_destroyed` `property` ¶

Whether the native secret-key allocation has been destroyed.

`generate(key_id, *, seed)` `classmethod` ¶

Create a signer whose key is deterministically derived from seed.

Parameters¶

key_id The stable identifier ("<studio>:<keyid>") recorded in envelopes this signer seals. seed A 32-byte secret seed. The same seed always yields the same key, so the signer is reproducible; supply it from a secure RNG or a key-management system in production and a fixed vector in tests.

Raises¶

ValueError If seed is not exactly 32 bytes long or key_id is empty. RuntimeError If the compiled zeroizing signing-key backend is unavailable.

`sign(message)` ¶

Return the detached ML-DSA-65 seal signature over message.

Deterministic: the same key and message always produce byte-identical output, which is what lets a third party recompute and compare the signature.

Parameters¶

message The canonical bytes to sign.

`destroy()` ¶

Zeroize and permanently disable the native signing key.

A signer constructed directly with a Python :class:MLDSAKeyPair has no reliable wipe operation and therefore fails instead of claiming one.

`enter()` ¶

Return this signer for a bounded native-key custody scope.

`exit(exc_type, exc_value, traceback)` ¶

Destroy native secret material when leaving the custody scope.

`verifier()` ¶

Return the public :class:MLDSAVerifier for this signer's key.

`public_bytes()` ¶

Return the raw 1952-byte ML-DSA-65 public key (for keyring publication).

`MLDSAVerifier` ¶

ML-DSA-65 public-key verifier satisfying the platform Verifier protocol.

Parameters¶

public_key The 1952-byte ML-DSA-65 public key (FIPS 204 pk encoding).

Raises¶

ValueError If public_key is not exactly :data:PUBLIC_KEY_BYTES long.

`verify(message, signature)` ¶

Return True iff signature is a valid seal signature of message.

A malformed signature, a wrong-length signature, or a signature produced under a different context returns False — a verifier on an untrusted page reports a verdict, it never raises.

Parameters¶

message The canonical bytes the signature is taken over. signature The detached ML-DSA-65 signature to check.

`public_bytes()` ¶

Return the raw 1952-byte ML-DSA-65 public key (for keyring publication).

`PqcTriggerSigner` ¶

ML-DSA-65 signer for capacitor-bank trigger authorisation.

`keygen(*, seed=None)` ¶

Generate a key pair (deterministic when seed is supplied).

`sign(payload, private_key, *, timestamp_ns=None)` ¶

Sign payload bound to a timestamp.

`verify(payload, signature, public_key, *, max_age_ns=None, now_ns=None)` ¶

Verify a signature and (optionally) enforce a freshness window.

`sign_capacitor_bank_trigger(pulse_id, voltage_v, timestamp_ns, private_key)` ¶

Sign a capacitor-bank discharge command with a canonical payload.

`PrivateKey` `dataclass` ¶

An ML-DSA-65 private key.

`PublicKey` `dataclass` ¶

An ML-DSA-65 public key.

`Signature` `dataclass` ¶

A timestamped ML-DSA-65 signature.

`bell_inequality_test(sv, qubit_a, qubit_b, n_total)` ¶

CHSH inequality test for a qubit pair.

S = |E(a,b) - E(a,b') + E(a',b) + E(a',b')| Classical bound: S ≤ 2. Quantum bound: S ≤ 2√2. Violation (S > 2) certifies entanglement.

`correlator_matrix(sv, alice_qubits, bob_qubits)` ¶

Cross-correlation matrix between Alice and Bob qubits.

Apply depolarizing channel: rho → (1-p)rho + pI/d.

Parameters¶

rho Square density matrix. p Depolarizing probability.

Returns¶

numpy.ndarray Complex density matrix mixed with the maximally mixed state.

`devetak_winter_rate(qber)` ¶

Secret key rate from Devetak-Winter bound.

r = max(0, 1 - h(QBER) - h(QBER)) where h(x) = -x log2(x) - (1-x) log2(1-x) is binary entropy. Positive rate requires QBER < 0.11.

Parameters¶

qber Quantum bit-error rate.

Returns¶

float Secret-key rate clipped to the non-negative interval.

`intercept_resend_qber(sv, qubit_i, qubit_j, n_total)` ¶

QBER introduced by intercept-resend attack on qubit j.

Eve measures qubit j in Z basis, prepares new state, sends to Bob. In BB84, this introduces QBER = 0.25 when Eve guesses the wrong basis. For entangled states, the disturbance depends on the entanglement structure.

Returns the QBER that Bob would observe on qubit j after Eve's attack.

Parameters¶

sv Full-system statevector before interception. qubit_i Alice's reference qubit index. qubit_j Bob's intercepted qubit index. n_total Total number of qubits represented by sv.

Returns¶

float Absolute correlation-loss QBER clipped to [0, 0.5].

`noisy_concurrence(sv, qubit_i, qubit_j, n_total, p_depol)` ¶

Concurrence of a qubit pair after local depolarizing noise.

Traces out all qubits except (i,j), applies depolarizing channel to the 2-qubit reduced state, then computes Wootters concurrence.

Parameters¶

sv Full-system statevector. qubit_i First retained qubit index. qubit_j Second retained qubit index. n_total Total number of qubits represented by sv. p_depol Depolarizing probability applied to the reduced pair.

Returns¶

float Wootters concurrence of the noisy reduced state.

`security_analysis(sv, alice_qubits, bob_qubits, p_depol_range=None)` ¶

Compute key-rate curves versus noise for every Alice/Bob qubit pair.

Parameters¶

sv Full-system statevector used for all reduced-pair calculations. alice_qubits Alice-side qubit indices. bob_qubits Bob-side qubit indices. p_depol_range Depolarizing probabilities to scan. A 16-point [0, 0.3] grid is used when omitted.

Returns¶

dict Pairwise rate curves, maximum tolerable noise per pair, and aggregate rate versus noise.

`active_channel_graph(K, threshold)` ¶

List of above-threshold entangled pairs usable as QKD channels.

Returns list of (i, j, K_ij) tuples.

`best_entanglement_path(K, source, target)` ¶

Find the path from source to target maximizing minimum edge weight.

In entanglement routing, the bottleneck link determines the path's entanglement fidelity. Uses a modified Dijkstra with max-min metric.

Returns dict with 'path' (list of node indices) and 'bottleneck' (float).

`concurrence_map(K, omega, maxiter=100)` ¶

Compute pairwise concurrence from ground state reduced density matrices.

C(i,j) = max(0, sqrt(e1) - sqrt(e2) - sqrt(e3) - sqrt(e4)) where e_k are eigenvalues of rho * (Y⊗Y) rho* (Y⊗Y) in decreasing order.

Returns n×n symmetric matrix with concurrence values.

`key_rate_per_channel(conc_map)` ¶

Devetak-Winter key rate estimate for each link.

r(i,j) = max(0, 1 - h(e(C))) where e = (1 - sqrt(1 - C^2)) / 2 and h is binary entropy.

`percolation_threshold(K)` ¶

Minimum K_nm value for end-to-end entanglement.

Estimated from the Fiedler value of the coupling graph: when lambda_1 > 0, the graph is connected and entanglement percolates. Returns the smallest nonzero off-diagonal K_nm entry that keeps the graph connected.

`robustness_random_removal(K, n_trials=50)` ¶

Test connectivity under random edge removal.

Removes edges one at a time in random order. Returns the fraction of edges that can be removed before the graph disconnects.

This models random noise or calibration drift degrading K_nm entries.

`robustness_targeted_removal(K)` ¶

Test connectivity under targeted removal of strongest edges.

Removes edges in decreasing weight order — worst-case attack. Returns the number of edges removed before disconnection.

`challenge_response_prove(K, challenge)` ¶

Prover: compute HMAC(K_nm, challenge) as proof of K_nm knowledge.

The challenge is a random nonce from the verifier. The response proves the prover knows K_nm without transmitting it.

Parameters¶

K Secret coupling matrix used as HMAC key material. challenge Verifier-issued challenge bytes.

Returns¶

bytes SHA-256 HMAC response.

Compute public spectral fingerprint of coupling matrix.

Parameters¶

K Square coupling matrix.

Returns¶

dict Fiedler value, gap ratio, spectral entropy, component count, and sorted combinatorial-Laplacian eigenvalues.

`topology_commitment(K, nonce=b'')` ¶

Commit to K_nm without revealing it.

Returns SHA-256(K_nm_bytes || nonce). The commitment binds the prover to a specific K_nm. Later, the prover opens by revealing K_nm + nonce, and the verifier recomputes the hash.

Parameters¶

K Coupling matrix serialized as commitment material. nonce Optional public commitment nonce.

Returns¶

bytes SHA-256 commitment digest.

`topology_distance(fp1, fp2)` ¶

Applications¶

`scpn_quantum_control.applications` ¶

Physical system benchmarks and application modules.

`ApplicationPluginBenchmark` `dataclass` ¶

Result emitted by an application plugin benchmark run.

`as_dict()` ¶

Serialise the benchmark result without NumPy objects.

`ApplicationPluginRegistry` ¶

Registry for application plugins discovered through entry points.

`register(name, factory)` ¶

Register a plugin factory.

`unregister(name)` ¶

Remove a plugin factory and cached instance if present.

`clear()` ¶

Remove all registered plugins.

`names()` ¶

Return registered plugin names.

`get(name)` ¶

Instantiate, validate and cache one plugin.

Invalid factories or dataset metadata raise without caching a failed instance. A subsequent call retries construction; unrelated entries remain registered. Discovery does not validate factory results.

`discover(*, force=False)` ¶

Discover third-party plugins from package entry points.

`datasets()` ¶

Return plugin-to-dataset mapping.

`run_all()` ¶

Run every registered plugin against its packaged datasets.

`CrossDomainResult` `dataclass` ¶

Cross-domain structural-similarity summary.

`topology_similarity_proxies` `property` ¶

Spearman topology-similarity proxies for each domain system.

`best_similarity_proxy` `property` ¶

Largest absolute topology-similarity proxy in the comparison set.

`mean_similarity_proxy` `property` ¶

Mean absolute topology-similarity proxy across compared systems.

`ApplicationBenchmarkDescriptor` `dataclass` ¶

Metadata and privacy boundary for a packaged benchmark artifact.

contains_personal_data describes the packaged file, not every possible external input accepted by a third-party plugin. The built-in catalogue is intentionally restricted to curated public constants and small matrices with no raw participant, clinical, SCADA, or proprietary facility records.

`path` `property` ¶

Absolute path to the packaged artifact.

`ApplicationBenchmarkPrivacyAudit` `dataclass` ¶

One successful packaged-dataset privacy audit row.

Parameters¶

dataset_id Stable packaged dataset identifier. source_mode Validated artifact provenance mode. privacy_classification Descriptor classification for the packaged bytes. contains_personal_data Whether the packaged artifact contains personal data. Built-in rows must remain False. privacy_boundary Exact licence/provenance note bound to the artifact metadata. artifact_hashes Validated SHA-256 custody hashes embedded in the artifact. passed Always True for returned rows; mismatches raise instead of returning an ambiguous partial result.

`as_dict()` ¶

Return a JSON-ready audit row with defensive hash copying.

`EEGBenchmarkResult` `dataclass` ¶

EEG vs SCPN structural-comparison result.

`topology_similarity_proxy` `property` ¶

Spearman PLV-vs-K_nm similarity proxy, not a neural model reproduction.

`FMOBenchmarkResult` `dataclass` ¶

Structural comparison between SCPN and FMO coupling matrices.

`topology_similarity_proxy` `property` ¶

Spearman FMO-coupling-vs-K_nm proxy, not an exciton model reproduction.

`ApplicationDataOrigin` ¶

Bases: StrEnum

`ReservoirTrainingCertificate` `dataclass` ¶

Digest-bound held-out QRC and matched-feature ESN metrics.

`to_dict()` ¶

Return a JSON-ready certificate mapping.

`SyntheticReservoirDataset` `dataclass` ¶

Disjoint synthetic train/validation data for one reservoir task.

`__post_init__()` ¶

Validate shapes, finiteness, domain, and disjoint sample rows.

`compile_application_problem(plugin_name, dataset_id=None)` ¶

Load a plugin dataset and adapt it to the public Kuramoto facade.

`discover_application_plugins(*, force=False)` ¶

Discover application plugins via package entry points.

`get_application_plugin(name)` ¶

Return one application plugin by name.

`get_application_plugin_registry()` ¶

Return the process-wide application plugin registry.

`load_application_dataset(plugin_name, dataset_id=None)` ¶

Load a benchmark artifact through an application plugin.

`run_application_benchmark_suite()` ¶

Run all registered application benchmark plugins.

`run_cross_domain_validation(n_max=16)` ¶

Run all five structural-comparison benchmarks against SCPN K_nm.

Uses the appropriate oscillator count for each system.

`artifact_to_kuramoto_problem(artifact)` ¶

Adapt a validated QPU data artifact to the public Kuramoto facade.

Parameters¶

artifact : QPUDataArtifact Hash-locked oscillator artifact carrying a symmetric K_nm matrix and natural-frequency vector.

Returns¶

KuramotoProblem Immutable Kuramoto facade with provenance metadata copied from the artifact identity fields and artifact digest.

`audit_application_benchmark_privacy()` ¶

Audit every packaged application artifact against its privacy descriptor.

Returns¶

tuple[ApplicationBenchmarkPrivacyAudit, ...] One immutable, JSON-ready success row per catalogue descriptor.

Notes¶

This audit reads only files beneath data/public_application_benchmarks. It never traverses external paths, downloads data, or treats a curated matrix as raw domain evidence. Any mismatch raises immediately.

`get_application_benchmark_descriptor(dataset_id)` ¶

Return one packaged benchmark descriptor by stable identifier.

`list_application_benchmark_descriptors()` ¶

Return packaged application benchmark descriptors.

`load_application_benchmark_artifact(dataset_id)` ¶

Load a packaged artifact and enforce descriptor and privacy custody.

Raises¶

KeyError If dataset_id is not registered. ValueError If identity, domain, provenance mode, privacy boundary, or publication safety disagrees with the catalogue descriptor.

`fmo_coupling_matrix(*, allow_builtin_reference=False)` ¶

Return the built-in FMO coupling matrix and site energies.

Scaled to natural units: energies in rad/ps (divide cm⁻¹ by 5309).

`build_application_honesty_audit_report()` ¶

Build deterministic local evidence for every kit and catalogue row.

Returns¶

ApplicationHonestyAuditReport Immutable report with a canonical content digest.

Notes¶

The audit loads only versioned packaged application artifacts. It performs no network access and never opens a user-supplied or private dataset.

`get_domain_application_honesty_kit(kit_id)` ¶

Return one built-in honesty kit by stable identifier.

Parameters¶

kit_id Exact identifier returned by :func:list_domain_application_honesty_kits.

Raises¶

KeyError If kit_id is unknown. The error includes the known identifiers.

`get_domain_application_honesty_kit_for_dataset(dataset_id)` ¶

Return the unique kit governing a packaged dataset identifier.

Synthetic-only kits intentionally have no packaged dataset identifiers and therefore cannot be resolved through this function.

Raises¶

KeyError If no built-in kit governs dataset_id. RuntimeError If registry corruption assigns the same dataset to multiple kits.

`list_domain_application_honesty_kits()` ¶

Return all built-in domain application honesty kits in stable order.

`render_application_honesty_audit_markdown(report)` ¶

Render a human-readable Markdown evidence report.

Parameters¶

report Validated report returned by :func:build_application_honesty_audit_report.

`josephson_benchmark(K_scpn, omega_scpn, topology='all_to_all', parameters=None, coupling_edges=None, allow_illustrative_topology=False)` ¶

Compare SCPN K_nm with Josephson junction array coupling.

`build_josephson_knm_magnitude_study_design(*, n_junctions=DEFAULT_CANDIDATE_N, topology=DEFAULT_TOPOLOGY, parameters=None, extension_targets=DEFAULT_EXTENSION_TARGETS)` ¶

Build the Josephson K_nm magnitude-study preregistration manifest.

Parameters¶

n_junctions: Number of Josephson-array nodes used for the topology candidate. topology: Josephson topology model passed to :func:josephson_benchmark. parameters: Parameter set used to evaluate the topology candidate. When omitted, explicitly labelled nominal transmon literature parameters are used. extension_targets: Larger node counts to preregister for the same study after calibrated Josephson coupling artifacts exist.

Returns¶

JosephsonMagnitudeStudyDesign Design manifest with topology evidence, required calibration fields, and fail-closed promotion gates.

`render_josephson_knm_magnitude_study_markdown(design)` ¶

Render a human-reviewable Josephson K_nm magnitude-study report.

`power_grid_benchmark(K_scpn, omega_scpn, grid_name='IEEE-5bus', *, grid_coupling=None, grid_frequencies=None, reference_source_mode='curated', allow_builtin_reference=False)` ¶

Compare SCPN coupling topology with power grid.

Uses the smaller dimension (min(n_scpn, n_grid)) for comparison.

`classical_esn_feature_matrix(X, *, reservoir_size, spectral_radius=0.9, input_scale=0.5, leak_rate=1.0, seed=0)` ¶

Return deterministic echo-state features for a sample sequence.

Parameters¶

X: Input samples with shape (n_samples, n_features). reservoir_size: Number of classical reservoir units. Use the QRC feature count for a matched-feature comparison. spectral_radius: Target spectral radius of the recurrent matrix. input_scale: Uniform input-weight scale. leak_rate: Leaky integration rate in (0, 1]. seed: Seed for the deterministic reservoir weights.

Returns¶

numpy.ndarray Feature matrix with shape (n_samples, reservoir_size).

Enhance EVS features through quantum Kuramoto evolution.

Parameters¶

features Finite non-empty one-dimensional classical EVS feature vector. n_osc Quantum oscillator count in the supported Paper-27 frequency range. dt Positive finite evolution time. trotter_reps Positive integer number of Lie-Trotter repetitions.

Returns¶

QuantumEVSResult Preserved classical features, quantum features, synchronisation, phase-topology proxy, and norm enhancement factor.

Raises¶

TypeError If n_osc or trotter_reps is not an integer. ValueError If features, oscillator count, evolution time, or repetitions violate their public contracts.

`canonical_edge_pairs(n_qubits)` ¶

Return canonical undirected pairs in upper-triangular order.

Parameters¶

n_qubits: Positive qubit count.

Returns¶

tuple[tuple[int, int], ...] Pairs (i, j) with 0 <= i < j < n_qubits.

Raises¶

ValueError If n_qubits is not a positive integer.

`compute_kernel_matrix(X, K, n_qubits)` ¶

Compute the full kernel matrix for a set of feature vectors.

Parameters:

Name	Type	Description	Default
`X`	`NDArray[float64]`	(n_samples, n_features) feature matrix	required
`K`	`NDArray[float64]`	coupling matrix	required
`n_qubits`	`int`	number of qubits for encoding	required

`encode_topology_edge_features(x, K, n_qubits, *, t=0.8, reps=2, max_qubits=8)` ¶

Encode canonical edge features through a coupling-modulated XY circuit.

Feature x[k] multiplies the coupling for the k-th pair returned by :func:canonical_edge_pairs. The circuit prepares |+>**n and applies one Trotter-synthesised evolution of the resulting XY Hamiltonian. No local feature rotations or provider calls are performed.

Parameters¶

x: Finite vector of length n_qubits * (n_qubits - 1) // 2. K: Finite symmetric (n_qubits, n_qubits) coupling matrix with zero diagonal. Zero entries are topology masks and ignore their features. n_qubits: Qubit count, bounded by max_qubits before dense simulation. t: Positive finite evolution time. reps: Positive integer Lie-Trotter repetition count, at most 16. max_qubits: Positive dense-state allocation budget, at most 20.

Returns¶

qiskit.quantum_info.Statevector Exact local statevector of dimension 2**n_qubits.

Raises¶

ValueError If shapes, symmetry, diagonal, finiteness, evolution settings, or resource budgets violate the contract.

`reservoir_features(x, K, omega=None, t=1.0, max_weight=2, *, max_dense_gib=None)` ¶

Compute quantum reservoir features for input x.

Parameters¶

x: Input feature vector with at most one value per qubit. K: Finite square coupling matrix. omega: Optional natural-frequency vector. t: Non-negative reservoir evolution time. max_weight: Maximum Pauli-string weight included in the feature map. max_dense_gib: Optional exact-statevector allocation ceiling.

Returns¶

ReservoirResult Pauli expectation features and their labels.

`certify_reservoir_training(dataset, K, *, omega=None, alpha=0.1, max_weight=1, t=1.0, seed=0, max_dense_gib=None)` ¶

Fit QRC/ESN readouts and certify their disjoint held-out metrics.

`generate_synthetic_reservoir_task(task_kind, *, n_train, n_validation, seed)` ¶

Generate a deterministic synthetic forecast or classification task.

The tasks are small functional certificates, not domain benchmarks. They contain no clinical, grid, plasma, private, or operational data.

`getattr(name)` ¶

Resolve and cache a public export from its original owning module.

Parameters¶

name Public export requested through this package.

Returns¶

Any Original object, including module-valued exports.

Raises¶

AttributeError If the name is undeclared or the original module lacks its attribute. ImportError If the owning module cannot be imported.

`dir()` ¶

List cached and deferred names for inspection tools.

Returns¶

list[str] Sorted package namespace and declared lazy export names.

`scpn_quantum_control.applications.dataset_catalog` ¶

Packaged application benchmark datasets exposed as QPU data artifacts.

`ApplicationBenchmarkDescriptor` `dataclass` ¶

Metadata and privacy boundary for a packaged benchmark artifact.

contains_personal_data describes the packaged file, not every possible external input accepted by a third-party plugin. The built-in catalogue is intentionally restricted to curated public constants and small matrices with no raw participant, clinical, SCADA, or proprietary facility records.

`path` `property` ¶

Absolute path to the packaged artifact.

`ApplicationBenchmarkPrivacyAudit` `dataclass` ¶

One successful packaged-dataset privacy audit row.

Parameters¶

dataset_id Stable packaged dataset identifier. source_mode Validated artifact provenance mode. privacy_classification Descriptor classification for the packaged bytes. contains_personal_data Whether the packaged artifact contains personal data. Built-in rows must remain False. privacy_boundary Exact licence/provenance note bound to the artifact metadata. artifact_hashes Validated SHA-256 custody hashes embedded in the artifact. passed Always True for returned rows; mismatches raise instead of returning an ambiguous partial result.

`as_dict()` ¶

Return a JSON-ready audit row with defensive hash copying.

`list_application_benchmark_descriptors()` ¶

Return packaged application benchmark descriptors.

`get_application_benchmark_descriptor(dataset_id)` ¶

Return one packaged benchmark descriptor by stable identifier.

`load_application_benchmark_artifact(dataset_id)` ¶

Load a packaged artifact and enforce descriptor and privacy custody.

Raises¶

KeyError If dataset_id is not registered. ValueError If identity, domain, provenance mode, privacy boundary, or publication safety disagrees with the catalogue descriptor.

`audit_application_benchmark_privacy()` ¶

Audit every packaged application artifact against its privacy descriptor.

Returns¶

tuple[ApplicationBenchmarkPrivacyAudit, ...] One immutable, JSON-ready success row per catalogue descriptor.

Notes¶

This audit reads only files beneath data/public_application_benchmarks. It never traverses external paths, downloads data, or treats a curated matrix as raw domain evidence. Any mismatch raises immediately.

`artifact_to_kuramoto_problem(artifact)` ¶

Adapt a validated QPU data artifact to the public Kuramoto facade.

Parameters¶

artifact : QPUDataArtifact Hash-locked oscillator artifact carrying a symmetric K_nm matrix and natural-frequency vector.

Returns¶

KuramotoProblem Immutable Kuramoto facade with provenance metadata copied from the artifact identity fields and artifact digest.

`scpn_quantum_control.applications.honesty_kits` ¶

Fail-closed claim and data boundaries for domain-facing applications.

The objects in this module do not certify domain validity. They make the opposite boundary explicit: each kit identifies the small software route that is supported, the data origin admitted by that route, and the claims that remain forbidden. The built-in registry covers the application-honesty power-grid, Josephson, EEG-like, and ITER-inspired application families.

All returned records are immutable and JSON-ready. The audit functions are local and deterministic; they do not read credentials, contact providers, submit hardware work, or inspect private datasets.

`ApplicationSupportStatus` ¶

Bases: StrEnum

Public support grade for a domain-facing application route.

BOUNDED_RESEARCH means that the named software path is tested for its documented small benchmark, while SIMULATION_ONLY requires generated inputs and forbids measured-domain interpretation.

`ApplicationDataOrigin` ¶

Synthetic-only kits intentionally have no packaged dataset identifiers and therefore cannot be resolved through this function.

Raises¶

KeyError If no built-in kit governs dataset_id. RuntimeError If registry corruption assigns the same dataset to multiple kits.

`build_application_honesty_audit_report()` ¶

Build deterministic local evidence for every kit and catalogue row.

Returns¶

ApplicationHonestyAuditReport Immutable report with a canonical content digest.

Notes¶

The audit loads only versioned packaged application artifacts. It performs no network access and never opens a user-supplied or private dataset.

`render_application_honesty_audit_markdown(report)` ¶

Render a human-readable Markdown evidence report.

Parameters¶

report Validated report returned by :func:build_application_honesty_audit_report.

`scpn_quantum_control.applications.app_plugins` ¶

Application-specific plugin registry for benchmark datasets and workflows.

`ApplicationPluginBenchmark` `dataclass` ¶

Result emitted by an application plugin benchmark run.

`as_dict()` ¶

Serialise the benchmark result without NumPy objects.

`ApplicationPluginRegistry` ¶

Registry for application plugins discovered through entry points.

`register(name, factory)` ¶

Register a plugin factory.

`unregister(name)` ¶

Remove a plugin factory and cached instance if present.

`clear()` ¶

Remove all registered plugins.

`names()` ¶

Return registered plugin names.

`get(name)` ¶

Instantiate, validate and cache one plugin.

Invalid factories or dataset metadata raise without caching a failed instance. A subsequent call retries construction; unrelated entries remain registered. Discovery does not validate factory results.

`discover(*, force=False)` ¶

Discover third-party plugins from package entry points.

`datasets()` ¶

Return plugin-to-dataset mapping.

`run_all()` ¶

Run every registered plugin against its packaged datasets.

`get_application_plugin(name)` ¶

Return one application plugin by name.

`load_application_dataset(plugin_name, dataset_id=None)` ¶

Load a benchmark artifact through an application plugin.

`compile_application_problem(plugin_name, dataset_id=None)` ¶

Load a plugin dataset and adapt it to the public Kuramoto facade.

`run_application_benchmark_suite()` ¶

Run all registered application benchmark plugins.

Gauge¶

`scpn_quantum_control.gauge` ¶

U(1) gauge theory observables for the Kuramoto-XY quantum model.

`CFTResult` `dataclass` ¶

CFT central charge extraction result.

`ConfinementResult` `dataclass` ¶

Confinement analysis result.

`GaugeLatticeCrosscheck` `dataclass` ¶

Side-by-side confinement report from the quantum and lattice routes.

`both_tensions_available` `property` ¶

Whether both routes produced a finite string tension.

`UniversalityResult` `dataclass` ¶

Universality class analysis result.

`VortexResult` `dataclass` ¶

Vortex density measurement result.

`WilsonLoopResult` `dataclass` ¶

Wilson loop measurement result.

`extract_central_charge(K, omega)` ¶

Extract CFT central charge c from entanglement scaling at given K.

Uses Calabrese-Cardy formula with chord length correction.

`find_critical_coupling(omega, k_range=(0.01, 5.0), n_points=30)` ¶

Find K where half-chain entanglement entropy is maximised.

At the critical point, entanglement is maximal (log divergence).

`confinement_analysis(K, omega)` ¶

Full confinement-deconfinement analysis.

Computes Wilson loops for triangles (length 3) and squares (length 4), extracts string tension from their ratio.

`confinement_vs_coupling(omega, k_values=None)` ¶

Scan confinement across coupling strength.

At K_c, the string tension should vanish (deconfinement transition).

`crosscheck_confinement_on_lattice(K, omega, *, beta=1.0, n_thermalisation=200, n_leapfrog=10, step_size=0.1, seed=None)` ¶

Run both confinement probes on one coupling topology.

Parameters¶

K : NDArray[np.float64] Symmetric coupling matrix, shape (n, n); non-zero entries define the gauge-link graph for both routes. omega : NDArray[np.float64] Natural frequencies, shape (n,) (quantum route only). beta : float, optional Inverse gauge coupling of the classical lattice ensemble; positive. n_thermalisation : int, optional HMC updates before measuring; at least 1. n_leapfrog : int, optional Leapfrog steps per HMC update; at least 1. step_size : float, optional Leapfrog step size; positive. seed : int or None, optional Lattice RNG seed for reproducible sampling.

Returns¶

GaugeLatticeCrosscheck The quantum confinement result plus classical lattice observables measured after thermalisation, with the HMC acceptance rate as a sampling-health indicator.

Raises¶

ValueError If K is not square-symmetric, omega has the wrong shape, or a sampling parameter is out of range.

`universality_analysis(K, omega)` ¶

Full BKT universality class check.

`measure_vortex_density(K, omega)` ¶

Measure vortex density from the ground state of H(K, omega).

`vortex_density_vs_coupling(omega, k_base_values=None)` ¶

Scan vortex density vs coupling strength.

At the BKT transition, vortex density should jump from 0 to finite.

`compute_wilson_loops(K, omega, max_length=4, max_loops=20)` ¶

Compute Wilson loop expectation values for the ground state.

Finds all loops up to max_length on the coupling graph and measures for each.

`wilson_loop_expectation(psi, loop, n_qubits)` ¶

Compute <ψ|W(C)|ψ> for a given state and loop.

`getattr(name)` ¶

Resolve and cache a public export from its original owning module.

Parameters¶

name Public export requested through this package.

Returns¶

Any Original object, including module-valued exports.

Raises¶

AttributeError If the name is undeclared or the original module lacks its attribute. ImportError If the owning module cannot be imported.

`dir()` ¶

List cached and deferred names for inspection tools.

Returns¶

list[str] Sorted package namespace and declared lazy export names.

TCBO¶

`scpn_quantum_control.tcbo` ¶

TCBO quantum extensions: topological coherence observer.

`TCBOResult` `dataclass` ¶

Collect small-system TCBO proxy diagnostics.

Attributes¶

p_h1 : float Gauge vortex density, reused as the Betti-1-labelled proxy. tee : float Seven-term entropy inclusion-exclusion proxy in bits. string_order : float Real expectation of the endpoint-Z/interior-X Pauli string. n_qubits : int Number of oscillators represented by the exact ground state. betti_0_proxy : float Fraction of qubits with absolute Z expectation above 0.5. betti_1_proxy : float Alias of p_h1; not a computed persistent-homology Betti number.

`compute_tcbo_observables(K, omega)` ¶

Compute TCBO proxy diagnostics from a small-system exact ground state.

Parameters¶

K : NDArray[np.float64] Square oscillator-coupling matrix passed to the exact-diagonalisation and gauge-vortex owners. omega : NDArray[np.float64] Oscillator-frequency vector with one entry per row of K.

Returns¶

TCBOResult Vortex-density, entropy inclusion-exclusion, Pauli-string, and polarization-fraction diagnostics.

Notes¶

The state-based fields use classical_exact_diag. The p_h1 field delegates independently to measure_vortex_density, whose gauge-module contract owns its own ground-state solve. Consequently this aggregator is a small-system library utility, not a large-system or hardware pipeline.

`getattr(name)` ¶

Resolve and cache a public export from its original owning module.

Parameters¶

name Public export requested through this package.

Returns¶

Any Original object, including module-valued exports.

Raises¶

AttributeError If the name is undeclared or the original module lacks its attribute. ImportError If the owning module cannot be imported.

`dir()` ¶

List cached and deferred names for inspection tools.

Returns¶

list[str] Sorted package namespace and declared lazy export names.

PGBO¶

`scpn_quantum_control.pgbo` ¶

PGBO quantum extensions: phase-geometry bridge.

`PGBOResult` `dataclass` ¶

Quantum PGBO tensor result.

`compute_pgbo_tensor(K, omega, epsilon=0.005)` ¶

Compute the quantum geometric tensor Q_μν for K_ij parameters.

Parameters are the upper-triangle entries of K.

`getattr(name)` ¶

Resolve and cache a public export from its original owning module.

Parameters¶

name Public export requested through this package.

Returns¶

Any Original object, including module-valued exports.

Raises¶

AttributeError If the name is undeclared or the original module lacks its attribute. ImportError If the owning module cannot be imported.

`dir()` ¶

List cached and deferred names for inspection tools.

Returns¶

list[str] Sorted package namespace and declared lazy export names.

Return a JSON-ready scenario mapping.

`L16DirectorPolicyError` ¶

Bases: RuntimeError

Raised when the closed-loop execution policy refuses bounded L16 evaluation.

`L16Result` `dataclass` ¶

Legacy L16 indicators and heuristic action label.

`validate_l16_evidence(payload)` ¶

Return fail-closed findings for one L16 director evidence payload.

`write_l16_evidence(json_path, markdown_path, *, payload=None)` ¶

Validate and atomically write real or independently supplied L16 evidence.

`frozen_l16_scenarios()` ¶

Return the three ordered small-system L16 director scenarios.

`informative_l16_indicators(result)` ¶

Name raw indicators that differ nontrivially from their invariant baseline.

`l16_promotion_blockers(certificates)` ¶

Return fixed claim boundaries plus findings from the supplied real certificates.

`observer_inputs_from_l16(action, *, reason='')` ¶

Map a legacy L16 action into the conservative observer interlock contract.

`run_l16_director_suite(*, policy=None)` ¶

Run complete bounded evidence and retain permanent promotion blockers.

`run_l16_indicator_scenario(scenario, *, policy, backend=None)` ¶

Execute and replay one frozen scenario under the shared execution policy.

`compute_l16_lyapunov(K, omega, t=0.5)` ¶

Compute the legacy L16 indicator bundle and weighted heuristic.

The returned stability_score name is retained for compatibility. It is an uncalibrated weighted composite, not a Lyapunov exponent or stability guarantee. Use the bounded L16 director product for policy gating and claim boundaries.

`getattr(name)` ¶

Resolve and cache a public export from its original owning module.

Parameters¶

name Public export requested through this package.

Returns¶

Any Original object, including module-valued exports.

Raises¶

AttributeError If the name is undeclared or the original module lacks its attribute. ImportError If the owning module cannot be imported.

`dir()` ¶

List cached and deferred names for inspection tools.

Returns¶

list[str] Sorted package namespace and declared lazy export names.

Auto-Generated API Reference¶

Stable Facades¶

scpn_quantum_control.kuramoto_core ¶

KuramotoProblem dataclass ¶

n_oscillators property ¶

K property ¶

__post_init__() ¶

validate() ¶

to_metadata() ¶

build_kuramoto_problem(K_nm, omega, metadata=None) ¶

validate_kuramoto_inputs(K_nm, omega) ¶

compile_hamiltonian(problem) ¶

compile_dense_hamiltonian(problem, *, max_dense_gib=None) ¶

compile_trotter_circuit(problem, time, trotter_steps=10, trotter_order=1) ¶

compile_analog_program(problem, *, platform, duration, coupling_scale=1.0) ¶

compile_hybrid_program(problem, *, platform, duration, digital_time=None, max_analog_couplers=None, analog_threshold=0.0, trotter_steps=8, trotter_order=1) ¶

measure_order_parameter(problem, statevector) ¶

simulate_variant_trajectory(problem, variant, *, dt, n_steps, theta0=None, hyperedges=None, hyper_weights=None, target_r=0.75, monitor_gain=0.8, measurement_strength=0.2, gain_loss=None, prefer_rust=True) ¶

Advanced Module Reference¶

Bridge¶

scpn_quantum_control.bridge.knm_hamiltonian ¶

OMEGA_N_16 = np.array([1.329, 2.61, 0.844, 1.52, 0.71, 3.78, 1.055, 0.625, 2.21, 1.74, 0.48, 3.21, 0.915, 1.41, 2.83, 0.991], dtype=(np.float64)) module-attribute ¶

omega_for_oscillators(n_oscillators) ¶

Parameters¶

Returns¶

Raises¶

build_knm_paper27(L=16, K_base=0.45, K_alpha=0.3) ¶

build_kuramoto_ring(n, coupling=1.0, omega=None, rng_seed=None) ¶

knm_to_hamiltonian(K, omega) ¶

knm_to_ansatz(K, reps=2, threshold=0.01) ¶

scpn_quantum_control.bridge.qpu_data_artifact ¶

QPUDataArtifact dataclass ¶

Attributes¶

n_oscillators property ¶

is_synthetic property ¶

__post_init__() ¶

require_publication_safe() ¶

Raises¶

to_dict() ¶

Returns¶

to_json(*, indent=2) ¶

Parameters¶

Returns¶

from_dict(data) classmethod ¶

Parameters¶

Returns¶

Raises¶

from_json(payload) classmethod ¶

Parameters¶

Returns¶

from_scpn_datastream_payload(payload, *, source_mode='synthetic', domain='scpn', source_name='sc-neurocore-datastream', normalization='sc-neurocore canonical stream', extraction_method='sc_neurocore.scpn.datastream') classmethod ¶

Parameters¶

Returns¶

Raises¶

artifact_from_arrays(*, domain, source_name, source_mode, K_nm, omega, normalization, extraction_method, theta0=None, layer_assignments=(), source_timestamp=None, replay_id=None, metadata=None) ¶

Parameters¶

Returns¶

artifact_to_kuramoto_problem(artifact) ¶

Parameters¶

Returns¶

validate_qpu_data_artifact(artifact, *, require_publication_safe=True) ¶

Parameters¶

Returns¶

Raises¶

read_qpu_data_artifact(path) ¶

Parameters¶

Returns¶

write_qpu_data_artifact(path, artifact) ¶

Parameters¶

scpn_quantum_control.bridge.scpn_upde_edge ¶

SCPNUPDEEdge dataclass ¶

n_oscillators property ¶

dt property ¶

__post_init__() ¶

to_payload() ¶

build_paper27_scpn_upde_edge(*, time=0.1, trotter_steps=1, trotter_order=1) ¶

build_scpn_upde_edge(K_nm, omega, *, time=0.1, trotter_steps=1, trotter_order=1, claim_boundary=PAPER27_PROVISIONAL_BOUNDARY) ¶

validate_scpn_upde_edge_payload(payload) ¶

scpn_quantum_control.bridge.snn_adapter ¶

SNNQuantumBridge ¶

`scpn_quantum_control.kuramoto_core` ¶

`KuramotoProblem` `dataclass` ¶

`n_oscillators` `property` ¶

`K` `property` ¶

`__post_init__()` ¶

`validate()` ¶

`to_metadata()` ¶

`build_kuramoto_problem(K_nm, omega, metadata=None)` ¶

`validate_kuramoto_inputs(K_nm, omega)` ¶

`compile_hamiltonian(problem)` ¶

`compile_dense_hamiltonian(problem, *, max_dense_gib=None)` ¶

`compile_trotter_circuit(problem, time, trotter_steps=10, trotter_order=1)` ¶

`compile_analog_program(problem, *, platform, duration, coupling_scale=1.0)` ¶

`compile_hybrid_program(problem, *, platform, duration, digital_time=None, max_analog_couplers=None, analog_threshold=0.0, trotter_steps=8, trotter_order=1)` ¶

`measure_order_parameter(problem, statevector)` ¶

`simulate_variant_trajectory(problem, variant, *, dt, n_steps, theta0=None, hyperedges=None, hyper_weights=None, target_r=0.75, monitor_gain=0.8, measurement_strength=0.2, gain_loss=None, prefer_rust=True)` ¶

`scpn_quantum_control.bridge.knm_hamiltonian` ¶

`OMEGA_N_16 = np.array([1.329, 2.61, 0.844, 1.52, 0.71, 3.78, 1.055, 0.625, 2.21, 1.74, 0.48, 3.21, 0.915, 1.41, 2.83, 0.991], dtype=(np.float64))` `module-attribute` ¶

`omega_for_oscillators(n_oscillators)` ¶

`build_knm_paper27(L=16, K_base=0.45, K_alpha=0.3)` ¶

`build_kuramoto_ring(n, coupling=1.0, omega=None, rng_seed=None)` ¶

`knm_to_hamiltonian(K, omega)` ¶

`knm_to_ansatz(K, reps=2, threshold=0.01)` ¶

`scpn_quantum_control.bridge.qpu_data_artifact` ¶

`QPUDataArtifact` `dataclass` ¶

`n_oscillators` `property` ¶

`is_synthetic` `property` ¶

`__post_init__()` ¶

`require_publication_safe()` ¶

`to_dict()` ¶

`to_json(*, indent=2)` ¶

`from_dict(data)` `classmethod` ¶

`from_json(payload)` `classmethod` ¶

`from_scpn_datastream_payload(payload, *, source_mode='synthetic', domain='scpn', source_name='sc-neurocore-datastream', normalization='sc-neurocore canonical stream', extraction_method='sc_neurocore.scpn.datastream')` `classmethod` ¶

`artifact_from_arrays(*, domain, source_name, source_mode, K_nm, omega, normalization, extraction_method, theta0=None, layer_assignments=(), source_timestamp=None, replay_id=None, metadata=None)` ¶

`artifact_to_kuramoto_problem(artifact)` ¶

`validate_qpu_data_artifact(artifact, *, require_publication_safe=True)` ¶

`read_qpu_data_artifact(path)` ¶

`write_qpu_data_artifact(path, artifact)` ¶

`scpn_quantum_control.bridge.scpn_upde_edge` ¶

`SCPNUPDEEdge` `dataclass` ¶

`n_oscillators` `property` ¶

`dt` `property` ¶

`__post_init__()` ¶

`to_payload()` ¶

`build_paper27_scpn_upde_edge(*, time=0.1, trotter_steps=1, trotter_order=1)` ¶

`build_scpn_upde_edge(K_nm, omega, *, time=0.1, trotter_steps=1, trotter_order=1, claim_boundary=PAPER27_PROVISIONAL_BOUNDARY)` ¶

`validate_scpn_upde_edge_payload(payload)` ¶

`scpn_quantum_control.bridge.snn_adapter` ¶

`SNNQuantumBridge` ¶

`forward(spike_history)` ¶

`ArcaneNeuronBridge` ¶

`step_neurons(currents)` ¶

`quantum_forward()` ¶

`step(external_currents)` ¶

`reset()` ¶

`spike_train_to_rotations(spikes, window=10)` ¶

`quantum_measurement_to_current(values, scale=1.0)` ¶

`scpn_quantum_control.bridge.ssgf_adapter` ¶

`SSGFQuantumLoop` ¶

`quantum_step()` ¶

`ssgf_w_to_hamiltonian(W, omega)` ¶

`ssgf_state_to_quantum(state_dict)` ¶

`quantum_to_ssgf_state(sv, n_osc)` ¶

`scpn_quantum_control.phase.xy_kuramoto` ¶

`QuantumKuramotoSolver` ¶

`init(n_oscillators, K_coupling, omega_natural, trotter_order=None, evolution_config=None)` ¶

`build_hamiltonian()` ¶

`evolve(time, trotter_steps=None)` ¶

`measure_order_parameter(sv)` ¶

`run(t_max, dt, trotter_per_step=None, *, max_statevector_gib=None, deadline_monotonic=None, cancelled=None)` ¶

`energy_expectation(sv)` ¶

`scpn_quantum_control.phase.kuramoto_variants` ¶

`KuramotoVariant` ¶

`KuramotoVariantResult` `dataclass` ¶

`final_r` `property` ¶

`peak_r` `property` ¶

`__post_init__()` ¶

`to_metadata()` ¶

`HigherOrderKuramotoSpec` `dataclass` ¶