SPDX-License-Identifier: AGPL-3.0-or-later¶

Commercial license available¶

© Concepts 1996–2026 Miroslav Šotek. All rights reserved.¶

© Code 2020–2026 Miroslav Šotek. All rights reserved.¶

ORCID: 0009-0009-3560-0851¶

Contact: www.anulum.li | protoscience@anulum.li¶

scpn-quantum-control — Test Infrastructure Documentation¶

Test Infrastructure¶

Overview¶

scpn-quantum-control has a CI-gated test suite with 97%+ branch coverage. The active count is intentionally left to CI summaries and release notes because the suite changes frequently. The test suite verifies correctness, pipeline wiring, Rust acceleration parity, and performance benchmarks.

tests/
  conftest.py              # Shared fixtures: knm_Nq, coupling_variant, hypothesis strategies
  test_pipeline_wiring_performance.py  # 155 tests — every __all__ export verified functional
                                       # (now includes TestGUESSPipeline, TestDynQPipeline,
                                       # TestPulseShapingPipeline)
  test_rust_path_benchmarks.py         # 68 tests — all 37 Rust functions benchmarked
  test_symmetry_decay.py               # 20 multi-angle tests — GUESS (April 2026)
  test_qubit_mapper.py                 # 17 multi-angle tests — DynQ (April 2026)
  test_pulse_shaping.py                # 25 multi-angle tests — ICI + (α,β)-hypergeometric (April 2026)
  test_*.py                            # module-specific tests

Running Tests¶

# Full suite (skip slow 18-qubit tests)
pytest tests/ -v --tb=short -m "not slow"

# Single file
pytest tests/test_xy_kuramoto.py -v --tb=short -s

# With performance output
pytest tests/test_pipeline_wiring_performance.py -v -s

# Rust benchmarks
pytest tests/test_rust_path_benchmarks.py -v -s

# Coverage
pytest tests/ --cov=scpn_quantum_control --cov-report=html -m "not slow"

Test Categories¶

1. Pipeline Wiring Tests (`test_pipeline_wiring_performance.py`)¶

155 tests that verify every symbol in scpn_quantum_control.__all__ (104 symbols) is importable, callable, and produces valid output when wired into a data pipeline.

Each test follows the pattern: 1. Build inputs from canonical SCPN parameters (build_knm_paper27, OMEGA_N_16) 2. Call the function/class under test 3. Assert output has correct type, shape, and physical bounds 4. Print wall-time performance

class TestTopLevelExports:
    @pytest.mark.parametrize("name", sqc.__all__)
    def test_export_exists(self, name):
        obj = getattr(sqc, name, None)
        assert obj is not None, f"{name} is None — not wired"

15 subsystems tested end-to-end: - Bridge (Knm→H, Knm→Ansatz) - Phase Solvers (VQE, UPDE, Kuramoto) - Hardware (Runner, Noise Model) - Mitigation (ZNE, PEC) - QEC (ControlQEC, SurfaceCodeUPDE) - QSNN (Synapse, LIF, STDP) - Identity (Attractor, Fingerprint) - Crypto (Key Hierarchy, QKD) - Analysis (FSS, H1, OTOC, XXZ) - SSGF (Quantum Loop) - Orchestrator (Adapter Roundtrip) - Cutting (24-oscillator Partitioned Simulation) - Control (VQLS, QAOA-MPC, QPetriNet) - Benchmarks (Scaling) - Applications (Reservoir, Kernel, Disruption)

2. Rust Path Benchmarks (`test_rust_path_benchmarks.py`)¶

68 tests covering all 37 functions in scpn_quantum_engine (PyO3 + rayon).

Each Rust function is tested for: - Correctness: Output shape, dtype, physical bounds - Parity: Exact match with Python fallback (where applicable) - Performance: Wall-time measurement with time.perf_counter()

class TestBuildKnm:
    def test_parity_with_python_paper27(self):
        K_rust = np.array(eng.build_knm(16, 0.45, 0.3))
        K_py = build_knm_paper27(L=16)
        np.testing.assert_allclose(K_rust, K_py, atol=1e-12)

Measured speedups:

Function	Speedup
`build_knm`	4.7×
`kuramoto_euler`	33.1×
`pec_coefficients`	exact parity
`build_xy_hamiltonian_dense`	exact parity with Qiskit

3. Module-Specific Tests (217 files)¶

Each test file covers one source module with multi-angle tests:

Physical invariants — Hermiticity, unitarity, trace, bounds:

def test_hamiltonian_hermitian():
    H = knm_to_hamiltonian(K, omega)
    mat = H.to_matrix()
    np.testing.assert_allclose(mat, mat.conj().T, atol=1e-12)

Pipeline wiring — Data flows end-to-end, not decorative:

def test_pipeline_knm_to_spectrum():
    K = build_knm_paper27(L=4)
    H = knm_to_dense_matrix(K, omega)
    eigvals = np.linalg.eigvalsh(H)
    assert eigvals[0] < 0
    print(f"\n  PIPELINE Knm→H→spectrum (4q): {dt:.1f} ms")

Rust path parity — Python and Rust produce identical results:

