Debugging with Simulators

Debugging a quantum program is fundamentally different from debugging classical code, because the thing you most want to inspect — the quantum state mid-computation — is exactly the thing measurement destroys. The simulator is the escape hatch: it computes the entire state vector at any point, with no measurement back-action, so you can watch your circuit's wavefunction evolve gate by gate. This lesson is about using that superpower methodically.

The classical debugger does not apply

On a real device there is no breakpoint that prints the state: reading a qubit collapses it, and the no-cloning theorem forbids copying it out for inspection. What hardware gives you is only the final measurement histogram, after many shots. By contrast a state-vector simulator exposes:

the amplitudes $\alpha_x$ of every basis state $|x\rangle$ ,
the probabilities $|\alpha_x|^2$ ,
and the per-qubit Bloch vector $(x, y, z)$ .

These are visible because the simulator is classical and tracks the full $2^n$ -dimensional vector explicitly. That is also its limit — it works only up to a few tens of qubits — so simulator-based debugging targets small instances, not full-scale runs.

A debugging workflow

A reliable workflow mirrors classical "bisect the failure":

Reproduce on a tiny instance. Shrink the register to the smallest size that still exhibits the bug — 2 or 3 qubits. Most index, phase, and ordering bugs survive shrinking.
Inspect the state after each step. Build the circuit incrementally and read the statevector after each gate. Compare against the state you derived by hand. The first gate whose output surprises you is where the bug lives.
Check the Bloch sphere for single-qubit logic. A misplaced phase or a wrong rotation axis shows up immediately as a Bloch vector pointing the wrong way.
Diff against a reference. Prepare the state your routine should produce with a known-good circuit and compare amplitudes. This is the assertion discipline from the previous lesson, used interactively.

The four bugs simulators catch instantly

Most quantum bugs fall into a handful of categories, and the state vector exposes each:

Qubit-index / ordering errors. A gate applied to the wrong qubit, or a register read in the wrong endianness, puts amplitude on the wrong basis index. The amplitude list shows it directly.
Phase errors. A forgotten $S$ vs $S^\dagger$ , or a $Z$ where you meant $-Z$ , leaves probabilities unchanged but corrupts relative phases. You can only see this in the amplitudes (or after an interference step), never in the histogram alone.
Missing uncomputation. An ancilla left entangled with the data register shows up as a product state that should have factorised — the data qubit's Bloch vector is shortened (it has become mixed) because it is still correlated with scratch.
Normalisation mistakes. Hand-built states whose probabilities do not sum to 1 indicate a construction error; the simulator's probabilities make this obvious.

Phase bugs: the silent killer

The most insidious failures are phase bugs, because measuring in the computational basis hides them. Two states with identical $|\alpha_x|^2$ but different $\arg(\alpha_x)$ give the same histogram, yet behave completely differently once an interference step (a Hadamard, a QFT) mixes the basis states. The discipline is: when an algorithm relies on interference — and most do — debug by reading amplitudes, not probabilities, and only trust the histogram after the interference has happened. A simulator is the one tool that lets you do this at all.

From debugging to confidence

Simulator debugging is not just for fixing failures; it builds the evidence that a routine is correct before you spend scarce hardware time on it. Once a circuit's statevector matches your hand derivation on every small instance, and its unitary matches the target operator, you have strong reason to trust the asymptotic version you will eventually run on a device you cannot fully observe. That transfer of confidence — from the fully-visible small case to the invisible large one — is the entire point of debugging with simulators.