Decisive classical-run API

scpn_quantum_control.benchmarks.decisive_run_harness executes the classical side of the preregistered decisive-advantage protocol. It assembles comparable rows for exact statevector evolution, a classical phase ODE, and an optional matrix-product-state evolution, then delegates validation and the final verdict to the protocol owner.

The harness never creates a quantum result. Without a real QPU row the default decision remains inconclusive, even when all classical rows are valid.

Configuration and output records

DecisiveRunConfig bounds all execution controls:

• t_max and dt must be finite and positive, with dt <= t_max;
• mps_bond_dim must be positive;
• reserved_core must be a non-negative logical-core index; and
• include_mps=False produces a reasoned skipped row rather than deleting the required baseline from the evidence table.

DecisiveRunArtifact is an immutable, JSON-ready record containing the protocol identifier, decision size, reference observable, timing grade, three classical rows, delegated schema validation, fail-closed decision, provenance, host readiness, claim boundary, and run metadata. to_dict() returns fresh mappings and lists suitable for serialisation.

Row builders

dense_reference_row(...) evolves the exact statevector, extracts final synchronisation order parameter R, and records zero reference error. It also records the exact ground energy supplied by the existing diagonalisation path.

ode_row(...) executes the classical phase ODE and compares its final R with the dense reference. A missing final observable produces infinite error and therefore cannot pass the accuracy gate.

mps_row(...) maps the tensor-network result into the same schema. Missing tensor-network support becomes an explicit skipped row with its dependency or size reason; an available run without a final observable cannot pass accuracy.

All rows carry the command, machine, dependency versions, exact Git commit when available, wall-clock measurement, and a documented analytic memory estimate.

Complete execution

from scpn_quantum_control.benchmarks.decisive_run_harness import (
    DecisiveRunConfig,
    run_decisive_benchmark,
)

artifact = run_decisive_benchmark(
    config=DecisiveRunConfig(t_max=1.0, dt=0.1),
)
print(artifact.decision["label"])
print(artifact.timing_grade)

When no protocol is supplied, run_decisive_benchmark() uses the frozen decisive-advantage protocol. When no host verdict is supplied, it captures the live isolation state for reserved_core. Passing a pre-captured HostReadiness is intended for controlled orchestration and deterministic tests; it does not alter numerical results.

Provenance helpers

command_line() records the current argument vector and uses python only for an empty vector. dependency_versions() records Python plus the tracked scientific packages, representing absent optional packages as not installed. git_commit() resolves an actual Git executable and returns unknown when the repository identity cannot be read; it never fabricates a commit.

Evidence boundary

Wall-clock values are measurements of one execution environment. They are labelled isolated_measured only when the host-readiness contract passes; otherwise they are advisory_shared_host. Memory values are analytic models, not process-resident-set measurements. Neither timing grade can establish quantum advantage without a valid, matched-budget QPU row.

API reference

scpn_quantum_control.benchmarks.decisive_run_harness

Measured classical-baseline harness feeding the decisive-advantage gate.

The decisive-advantage protocol (:mod:.decisive_advantage_protocol) declares which comparison must be decided; this harness runs the classical side of it at the preregistered decision size and emits schema-valid rows that :func:~.decisive_advantage_protocol.evaluate_decision can score. It never fabricates a quantum row: with no QPU credits the qpu_hardware column is absent, so the honest outcome of the default protocol is inconclusive — the promotion gate stays closed, exactly as the quantum-advantage gap contract requires.

Every decision baseline produces the same dynamical observable — the synchronisation order parameter R at the final evolution time — so the comparison is like-for-like:

• dense_statevector_evolution reuses :func:~scpn_quantum_control.hardware.classical.classical_exact_evolution, the exact reference at the decision size; its reference_error is zero.
• classical_ode reuses :func:~.classical_baselines.scipy_ode_baseline, the classical phase model.
• mps_tensor_network reuses :func:~.classical_baselines.mps_tebd_baseline; when the tensor-network extra is unavailable the row degrades to an explicit size-gated skip rather than a fabricated number.

Measurement grade

Wall-clock timing is measured; memory_bytes is the documented analytic memory model shared with the other benchmark surfaces (statevector 2^n·16 B, MPS n·2·χ²·16 B, ODE trajectory n_times·n·8 B). The artifact records the host-isolation verdict from :func:~.isolated_host_readiness.capture_host_readiness; on a shared host the timings are labelled advisory, and because the decision is inconclusive without a QPU row, no advantage is ever claimed on advisory timings.

DecisiveRunConfig dataclass

Deterministic inputs for one decisive classical-baseline run.

Parameters

t_max Total evolution time; must be finite and positive. dt Time step; must be finite, positive, and not exceed t_max. mps_bond_dim Bond dimension for the MPS TEBD baseline; must be positive. include_mps When False the MPS row is emitted as an explicit configuration-gated skip instead of being run. Lets callers avoid the optional tensor-network dependency without fabricating a row. reserved_core CPU core index whose isolation state is captured for the timing-grade label; must be non-negative.

__post_init__()

Validate the run configuration.

Raises

ValueError If any field falls outside its documented bound.

DecisiveRunArtifact dataclass

Serialisable record of one decisive classical-baseline run.

to_dict()

Return a JSON-serialisable mapping of the full artifact.

git_commit()

Return the current repository HEAD commit, or "unknown".

command_line()

Return the invoking command line, or "python" when unavailable.

dependency_versions()

Return versions of the tracked runtime dependencies.

Returns

dict of str to str Maps "python" and each tracked package to its installed version, or "not installed" when the package is absent. Read from installed metadata so the record reflects the true environment, never a guess.

dense_reference_row(n_qubits, protocol_id, K, omega, *, t_max, dt)

Run the dense statevector reference and return its row and final R.

Parameters

n_qubits System size in qubits. protocol_id Protocol identifier stamped into the row. K, omega Coupling matrix and frequency vector for the Kuramoto-XY problem. t_max, dt Evolution horizon and step.

Returns

tuple of (dict, float) The schema-valid ok row (with reference_error of zero, since this row is the reference) and the reference order parameter R.

ode_row(n_qubits, protocol_id, K, omega, reference_r, *, t_max, dt)

Run the classical ODE baseline and return its schema-valid row.

The relative error is taken against reference_r; the classical phase model is a different model from the quantum XY dynamics, so a reference_error above the accuracy target is an honest, expected result rather than a defect.

mps_row(run, n_qubits, protocol_id, reference_r, *, bond_dim)

Map an MPS baseline run to an ok or size-gated skipped row.

Parameters

run The result of :func:~.classical_baselines.mps_tebd_baseline; an unavailable run becomes an explicit skipped row with notes. n_qubits, protocol_id, reference_r, bond_dim Row metadata and the reference order parameter for the relative error.

run_decisive_benchmark(protocol=None, config=None, *, host_readiness=None)

Run the classical baselines for one decisive-advantage protocol.

Parameters

protocol The decisive protocol to decide; defaults to :func:~.decisive_advantage_protocol.default_decisive_advantage_protocol. config Deterministic run configuration; defaults to :class:DecisiveRunConfig. host_readiness Pre-captured host-isolation verdict; when None the live host is assessed via :func:~.isolated_host_readiness.capture_host_readiness.

Returns

DecisiveRunArtifact The measured rows, the delegated protocol validation, and the fail-closed decision (inconclusive for the default no-QPU protocol), with full provenance and the timing-grade label.