Skip to content

analysis_api.md

Latest commit

 

History

History
885 lines (673 loc) · 33.9 KB

analysis_api.md

File metadata and controls

885 lines (673 loc) · 33.9 KB
Raw

Analysis API Reference

Advanced references for the analysis stack. The governed research-lane registry currently classifies 74 ordinary analysis/ and gauge/ modules by maturity, differentiable relevance, and claim status.

This is an advanced module reference. Use Stable Facades API and Kuramoto Core Facade for first-path workflows, then drop into this page when a specific analysis probe or low-level diagnostic is needed.

Experimental QSL, Hamiltonian-learning, Koopman, minimum-QMI, magic, and SFF routes are governed by the Theory-Hook Promotion Matrix and its typed API. Importability does not grant control, differentiability, criticality, hardware, consciousness, or publication claims.

RL-adjacent witness discovery and the unimplemented pulse shell are governed by RL Research Governance and its typed API. Research execution is disabled by default and requires preregistration, fixed seeds, and explicit budgets.

The broader module inventory is enforced by assert_research_lane_inventory(). Consult the Research-lane Registry API before treating an importable analysis helper as a supported integration surface.

Synchronization Detection

sync_order_parameter — Z-Basis Synchronisation Proxy

SyncOrderParameter consumes computational-basis counts and returns the absolute mean Z-basis spin per shot. The compatibility key sync_order is preserved for existing result artefacts, but it is an alias of sync_order_z_magnetisation. The callable also emits is_xy_kuramoto_order_parameter = 0.0 because a counts-only Z-basis record does not measure the continuous Kuramoto $R = |(1/N)\sum_j(\langle X_j\rangle+i\langle Y_j\rangle)|$.

from scpn_quantum_control.analysis.sync_order_parameter import SyncOrderParameter

observable = SyncOrderParameter()
result = observable({"000": 75, "111": 25})

assert result["sync_order"] == result["sync_order_z_magnetisation"]
assert result["is_xy_kuramoto_order_parameter"] == 0.0

Use analysis.sync_witness for X/Y-count witnesses and phase statevector helpers for true Kuramoto-R calculations.

thermodynamic_witness — Calibrated Work Samples

ThermodynamicWitness summarizes explicitly supplied work values from a calibrated protocol. It rejects counts-only calls and does not infer work from bitstrings; callers must provide either work_samples_joule or work_joule. All work, free-energy, and inverse-temperature inputs are validated at runtime with explicit exceptions, so the fail-closed contract is unchanged under optimized Python bytecode.

from scpn_quantum_control.analysis.thermodynamic_witness import ThermodynamicWitness

witness = ThermodynamicWitness()
result = witness(
    counts={"0": 10, "1": 6},
    work_samples_joule=[1.0e-21, 1.2e-21, 0.8e-21],
    delta_free_energy_joule=0.9e-21,
    beta_per_joule=2.5e20,
)

assert result["mean_work_joule"] > 0.0
assert "jarzynski_delta_free_energy_joule" in result
Input Requirement
work_samples_joule Non-empty finite iterable of calibrated work samples
work_joule Finite scalar work value when no sample iterable is supplied
delta_free_energy_joule Optional finite free-energy difference
beta_per_joule Optional finite positive inverse temperature

sync_witness — Synchronization Witness Operators

Three Hermitian witness constructions that certify quantum synchronization from hardware measurement counts. No state tomography required.

from scpn_quantum_control.analysis.sync_witness import (
    WitnessResult,
    correlation_witness_from_counts,
    fiedler_witness_from_counts,
    fiedler_witness_from_correlator,
    topological_witness_from_correlator,
    evaluate_all_witnesses,
    calibrate_thresholds,
)
Function Input Output Description
correlation_witness_from_counts X/Y counts, n_qubits, threshold WitnessResult Mean pairwise XY correlator vs threshold
fiedler_witness_from_counts X/Y counts, n_qubits, threshold WitnessResult Algebraic connectivity of correlation Laplacian
fiedler_witness_from_correlator corr_matrix, threshold WitnessResult From pre-computed correlation matrix
topological_witness_from_correlator corr_matrix, threshold, max_dim WitnessResult Persistent H₁ via Vietoris-Rips (requires ripser)
evaluate_all_witnesses X/Y counts, n_qubits, thresholds dict[str, WitnessResult] All three witnesses from one measurement set
calibrate_thresholds K, omega, K_base_range, n_samples dict[str, float] Classical Kuramoto calibration of thresholds

