Use this quantum code review checklist to evaluate a circuit or hybrid quantum-classical pull request before approval. It gives reviewers a repeatable way to check measurement semantics, parameter binding, classical baselines, randomness, qubit mapping, resource use, shot budgets, backend assumptions, and result validation, with practical evidence requirements for simulator and hardware execution.
Overview
Quantum code can pass ordinary unit tests and still produce misleading results. A test may verify that a circuit constructs successfully while missing an incorrect measurement mapping, an unbound parameter, an unrealistic backend assumption, or a comparison against a weak classical baseline. A useful review therefore examines both software correctness and experimental validity.
The goal is not to reject every circuit that is deep, noisy, or exploratory. The goal is to make the assumptions visible and ensure that the reported outcome follows from the implementation. For an enterprise team, a review should answer four questions:
- Does the code express the intended algorithm? Gates, parameters, measurements, and post-processing should match the design.
- Can another developer reproduce the result? The pull request should identify versions, seeds where applicable, inputs, shot counts, and backend configuration.
- Is the resource demand understood? Qubit count, gate depth, two-qubit operations, circuit repetitions, and classical optimization work should be estimated before execution.
- Is the evidence strong enough for the claim? A simulator result, noisy simulation, and hardware result answer different questions and should not be presented as interchangeable.
Use this checklist alongside a team testing policy. For larger workflows, the enterprise CI/CD and testing checklist for hybrid quantum-classical workflows can help turn review expectations into automated checks.
How to estimate
Before approving a quantum pull request, estimate its review readiness rather than relying on a single pass or fail judgment. Record a status for each review area: pass, needs evidence, or blocker. A blocker means the result cannot be interpreted reliably; needs evidence means the implementation may be sound but the pull request lacks documentation or a reproducible test.
For a practical estimate, assign each area a weight based on the change. For example, measurement semantics and result validation deserve high weight when the pull request changes observables. Parameter binding and random seeds deserve high weight when it changes a variational loop. Mapping, depth, and backend configuration deserve high weight when the target is real hardware.
| Review area | What to inspect | Acceptable evidence |
|---|---|---|
| Measurement semantics | Which qubits and classical bits are measured, how bitstrings are ordered, and how counts become labels or expectations | A small hand-checkable circuit, expected output, and a test for bit ordering |
| Parameter binding | Parameter names, binding shape, parameter order, and whether all parameters are bound before execution | An assertion showing the bound circuit contains no unintended free parameters |
| Classical baseline | Whether the quantum result is compared with a relevant, correctly implemented classical method | Baseline code, fixed data split, metrics, and an explanation of comparable resources |
| Random seeds | Random generators used for data, initialization, sampling, or optimization | Explicit seed handling and recorded seed values, or a clear explanation of nondeterminism |
| Qubit mapping | Logical-to-physical assignment, connectivity, added routing, and measurement mapping | Transpiled or compiled circuit inspection for the intended backend |
| Gate depth | Total depth, two-qubit gate count, repeated layers, and depth after compilation | Resource summary before and after compilation |
| Shot budget | Shots per circuit, number of parameter evaluations, retries, and total executions | A calculation of total circuit executions and a reason for the budget |
| Backend assumptions | Backend name or class, supported gates, limits, noise model, queue or execution behavior, and configuration fields | Captured backend configuration and a documented fallback or simulator path |
| Result validation | Expected invariants, tolerances, confidence or uncertainty treatment, and failure behavior | Assertions, regression fixtures, plots or summaries, and an interpretation of deviations |
A simple effort estimate can use this formula:
Review effort = code complexity + experiment complexity + hardware uncertainty.
Code complexity increases with dynamic circuit construction, multiple abstractions, custom post-processing, and optimizer callbacks. Experiment complexity increases with datasets, parameter sweeps, repeated runs, and hybrid training loops. Hardware uncertainty increases when the circuit depends on a particular topology, native gate set, calibration state, or provider-specific execution option. This is not a performance metric; it is a way to decide how much evidence the reviewer should request.
Inputs and assumptions
1. Confirm the circuit’s contract
The pull request should state the circuit’s input shape, output meaning, qubit count, classical register layout, and measurement convention. Review the smallest possible example first. For a Bell-state circuit, for instance, the test should establish the expected correlation and make clear whether a result such as 01 is interpreted from left to right, right to left, or through an SDK-specific bitstring convention.
Do not infer semantics from variable names alone. Inspect the measurement instructions and the code that converts counts into probabilities, labels, expectation values, or loss values.
2. Check parameters before execution
Parameterized circuits are especially vulnerable to silent errors. Verify that the number and order of parameter values match the circuit definition. Confirm that data features and trainable weights are bound to the intended parameters, and test an input where the expected behavior is known. A useful failure test attempts to execute with a missing or extra parameter and confirms that the code fails clearly rather than silently changing shape.
3. Separate quantum evidence from classical evidence
For a variational algorithm or quantum machine learning experiment, require a classical baseline using the same data split, preprocessing, evaluation metric, and, where practical, comparable optimization effort. A quantum result without a meaningful baseline cannot establish that the quantum component adds value. The data pipeline should also document scaling and encoding choices; the quantum machine learning data pipeline guide provides a useful companion checklist.
4. Make randomness deliberate
Record seeds for dataset shuffling, parameter initialization, simulator sampling, and optimizer behavior when those controls exist. A fixed seed is useful for regression tests, but it is not a substitute for checking sensitivity across multiple seeds. For exploratory work, document the seed and rerun policy instead of presenting one random run as a stable conclusion. See the reproducible quantum experiment setup guide for environment and metadata practices.
5. Inspect compiled resources
Logical circuit depth is not enough for hardware readiness. Compilation can alter depth, introduce routing operations, change the gate set, and change the effective qubit mapping. Capture both the logical and compiled resource summaries. Include active qubits, total depth, two-qubit gate count, and any measurement or reset operations relevant to the target workflow.
Also distinguish circuit count from shot count. If an optimizer evaluates 40 parameter points at 1,000 shots each, that is 40,000 shots before accounting for validation runs, calibration-related executions, retries, or separate circuits for observables. The quantum resource estimation worksheet can help standardize this calculation.
6. Treat backend settings as part of the code
Provider and SDK interfaces change, so reviewers should inspect the current backend configuration rather than copying assumptions from an older example. Check the selected backend, supported operations, qubit availability, transpilation or compilation settings, shot limits, resilience or mitigation options, and result format. If the code supports several providers, test each adapter separately and keep provider-specific logic behind a narrow interface.
Worked examples
Example A: A simulator test passes, but measurements are reversed
A pull request creates a two-qubit entangled state and classifies counts as equal or unequal. The circuit test checks that the two most common strings are equal, so it passes. The reviewer notices that production post-processing reverses the bitstring before reading the label. The defect is not in the state preparation; it is in the measurement contract.
Acceptable evidence includes a fixture with explicit classical-bit positions, an expected count format, and a test that distinguishes 01 from 10. The reviewer should request the fix before approval because hardware execution will not resolve an ambiguous interpretation.
Example B: A variational loop reports improvement without a baseline
A hybrid training pull request shows that the loss decreases over 20 optimizer steps. The code uses randomly initialized weights and a simulator seed, but it does not compare against a classical model or a fixed initial value across repeated runs. The result may demonstrate that the optimizer is functioning, but it does not establish useful model performance.
Approval evidence should include the loss definition, train-validation split, initialization policy, seed records, baseline metrics, and a small repeatability check. If the work is explicitly exploratory, label it as such and avoid a stronger performance claim.
Example C: A circuit is logically small but hardware-unready
A circuit uses six logical qubits and shallow layers, but the selected hardware topology requires additional routing. After compilation, the circuit has substantially more two-qubit operations than the logical version. The pull request also assumes a gate or execution option that the target backend does not support.
The reviewer should ask for a compiled resource report, explicit logical-to-physical mapping, and a backend-compatible configuration. If noise is part of the acceptance criterion, compare an ideal simulator, a configured noisy simulator where appropriate, and hardware results separately. Error mitigation should be documented rather than treated as an invisible correction; the error mitigation comparison outlines the evidence reviewers should expect.
When to recalculate
Revisit this quantum code review checklist whenever the circuit, execution environment, or business claim changes. Recalculate resource needs when qubit count, ansatz depth, feature dimension, observable count, optimizer iterations, shot budget, or validation runs change. A small change to a training loop can multiply the number of circuit executions even if the circuit itself is unchanged.
Repeat backend-readiness checks after an SDK upgrade, provider migration, compiler configuration change, target-backend change, or update to supported gate and result formats. Recheck reproducibility when a random initialization method, simulator, optimizer, dataset split, or preprocessing step changes. Recheck result validity when a baseline, metric, error-mitigation method, or interpretation of the output changes.
For team adoption, make the following evidence a pull-request requirement:
- A plain-language circuit contract and a minimal expected-output test.
- A parameter-binding test and a record of seeds or nondeterministic steps.
- Logical and compiled resource summaries, including qubits, depth, and two-qubit operations.
- A shot and execution-count estimate for the full hybrid workflow.
- Backend configuration, provider-specific assumptions, and a simulator fallback where applicable.
- Classical baseline results and validation criteria tied to the claim being made.
- Metadata sufficient for another developer to reproduce or explain a changed result.
Finally, record the review date, SDK versions, backend assumptions, and open limitations in the repository. That small discipline turns a one-time approval into an auditable engineering decision and makes the checklist useful again during SDK migrations, hardware deployments, onboarding, and investigations into results that passed unit tests but failed in production-like execution.