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.

`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 boosts from S4.3.

`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` ¶

Validated oscillator data ready for quantum-control compilation.

K_nm follows the Phase Orchestrator convention: row i receives coupling from column j. Current Kuramoto-XY circuits require a symmetric, non-negative, zero-diagonal matrix unless the caller explicitly opts into more specialised models.

`n_oscillators` `property` ¶

Number of oscillators/qubits implied by the artifact.

`is_synthetic` `property` ¶

Whether this artifact is non-publication synthetic data.

`require_publication_safe()` ¶

Reject synthetic or insufficiently traceable artifacts.

`to_dict()` ¶

Serialise to a JSON-compatible mapping.

`to_json(*, indent=2)` ¶

Serialise to JSON.

`from_dict(data)` `classmethod` ¶

Load and validate an artifact from a mapping.

`from_json(payload)` `classmethod` ¶

Load and validate an artifact from JSON.

`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` ¶

Adapt the current SC-NeuroCore datastream payload for smoke tests.

The SC-NeuroCore stream generated by commit 52bd3649 is deterministic and useful for interface tests, but it is not a recorded source artifact. It therefore defaults to source_mode='synthetic'.

`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)` ¶

Construct a QPU data artifact for bridge tests and loaders.

`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.

`validate_qpu_data_artifact(artifact, *, require_publication_safe=True)` ¶

Validate a QPU artifact and optionally enforce publication safety.

`read_qpu_data_artifact(path)` ¶

Read a QPU data artifact from JSON.

`write_qpu_data_artifact(path, artifact)` ¶

Write a QPU data artifact to JSON.

`scpn_quantum_control.bridge.scpn_upde_edge` ¶

Bounded knm.scpn-upde edge payloads for SPO federation.

`SCPNUPDEEdge` `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` ¶

Return the oscillator/qubit count carried by the edge.

`dt` `property` ¶

Return the implied per-step Trotter interval.

`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. 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. 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)` ¶

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

This local simulator path stores an exact dense statevector. Use max_statevector_gib to fail closed before Qiskit allocates that vector; hardware or tensor-network paths should be used for larger systems.

`energy_expectation(sv)` ¶

Compute for a given statevector.

`scpn_quantum_control.phase.kuramoto_variants` ¶

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

`KuramotoVariant` ¶

Bases: str, Enum

Supported Kuramoto trajectory variants.

`KuramotoVariantResult` `dataclass` ¶

Trajectory and diagnostics for one Kuramoto variant run.

`final_r` `property` ¶

Final Kuramoto order parameter.

`peak_r` `property` ¶

Peak Kuramoto order parameter along the trajectory.

`to_metadata()` ¶

Return a serialisable trajectory summary.

`HigherOrderKuramotoSpec` `dataclass` ¶

Pairwise Kuramoto system plus anchored triadic simplicial couplings.

`MonitoredKuramotoSpec` `dataclass` ¶

Kuramoto trajectory with deterministic measurement-feedback closure.

`PTSymmetricKuramotoSpec` `dataclass` ¶

Complex Kuramoto oscillator system with balanced gain/loss channels.

`build_triadic_ring_terms(n_oscillators, weight)` ¶

Build anchored nearest-neighbour triadic terms on a periodic ring.

`simulate_higher_order_kuramoto(spec, *, dt, n_steps, prefer_rust=True)` ¶

Simulate pairwise plus anchored triadic Kuramoto dynamics.

`simulate_monitored_kuramoto(spec, *, dt, n_steps, prefer_rust=True)` ¶

Simulate monitored Kuramoto dynamics with order-parameter feedback.

`simulate_pt_symmetric_kuramoto(spec, *, dt, n_steps, prefer_rust=True)` ¶

Simulate balanced gain/loss PT-symmetric Kuramoto dynamics.