WitnessResult fields: witness_name, expectation_value (negative = synchronised), threshold, is_synchronized, raw_observable, n_qubits.

Full theory and examples: Research Gems — Gem 1.

witness_discovery — Automated Witness Search

Bayesian plus bandit search over Kuramoto control candidates, scored by the existing correlation and Fiedler synchronisation witnesses.

from scpn_quantum_control.analysis.witness_discovery import (
    WitnessCandidate,
    WitnessDiscoverySpec,
    discover_kuramoto_witnesses,
    score_witness_candidates,
)
Function Description
discover_kuramoto_witnesses(K_nm, omega, theta0, spec) Run deterministic initial design, RBF Bayesian UCB, and bandit local exploration.
score_witness_candidates(K_nm, omega, candidates) Score fixed candidates through the same witness objective.
WitnessDiscoveryResult.ranked(limit) Return candidates sorted by descending witness score.

The Rust path kuramoto_witness_candidate_features evaluates final order parameter, mean pairwise correlation, and final phases for candidate batches. The Python scorer then evaluates the existing witness objects, so the discovery loop stays connected to the hardware-measurable witness definitions.

RLDiscoveryAgent is a compatibility wrapper around the same production search. It accepts only the wired objective: correlation and Fiedler observables with reward_function="witness_score", positive n_episodes, and no external runner. Unsupported compatibility parameters fail at construction instead of being silently ignored.

sync_entanglement_witness — R as Entanglement Witness

The Kuramoto order parameter $R$ reinterpreted as an entanglement witness. For separable states, $R \leq R_{\mathrm{sep}}$. Exceeding the separable bound certifies entanglement.

from scpn_quantum_control.analysis.sync_entanglement_witness import (
    EntanglementWitnessResult,
    R_entanglement_scan,
    R_from_statevector,
    R_separable_bound,
    R_separable_bound_at_energy,
    detect_entanglement_from_R,
)
Function Description
R_from_statevector(psi, n_qubits) Compute $R = |(1/N)\sum_i(\langle X_i\rangle + i\langle Y_i\rangle)|$
R_separable_bound(n_qubits) Maximum $R$ achievable by any separable state (= 1.0)
R_separable_bound_at_energy(K, omega, target_energy, n_samples=1000, seed=42, *, max_dense_gib=None) Dense exact max $R$ over sampled product states at fixed energy
detect_entanglement_from_R(K, omega, n_samples=2000, seed=42, *, max_dense_gib=None) Ground-state witness evaluation with dense exact small-system guard
R_entanglement_scan(K, omega, K_base_range=None, n_K_values=15, n_samples=500, seed=42, *, max_dense_gib=None) Coupling scan of $R_\mathrm{ground}$ and the energy-constrained separable bound

The returned entanglement_depth is a certified lower bound from this witness: 1 when the separable bound is not violated and 2 when entanglement is certified. The R witness alone does not certify stronger multipartite depth; that requires separate k-producibility bounds or a dedicated depth witness.

critical_concordance — Multi-Probe $K_c$ Agreement

Runs a finite-size dense exact coupling scan and compares where the order parameter, QFI, spectral gap, and concurrence-graph probes localise the same coupling region.

from scpn_quantum_control.analysis.critical_concordance import (
    critical_concordance,
    ConcordanceResult,
)

critical_concordance(omega, K_topology, k_range=None, concurrence_threshold=1e-4, *, max_dense_gib=None) returns ConcordanceResult with fields: k_values, R_values, qfi_values, gap_values, fiedler_values, n_entangled_pairs, k_c_from_gap, k_c_from_qfi, k_c_from_fiedler, k_c_from_R_deriv, and concordance_spread.

Phase Transition Probes

qfi_criticality — Quantum Fisher Information at $K_c$

QFI diverges where the spectral gap closes — the synchronization transition is a metrological sweet spot.

