Quantum Circuit Debugging: How to Find and Fix Errors in Qiskit and Cirq

Overview

Quantum debugging is different from checking a conventional function return value. A circuit may produce a probability distribution rather than one deterministic answer, and measurement can hide the state that existed immediately before the final operation. On top of that, frameworks may display qubits and bit strings in different orders, while a compiler or hardware backend can transform the circuit before execution.

A reliable investigation separates the problem into four layers:

1. Circuit construction: Are the intended qubits, gates, parameters, and controls present?
2. State evolution: Does the statevector, stabilizer result, or expectation value match the mathematical expectation?
3. Measurement and interpretation: Are outcomes mapped to classical bits and read in the intended order?
4. Execution environment: Are shots, seeds, transpilation, noise, or hardware changing the result?

Do not change several layers at once. First reduce the circuit to the smallest example that still fails. Then inspect the state before measurement, test the measurement mapping, and only afterward investigate sampling or hardware effects. This order prevents a display convention from being mistaken for a quantum programming error.

For larger experiments, record the circuit depth, gate count, qubit count, and shot count alongside each result. The quantum circuit resource estimation guide provides a useful framework for keeping those execution details visible.

Checklist by scenario

When the circuit returns the wrong state

1. Write the expected state explicitly. For a small circuit, describe the expected basis state or amplitudes on paper before running code. For example, an X gate applied to |0⟩ should produce |1⟩, while an H gate should create equal probabilities for |0⟩ and |1⟩ when measured in the computational basis.
2. Inspect before measurement. Measurement converts quantum information into classical data and can make state inspection impossible or misleading. Use the appropriate simulator state-inspection method, such as a statevector or stabilizer representation, where supported.
3. Test one gate at a time. Build the circuit incrementally: initialize, apply the first gate, inspect; add the next gate, inspect again. The first step that differs from expectation usually identifies the faulty assumption.
4. Check gate direction. Controlled gates are not interchangeable when control and target are reversed. Verify the framework's argument order and draw the circuit if necessary.
5. Confirm parameter values. Print bound parameters, rotation angles, and any classical values used to construct the circuit. Unit mistakes, such as confusing degrees and radians, can produce a valid but unintended circuit.

When counts look reversed or scrambled

1. Separate qubit labels from displayed bit strings. A result labelled 01 may mean different physical assignments depending on whether the leftmost character represents the highest- or lowest-indexed bit.
2. Inspect classical-bit mapping. In Qiskit, a measurement can map selected quantum bits into selected classical bits. In Cirq, measurement keys and the order of measured qubits determine how result columns are represented. Never infer the mapping from visual position alone.
3. Measure a single known qubit. Prepare one qubit in |1⟩ and the others in |0⟩. Record which output position changes. Repeat for each qubit if the mapping is unclear.
4. Use named measurement keys. In Cirq, give measurements descriptive keys such as ancilla or data_register rather than relying on an unnamed result. In any framework, label registers in the surrounding Python code.
5. Draw or print the circuit. A circuit diagram can reveal an accidental swap, an omitted measurement, or a gate applied to a neighbouring wire.

When results change from run to run

1. Ask whether the circuit is probabilistic. A superposition, interference pattern, or sampling-based algorithm may legitimately return different individual shots. Compare distributions, not one output.
2. Increase shots for diagnosis. A small sample can make a modest-probability outcome appear absent or overly common. Use enough shots to distinguish a likely pattern from sampling noise, while keeping the number documented.
3. Set a seed when supported. A fixed simulator seed can make a debugging run reproducible. Treat the seed as a diagnostic tool, not proof that the algorithm is deterministic.
4. Compare an exact calculation. Where practical, compare sampled counts with an exact statevector probability or analytically calculated distribution.
5. Check hidden randomness. Random parameter generation, randomized transpilation, noisy simulators, and hardware calibration can all change output. Make each source explicit in the test.

When simulation and hardware disagree

1. Run the same logical circuit on an ideal simulator and a noise-aware simulator, if available.
2. Inspect the transpiled or compiled circuit rather than assuming the submitted circuit ran unchanged.
3. Compare the result with a baseline circuit, such as repeated preparation and measurement of |0⟩.
4. Check readout errors, gate noise, connectivity constraints, and execution settings before changing the algorithm.
5. Repeat the experiment with a smaller circuit to determine whether the discrepancy begins with depth, qubit count, or a particular gate.

For the transition from a local simulator to a cloud QPU, use the quantum hardware job submission checklist. If the circuit is intentionally noisy, separate debugging from mitigation and benchmark both the raw and processed results as described in the error mitigation workflow.

What to double-check

Framework version and API behavior: Qiskit and Cirq APIs evolve. Confirm the installed package versions, backend or simulator configuration, and the current documentation for inspection and execution methods. Avoid debugging a copied example against an incompatible environment.

Initialisation: Most introductory examples assume every qubit begins in |0⟩. If your code starts from a prepared state, reset operation, imported circuit, or reused object, verify that assumption explicitly.

Measurement placement: A measurement placed before a later gate changes the experiment. Check whether the circuit contains mid-circuit measurements, resets, or conditional operations that are not visible in a simplified sketch.

Register and array order: Python lists, NumPy arrays, qubit objects, classical registers, and displayed strings may each use a different ordering convention. Create a tiny mapping table when working with more than one register.

Compilation changes: Transpilation can decompose gates, insert swaps, alter depth, and remap logical qubits to physical qubits. Those changes are expected, but they should be inspected when diagnosing hardware output. The guide to quantum compiler basics explains why the executed circuit may look different from the source.

Minimal reproducible example: Keep only imports, version information, circuit construction, execution, and result inspection. Remove notebooks cells, unrelated preprocessing, plotting, and application-specific data until the failure is isolated. Include the expected result and the actual result.

Common mistakes

• Reading one shot as the answer: A single sampled bit string does not describe a probability distribution.
• Assuming bit-string order: Reversing a displayed string may hide the symptom without fixing the mapping.
• Debugging hardware first: Establish ideal-simulator behaviour before investigating calibration and noise.
• Inspecting only the final counts: State inspection and intermediate checkpoints reveal where the circuit diverges.
• Mutating a circuit unintentionally: Reusing a circuit object, appending gates in a loop, or executing a notebook cell twice can add operations that are not obvious in the final code.
• Changing the algorithm to fit the output: First verify the expected basis, register mapping, and measurement convention.
• Ignoring warnings: Deprecation notices, dropped operations, unsupported gates, and implicit conversions can be important debugging evidence.

When a circuit supports a hybrid workflow, log the classical inputs, parameter values, circuit hash or representation, backend, shots, and returned metrics for every iteration. This is especially important in variational algorithms and quantum machine learning, where a surprising result may come from the optimizer or data pipeline rather than the circuit itself. The hybrid quantum-classical workflow guide offers a broader experiment structure.

When to revisit

Revisit this checklist whenever a circuit produces a new result after refactoring, moves from simulation to hardware, gains a register or control operation, or is ported between Qiskit and Cirq. It is also worth repeating after a package upgrade, backend change, compiler-setting change, or modification to shot count and noise configuration.

For a practical debugging pass, save the following with each experiment:

1. The smallest failing circuit and its diagram or text representation.
2. The expected state or probability distribution.
3. Package, Python, simulator, and backend versions.
4. Qubit-to-classical-bit and measurement-key mappings.
5. Shot count, random seed, noise settings, and compilation options.
6. Ideal, noisy-simulator, and hardware results where relevant.

Start with one qubit, one gate, and one measurement. Expand only after that baseline passes. This habit turns quantum circuit troubleshooting from guesswork into a repeatable quantum programming test process.