`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).

`scpn_quantum_control.phase.coupling_learning` ¶

Parameter-shift coupling learning for oscillator observation models.

`CouplingGradientVerificationResult` `dataclass` ¶

Finite-difference agreement certificate for coupling-learning gradients.

`to_dict()` ¶

Return JSON-ready gradient-verification evidence.

`CouplingLearningResult` `dataclass` ¶

Auditable parameter-shift coupling-learning result.

`best_loss` `property` ¶

Return the best full-observation mean-squared loss.

`max_abs_residual` `property` ¶

Return 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 BL-17 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 BL-18 synchronisation-witness records.

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

Evidence class for local synthetic synchronisation-witness runs.

Run the deterministic BL-18 synchronisation-witness evidence suite.

`sync_witness_boundary_rows()` ¶

Return fail-closed BL-18 synchronisation-witness boundary rows.

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

`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` ¶

Return optimizer names in first-seen order.

`certificate_failures` `property` ¶

Return 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.

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 optimization.

Discretizes the MPC action space to binary (coil on/off per timestep), maps the quadratic cost to an Ising Hamiltonian, then solves via QAOA.

`QAOA_MPC` ¶

QAOA-based model predictive controller.

Cost: C = sum_t ||B*u(t) - target||^2 discretized to binary u_t in {0,1}. This quadratic-in-binary is equivalent to an Ising Hamiltonian.

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

Set up MPC: B_matrix maps actions to state, horizon = number of binary timesteps.

`build_cost_hamiltonian()` ¶

Map per-timestep quadratic binary cost to Ising Hamiltonian.

C(u) = sum_t (a*u_t - b)^2, a=||B||, b=||target||/H. Expanding with u_t^2=u_t and u_t=(1-Z_t)/2: C = const + h_z * sum_t Z_t where h_z = -(a^2 - 2ab)/2. No ZZ terms (timesteps are independent).

`optimize(seed=None)` ¶

Run QAOA optimization, return binary action sequence.

Returns¶

shape (horizon,) array of 0/1 actions.

`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)

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

weights: (n_neurons, n_inputs) or None for random init in [0, 1].

`forward(input_values)` ¶

Build circuit, measure neuron register, return spike array.

Parameters:

Name	Type	Description	Default
`input_values`	`NDArray[float64]`	shape (n_inputs,) with values in [0, 1]	required

Returns¶

shape (n_neurons,) int array of 0/1 spikes

`get_weights()` ¶

Return (n_neurons, n_inputs) weight matrix.

`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.

`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 DP-004 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` ¶

`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.

Static semantics summary for whole-program AD graph capture.

`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` ¶

Return the number of bytecode instructions in the frontend report.

`source_feature_count` `property` ¶

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

`frontend_ready` `property` ¶

Return whether bytecode and source frontend metadata passed preflight.

`bytecode_basic_block_count` `property` ¶

Return the number of bytecode basic blocks in the frontend report.

`source_region_count` `property` ¶

Return the number of source regions in the frontend report.

`source_bytecode_line_map_count` `property` ¶

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

`symbol_scope_entry_count` `property` ¶

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

`unsupported_semantic_diagnostic_count` `property` ¶

Return the number of unsupported-semantics diagnostics in the report.

`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` ¶

Return the rank of the derivative-carrying array.

`size` `property` ¶

Return the total number of derivative-carrying elements.

`T` `property` ¶

Return 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)` ¶

Reject ndarray coercion that would discard trace metadata.

`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 a supported NumPy ufunc through array trace semantics.

`__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.

`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)` ¶

Returns¶

bool True when both jax and jax.numpy import successfully, otherwise False.

`vmap(function, in_axes=0, out_axes=0, *, primitive_identity=None, registry=None)` ¶

`scpn_quantum_control.whole_program_trace_values` ¶

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.

`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` ¶

Return the rank of the derivative-carrying array.

`size` `property` ¶

Return the total number of derivative-carrying elements.

`T` `property` ¶

Return 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)` ¶

Reject ndarray coercion that would discard trace metadata.

`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 a supported NumPy ufunc through array trace semantics.

`__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` ¶

Return sorted categories covered by this audit.

`missing_categories` `property` ¶

Return required categories missing from the audit.

`passed_cases` `property` ¶

Return cases whose executed residuals are within tolerance.

`failed_cases` `property` ¶

Return cases whose executed residuals exceeded tolerance.

`blocked_cases` `property` ¶

Return explicit fail-closed transform-algebra boundaries.

`support_matrix` `property` ¶

Return support rows generated from executable and blocked cases.

`missing_support_rows` `property` ¶

Return required support-matrix rows missing from the generated matrix.

`failed_support_rows` `property` ¶

Return generated support rows whose source cases failed.

`passed` `property` ¶

Return 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` ¶

Return 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 BL-15 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 BL-15 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 BL-16 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 BL-16 open-system objective evidence payload.