from scpn_quantum_control.analysis.qfi_criticality import (
    QFICriticalityResult,
    qfi_single_coupling,
    qfi_vs_coupling,
)

qfi_single_coupling(K, omega, *, max_dense_gib=None) returns the maximum coupling-parameter QFI diagonal, spectral gap, and QFI trace for one dense exact Kuramoto-XY Hamiltonian.

qfi_vs_coupling(omega, K_topology, k_range=None, *, max_dense_gib=None) returns QFICriticalityResult with k_values, max_qfi, spectral_gap, total_qfi, peak_k, and peak_qfi. The scan is dense exact and small-system only; pass max_dense_gib to fail closed before Hamiltonian or derivative-operator allocation.

sensing — S11 QFI-Criticality Readiness

Combines the QFI criticality scan with a classical sync-order Fisher proxy and a pair-level Cramer-Rao operating-point recommendation. This is a no-submit readiness surface, not hardware evidence.

from scpn_quantum_control.analysis.sensing import (
    CriticalitySensingTail,
    QuantumSensingReadinessConfig,
    metrological_gain_vs_k,
    optimal_sensing_k,
    qfi_criticality_sensing_tail,
)

metrological_gain_vs_k(omega, topology, k_grid, *, config=None) returns a SensingGainScan over the finite coupling grid. optimal_sensing_k(...) returns the row with the largest QFI/classical-Fisher ratio.

qfi_criticality_sensing_tail(omega, topology, k_grid, *, measurements=10000, geometric_epsilon=0.005, run_geometric_crosscheck=True, config=None) selects the QFI peak, recomputes the full QFI matrix at that coupling, identifies the most informative coupling-pair generator, reports the Cramer-Rao variance and standard deviation bounds for the measurement budget, and records whether the spectral route agrees with the geometric QGT cross-check.

entanglement_percolation — Finite-Size Entanglement Percolation

Compares the concurrence-graph percolation point with a selected finite-size order-parameter threshold. This is a dense exact diagnostic, not a standalone thermodynamic-limit proof.

from scpn_quantum_control.analysis.entanglement_percolation import (
    percolation_scan,
    PercolationScanResult,
)

percolation_scan(omega, K_topology, k_range=None, concurrence_threshold=1e-4, R_threshold=0.5, *, max_dense_gib=None) → PercolationScanResult with: k_values, fiedler_values, max_concurrence, mean_concurrence, n_entangled_pairs, R_values, k_percolation, and k_sync.

berry_phase — Berry Connection and Fidelity Susceptibility

Finite-size dense exact scan of ground-state overlaps. On the one-dimensional open coupling path, the accumulated Berry connection is gauge-dependent; the fidelity and fidelity susceptibility are the gauge-invariant diagnostics.

from scpn_quantum_control.analysis.berry_phase import (
    berry_phase_scan,
    BerryPhaseResult,
)

berry_phase_scan(omega, K_topology, k_range=None, *, max_dense_gib=None) → BerryPhaseResult with: k_values, berry_connection, berry_curvature, accumulated_phase, fidelity, fidelity_susceptibility, spectral_gap, and curvature_peak_k.

finite_size_scaling — Finite-Size Gap-Minimum Scaling

Fits finite-size gap-minimum estimates to a BKT-motivated $K_c(N) = K_c(\infty) + a/(\ln N)^2$ ansatz and a power-law comparison model.

from scpn_quantum_control.analysis.finite_size_scaling import (
    FSSFitDiagnostics,
    finite_size_scaling,
    FSSResult,
)

finite_size_scaling(system_sizes=None, k_range=None, *, max_dense_gib=None) → FSSResult with: system_sizes, k_c_values, gap_min_values, k_c_extrapolated_bkt, k_c_extrapolated_power, bkt_fit, power_fit, and claim_boundary. The optional FSSFitDiagnostics records expose the linearized ansatz name, extrapolated intercept, correction coefficient, pointwise residuals, residual norm, maximum absolute residual, design-matrix condition number, rank, point count, and the same non-promotional claim boundary. By default the scan uses system sizes [2, 3, 4, 5]. system_sizes must be unique integer qubit counts from 2 through the available frequency table; k_range must be one-dimensional, finite, strictly increasing, and at least two points. The scan is local dense exact finite-size evidence only, not hardware execution, isolated performance evidence, or a thermodynamic-limit proof.

