A quantum experiment is only as useful as the record left behind. This quantum experiment documentation template gives developers a practical way to capture circuits, software versions, backend settings, execution details, results, and interpretation notes so a teammate can reproduce the run, compare it with another configuration, or review it months later.
Overview
Quantum workflows often combine several layers: source code, an SDK, a transpiler or compiler, a simulator or quantum processor, measurement settings, post-processing, and sometimes error mitigation. A result can change when any one of these inputs changes. Recording only the circuit and final measurement counts makes it difficult to determine whether a difference came from the algorithm, compilation, hardware conditions, random sampling, or analysis code.
Good documentation does not require a long research report for every test. It requires a consistent minimum record and a clear separation between inputs, observed outputs, and interpretation. Store the record alongside the code and raw artifacts rather than relying on a notebook cell, a chat message, or memory.
Use the following fields as a reusable quantum computing reproducibility checklist:
- Experiment identity: name, purpose, owner, date, and a short hypothesis or question.
- Source reference: repository URL or commit identifier, notebook path, script name, and relevant branch or release.
- Environment: programming language version, SDK and package versions, operating system or container image, and dependency lockfile when available.
- Problem definition: number of logical qubits, number of classical bits, input data, observable, cost function, and success criteria.
- Circuit specification: circuit source, qubit and bit ordering, gates, parameters, parameter values, measurements, barriers, and circuit depth or width.
- Compilation details: transpiler or compiler version, optimization level, target instruction set, layout or mapping, routing method, and final compiled circuit.
- Execution configuration: simulator or hardware backend, backend identifier, shots, execution mode, batching, queue or job identifiers, and random seeds where supported.
- Noise and mitigation: noise model, calibration assumptions, readout mitigation, zero-noise extrapolation, error correction settings, or an explicit statement that none were used.
- Results: raw measurement counts or expectation values, metadata returned by the provider, intermediate files, processed results, uncertainties, and plots.
- Interpretation: what the result supports, what it does not establish, anomalies, failed runs, and the next action.
Checklist by scenario
For a simulator-only experiment
Record the simulator name and version, state-vector or sampling mode, precision if configurable, noise model, shot count, and random seed. State whether the output is exact or sampled. If the simulator uses a custom noise model, preserve its parameters in a machine-readable file. A noiseless result should not be presented as an estimate of hardware performance.
For a real-hardware run
Capture the provider, backend name or identifier, job identifier, submission and completion timestamps when available, number of shots, queue or retry behavior, and any backend configuration returned with the job. Save the submitted circuit and the compiled circuit separately. Hardware results should also note whether calibration data, dynamic scheduling, measurement mitigation, or other provider-specific options were applied.
For a comparison between backends
Define the comparison before running it. Keep the logical circuit, input parameters, shot budget, observable, and post-processing method constant unless the experiment explicitly tests one of those variables. Record backend-specific changes such as qubit mapping, gate decomposition, connectivity constraints, and supported instruction sets. When comparing a simulator with hardware, label the comparison as ideal, noisy simulated, or measured rather than treating all outputs as equivalent.
For a variational or hybrid experiment
Document the classical optimizer, initial parameters, stopping rule, learning rate or other optimizer settings, objective definition, parameter-shift or gradient method, number of circuit evaluations, and checkpoint schedule. Save parameter histories and objective values, not only the final answer. For VQE, QAOA, or quantum machine learning workflows, record the data split, encoding method, preprocessing, baseline, and evaluation metric. A useful reference is this guide to benchmarking quantum machine learning models against classical baselines.
For a handoff or internal review
Prepare a short readme that explains how to install dependencies, select a backend, run a small smoke test, and locate raw results. Include expected output ranges rather than a single exact output when sampling is involved. Link to the quantum circuit testing and debugging workflow so reviewers can distinguish a reproducibility failure from normal statistical variation.
What to double-check
Before publishing, handing off, or comparing an experiment, inspect the record for details that commonly disappear between a notebook and a final chart.
- Ordering conventions: Confirm the meaning of qubit indices, classical-bit indices, bitstrings, tensor axes, and observable terms. A reversed bit order can create a plausible but incorrect result.
- Compiled versus logical circuit: Save both versions. Depth, two-qubit gate count, inserted swaps, and basis-gate decomposition can materially affect execution.
- Shot interpretation: Record whether values are raw counts, normalized frequencies, expectation values, or post-processed estimates. Include confidence intervals or another uncertainty description where appropriate. See the practical guide to shots and statistical confidence.
- Randomness: Identify every controlled seed, including seeds used by the simulator, parameter initialization, data shuffling, or classical optimizer. If a provider does not expose a seed, say so.
- Post-processing: Preserve the code and parameters used to filter counts, normalize values, mitigate readout error, aggregate runs, or select the best candidate.
- Artifact integrity: Give raw files stable names and record checksums or commit references when your workflow requires stronger provenance. Do not overwrite raw results with cleaned output.
- Failure context: Keep rejected jobs, compilation errors, timeouts, and partial runs in a log. Failed attempts can explain gaps in a comparison and prevent duplicated debugging.
A compact record can be stored as YAML or JSON. The exact field names may vary by SDK, but the separation of concerns should remain stable:
experiment_id: example-001
purpose: Compare ideal and noisy execution
source:
repository: https://example.invalid/project
commit: <commit-id>
environment:
language: <version>
sdk: <package-and-version>
circuit:
logical_qubits: <number>
classical_bits: <number>
source_file: <path>
compiled_artifact: <path>
execution:
backend: <simulator-or-provider-backend>
shots: <number>
seed: <value-or-not-exposed>
noise_and_mitigation:
model: <description-or-none>
methods: []
results:
raw_artifact: <path>
processed_artifact: <path>
interpretation: <short-summary>Common mistakes
Recording only the final chart. A chart is an interpretation, not provenance. Keep raw counts, expectation values, parameter histories, and the script that generated the figure.
Using “latest” as a version. Replace vague labels with package versions, commit identifiers, container digests, or dated environment exports. If a provider-managed component cannot be pinned, record the metadata that is available and note the limitation.
Mixing logical and physical terminology. Logical qubits describe the algorithm; physical qubits and hardware mappings describe execution. Label both so a reader can understand what changed.
Ignoring failed or repeated jobs. Retries may alter queue timing, calibration context, or sampling totals. Record whether a result combines multiple jobs and how they were aggregated. The quantum job management guide provides a useful structure for this operational metadata.
Leaving assumptions in prose only. Put important settings in a structured record that can be parsed, checked, and rerun. A notebook narrative is valuable, but it should supplement machine-readable metadata.
Overstating reproducibility. Reproducing the same code may not reproduce the same hardware output. Distinguish exact reruns, statistically similar reruns, and conceptual replications.
When to revisit
Review the documentation template whenever the workflow or its inputs change. That includes moving between Qiskit, Cirq, PennyLane, Braket, Azure Quantum, or another SDK; changing compiler settings; switching simulator or hardware; adding noise modeling or error mitigation; changing the shot budget; or updating the classical post-processing pipeline. A quantum SDK migration playbook can help identify fields that need translation rather than simple renaming.
Use a formal review before seasonal planning cycles, paper or report preparation, major internal technical reviews, and transfers between teams. At minimum, run a small reproducibility check: create a clean environment, execute the documented command, verify that the circuit and configuration match, and compare outputs using an appropriate tolerance for sampling.
Make this checklist part of the pull request or experiment-completion workflow. Do not wait until a result becomes important. For the next experiment, copy the record, fill in the identity and hypothesis first, save raw artifacts during execution, and complete the interpretation only after the run has been independently checked. This small habit turns quantum experiment metadata from an afterthought into a dependable developer utility.