`render_open_system_objective_evidence_markdown(payload)` ¶

Render the BL-16 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 BL-16 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)` ¶

Batched replay result from an executable whole-program AD kernel.

`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.

`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.

`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.

`CloudDeploymentSpec` `dataclass` ¶

Cloud-native deployment request for an offline SCPN workload.

`CloudManifestBundle` `dataclass` ¶

Generated cloud-native manifest files plus provenance digest.

`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.

`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)` ¶

Assess route-level provider metadata without submitting work.

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

Resolve a route, collect provider metadata, and assess it without submission.

`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.

`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` ¶

Provider-neutral hardware abstraction layer.

This module separates SCPN workload routing from provider SDKs. Discovery is metadata-only: constructing profiles does not import Qiskit, Braket, Azure, IonQ, Rigetti, QuEra, IQM, Pasqal, OQC, D-Wave, or simulator packages. Live execution is available only through an injected backend adapter that satisfies QuantumBackend and, for cloud profiles, carries an explicit approval token.

`BackendCapabilities` `dataclass` ¶

Provider route capabilities used for fail-fast workload validation.

`BackendProfile` `dataclass` ¶

Static profile for a concrete provider, broker, or simulator route.

`QuantumWorkload` `dataclass` ¶

Provider-neutral workload handed to an injected backend adapter.

`QuantumJobRef` `dataclass` ¶

Stable handle returned by a backend adapter after submission.

`QuantumJobResult` `dataclass` ¶

Provider-neutral result payload for shot-count workloads.

`QuantumBackend` ¶

`cancel(job)` ¶

Cancel a job by delegating to the owning adapter.

`built_in_backend_profiles()` ¶

`submit(workload, *, approval_id=None)` ¶

Submit a workload to the backend and return its job reference.

`status(job)` ¶

Return the current status for a submitted backend job.

`result(job)` ¶

Return the completed result for a submitted backend job.

`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.

Returns dict with max_depth (the budget), fidelity_at_max, fidelity_curve (sampled at key depths), and hardware_params.

`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:

Name	Type	Description	Default
`depth`	`int`	Total gate layers.	required
`n_qubits`	`int`	Number of qubits in the circuit.	required
`two_qubit_fraction`	`float`	Fraction of layers that are two-qubit gates.	`0.4`

Returns¶

Estimated fidelity in [0, 1].

`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` ¶

