Reproduce the Paper

This page is the published-docs counterpart to the repo-level REPRODUCIBILITY.md guide. Use it when you want the shortest supported path for replaying the paper-facing artifact bundle without digging through legacy scripts or CI config.

The canonical rerun surface is the committed artifacts/paper_2026/ bundle, the pinned package zeroproofml==0.4.3, and the matching v0.4.3 release tag. Current v0.6.x benchmark commands are maintained as smoke/regression checks, not as paper-exact reruns.

The paper bundle and the requirements-paper.txt / requirements-bench.txt lock files live in the current release tree; they are not part of the v0.4.3 source tag. Keep this checkout available, or copy those files, when creating a v0.4.3 replay checkout.

Paper-exact contract targets v0.4.3. The paper artifact bundle was produced on the v0.4.3 tag (commit cc9a6635). For paper-exact reproduction, pin to zeroproofml==0.4.3 (or check out the v0.4.3 tag) and use its recorded environment. The current v0.6.1 Makefile refuses make reproduce-paper rather than launching current code and presenting it as a paper rerun. Use make benchmark-contract for current release contract runs.

Quickest supported path

For a paper-exact replay from a source checkout:

# from the current checkout that contains artifacts/paper_2026/
export ZPML_REPLAY_ROOT="$PWD"
git worktree add ../zeroproofml-v043-replay v0.4.3

python -m venv ../zeroproofml-paper-venv
. ../zeroproofml-paper-venv/bin/activate
python -m pip install -r "$ZPML_REPLAY_ROOT/requirements-paper.txt"
python -m pip install -e ../zeroproofml-v043-replay

cd ../zeroproofml-v043-replay
# run the commands recorded in "$ZPML_REPLAY_ROOT/artifacts/paper_2026/commands.json"

Run those commands from the v0.4.3 checkout, or from a directory outside the current source checkout, so Python imports the pinned 0.4.3 package rather than the current v0.6.x working tree.

For a current v0.6.1 contract check instead:

python -m pip install "zeroproofml[benchmarks]"
make benchmark-contract
python -m zeroproofml.benchmarks dose --mode contract --device cpu

Use --out-root if you want current smoke outputs outside the default results/benchmarks/ tree.

What the paper bundle freezes

artifacts/paper_2026/ records the current paper-facing replay contract:

  • manifest.json: artifact metadata, package version, git commit, and pinned CPU/GPU container recipes.
  • commands.json: exact replay commands for the frozen paper artifact.
  • configs/: captured argument snapshots for each replay command.
  • expected_outputs.json: required files under each output root.
  • metric_tolerances.json: allowed drift bands for rerun comparisons.
  • checksums.sha256: SHA256 digests for the artifact files and pinned environment locks that define the bundle. Current v0.6.x source files are intentionally not part of this frozen v0.4.3 checksum contract.
  • archive_record.json: DOI archive status and published Zenodo DOI for the paper artifact snapshot.
  • traceability.yaml: the bridge from the software citation and frozen command IDs to the expected run manifests plus table/figure source conventions. The manuscript itself is not stored here, so this records reproducibility inputs rather than silently claiming a current-code paper reproduction.

Paper Version And Bundle Schema

The canonical package pin for reproducing the paper artifact bundle is zeroproofml==0.4.3; use the matching release tag v0.4.3 when replaying from a release checkout. artifacts/paper_2026/manifest.json records "package_version": "0.4.3"; keep that manifest and each bundle's recorded schema metadata with the artifact, and do not reinterpret paper-era bundles under newer strict-inference bundle schemas.

Native and containerized reruns

  • Native CPU from source: Python 3.10 with pip install -r "$ZPML_REPLAY_ROOT/requirements-paper.txt", then pip install -e <v0.4.3-checkout>. requirements-paper.txt delegates to the shared requirements-bench.txt lock used by native benchmark reruns.
  • Native CPU from package: install requirements-paper.txt, then install zeroproofml==0.4.3, and run from a directory that is not the current source checkout.
  • Containerized: build one of the recipes listed in artifacts/paper_2026/manifest.json from the current checkout, then mount the v0.4.3 replay checkout at /workspace when running the container.
  • DOI archive: artifacts/paper_2026/archive_record.json records the published Zenodo DOI 10.5281/zenodo.18944465 and record URL https://doi.org/10.5281/zenodo.18944465.

What to keep for an auditable rerun

For a paper-grade replay, retain:

  • the repo commit you ran,
  • the relevant files from artifacts/paper_2026/,
  • the produced run directory under the recorded results/paper_2026/... output root, or the explicit --out-root you used,
  • the generated run-local manifest.json / provenance.json files.

Where to go next

  • Start at 21_experiments.md for the broader benchmark, deployment, and archived-workflow map.
  • Keep REPRODUCIBILITY.md as the compact repo-root version of this same guidance when you need a top-level file outside the published docs site.