Reproducible Quantum Computing Experiments: A Checklist for Notebooks, Dependencies, and Results
reproducibilityquantum researchquantum notebooksexperimentsquantum softwaredeveloper workflow

Reproducible Quantum Computing Experiments: A Checklist for Notebooks, Dependencies, and Results

QQubit Directory Editorial Team
2026-11-13
8 min read

A practical checklist for recording quantum circuits, dependencies, backend settings, randomness, results, and artifacts for reproducible experiments.

A quantum experiment is not reproducible merely because its notebook runs once. This checklist shows what to record about circuits, software dependencies, backend settings, randomness, noise, results, and artifacts so a teammate, reviewer, or future version of yourself can rerun the work with fewer assumptions.

Overview

Reproducibility in quantum computing has two related goals. Repeatability means running the same procedure again under the same conditions and obtaining comparable results. Portability means moving the experiment to a different machine, simulator, SDK version, or cloud platform while making the changes visible and interpretable.

Both goals require more than saving a Jupyter notebook. A notebook may contain executable code, but it can also hide package versions, environment variables, generated circuit transformations, backend defaults, and manual steps. A useful record separates the experiment into four layers:

  • Definition: the algorithm, circuit, inputs, observables, and success criteria.
  • Execution: the simulator or quantum device, transpilation settings, shots, noise model, and runtime configuration.
  • Environment: the SDK, language runtime, operating system, dependencies, and credentials setup.
  • Evidence: raw results, processed data, figures, logs, circuit representations, and metadata.

Use the checklist below before publishing results, handing a project to another developer, changing a backend, or archiving an experiment. If you are selecting an SDK or platform, the comparison guidance in Quantum SDKs Compared can complement this workflow.

Checklist by scenario

1. Before running a simulator experiment

  • Record the experiment name, research question, hypothesis, and a short description of the expected outcome.
  • Save the circuit definition in a machine-readable form, not only as an image. Include qubit count, classical-bit count, gate sequence, parameter values, measurement mapping, and any custom instructions.
  • Identify the algorithm or subroutine and state which metrics will be measured. Examples include bitstring frequencies, expectation values, approximation error, runtime, or convergence.
  • Record the simulator name and configuration, including statevector, shot-based, tensor-network, stabilizer, or other simulation method when relevant.
  • Set and record random seeds for circuit generation, parameter initialization, sampling, and noise generation. A seed is useful only if the relevant software actually uses it and the seeded components are documented.
  • Record the number of shots, repetitions, batches, and optimization iterations. Do not rely on an SDK default remaining unchanged.
  • If noise is included, save the complete noise model or the code that constructs it. Document whether errors are applied by gate, measurement, readout, relaxation, or another mechanism.
  • Save both raw output and derived metrics. A histogram alone may not be enough to reconstruct expectation values or filtering decisions.

2. Before submitting to a real quantum device

  • Record the provider, service or project context, backend identifier, and the date and time of submission when those details affect interpretation.
  • Capture the backend properties used for the run, or save a reference to the provider response if the platform exposes calibration metadata. Relevant fields may include available qubits, connectivity, gate support, readout information, and timing data.
  • Save the original circuit and the transpiled or compiled circuit. These are different artifacts and should not be treated as interchangeable.
  • Document optimization level, routing method, basis-gate choices, layout, initial mapping, dynamical decoupling, error mitigation, and any other compilation or runtime options.
  • Record shot count, queue or execution mode when relevant, measurement settings, and any post-processing performed by the platform or your own code.
  • Store the job identifier and status history where possible. A job ID should support discovery of the result without exposing an access token.
  • Note whether the device or service changed between planning and execution. Hardware calibration and availability can vary, so the recorded execution context matters.

For a first real-device run, use this checklist alongside the Quantum Hardware Access Checklist. For context on device trade-offs, see Quantum Computing Hardware Architectures Compared.

3. Before sharing a notebook with a teammate

  • Restart the kernel and run every cell from top to bottom in a clean environment. This catches hidden state, undeclared variables, and dependencies on execution order.
  • Replace hard-coded local paths with configurable paths or repository-relative paths.
  • Separate setup, experiment, analysis, and visualization cells. A reader should be able to identify which cells perform a run and which only format results.
  • Make expensive or remote execution explicit. A rerun guide should say whether a cell submits a cloud job, consumes credits, or uses a local simulator.
  • Include a small smoke test that checks imports, circuit construction, expected dimensions, and result parsing before a full run.
  • Provide a README with setup commands, expected runtime, required access, output locations, and a short example invocation.
  • Export important outputs to files rather than leaving them only in notebook state. Use stable names and include run metadata alongside each result.

4. Before submitting research or archiving a project

  • Freeze the code revision with a commit hash, release tag, or archived snapshot.
  • Include dependency manifests and, where practical, a lockfile or environment specification. Record the language runtime and operating system as well.
  • Preserve raw data, processed data, scripts, notebooks, figures, tables, and configuration files as separate, clearly labeled artifacts.
  • Write a data dictionary for non-obvious fields, units, column names, measurement conventions, and filtering rules.
  • Describe failed runs, discarded circuits, outlier handling, and changes made after an initial result. Excluding these details can make a successful result difficult to interpret.
  • Check that another person can follow the instructions without access to your personal machine, private filesystem, or undocumented credentials.