Arcane Sapience identity binding spec: 6-layer, 18-oscillator Kuramoto 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': ['ws_0', 'ws_1', 'ws_2'], '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 = {'ws_0': ['ws_action_first', 'ws_verify_before_claim'], 'ws_1': ['ws_commit_incremental', 'ws_preflight_push'], 'ws_2': ['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 IdentityAttractor from binding spec (defaults to ARCANE_SAPIENCE_SPEC).

`solve_identity(spec=None, maxiter=200, seed=None)` ¶

Build + solve identity attractor in one call.

`quantum_to_orchestrator_phases(quantum_theta, spec=None)` ¶

Map 18 quantum phases to 35 orchestrator oscillator phases.

Each quantum oscillator's phase is broadcast to its orchestrator sub-group. Returns {orchestrator_osc_id: phase} dict for injection into the identity_coherence domainpack simulation.

`orchestrator_to_quantum_phases(orchestrator_phases, spec=None)` ¶

Map 35 orchestrator phases back to 18 quantum oscillator phases.

Each quantum oscillator gets the circular mean of its sub-group phases.

Benchmarks¶

`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)` ¶

Execute one QEC-protected Trotter step and extract syndromes.

`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)` ¶

Global unitary folding: G -> G (G^dag G)^((scale-1)/2).

scale must be an odd positive integer. scale=1 returns the original circuit. Measurement gates are stripped before folding and re-appended.

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

Richardson extrapolation to zero noise.

order controls polynomial degree: 1=linear, 2=quadratic.

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:

Name	Type	Description	Default
`K`	`NDArray[float64]`	Coupling matrix.	required
`omega`	`NDArray[float64]`	Natural frequencies.	required
`t_total`	`float`	Total evolution time.	required
`n_steps`	`int`	Number of intermediate time steps to return.	required
`initial_state`	`NDArray[complex128] \| None`	Initial statevector (default: \|0...0>).	`None`
`delta`	`float`	XXZ anisotropy parameter (default: 0.0 = XY model).	`0.0`

Returns¶

dict: Containing 'times' and 'states' (statevector at each step).

`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; see the internal gap audit §C8 for the motivation.

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 (audit AUD-4b).

`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)` ¶

`ranked(limit=None)` ¶

Return evaluations sorted by descending score.

`to_json()` ¶

Serialise the discovery trace to compact JSON.

`WitnessSearchMode` ¶

Bases: str, Enum

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:

Name	Type	Description	Default
`x_counts`	`dict[str, int]`	Measurement counts in X basis.	required
`y_counts`	`dict[str, int]`	Measurement counts in Y basis.	required
`n_qubits`	`int`	Number of qubits.	required
`persistence_threshold`	`float`	Minimum H1 lifetime to count as persistent.	`0.1`

Returns¶

QuantumPHResult with p_h1 and full persistence data.

`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.

Returns dict with K_base values and corresponding p_h1 values, suitable for plotting the topological phase diagram.

`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 BL-98 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: str, Enum

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: str, Enum

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.

BL-84 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: str, Enum

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: str, Enum

Relationship between a lane and differentiable-control work.

`ResearchLaneClaimStatus` ¶

Bases: str, Enum

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` ¶

Return analysis or gauge from the fully qualified module.

`registry_grants_productisation` `property` ¶

Return False because catalogue membership is non-promotional.

`registry_grants_control` `property` ¶

Return False because BL-84 grants no actuation authority.

`registry_grants_publication_claim` `property` ¶

Return False because BL-84 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.

BL-102 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 BL-58 pulse boundary.

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

`RLResearchLane` ¶

Bases: str, Enum

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 BL-102 three-seed fixture.

`render_rl_research_evidence_markdown(report=None)` ¶

Render deterministic human-readable BL-102 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 The ML-DSA-65 key pair backing the signer.

Raises¶

ValueError If key_id is empty or whitespace.

`key_id` `property` ¶

The stable identifier recorded in the envelope.

`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 (key_gen enforces this) or key_id is empty.

`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.

`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.

Element (i,j) = - . Non-zero off-diagonal elements indicate entanglement.

`scpn_qkd_protocol(K, omega, alice_qubits, bob_qubits, shots=10000, *, seed)` ¶

Execute SCPN-QKD protocol on statevector simulator.

seed is REQUIRED: a key-distribution simulation must never source its randomness from a hidden default, so the caller states the seed explicitly (simulation-only — see the module docstring).

Returns dict with raw_key_alice, raw_key_bob, qber, secure_key (the privacy-amplified bit array, empty when the measured QBER is at or above the security threshold), secure_key_length (in bits), and bell_correlator (CHSH value).

`derive_layer_key(K, layer_idx, phase_sequence, nonce=b'')` ¶

Layer-specific subkey from coupling row + phase trajectory.

Parameters:

Name	Type	Description	Default
`K`	`NDArray[float64]`	Full coupling matrix (uses row layer_idx).	required
`layer_idx`	`int`	0-indexed layer number.	required
`phase_sequence`	`NDArray[float64]`	Array of phase values theta_n(t) over time window.	required
`nonce`	`bytes`	Additional entropy.	`b''`

`derive_master_key(K, R_global, nonce=b'')` ¶

Master key from full coupling matrix + order parameter.

32-byte SHA-256 digest of K_nm flattened || R_global || nonce.

`evolve_key_phases(K, omega, theta_0, t_window, n_samples=32)` ¶

Evolve Kuramoto dynamics and sample phase trajectory.

Returns (n_layers, n_samples) array of phase values over the time window. Each column is a snapshot at a different time.

`group_key(K, member_layers, phases, nonce=b'')` ¶

Derive a shared key for a subset of SCPN layers.

Uses the sub-matrix K[members, members] and their phase values. Any subset of layers can form a group with a shared key.

`hmac_sign(key, message)` ¶

Produce HMAC-SHA256 authentication tag for message under key.

`hmac_verify_key(key, message, expected_mac)` ¶

Verify HMAC-SHA256 tag in constant time.

Returns True iff the tag computed from (key, message) matches expected_mac.

`key_hierarchy(K, phases, R_global, nonce=b'')` ¶

Full hierarchy: master key + all layer subkeys.

Parameters:

Name	Type	Description	Default
`K`	`NDArray[float64]`	n×n coupling matrix.	required
`phases`	`NDArray[float64]`	n-element array of current phase values.	required
`R_global`	`float`	Global order parameter.	required
`nonce`	`bytes`	Session nonce.	`b''`

Returns dict with 'master' (bytes) and 'layers' (dict[int, bytes]).

`rotating_key_schedule(K, omega, theta_0, n_windows=4, window_duration=1.0)` ¶

Generate a sequence of key hierarchies from evolving Kuramoto dynamics.

Each window produces a different key hierarchy because the phase trajectory changes. Natural key rotation without re-keying.

Returns list of dicts, each with 'window', 'master', 'layers', 'R_global'.

`verify_key_chain(master, layer_keys, K, phases, R_global, nonce=b'')` ¶

Verify layer keys are consistent with master and K_nm.

Recomputes all keys from K and checks equality.

`estimate_qber(alice_bits, bob_bits)` ¶

Quantum bit error rate from shared verification subset.

QBER = (number of disagreements) / (total compared bits). Secure threshold: QBER < 0.11 for BB84-family protocols.

`extract_raw_key(counts, basis, keep_qubits=None)` ¶

Sift measurement results into raw key bits.

Parameters:

Name	Type	Description	Default
`counts`	`dict[str, int]`	Measurement outcome counts from Qiskit.	required
`basis`	`str`	"Z" or "X" — measurement basis used.	required
`keep_qubits`	`list[int] \| None`	Qubit indices to extract (None = all).	`None`

Returns¶

1D array of {0, 1} bits, majority-vote per qubit.

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

Build VQE-optimized circuit encoding K_nm's ground state.

Returns dict with 'circuit' (bound QuantumCircuit), 'energy' (float), and 'statevector' (Statevector).

`privacy_amplification(raw_key, qber, *, seed)` ¶

Toeplitz-hash privacy amplification (Universal₂, leftover-hash lemma).

The extractor is a random binary Toeplitz matrix T of shape (n_secure_bits, len(raw_key)) whose diagonals are drawn from the seed-keyed PRNG. Binary Toeplitz matrices form a Universal₂ hash family, so the leftover-hash lemma bounds the adversary's information on the output T @ raw_key mod 2. The output length is the asymptotic BB84 secret fraction 1 - 2*h2(QBER) of the input length (Shor & Preskill, PRL 85 441); finite-key corrections are out of scope for this simulation-only module.

Parameters:

Name	Type	Description	Default
`raw_key`	`NDArray[uint8]`	Sifted key bits ({0, 1}, dtype uint8).	required
`qber`	`float`	Estimated quantum bit error rate.	required
`seed`	`int`	PRNG seed selecting the Toeplitz family member. In a real deployment this must be fresh public randomness agreed after the raw key exists; it is a required parameter so no entropy is silently fabricated.	required

Returns¶

Extracted key bits of length ``n_secure_bits`` — empty above the
QBER security threshold or when the secret fraction rounds to zero.

`amplitude_damping_single(rho_2x2, gamma)` ¶

Single-qubit amplitude damping: |1⟩ → |0⟩ with probability gamma.

Kraus operators: K0 = [[1,0],[0,sqrt(1-gamma)]], K1 = [[0,sqrt(gamma)],[0,0]].

`depolarizing_channel(rho, p)` ¶

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

Parameters:

Name	Type	Description	Default
`rho`	`NDArray[complex128]`	Density matrix (d×d).	required
`p`	`float`	Depolarizing probability in [0, 1].	required

`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.

`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.

`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.

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

Full security analysis: key rates vs noise for each qubit pair.

Returns dict with

pair_rates: dict mapping (i,j) to list of (p_depol, key_rate) critical_noise: dict mapping (i,j) to max tolerable p_depol aggregate_rate: total key rate summed over all pairs at each noise level

`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.

`challenge_response_verify(K, challenge, response)` ¶

Verify a response against the HMAC for a topology challenge.

Parameters¶

K : NDArray[np.float64] Secret coupling matrix used as the HMAC key material. challenge : bytes Verifier-issued challenge bytes. response : bytes Claimed SHA-256 HMAC response.

Returns¶

bool True when the response matches the expected HMAC.

`fingerprint_noise_tolerance(K, n_trials=100, sigma=0.01)` ¶

Estimate fingerprint stability under small perturbations to K.

Adds Gaussian noise N(0, sigma²) to K, recomputes fingerprint, measures drift. Returns mean and max drift across trials.

`normalized_laplacian_fingerprint(K)` ¶

Fingerprint from the normalized Laplacian L_sym = I - D^{-1/2} K D^{-1/2}.

More robust to degree heterogeneity than the combinatorial Laplacian. Eigenvalues lie in [0, 2] for connected graphs.

`row_hash_fingerprint(K)` ¶

Per-row SHA-256 hashes of K_nm.

Enables selective verification: prove knowledge of specific coupling rows without revealing the full matrix. Useful for hierarchical authentication where different parties control different SCPN layers.

`spectral_fingerprint(K)` ¶

Compute public spectral fingerprint of coupling matrix.

Returns dict with

fiedler: Second-smallest eigenvalue of graph Laplacian (algebraic connectivity). gap_ratio: lambda_1 / lambda_2 (spectral gap quality). spectral_entropy: Shannon entropy of normalized eigenvalue distribution. n_components: Number of connected components (eigenvalues ≈ 0).

`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.

`topology_distance(fp1, fp2)` ¶

L2 distance between two spectral fingerprints.

Useful for detecting calibration drift or K_nm tampering.

`verify_commitment(K, nonce, commitment)` ¶

Verify that K_nm matches a previously issued commitment.

`verify_fingerprint(K, fingerprint, tol=1e-06)` ¶

Check K against a claimed spectral fingerprint.

`verify_row_hash(K, row_idx, expected_hash)` ¶

Verify a single row of K_nm against its hash.

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 and return one plugin.

`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: str, Enum

Admitted input provenance for an honesty kit.

`ApplicationHonestyAuditReport` `dataclass` ¶

Deterministic aggregate of honesty kits and dataset privacy checks.

Parameters¶

kits Validated built-in honesty-kit records. dataset_privacy Catalogue privacy audit rows. Each row has already loaded and validated the corresponding packaged QPUDataArtifact.

`passed` `property` ¶

Return whether every built-in kit and dataset privacy row is valid.

`__post_init__()` ¶

Reject empty, duplicate, or incomplete aggregate reports.

`content_digest()` ¶

Return a SHA-256 digest of the canonical report payload.

`as_dict()` ¶

Return the canonical JSON evidence payload including its digest.

`ApplicationSupportStatus` ¶

Bases: str, Enum

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.

`DomainApplicationHonestyKit` `dataclass` ¶

Immutable claim boundary for one domain-facing application family.

Parameters¶

kit_id Stable machine identifier for the kit. domain_tag Non-promotional domain label used in reports and user interfaces. title Human-readable kit name. support_status Whether the route is a bounded research benchmark or simulation-only. data_origin Provenance class admitted by this kit. synthetic_only True when measured or curated domain data must not enter the route. dataset_ids Packaged public catalogue identifiers governed by the kit. An empty tuple means that the route generates its inputs in code. source_modules Import paths implementing the bounded route. allowed_uses Positive, narrowly worded descriptions of supported software use. caveats Scientific and operational limitations that callers must preserve. claims_forbidden Explicit claims that this kit never authorises. forecasting_tags BL-37 simulation-only tags that may be cross-referenced. These tags do not convert a synthetic forecast into domain evidence.

Notes¶

Construction validates the internal policy relationships. In particular, a synthetic-only kit cannot declare curated input data or packaged dataset identifiers, and every kit must retain at least one forbidden claim.

`publication_safe` `property` ¶

Return False because a kit is not domain-publication evidence.

`__post_init__()` ¶

Validate the fail-closed relationships between policy fields.

`as_dict()` ¶

Return a JSON-ready representation with explicit non-claim fields.

`ITERBenchmarkResult` `dataclass` ¶

ITER MHD vs SCPN structural-comparison result.

`topology_similarity_proxy` `property` ¶

Spearman MHD-coupling-vs-K_nm proxy, not a plasma model reproduction.

`JosephsonBenchmarkResult` `dataclass` ¶

Josephson junction array vs SCPN structural-comparison result.

`topology_similarity_proxy` `property` ¶

Spearman JJA-coupling-vs-K_nm proxy, not a device model reproduction.

`JosephsonKnmCandidate` `dataclass` ¶

One Josephson topology candidate for measured-magnitude follow-up.

`to_dict()` ¶

Return JSON-compatible candidate data.

`JosephsonMagnitudeGate` `dataclass` ¶

One fail-closed gate required before a Josephson magnitude claim.

`to_dict()` ¶

Return JSON-compatible gate data.

`JosephsonMagnitudeStudyDesign` `dataclass` ¶

Complete Josephson K_nm magnitude-study design manifest.

`to_dict()` ¶

Return JSON-compatible design data.

`PowerGridBenchmarkResult` `dataclass` ¶

Power grid vs SCPN structural-comparison result.

`topology_similarity_proxy` `property` ¶

Spearman grid-coupling-vs-K_nm proxy, not a grid-dynamics reproduction.

`ClassicalESNReadoutResult` `dataclass` ¶

Classical echo-state readout fitted on a fixed reservoir.

`QRCBaselineComparison` `dataclass` ¶

Matched-feature comparison between QRC and a classical ESN readout.

`QRCHoldoutComparison` `dataclass` ¶

Disjoint-train/validation QRC and matched-feature ESN comparison.

`QuantumEVSResult` `dataclass` ¶

Quantum-enhanced EVS feature vector.

`QuantumKernelResult` `dataclass` ¶

Quantum kernel computation result.

`ReservoirResult` `dataclass` ¶

Exact-statevector quantum-reservoir feature result.

`ReservoirLinearObjective` `dataclass` ¶

Weighted Pauli-feature objective evaluated by the exact QRC path.

`__post_init__()` ¶

Validate coupling, objective terms, and simulator parameters.

`evaluate(parameters)` ¶

Evaluate the weighted objective through exact statevector features.

`call(parameters)` ¶

Evaluate the exact local objective.

`ReservoirTaskKind` ¶

Bases: str, Enum

Synthetic task families admitted by the BL-45 certificate suite.

`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 BL-63 honesty kits in stable registry 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:

Name	Type	Description	Default
`features`	`NDArray[float64]`	classical EVS feature vector (any length)	required
`n_osc`	`int`	number of quantum oscillators	`8`
`dt`	`float`	evolution time	`0.1`
`trotter_reps`	`int`	Trotter repetitions	`3`

`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.

`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 BL-63 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: str, Enum

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 and return one plugin.

`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.

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.

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.

Return a JSON-ready scenario mapping.

`L16DirectorPolicyError` ¶

Bases: RuntimeError

Raised when BL-67 policy refuses bounded L16 evaluation.

`L16Result` `dataclass` ¶

Legacy L16 indicators and heuristic action label.

`validate_l16_evidence(payload)` ¶

Return fail-closed findings for one BL-85 evidence payload.

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

Validate and atomically write real or independently supplied BL-85 evidence.

`frozen_l16_scenarios()` ¶

Return the three ordered small-system BL-85 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 BL-33 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 BL-67 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 BL-85 product for policy gating and claim boundaries.

Auto-Generated API Reference¶

Stable Facades¶

scpn_quantum_control.kuramoto_core ¶

KuramotoProblem dataclass ¶

n_oscillators property ¶

K property ¶

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 ¶

n_oscillators property ¶

is_synthetic property ¶

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) ¶

Parameters¶

Returns¶

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 ¶

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) ¶

Phase¶

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) ¶

energy_expectation(sv) ¶

scpn_quantum_control.phase.kuramoto_variants ¶

`scpn_quantum_control.kuramoto_core` ¶

`KuramotoProblem` `dataclass` ¶

`n_oscillators` `property` ¶

`K` `property` ¶

`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` ¶

`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` ¶

`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)` ¶

`energy_expectation(sv)` ¶

`scpn_quantum_control.phase.kuramoto_variants` ¶

`KuramotoVariant` ¶

`KuramotoVariantResult` `dataclass` ¶

`final_r` `property` ¶

`peak_r` `property` ¶

`to_metadata()` ¶

`HigherOrderKuramotoSpec` `dataclass` ¶

`MonitoredKuramotoSpec` `dataclass` ¶

`PTSymmetricKuramotoSpec` `dataclass` ¶

`build_triadic_ring_terms(n_oscillators, weight)` ¶

`simulate_higher_order_kuramoto(spec, *, dt, n_steps, prefer_rust=True)` ¶