adiabatic_preparation — Adiabatic State Preparation

Finite-size dense exact adiabatic path from a zero-coupling initial ground state to the target XY Hamiltonian. Computes instantaneous gap and fidelity along the selected schedule. The initial state and gap are evaluated at exactly the reported K_schedule[0]=0, without an implicit weak-coupling offset. In a degenerate ground space the dense eigensolver selects one ground vector; the reported fidelity is eigenvector overlap, not overlap with the entire ground-space projector. Historical results using the previous implicit K=0.01 initialization are not equivalent and must be recomputed if zero-coupling initialization is required.

from scpn_quantum_control.phase.adiabatic_preparation import (
    adiabatic_ramp,
    AdiabaticResult,
)

adiabatic_ramp(omega, K_topology, K_target, T_total=10.0, n_steps=50, *, max_dense_gib=None) → AdiabaticResult with: times, K_schedule, fidelity, gap, final_fidelity, min_gap, min_gap_K. The array fields are explicit float64 contracts; the dense evolution keeps its internal statevector as complex128. All numeric inputs must already be real numeric scalars or arrays; string, boolean, object, and complex values are rejected before dense Hamiltonian construction or fidelity/gap diagnostics.

Entanglement and Correlations

entanglement_entropy — Half-Chain Entropy and Schmidt Gap

Entanglement entropy and Schmidt gap across the synchronization transition. At BKT criticality, entropy follows CFT scaling $S \sim (c/3)\ln L$ with $c = 1$.

from scpn_quantum_control.analysis.entanglement_entropy import (
    entanglement_vs_coupling,
    EntanglementScanResult,
)

entanglement_vs_coupling(omega, K_topology, k_range=None) → EntanglementScanResult with: k_values, entropy, schmidt_gap, spectral_gap, entropy_peak_K, schmidt_gap_min_K.

Rust acceleration: Hamiltonian construction via build_xy_hamiltonian_dense (Qiskit-free).

entanglement_spectrum — Full Entanglement Spectrum

Computes the full entanglement spectrum (all Schmidt coefficients) and estimates the CFT central charge from the entropy scaling.

from scpn_quantum_control.analysis.entanglement_spectrum import (
    entanglement_spectrum,
    cft_central_charge,
)

pairing_correlator — Richardson Pairing $\langle S^+_i S^-_j\rangle$

Detects Richardson pairing (the superconducting analogue of synchronization) via spin-raising/lowering correlators. Strong pairing = synchronised phase.

from scpn_quantum_control.analysis.pairing_correlator import (
    pairing_map,
    pairing_vs_anisotropy,
    PairingResult,
)

pairing_map(omega, K_topology, K_base, delta=0.0, *, max_dense_gib=None) → PairingResult with the full pairing matrix, maximum/mean pairing, topology correlation, qubit count, anisotropy, and base coupling.

pairing_vs_anisotropy(omega, K_topology, K_base, delta_range=None, *, max_dense_gib=None) forwards the dense budget to every XXZ ground-state solve in the scan.

Quantum Chaos and Dynamics

otoc — Out-of-Time-Order Correlator

Core OTOC computation: $F(t) = \langle W^\dagger(t) V^\dagger W(t) V\rangle$.

from scpn_quantum_control.analysis.otoc import (
    compute_otoc,
    OTOCResult,
)

compute_otoc(K, omega, times, w_qubit=0, v_qubit=None) → OTOCResult with: times, otoc_values, lyapunov_estimate, scrambling_time.

Rust acceleration: When scpn_quantum_engine is installed, OTOC uses eigendecomposition

  • rayon-parallel time loop ($O(d^2)$ per time point vs $O(d^3)$ scipy.expm). Hamiltonian construction uses build_xy_hamiltonian_dense (bitwise, Qiskit-free). 10-50× faster for n ≤ 8.

otoc_sync_probe — OTOC Scan Across $K_c$

Scans OTOC diagnostics vs coupling strength to detect the synchronization transition via chaos measures.

from scpn_quantum_control.analysis.otoc_sync_probe import (
    otoc_sync_scan,
    OTOCSyncScanResult,
)

