Reproducible Computational Environments

A reproducible computational environment is the complete record needed to rerun one finite claim and judge the regenerated outputs by a rule fixed in advance. A lockfile, container, checksum, or persistent identifier can secure one layer of that record, but no single layer captures the model, conventions, hardware, execution, numerical evidence, and scientific interpretation. Computational reproducibility therefore remains distinct from replication and from correctness, as emphasized by National Academies 2019, Summary pp. 6–9.

Helpful background. Computational Experiments and Reproducible Workflows develops the full workflow; Numerical Analysis, Verification, and Validation separates rerunning a calculation from verifying its equations and validating its model.

Minimum rerun record

Layer	Record before execution	Decisive check
Scientific claim	Quantity, model, regime, units, conventions, uncertainty, and acceptance rule	The regenerated quantity answers the same question
Source and workflow	Immutable revision, generated source, local changes, build files, entry point, and transformation graph	A clean tree reaches every claimed product without manual edits
Inputs	Exact data or generation recipe, schema, checksum, license, and access conditions	Retrieved bytes and interpreted units match the declared input
Dependencies and build	Resolved dependency graph, compiler or interpreter, flags, package sources, and rebuild recipe	Reconstruction does not consult a moving branch, tag, or package index
Runtime and hardware	Operating system or image digest, architecture, drivers, numerical libraries, precision, threads, ranks, and reduction policy	Every relevant substitution is recorded and tested
Randomness	Generator and version, distribution routine, key or seed mapping, sample count, and scheduling rule	Reordering work does not silently change the ensemble
Products	Raw and intermediate outputs, schemas, logs, diagnostics, discrepancies, and pass or failure	The comparison can be repeated without trusting a plot or summary
Preservation	Version-specific deposit, content identifiers, checksum package, metadata, and licenses	An uninvolved reader can retrieve and lawfully inspect the exact materials

A provenance graph should connect the entities used and generated by each activity, with the responsible software or person stated where it matters; the core relations are defined in Moreau and Missier 2013, PROV-DM §§ 2.1 and 5.1–5.3. The graph explains derivation. It does not show that the equations or tolerances were appropriate.

Identity layers are not interchangeable

Mechanism	What it fixes	What it does not prove
Revision or SWHID	A source snapshot or content-derived software object	Buildability, dependencies, or scientific validity
Resolved lockfile	A dependency solution under a named package ecosystem	Availability, compiler behavior, or hardware semantics
OCI image digest	Content-addressed image configuration and layers	Host kernel, CPU or GPU, driver, external service, or correct physics
SPDX SBOM	Components, relationships, and licensing or security metadata	That those components rebuilt or executed the result
PROV record	Which entities and activities used or generated one another	Numerical convergence or causal correctness of the graph
BagIt manifests	Package completeness and byte integrity	Meaning, executability, or correctness of the bytes
Version DOI	One deposited version rather than a work family	Content identity unless the deposited files are also verified

The source-identity syntax is specified in SWHID v1.2, §§ 4–6, checked 2026-08-24. OCI descriptors make content addressable through digests and sizes OCI Image Specification v1.1.1, Descriptor headings “Properties” through “Verification”, while SPDX provides a separate component and relationship model SPDX 3.0.1, complete specification, checked 2026-08-24. BagIt checksum and tag semantics are defined in Kunze et al. 2018, RFC 8493 §§ 2–3. For an exact rerun, cite the version DOI rather than only the concept DOI Zenodo 2026, “Which DOI should I use in citations?”, checked 2026-08-24.

Declare agreement before the rerun

Choose the comparison per product. Bitwise agreement requires identical bytes. Numerical agreement requires a declared quantity, norm, absolute and relative tolerances, and a reference. One useful normalized discrepancy is

$$D(Q,Q_*)= \frac{\lVert Q-Q_*\rVert} {a_{\rm abs}+a_{\rm rel}\lVert Q_*\rVert} \le 1.$$

Statistical agreement requires the estimand, sample construction, test or distance, uncertainty, and decision rule. The tolerance must reflect the scientific error budget rather than be widened after the preferred result is seen. Even exact bitwise reproduction can repeat a bug National Academies 2019, Summary p. 9.

Clean-rerun protocol

1. Retrieve the exact version, verify every identifier and checksum, and record the retrieval route.
2. Reconstruct on a clean host; after lawful inputs are fetched, disable network access and record every unavoidable substitution.
3. Run the documented entry point without editing source, inputs, intermediates, or thresholds.
4. Preserve raw products and logs, then compare them under the predeclared bitwise, numerical, or statistical rule.
5. Retain failed criteria and actual discrepancies instead of publishing only a successful figure.
6. Classify failure as identity, reconstruction, execution, numerical comparison, or scientific interpretation before changing the experiment.

Environments, Dependencies, and Precision develops cross-platform variation; Workflow Automation and Provenance develops the dependency graph; Determinism, Randomness, and Ensemble Runs develops statistical products; and Archiving and Independent Reproduction develops the preservation and uninvolved-runner test.

Common pitfalls

The container is treated as the experiment. Preserve rebuild materials and record host hardware, drivers, external services, and numerical controls that the image does not contain.

Availability is mistaken for reproducibility. Public code and data make a rerun possible only when their exact identities, semantics, entry point, and comparison rule are recoverable.

A successful rerun is called validation. Reproduction tests a declared computational path. Verification, convergence, uncertainty, and comparison with the physical system remain separate evidence.

References

• Kunze, John, John Littman, Liz Madden, Emily Scancella, and Chris Adams. “The BagIt File Packaging Format (V1.0).” RFC 8493. Internet Engineering Task Force, 2018. Specification.
• Moreau, Luc, and Paolo Missier, eds. PROV-DM: The PROV Data Model. W3C Recommendation, 30 April 2013. Specification.
• National Academies of Sciences, Engineering, and Medicine. Reproducibility and Replicability in Science. Washington, DC: National Academies Press, 2019. DOI.
• Open Container Initiative. 2025. OCI Image Format Specification, version 1.1.1. Descriptor specification.
• Software Heritage. 2026. Software Hash Identifier (SWHID) Specification, version 1.2. Specification.
• SPDX Project. 2024. System Package Data Exchange Specification, version 3.0.1. Specification.
• Zenodo. “Versioning.” Documentation checked 24 August 2026. Documentation.