The Quantum Research Resources Directory can help you identify repositories, datasets, and research workflows to reference when organizing a public project.

What to double-check

Dependencies and environments

Record direct dependencies explicitly, including the quantum SDK, simulator packages, numerical libraries, notebook tooling, and plotting libraries. A package manifest alone may not reveal the language version or system-level requirements. When the experiment depends on a provider plugin, compiler extension, accelerator, or optional feature, list it separately.

Prefer a reproducible environment definition over an informal statement such as “install the latest SDK.” Pin exact versions for a publication or controlled handoff when compatibility matters. For exploratory work, a constrained version range may be appropriate, but test the documented range and state the assumption. Recheck the environment after rebuilding it from scratch.

Randomness and statistical interpretation

List every source of randomness you can identify. This may include circuit generation, initial parameters, simulator sampling, noise sampling, optimizer behavior, and data shuffling. A single global seed may not control all of these sources.

Also record how results are summarized. State whether values are based on raw counts, normalized frequencies, expectation estimates, repeated independent runs, or an average across seeds. If you report uncertainty, document the calculation and the number of independent samples behind it.

Circuit transformations

Save the circuit before compilation and the circuit actually executed. Record transpilation or compilation settings, because changes in optimization, qubit layout, routing, decomposition, or supported gate set can alter depth and behavior. When comparing backends, distinguish a change in hardware from a change introduced by compilation.

A circuit diagram is valuable for review, but it should accompany a serialized or code-based representation. Images are difficult to validate, search, diff, or rerun.

Credentials and sensitive configuration

Never place API keys, access tokens, private certificates, or secrets in notebooks, commits, screenshots, or exported logs. Document the variable names, authentication method, required permissions, and safe setup process without recording the secret itself. If a notebook was shared after containing credentials, treat the credential as exposed and follow the relevant rotation procedure.

Result provenance

Each result file should be traceable to a code revision, configuration, circuit version, backend, and run identifier. A practical metadata record can include:

  • experiment and run IDs;
  • code commit or archive version;
  • SDK and runtime versions;
  • circuit or problem-instance identifier;
  • backend and execution timestamp;
  • shots, seeds, and noise or mitigation settings;
  • raw output location and processing script;
  • notes about warnings, retries, exclusions, or manual intervention.

For testing and inspection ideas, consult the Quantum Circuit Testing and Debugging Tools Directory.

Common mistakes

  • Saving only the final figure: A plot cannot usually reconstruct raw counts, preprocessing, or the circuit that produced it.
  • Relying on notebook order: Variables left in memory can make a notebook appear correct when a clean run would fail.
  • Recording the platform but not the backend: A cloud provider may expose several devices and simulators with different behavior.
  • Confusing logical and executed circuits: The algorithmic circuit may differ substantially from the compiled circuit.
  • Using “default” as a setting: Defaults can change across SDK releases, providers, or execution modes. Write down the effective value when it matters.
  • Publishing a lockfile without a setup guide: A locked environment still needs instructions for credentials, system packages, data, and commands.
  • Overwriting raw results: Keep original outputs immutable and create derived files for cleaning, aggregation, or visualization.
  • Ignoring failed or excluded runs: A short note explaining exclusions is more useful than silently removing them.
  • Assuming a seed guarantees identical hardware results: Seeds can control software randomness, but they do not make a changing physical device deterministic.

When to revisit

Revisit this checklist whenever the workflow or its inputs change, not only when a paper is nearly complete. A practical review schedule includes the following checkpoints:

  • At project start: Choose the metadata fields, repository structure, environment format, and artifact locations before collecting results.
  • Before a seasonal planning cycle: Confirm that the chosen SDKs, cloud services, simulators, and storage practices still fit the team’s access and maintenance requirements.
  • Before moving to another backend: Re-record backend identity, calibration context, compilation settings, supported gates, shots, and execution constraints.
  • After a major software update: Rebuild the environment, rerun smoke tests, compare circuit transformations, and check result parsing.
  • Before sharing or publishing: Run from a clean environment, inspect the repository for secrets, verify artifact links, and ask someone unfamiliar with the project to follow the instructions.
  • After an unexpected result: Compare seeds, dependencies, circuit versions, backend metadata, job logs, and post-processing before changing the experiment.

Use the checklist as a gate rather than a retrospective exercise. Create a project template containing an environment file, metadata schema, README, smoke test, raw-results directory, and analysis script. Then require every run to produce a small manifest linking its inputs, execution context, and outputs. This habit makes quantum experiments easier to review, compare, move between platforms, and revisit months later.

For broader learning and workflow planning, see the practical quantum computing learning path for developers and the quantum computing learning path.

Related Topics

#reproducibility#quantum research#quantum notebooks#experiments#quantum software#developer workflow
Q

Qubit Directory Editorial Team

Editorial Team

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.