otoc_sync_scan(K, omega, K_base_range=None, n_K_values=15, t_max=2.0) → OTOCSyncScanResult with: K_base_values, lyapunov_values, scrambling_times, otoc_final_values, R_classical, peak_scrambling_K.

spectral_form_factor — SFF and Level Statistics

Exact finite-system spectral-form-factor and adjacent-gap-ratio diagnostics. Interpretation requires a specified symmetry sector, ensemble, energy window, null distribution, and finite-size protocol; these values do not by themselves certify quantum chaos or a Poisson-to-RMT transition.

from scpn_quantum_control.analysis.spectral_form_factor import (
    compute_sff,
    sff_vs_coupling,
    SFFResult,
    SFFScanResult,
)
Function Description
compute_sff(K, omega, t_max=20.0, n_times=200, *, level_spacing_basis="magnetisation", magnetisation=None, parity=None, max_dense_gib=None) Full-spectrum normalized SFF plus selected-sector and full-spectrum gap ratios
sff_vs_coupling(omega, K_topology, k_range=None, ..., max_dense_gib=None) Finite coupling-grid diagnostics; chaos_onset_K is a heuristic threshold crossing only

The default spacing ratio is resolved in a U(1) magnetisation sector. The SFF itself still uses the full spectrum, and both selected-sector and full-spectrum ratios remain explicit in SFFResult.

loschmidt_echo — Loschmidt Echo and DQPT

Dynamical Quantum Phase Transitions detected via non-analyticities in the Loschmidt return rate $\lambda(t) = -\ln\mathcal{L}(t)/N$.

from scpn_quantum_control.analysis.loschmidt_echo import (
    loschmidt_echo,
    LoschmidtResult,
)

loschmidt_echo(K, omega, K_i, K_f, times) → LoschmidtResult with: times, echo_values, return_rate, dqpt_times (cusp locations).

Rust acceleration: Hamiltonian construction via build_xy_hamiltonian_dense (Qiskit-free).

krylov_complexity — Operator Spreading Complexity

Lanczos coefficients $b_n$ and Krylov complexity $C_K(t) = \sum_n n |\phi_n(t)|^2$. Maximum at $K_c$.

from scpn_quantum_control.analysis.krylov_complexity import (
    krylov_complexity,
    krylov_vs_coupling,
    KrylovResult,
)

krylov_complexity(H, O_init, t_max=10.0, n_times=100, max_lanczos=50) → KrylovResult with Lanczos coefficients, times, complexity values, peak complexity, and realised Krylov dimension.

krylov_vs_coupling(omega, K_topology, k_range=None, t_max=10.0, n_times=50, *, max_dense_gib=None) builds the dense Hamiltonian/probe workspace under the caller's budget before scanning peak complexity against coupling.

Rust acceleration: Lanczos b-coefficients computed via lanczos_b_coefficients (complex matrix commutator loop in Rust, 5-10× for dim ≤ 256). Hamiltonian via build_xy_hamiltonian_dense.

Quantum Information Measures

qfi — Quantum Fisher Information Matrix

Full QFI matrix for parameter estimation precision bounds.

from scpn_quantum_control.analysis.qfi import (
    quantum_fisher_information,
    spectral_gap,
    precision_bounds,
)
Function Description
quantum_fisher_information(state, generators) QFI matrix $F_{ij}$
spectral_gap(H) $E_1 - E_0$
precision_bounds(qfi_matrix) Cramér-Rao lower bounds $\delta\theta_i \geq 1/\sqrt{F_{ii}}$

QuantumFisherInformation is the observable-wrapper adapter for production metrology calls. When coupling_matrix and natural_frequencies are supplied it routes to the spectral QFI engine and validates that the coupling matrix is square, symmetric, finite-valued, and dimension-compatible with the frequency vector. Optional coupling_pairs must be distinct in-range integer index pairs, and n_measurements must be a positive integer because it rescales the Cramér-Rao precision bound. Counts-derived sync/DLA estimates are exposed only through the explicit allow_proxy_estimate=True diagnostic path and are labelled as proxy values, never as production QFI.

magic_nonstabilizerness — Stabilizer Rényi Entropy

