Worked example · 8 September 2026 · Qiskit 2.5.2

Fewer gates can produce the wrong distribution.

A resource-only check can miss a functional regression. This two-qubit exercise removes one CX gate, measures the resulting output distribution and compares it against an explicit tolerance. The change is deliberate: this is a reproducible product example, not an observed Qiskit defect.

Start with a Bell circuit

from qiskit import QuantumCircuit

def prepare_state():
    circuit = QuantumCircuit(2)
    circuit.h(0)
    circuit.cx(0, 1)  # Remove this line for the deliberate candidate.
    return circuit

The baseline starts in the zero state, applies H to qubit 0 and then CX from qubit 0 to qubit 1. Its ideal computational-basis outcomes are 00 and 11, each with probability one half. Removing CX leaves qubit 1 at zero. Qiskit displays the qubit-1 bit first, so the candidate outcomes are 00 and 01.

Total-variation distance is half the sum of absolute probability differences: ½ × (0 + 0.5 + 0 + 0.5) = 0.5. The local Qiskit Statevector run agrees with that reference to floating-point precision.

Two checks, two different answers

The actual generated report records 1 compiled two-qubit gate in the baseline and 0 in the candidate. The resource policy forbids an increase, so that check passes. It does not establish that the change is useful.

The measured distribution distance is approximately 0.500, exceeding the declared 0.05 tolerance. The combined verdict is REGRESSION and the comparison returns exit 1. Upload success cannot override that exit code. Inspect the removed gate and intended observable before deciding whether to fix the code or propose a reviewed policy change.

Reproduce it, then use your own circuit

1. Follow the pinned source installation and run ketqat regression sample --output-dir sample. Exit 1 is the expected result of the deliberately changed example.
2. Use the copyable project to capture the unchanged factory twice. This comparison should be WITHIN_POLICY, exit 0.
3. Keep the baseline, remove CX and capture a new candidate. Compare with the same policy in a new output directory. Inspect the HTML and JSON, then follow the included same-runner Actions example.

Keep the claim narrow

This measurement uses ideal probabilities, with no finite-shot sampling, noise model or hardware execution. It says nothing about runtime, device cost or speed. Distribution agreement on this input and measurement basis also cannot prove circuit equivalence: for example, some phase changes leave these probabilities unchanged. Use an equivalence checker or additional declared observations when that is the claim you need.

For finite-shot comparisons, declare the sample budget and error budget before running. An interval overlapping the tolerance is INCONCLUSIVE, not a pass. Do not keep resampling or promote a failed candidate until the report turns green.

You can share this public example URL without sharing a workspace, private capture or upload token. Your own full snapshots can contain source details, circuit instructions and environment information; inspect them before sharing. The example demonstrates a technical check, not customer adoption or willingness to pay.