Studio executive benchmark API¶
Module: scpn_quantum_control.studio.executive_benchmark
The module implements the Studio benchmark action for bounded dense
XY-Hamiltonian construction. Importing it performs no timing loop, filesystem
write, provider call, or hardware action.
Construction functions¶
reference_dense_xy_hamiltonian(coupling, frequencies) builds the real dense
operator through NumPy. coupling must be an n × n matrix matching the
frequency count. The function uses little-endian Qiskit qubit ordering and
returns a float64 matrix with shape (2**n, 2**n).
native_dense_xy_hamiltonian(coupling, frequencies) calls the optional Rust
PyO3 kernel with the same ordering and output shape. It raises RuntimeError
when the extension or dense-construction symbol is unavailable.
measure_p50_us(fn, *, warmup, repeats) discards warmup calls, times exactly
repeats calls with perf_counter_ns, and returns their median in
microseconds. It does not isolate CPU affinity, host load, cache state, or
clock noise.
Action handler¶
BenchmarkActionHandler.plan() accepts only K_nm, omega, repeats, and
warmup. The coupling matrix must be symmetric, square, zero-diagonal, and
contain between two and ten nodes. Frequencies must match the node count.
Repeats are bounded from one through 32; warm-up calls from zero through eight.
The default backend is rust.
execute() always measures the NumPy reference. On the Rust backend it also
checks native/reference parity with absolute tolerance 1e-9 and reports the
observed median ratio when the native median is positive. It appends the
validated committed benchmark-databank summary. Every result sets
production_claim_allowed to false and includes the shared-host timing caveat.
generate_script() embeds only deterministic sealed verdicts: operator shape,
native parity when applicable, and committed databank row count. The script
prints fresh and sealed reference timing values but never asserts their
equality.
Evidence boundary¶
A passing action proves bounded operator construction, native/reference parity, and committed-databank integrity for that execution. It is not an isolated benchmark, stable speedup, production-performance claim, physical-coupling claim, provider run, or QPU execution.
Full autodoc¶
The benchmark executive action handler — native construction speedup.
The simulated benchmark verb measures the wall-clock construction time of
the dense XY Hamiltonian for a bounded K_nm/omega network on the
requested backend (the native Rust PyO3 kernel or the pure-numpy reference),
parity-checks the native operator against the numpy reference, and summarises
the committed tier-benchmark databank
(:mod:scpn_quantum_control.studio.benchmark_databank_bundle).
The claim boundary is deliberately narrow. Wall-clock timings on this host are
opportunistic local measurements on a shared workstation — they swing with CPU
pinning, cache state, and host load — so every sealed record carries
production_claim_allowed: False and its timing caveat verbatim. What is
reproducible is the parity verdict (the native operator matches the numpy
reference to tolerance) and the committed databank summary; the reproduction
script asserts exactly those and re-prints fresh timings without asserting them.
BenchmarkActionHandler
¶
Bases: ActionHandler
Executive handler for the simulated benchmark verb.
verb
property
¶
Return "benchmark".
plan(request, contract)
¶
Validate the network and resolve a construction-benchmark plan.
Parameters¶
request : ExecutiveRequest
The benchmark request; parameters must describe a bounded
network (K_nm, omega) and may bound the timing loop
(repeats, warmup).
contract : VerbContract
The resolved benchmark contract.
Returns¶
ExecutionPlan The normalised, inspectable plan.
execute(plan)
¶
Time the dense construction and summarise the committed databank.
Parameters¶
plan : ExecutionPlan The planned benchmark.
Returns¶
ExecutionResult A succeeded result carrying the P50 timings, the parity verdict, the (never asserted) speedup, and the databank summary.
Raises¶
RuntimeError
If the rust backend is requested but the native kernel is not
importable — the spine seals this as a failed record.
generate_script(plan, result)
¶
Write a standalone script that reproduces the deterministic verdicts.
The script re-asserts only what is reproducible — the operator shape, the parity verdict, and the committed databank row count — and re-prints fresh timings without asserting them, because wall-clock numbers are environment-dependent.
Parameters¶
plan : ExecutionPlan The executed plan. result : ExecutionResult The succeeded benchmark result.
Returns¶
GeneratedScript The reproduction script, digest attached.
reference_dense_xy_hamiltonian(coupling, frequencies)
¶
Build the dense XY Hamiltonian through the pure-numpy reference path.
Implements H = -sum_i omega_i Z_i - sum_{i<j} K[i,j] (X_i X_j + Y_i Y_j)
in Qiskit little-endian qubit ordering (qubit 0 is the rightmost
Kronecker factor), matching the convention of
:func:scpn_quantum_control.bridge.knm_hamiltonian.knm_to_hamiltonian and
the native Rust kernel. The XY Hamiltonian is real-symmetric, so the real
part is returned as float64.
Parameters¶
coupling : NDArray[np.float64]
Symmetric zero-diagonal coupling matrix of shape (n, n).
frequencies : NDArray[np.float64]
Natural frequencies of length n.
Returns¶
NDArray[np.float64]
The dense XY Hamiltonian of shape (2**n, 2**n).
native_dense_xy_hamiltonian(coupling, frequencies)
¶
Build the dense XY Hamiltonian through the native Rust PyO3 kernel.
Parameters¶
coupling : NDArray[np.float64]
Symmetric zero-diagonal coupling matrix of shape (n, n).
frequencies : NDArray[np.float64]
Natural frequencies of length n.
Returns¶
NDArray[np.float64]
The dense XY Hamiltonian of shape (2**n, 2**n).
Raises¶
RuntimeError
If the scpn_quantum_engine native kernel is not importable.
measure_p50_us(fn, *, warmup, repeats)
¶
Return the P50 wall-clock latency of fn in microseconds.
Parameters¶
fn : Callable[[], object] The zero-argument construction to time. warmup : int Discarded warm-up invocations run before sampling. repeats : int Timed invocations; the median sample is returned.
Returns¶
float The median (P50) latency in microseconds.