Reproducible quantum computing experiments require more than saving a notebook. This guide provides a practical setup for locking dependencies, recording backend and runtime metadata, controlling randomness, serializing circuits and results, and handing simulator or hardware work to another engineer with enough context to rerun it.
Overview
A quantum experiment can change when its SDK, compiler, simulator, transpilation settings, device calibration, shot count, or classical preprocessing changes. Hardware results may also vary because the backend is calibrated at execution time. Reproducibility therefore has two meanings:
- Computational reproducibility: another person can recreate the environment and obtain the same deterministic or statistically comparable result.
- Experimental comparability: a later run may differ, but the team can explain the difference using recorded inputs, software, backend, and execution conditions.
Start every project by separating source code from generated artifacts. A small project structure might look like this:
quantum-project/
├── pyproject.toml
├── uv.lock or poetry.lock
├── README.md
├── src/
│ ├── circuits.py
│ ├── execute.py
│ └── analysis.py
├── notebooks/
│ └── 01_baseline.ipynb
├── configs/
│ └── experiment.yaml
├── data/
│ ├── raw/
│ └── processed/
├── results/
│ ├── metadata/
│ └── measurements/
└── tests/
Commit code, configuration, lockfiles, notebook outputs when they are useful for review, and small example inputs. Keep credentials, private datasets, and large raw job outputs outside source control. For a broader quality process, pair this setup with the enterprise CI/CD and testing checklist for hybrid quantum-classical workflows.
Checklist by scenario
Starting a new project
- Choose a supported language runtime and record its exact version.
- Pin the quantum SDK, simulator libraries, numerical packages, notebook tools, and any machine-learning framework.
- Generate and commit one dependency lockfile. Do not rely only on a broad requirement such as
package>=version. - Record the operating system, processor architecture, accelerator type if relevant, and environment manager.
- Define a stable experiment identifier and a separate run identifier. The experiment ID describes the design; the run ID describes one execution.
- Decide which values are configuration: qubit count, circuit depth, ansatz, feature-map settings, optimizer, shots, seed, backend, and mitigation options.
Running on a simulator
- Record simulator name, simulator version, precision mode, noise model, coupling map or topology assumptions, and basis-gate configuration where applicable.
- Use explicit seeds for every supported random source: the SDK or simulator, Python, NumPy, machine-learning framework, and data-splitting utility.
- Save the pre-transpilation circuit and the exact compiled circuit, not just the circuit-building code.
- Store shot count, measurement mapping, observable definitions, and the raw counts or samples.
- Run a small smoke test after environment creation. Confirm that qubit ordering, bit ordering, and measurement labels match the project convention.
Simulator choice can affect memory use, supported operations, and noise behavior. Use the quantum simulator benchmarking guide when deciding which simulator is appropriate, then record that decision in the experiment metadata rather than leaving it implicit.
Submitting to quantum hardware
- Save provider and backend identifiers exactly as returned by the SDK.
- Record the submission timestamp, job identifier, queue or execution status, shot count, transpilation options, and any runtime or session settings.
- Capture available backend properties, calibration references, connectivity, and gate or readout-error information at submission time.
- Keep the original circuit, compiled circuit, measured results, and post-processing output together.
- Do not describe a hardware run as bit-for-bit reproducible unless the provider and execution conditions support that claim. Treat it as a traceable observation with comparable settings.
For operational details such as submission, monitoring, retry handling, and job records, use the quantum cloud job management guide.
Running a quantum machine-learning experiment
- Save the dataset version or content hash, train-validation-test split, preprocessing parameters, feature order, labels, and class encoding.
- Record the classical baseline and its configuration before interpreting a quantum model result.
- Capture initialization, optimizer, learning rate, batch size, number of epochs, parameter values, stopping rules, and seed values.
- Store each training checkpoint or a clearly defined final model artifact.
- Repeat the experiment across more than one seed when the result is sensitive to initialization or sampling.
The quantum machine-learning data pipeline guide and QML experiment checklist cover the classical controls that make a quantum result interpretable.
Handing work to a teammate
- Provide a clean-install command and a one-command smoke test.
- Include a README with expected output ranges, not only a statement that the code runs.
- Attach one metadata file, one small input, one circuit artifact, and one result artifact.
- Explain which values must match exactly and which may vary because of hardware noise or randomized compilation.
- Ask the teammate to run from a fresh environment and record any differences before changing the code.
What to double-check
Dependency locking
Use a lockfile that resolves transitive dependencies for the target platform when possible. Record the package manager and installation command. A lockfile alone does not guarantee identical behavior: operating-system libraries, compiler versions, hardware acceleration, and floating-point behavior can still matter. For important reviews, preserve a container definition or environment export in addition to the lockfile.
Before upgrading an SDK, copy the current environment or create a new branch. Run a fixed regression suite containing a deterministic circuit, a seeded sampling circuit, and one representative workload. Compare both numerical outputs and compiled-circuit structure.
Randomness and seeds
A seed is useful only when it is passed to the component that owns the random operation. Set seeds deliberately, but do not assume one global seed controls every layer. Record whether the seed affects circuit generation, parameter initialization, shot sampling, data splitting, transpilation, or a provider-side runtime.
For statistical experiments, preserve the seed list rather than reporting only one seed. A seeded simulator can reproduce a sampling stream; it cannot make a noisy hardware device deterministic.
Metadata schema
Use a machine-readable record for every run. A practical schema can include:
{"experiment_id":"vqe_baseline_001","run_id":"2026-01-15T120000Z_seed_07","code_commit":"git-sha","environment":{"python":"exact-version","sdk":"exact-version","lockfile_hash":"hash"},"problem":{"qubits":4,"ansatz":"named-or-local-definition"},"execution":{"backend":"backend-id","mode":"simulator-or-hardware","shots":1024,"seed":7},"artifacts":{"input_circuit":"path-or-hash","compiled_circuit":"path-or-hash","raw_result":"path-or-hash"}}
Add provider-specific fields when available, but keep the core schema stable. Store timestamps in a consistent format and use hashes for files that may be moved between systems.
Circuit and result serialization
Prefer a framework-supported serialization format for the SDK version used by the project, and test deserialization immediately after writing. Text formats such as OpenQASM may improve portability, but they can omit framework-specific objects, custom gates, runtime options, or metadata. A native format may preserve more information but be less portable across SDK versions.
For results, save raw counts or samples before aggregation, along with the measurement-key convention. A minimal pattern is:
save_json({
"metadata": metadata,
"counts": counts,
"observables": observable_values
}, "results/measurements/run-07.json")
When the SDK exposes a result object with provider-specific fields, export a normalized project format as well as the original response. This protects analysis code from changes in provider response models.
Common mistakes
- Saving only the notebook. A notebook may hide installation state, execution order, environment variables, and uncommitted helper code. Restart the kernel and run all cells before review.
- Recording the backend name but not the compiled circuit. Transpilation settings can change the operations actually sent to a device.
- Confusing a seed with reproducibility. A seed does not control provider scheduling, calibration drift, hardware noise, or every library in a hybrid workflow.
- Overwriting raw results. Keep immutable raw outputs and create derived analysis files separately.
- Changing preprocessing during a quantum comparison. Feature scaling, encoding, column order, and data splits belong in the run record. See the quantum data encoding comparison for why encoding choices should be explicit.
- Applying error mitigation without recording its configuration. Save extrapolation points, calibration circuits, correction matrices, or other inputs used by the method. The error mitigation comparison provides a useful checklist of what can vary.
- Upgrading dependencies in place. Use a fresh environment and compare against a known-good run before accepting changed results.
When to revisit
Revisit this checklist before each planning or review cycle, and whenever the workflow changes. Trigger a new reproducibility review when:
- the SDK, simulator, Python runtime, operating system, or numerical library changes;
- the circuit compiler, transpiler settings, optimizer, noise model, or serialization format changes;
- the experiment moves from simulation to hardware or from one provider or backend to another;
- the dataset, feature encoding, train-test split, or classical baseline changes;
- the team changes notebook tooling, CI runners, containers, or artifact storage;
- a result changes and the reason is not immediately visible from the run metadata.
For the next experiment, create a clean environment, install from the lockfile, run the smoke test, generate a metadata record, serialize both the input and compiled circuits, and save raw results before analysis. Then ask a teammate—or a CI job—to reproduce the run from the repository alone. If the result differs, classify the difference as software, compilation, statistical sampling, data, backend, or hardware behavior before modifying the experiment. That habit turns reproducibility from a last-minute documentation task into a repeatable team capability. For planning a larger effort, pair this workflow with the enterprise quantum pilot checklist.