Exact small-system stabilizer Rényi-2 resource diagnostic $M_2 = -\log_2(\sum_P \langle P\rangle^4 / 2^N)$. The implementation enumerates all $4^N$ Pauli strings. A finite-grid maximum is not a critical-point estimator, a fault-tolerant resource-cost certificate, or evidence of classical hardness or quantum advantage.

from scpn_quantum_control.analysis.magic_nonstabilizerness import (
    magic_at_coupling,
    magic_vs_coupling,
    MagicResult,
)

magic_at_coupling(omega, K_topology, K_base, *, max_dense_gib=None) computes the dense exact ground state and Stabilizer Renyi entropy at one coupling.

magic_vs_coupling(omega, K_topology, k_range=None, *, max_dense_gib=None) forwards the dense eigensolver budget to every coupling point and returns a MagicScanResult with the scanned values and peak location.

quantum_phi — Minimum Bipartite Quantum Mutual Information

compute_quantum_phi(K, omega) is a compatibility-named routine that computes quantum mutual information over all non-trivial bipartitions of the exact Kuramoto-XY ground state. It reports the minimum and maximum QMI plus the minimum-information partition. It does not compute Integrated Information Theory Φ: there is no causal model, intervention repertoire, cause-effect structure, or IIT composition/exclusion calculation.

from scpn_quantum_control.analysis.quantum_phi import (
    compute_quantum_phi,
    PhiResult,
)

IntegratedInformationPhi is the dashboard-facing wrapper. When supplied with coupling_matrix and natural_frequencies, it fails closed unless allow_mutual_information_proxy=True is explicit. The diagnostic returns minimum_bipartite_mutual_information, sets phi_available = 0.0 and is_integrated_information = 0.0, and never returns a phi key. Counts-only entropy similarly requires allow_entropy_proxy=True.

This route is tier D research-only and authorises no consciousness, sentience, cognition, or clinical interpretation. See the Theory-Hook Promotion Matrix.

shadow_tomography — Classical Shadow Estimation

$O(\log M)$ shots for $M$ observables via random Clifford measurements.

from scpn_quantum_control.analysis.shadow_tomography import (
    random_clifford_shadow,
    estimate_observable,
    ShadowResult,
)

quantum_speed_limit — Bounded State-Evolution Speed Limits

compute_qsl(...) evaluates a Mandelstam–Tamm target-overlap bound and a legacy Margolus–Levitin orthogonalization-time reference from the frequency-encoded product state and records the first simulated crossing of a visibility-aware local-phase-order threshold. The threshold time is a finite closed-system diagnostic, not a measured synchronisation time, critical exponent, or BKT certificate.

When the simulated target is not orthogonal to the initial state, tau_ML is not an arbitrary-fidelity lower bound for that target. The compatibility field remains explicitly labelled until an extended Margolus–Levitin contract is implemented and tested.

from scpn_quantum_control.analysis.quantum_speed_limit import (
    qsl_vs_coupling,
    QSLResult,
)

qsl_vs_coupling(K, omega, K_base_range=None, n_K_values=15, t_target=5.0, R_threshold=0.5, *, max_dense_gib=None) returns finite-grid K_base, tau_MT, tau_ML, tau_actual, delta_E, and R_final lists. The scan does not fit a critical point or distinguish BKT from power-law scaling.

Topological Analysis

quantum_persistent_homology — Full PH Pipeline

Hardware counts → correlation matrix → distance → Vietoris-Rips → persistence diagram → $p_{H_1}$.

from scpn_quantum_control.analysis.quantum_persistent_homology import (
    counts_to_persistence,
    coupling_scan_persistence,
    PersistenceResult,
    PersistenceScanResult,
)
Function Description
counts_to_persistence(x_counts, y_counts, n_qubits, max_dim=1) Single-point PH from hardware counts
coupling_scan_persistence(K, omega, K_range, ...) $p_{H_1}$ vs coupling strength

persistent_homology — Classical PH Utilities

Distance matrix construction, Rips filtration, Betti number extraction.

h1_persistence — Vortex Density at BKT

$H_1$ persistence as a function of coupling — the topological order parameter for the BKT transition.

vortex_binding — Kosterlitz RG Flow

