Reproducible quantum computing experiments are easier to trust, debug, and extend when every input is recorded—not just the circuit code. This checklist provides a reusable workflow for capturing software environments, circuit and transpilation details, simulator settings, hardware metadata, measurement results, and the decisions needed to rerun an experiment across local, cloud, and quantum hardware environments.
Overview
A quantum experiment is more than a sequence of gates. Its result can depend on the framework version, compiler options, circuit layout, optimization level, random seeds, number of shots, noise model, backend calibration, queue-time conditions, and even the way measurement data is serialized. If those details are missing, a future run may produce a different result without making it clear why.
Reproducibility does not mean that every hardware execution will return identical samples. Quantum measurements are probabilistic, and real devices introduce changing noise. A reproducible workflow instead makes the conditions visible and separates expected statistical variation from changes caused by code, compilation, configuration, or hardware.
Use version control for source code and experiment manifests, but do not rely on a repository alone. Store the exact environment specification, circuit representation, compiled circuit, execution request, raw counts, and analysis outputs together. A useful project should allow another developer—or your future self—to answer four questions:
- What was run?
- Where and under which software conditions was it run?
- What results were observed?
- Which differences are expected when the experiment is repeated?
Before evaluating an algorithm, it can also help to estimate its qubit count, gate count, depth, and shot requirements using a quantum circuit resource estimation guide. For broader project decisions, pair the experiment record with a quantum algorithm project evaluation template.
Checklist by scenario
1. Prepare the quantum software environment
Record the operating system, programming language version, quantum SDK, provider package, simulator package, and every direct dependency that affects execution or analysis. A lockfile or pinned environment file is preferable to a list containing only major package names. Also record the installation method and whether the run occurred in a notebook, container, virtual environment, or managed cloud workspace.
- Commit the source code and configuration files to version control.
- Record the exact commit identifier used for the run.
- Capture the language and package versions.
- Save the dependency lockfile, environment file, or container digest where available.
- Note any environment variables that affect provider selection, authentication, precision, or execution.
- Record the command, notebook entry point, or job definition used to start the experiment.
A clean setup guide is useful when another person needs to reproduce the project. The quantum developer roadmap can help place environment management and framework skills within a wider learning path.
2. Record the circuit before and after compilation
Save a logical circuit representation before transpilation or optimization. This is the experiment you intended to express. Then save the compiled circuit that was actually submitted to the simulator or device. These two artifacts may differ in qubit layout, gate set, depth, and measurement placement.
- Record the number of logical qubits and classical bits.
- Save the gate sequence, parameters, barriers, controls, resets, and measurements.
- Record parameter values and the order in which parameters were bound.
- Capture the target instruction set or basis gates.
- Record the transpiler or compiler version, optimization level, routing method, and layout method.
- Save the final physical-qubit mapping and compiled circuit depth.
- Store a machine-readable circuit format as well as a human-readable diagram or text representation.
Serialization formats vary between frameworks and may change over time. Treat serialized circuits as artifacts tied to the framework version that produced them. If a format is not guaranteed to remain portable, preserve the original source code and a plain-text summary alongside it.
3. Make simulator runs explicit
For a local or cloud simulator, record whether the run was ideal, noisy, state-vector based, shot based, or configured with another simulation method. Include the noise model source and its parameters rather than describing the run simply as “noisy.”
- Record the simulator name and version.
- Specify the number of shots and any batching or repetition behavior.
- Record all random seeds, including separate seeds used by circuit generation, transpilation, noise sampling, and execution.
- Save the noise model or its full construction parameters.
- Record precision, truncation, GPU or CPU mode, and parallelism when they can affect results.
- Keep the raw output, not only normalized probabilities or a plotted figure.
A seed improves repeatability only when the software path uses that seed consistently. It does not guarantee identical results across framework versions, hardware architectures, parallel execution modes, or changed compiler behavior. Record the seed as evidence of the intended configuration, not as a promise of universal determinism.
4. Capture hardware execution metadata
Hardware results require more context than simulator results because device conditions can change between submissions. Record the provider, backend identifier, execution timestamp, job identifier, shot count, and status. If the platform exposes calibration or characterization data, preserve the relevant snapshot or a reference to it.
- Record the provider and backend name exactly as returned by the platform.
- Save the job ID, submission time, completion time, and execution status.
- Record the device’s active-qubit mapping used by the compiled circuit.
- Capture calibration timestamp and relevant error, readout, connectivity, or gate-duration fields when available.
- Record dynamic settings such as dynamical decoupling, measurement mitigation, error suppression, or reset options.
- Save queue or retry behavior if the provider reran, split, or modified the request.
Do not assume that a backend name alone identifies a fixed machine state. A later run on the same named backend may use different calibration data, compiler defaults, or available qubits.
5. Store measurement results in a durable format
Preserve raw counts with an explicit bit-order convention. Bit-string interpretation is a common source of silent errors because frameworks can display classical registers in different orders. Include the number of shots and the mapping between displayed strings, classical bits, and measured qubits.
A practical result record should include:
- Experiment and circuit identifiers.
- Raw outcome counts.
- Total shots and any discarded or failed shots.
- Bit-order and register-order conventions.
- Post-processing code version.
- Derived probabilities, expectation values, uncertainties, and confidence or error estimates.
- Plots and tables generated from the raw result.
Keep raw data immutable. Generate cleaned or aggregated files as separate outputs so the original observation remains available for review.
What to double-check
Before publishing a result or comparing two runs, use this short review:
- Logical equivalence: Are the input circuits, parameters, initial states, and measurement operations the same?
- Compilation equivalence: Did the compiler produce the same depth, layout, basis gates, and routing decisions?
- Execution equivalence: Are shots, seeds, simulator mode, noise settings, and mitigation options unchanged?
- Hardware context: Did the runs use the same backend, qubits, calibration snapshot, and device settings?
- Analysis equivalence: Are bit ordering, filtering, normalization, observable definitions, and uncertainty calculations unchanged?
- Statistical interpretation: Is the observed difference larger than the variation expected from finite shots and hardware noise?
When a result changes, compare artifacts in this order: source circuit, bound parameters, compiled circuit, execution configuration, backend metadata, raw counts, and analysis code. This narrows the search faster than comparing final plots alone.
Common mistakes
- Saving only a notebook: Notebook outputs can hide execution order, unrecorded state, and dependency changes. Export the code, environment, and raw artifacts separately.
- Recording only the logical circuit: Hardware behavior depends on the compiled circuit that was actually submitted.
- Using “latest” dependencies: An unconstrained environment makes later reruns difficult to interpret. Pin versions or record a lockfile.
- Assuming a seed solves reproducibility: Seeds cannot freeze changing hardware calibration or compiler implementations.
- Keeping only percentages: Normalized values hide shot counts and prevent later uncertainty checks. Retain raw counts.
- Ignoring bit order: A correct circuit can appear incorrect if results are decoded with the wrong register convention.
- Over-comparing hardware runs: Identical code does not imply identical device conditions. Compare metadata before attributing changes to the algorithm.
- Overwriting old results: Store each run under a unique identifier and treat manifests as historical records.
For benchmarking context, review how fidelity, gate errors, and other measures are discussed in quantum computing benchmarks explained. A reproducible record makes those metrics easier to interpret and compare.
When to revisit
Revisit this workflow before each significant experiment, not only when something fails. Perform a quick checklist review before seasonal planning cycles, when moving from a local simulator to a cloud platform, and whenever a team member or environment changes.
Update the project’s recording policy after a major framework, provider SDK, compiler, simulator, or serialization change. A practical review interval is every six to twelve months, with an immediate review after a breaking release or a change in hardware access. Confirm that provider metadata fields, job response formats, environment commands, and circuit serialization methods still match the tools in use.
Before rerunning an older experiment:
- Restore the recorded environment or create an isolated replacement.
- Run a small deterministic or ideal-simulator smoke test.
- Regenerate the logical and compiled circuit artifacts.
- Compare compiler output with the original record.
- Run the original shot count and a clearly labeled validation run if needed.
- Record every difference rather than silently updating the old result.
Use a simple manifest as the final gate before execution: code commit, environment, circuit, compiler settings, seeds, shots, backend, calibration data, raw output, and analysis version. If one field is unavailable, mark it as unavailable and explain why. An explicit gap is more useful than an undocumented assumption. This habit turns quantum programming experiments into reviewable engineering work and gives future reruns a clear starting point.