def test_rust_dense_matrix_parity():
    H_py = knm_to_dense_matrix(K, omega)
    H_rust = np.array(eng.build_xy_hamiltonian_dense(K_flat, omega, n))
    np.testing.assert_allclose(H_rust, H_py, atol=1e-10)

Edge cases — Zero input, boundary values, degenerate systems:

def test_zero_coupling_decoupled():
    K = np.zeros((n, n))
    H = knm_to_dense_matrix(K, omega)
    eigvals = np.linalg.eigvalsh(H)
    np.testing.assert_allclose(eigvals[0], -np.sum(np.abs(omega)), atol=1e-10)

Performance benchmarks — Wall-time printed for regression tracking:

def test_pipeline_full_kuramoto_evolution():
    t0 = time.perf_counter()
    result = solver.run(t_max=0.3, dt=0.1, trotter_per_step=5)
    dt = (time.perf_counter() - t0) * 1000
    print(f"\n  PIPELINE Knm→KuramotoSolver→R(t) (4q): {dt:.1f} ms")

4. Property-Based Tests (Hypothesis)¶

Several files use hypothesis for randomised property testing:

@given(n=st.integers(min_value=2, max_value=6))
@settings(max_examples=10, deadline=30000)
def test_hamiltonian_hermitian(n: int) -> None:
    K = rng.uniform(0, 0.5, (n, n))
    K = (K + K.T) / 2
    H = knm_to_hamiltonian(K, omega)
    mat = H.to_matrix()
    assert np.allclose(mat, mat.conj().T, atol=1e-12)

Files using hypothesis: - test_knm_properties.py — Hermiticity, eigenvalues, ansatz params - test_qec_properties.py — Zero-error syndrome, correction shapes - test_crypto_properties.py — Key hierarchy determinism, HMAC roundtrip - test_new_module_properties.py — Cross-module property tests

Shared Fixtures (`conftest.py`)¶

# System sizes
SMALL_SIZES = [2, 3, 4]
MEDIUM_SIZES = [2, 3, 4, 6]
ALL_SIZES = [2, 3, 4, 6, 8]

# Coupling matrices
@pytest.fixture
def knm_4q():
    return build_knm_paper27(L=4), OMEGA_N_16[:4]

# Coupling variants
@pytest.fixture(params=["paper27", "ring", "zero", "identity"])
def coupling_variant_4q(request): ...

# Hardware runner
@pytest.fixture
def sim_runner(tmp_path):
    runner = HardwareRunner(use_simulator=True, results_dir=str(tmp_path))
    runner.connect()
    return runner

# Hypothesis strategies
@st.composite
def st_coupling_matrix(draw, n=None): ...

@st.composite
def st_statevector(draw, n_qubits=None): ...

Markers¶

# pyproject.toml
[tool.pytest.ini_options]
markers = ["slow: marks tests as slow (18-qubit, OOM on CI)"]

The @pytest.mark.slow marker is applied to tests that: - Create 18-qubit systems (2^18 = 262,144 Hilbert space dimension) - Require > 7 GB RAM (GitHub Actions runner limit) - Take > 60 seconds

CI skips slow tests: pytest -m "not slow".

CI Integration¶

# .github/workflows/ci.yml
- name: Run tests
  run: pytest tests/ -v --tb=short -x -m "not slow" --ignore=tests/test_hardware_runner.py

Test matrix: Python 3.10, 3.11, 3.12, 3.13. Coverage target: 95% (--cov-fail-under=95).

Test Quality Standards¶

Every test file must have: 1. 11+ test functions (no exceptions) 2. Physical invariant checks (Hermiticity, bounds, conservation laws) 3. Pipeline wiring test proving data flows end-to-end 4. Performance benchmark with wall-time output 5. Rust path verification where scpn_quantum_engine function exists 6. Edge cases (zero input, boundary, degenerate) 7. SPDX 7-line header

File Naming Convention¶

tests/test_{module_name}.py           # Primary module test
tests/test_{module_name}_edge_cases.py # Edge case / error path focus
tests/test_{module_name}_properties.py # Property-based (hypothesis)
tests/test_coverage_100_{area}.py      # Coverage-push tests
tests/test_e2e_{pipeline}.py           # End-to-end integration

Performance Regression¶

Pipeline benchmark values are printed to stdout during test execution. To capture a performance baseline:

pytest tests/test_pipeline_wiring_performance.py -v -s 2>&1 | grep "PIPELINE" > benchmarks.txt
pytest tests/test_rust_path_benchmarks.py -v -s 2>&1 | grep "RUST" >> benchmarks.txt

Key regression indicators: - Kuramoto solver (4q): should be < 50 ms - VQE solve (2q): should be < 300 ms - Rust kuramoto_euler: should show > 20× speedup - Pipeline wiring: all 155 tests should pass in < 10 s total

Dependencies¶

Test-only dependencies (in [dev] extras): - pytest >= 8.0 - pytest-cov >= 7.0 - hypothesis >= 6.100 - qiskit-aer >= 0.17

Optional (for full test coverage): - scpn-quantum-engine >= 0.2.0 (Rust acceleration tests) - quimb >= 1.8 (MPS/DMRG tests — importorskip) - sc-neurocore >= 3.14 (ArcaneNeuron E2E tests — skipif) - pennylane >= 0.40 (PennyLane adapter tests — skipif)