Vortex-antivortex binding energy and Kosterlitz renormalization group flow equations.

Algebraic Structure

dynamical_lie_algebra — DLA Computation

Computes the Dynamical Lie Algebra and its dimension for the Kuramoto-XY Hamiltonian. Result: $\dim(\mathrm{DLA}) = 2^{2N-1} - 2$ for non-degenerate frequencies.

from scpn_quantum_control.analysis.dynamical_lie_algebra import (
    compute_dla,
    DLAResult,
)

compute_dla(K, omega) → DLAResult with: generators (list of Pauli strings), dimension, n_qubits, predicted_dim ($2^{2N-1} - 2$).

dla_parity_theorem — Z₂ Parity Proof

Formal verification that Z₂ parity is the only symmetry of the heterogeneous XY Hamiltonian.

from scpn_quantum_control.analysis.dla_parity_theorem import (
    verify_z2_parity,
    ParityTheoremResult,
)

BKT Phase Analysis

bkt_analysis — Core BKT Diagnostics

Fiedler eigenvalue, $T_{\mathrm{BKT}}$, $p_{H_1}$ prediction from coupling structure.

from scpn_quantum_control.analysis.bkt_analysis import (
    bkt_scan,
    BKTResult,
)

bkt_universals — Candidate Expressions for the Open $p_{H_1}$ Threshold

Systematic negative-control search over candidate expressions for the open empirical/theoretical $p_{H_1}=0.72$ threshold. The square-lattice expression is the closest numerical fit, but the K_nm graph check keeps the threshold open.

p_h1_derivation — $A_{HP} \times \sqrt{2/\pi}$ Negative Control

Audits the square-lattice coincidence and records why it does not derive the K_nm graph threshold. The current status remains open rather than promoted.

p_h1_open_guard — Public Open-Claim Guard

Scans outward-facing Markdown for wording that would turn the open empirical/theoretical $p_{H_1}=0.72$ parameter into a closed derivation, universal constant, or measured TCBO reproduction. The guard is runnable through scripts/check_p_h1_open_claim_guard.py.

phase_diagram — $K_c$ vs $T_{\mathrm{eff}}$ Boundary

Full synchronization phase diagram in the coupling-temperature plane.

xxz_phase_diagram — $K_c$ vs Anisotropy $\Delta$

Finite-size gap-minimum diagnostics in the $(K, \Delta)$ plane from XY-like ($\Delta=0$) to Heisenberg-like ($\Delta=1$) Hamiltonians.

from scpn_quantum_control.analysis.xxz_phase_diagram import (
    anisotropy_phase_diagram,
    PhaseDiagramResult,
)

anisotropy_phase_diagram(omega, K_topology, delta_range=None, k_range=None, *, max_dense_gib=None) → PhaseDiagramResult with: delta_values, k_c_values, gap_min_values, and scans.

Open Quantum Systems

quantum_mpemba — Quantum Mpemba Effect

Ordered states thermalize faster under amplitude damping — the quantum Mpemba effect in synchronization dynamics.

from scpn_quantum_control.analysis.quantum_mpemba import (
    mpemba_experiment,
    MpembaResult,
)

mpemba_experiment(omega, K, K_base=1.0, gamma=0.1, t_max=5.0, n_steps=50) → MpembaResult with: times, fidelity_ground, fidelity_plus (|+⟩^N), mpemba_detected (True if |+⟩ thermalizes faster).

lindblad_ness — Non-Equilibrium Steady State

Lindblad NESS under amplitude damping: the long-time limit that retains synchronization signatures.

from scpn_quantum_control.analysis.lindblad_ness import (
    ness_vs_coupling,
    NESSResult,
)

ness_vs_coupling(K, omega, gamma=0.1, K_base_range=None, n_K=15) → NESSResult with: K_values, R_ness (order parameter of NESS), purity_ness, entropy_ness.

Reservoir Computing

qrc_phase_detector — Exact QRC-Style Feature Map

The Kuramoto-XY Hamiltonian supplies exact dense ground-state Pauli features for a ridge-regression classifier. This is a deterministic small-system feature-map reference, not a scalable reservoir simulator.

from scpn_quantum_control.analysis.qrc_phase_detector import (
    qrc_phase_detection,
    QRCPhaseResult,
)

qrc_phase_detection(omega, K_topology, k_train, k_test, k_threshold, alpha=0.1, max_weight=2, *, max_dense_gib=None) → QRCPhaseResult with: accuracy, n_train, n_test, n_features, weights, and k_boundary_predicted.

Classical Simulations

monte_carlo_xy — Classical XY Monte Carlo

Metropolis Monte Carlo for the classical XY model. Uses the Rust engine (scpn_quantum_engine) when available; falls back to pure Python.

from scpn_quantum_control.analysis.monte_carlo_xy import (
    mc_simulate,
    MCResult,
)

graph_topology_scan — Coupling Graph Analysis

Network topology metrics (clustering, betweenness, modularity) of the $K_{nm}$ matrix.

koopman — Koopman Linearisation

Finite, reference-point-dependent Koopman-style closure over phase identities and pairwise sine/cosine observables. Higher-order terms are truncated, so the matrix and its spectrum are classical local-baseline diagnostics, not an exact finite invariant subspace or full nonlinear dynamics. The Hermitian projection i(L-L†)/2 discards the symmetric part of L; it does not establish dynamical equivalence, BQP-completeness, or quantum advantage.

build_koopman_generator_rust() now routes to the optional scpn_quantum_engine.koopman_generator kernel when that export is present and falls back to the validated NumPy generator otherwise. Set require_rust=True when a benchmark or release gate must prove that the native kernel, not the fallback, served the dense generator.

hamiltonian_learning — Recover $K_{nm}$ from Measurements

learn_hamiltonian(C_measured, omega, K_init=None, maxiter=100) performs a small dense fit of a symmetric non-negative coupling matrix to supplied exact ground-state XX+YY correlators. It uses COBYLA, not compressed sensing.

The input name preserves compatibility but does not establish measurement provenance. A low in-sample residual is not an identifiability, uncertainty, held-out, noise-robustness, or experimental-recovery certificate.

hamiltonian_self_consistency — Self-Consistency Loop

Round-trip verification: $K_{nm}$ → Hamiltonian → ground state → correlators → $K_{nm}^{\mathrm{eff}}$.

from scpn_quantum_control.analysis.hamiltonian_self_consistency import (
    self_consistency_check,
    correlator_shot_noise,
    SelfConsistencyResult,
)

enaqt — Environment-Assisted Quantum Transport

enaqt_scan(...) evolves a single excitation over the site Hamiltonian diag(omega) + K, with local dephasing, an irreversible target sink, and an optional competing loss channel. It maximises finite-horizon sink population, not a Kuramoto phase proxy. The result records explicit efficiency fields, the exact zero-dephasing endpoint, the largest-scanned-gamma endpoint, and a strict intermediate-optimum classification. Legacy *_r fields remain read-only aliases only.

The trace-preserving Lindblad generator is applied through scipy.sparse.linalg.expm_multiply; max_dense_gib gates the site-basis density workspace before Hamiltonian allocation. See ENAQT Optimal-Noise Scan for equations, evidence, primary citations, negative controls, and the no-setpoint boundary.

entanglement_enhanced_sync — Entangled Initial-State Coherence Study

simulate_sync_trajectory(K, omega, state_type, t_max=2.0, n_steps=20, *, max_dense_gib=None) evolves product, Bell-pair, GHZ, or W initial states under the dense exact Kuramoto-XY Hamiltonian. It records a visibility-aware local phase order and a separate pairwise transverse-exchange-coherence score. When local transverse visibility vanishes, phase_defined is false and the compatibility R value is zero; the historical false atan2(0, 0) -> R=1 mapping is removed.

compare_all_initial_states(K, omega, t_max=2.0, n_steps=20, *, max_dense_gib=None) uses one budgeted exact propagator for all pure states. compare_initial_states_with_dephased_controls(...) adds population-matched computational-basis-dephased controls and retains the separable product row as an attribution control. entanglement_advantage(...) is a compatibility name that now returns descriptive differences with a default no-advantage certificate; it does not report speedup or an entanglement-specific effect.

See Entangled initial-state coherence study for equations, committed evidence, primary-source scope, and limitations.