A reproducible environment is a computational setup that another person can recreate from a recorded specification. For a quant, this helps keep a valuation or backtest from changing because a different interpreter, package build or machine setting was used. Recreating that setup is one part of reproducing a result: the code, configuration and original data must also be available.
What needs to be recorded?
A virtual environment isolates a Python project's installed packages. Its directory is disposable and generally non-portable; Python recommends recreating it at the destination. Preserve the recipe and required artifacts, rather than treating a copied environment folder as the reproducibility record. Python's venv documentation explains this distinction.
| Record | Why it matters |
|---|---|
| Interpreter implementation and version | Python implementations and releases can differ in supported behavior. |
| Direct and transitive package versions; installation artifacts or their hashes | Package pinning narrows versions; artifact hashes identify the downloads used. |
| Native libraries, operating system and processor architecture | Compiled packages and numerical backends may depend on the platform. |
| Relevant execution settings | Thread counts, locale, timezone and environment variables can affect programs that use them. Record required settings without storing secrets. |
| Reconstruction instructions | A version list is useful only if the matching interpreter and artifacts can still be obtained and the setup can be rebuilt. |
pip describes progressively stronger forms of repeatable installation: exact versions, hash checking and retained installation bundles. Its documentation also warns that bundles containing compiled packages can be specific to an operating system and architecture. A package list alone does not capture the entire machine.
Keep a run record beside this environment record: the exact source revision or source archive checksum, input snapshot and checksum, full configuration, command, relevant random-generator settings, and output to compare. Version control identifies tracked code; it does not automatically retain external market data. A checksum helps identify bytes but cannot recover a file that was never preserved.
Same environment, different price
Suppose a fictional position contains 2 shares. The saved price snapshot is USD 100 per share, so its value is USD 200. Later, a replacement snapshot reports USD 110 per share and the same calculation returns USD 220. Neither an unchanged environment nor an unchanged source file makes the replacement data equal to the original data.
Fictional example. Rebuilding the environment holds the computational setup fixed; replaying the original result also requires the original input bytes.
This standard-library example keeps both fictional snapshots in memory. It compares the exact input bytes rather than trusting a stable filename:
from hashlib import sha256
import json
snapshots = {
"original": b'{"price_usd": 100}',
"revised": b'{"price_usd": 110}',
}
quantity = 2
saved_digest = sha256(snapshots["original"]).hexdigest()
for label, data in snapshots.items():
price = json.loads(data)["price_usd"]
print(f"{label}: USD {quantity * price}")
# original: USD 200
# revised: USD 220
matches = sha256(snapshots["revised"]).hexdigest() == saved_digest
print(f"Revised input matches saved checksum: {matches}")
# Revised input matches saved checksum: FalseThe environment is held fixed inside this run. Replaying it with
snapshots["original"] recovers USD 200 because the original bytes were retained. In a real research package, preserve an accessible snapshot with its economic meaning: instrument identifiers, currency, timestamp and adjustment policy. Identical bytes can still represent the wrong market convention or contain look-ahead information. Reproduction makes a claim inspectable; it does not establish its financial validity.Decide what “same result” means
Bitwise reproduction requires identical compared output bytes. Numerical reproduction within tolerance permits declared differences in specified quantities. State which contract applies before examining a mismatch; exclude volatile metadata such as run timestamps from a numerical comparison.
For example, a fictional valuation check might permit an absolute difference of 0.000001 USD and no relative tolerance. That accepts a replay of 200.0000004 USD against 200 USD, but rejects 200.01 USD:
from math import isclose
print(isclose(200.0000004, 200.0, rel_tol=0.0, abs_tol=0.000001))
print(isclose(200.01, 200.0, rel_tol=0.0, abs_tol=0.000001))
# True
# FalseThis is an illustrative comparison rule, not a universal valuation standard. Choose tolerances from units, algorithmic error and the decision being made. Python's
math.isclose combines an absolute and a relative bound; setting the relative bound to zero makes this check purely absolute. Passing it does not prove bitwise equality or explain why two calculations differ.A fixed random seed also needs a precise contract. NumPy's random compatibility policy gives strict conditions involving the generator, seed, method calls and arguments, build, environment and machine. Native linear-algebra libraries can affect some generated samples. Record the generator and relevant execution details, then test the promised replay; a seed does not freeze every stochastic computation across platforms or releases. The valuation example above is deterministic and needs no seed.
Further learning
Reproducible Environments develops the computational record and clean-state command. Reproducible research applies second-person replay to a research dossier. Both offer public previews; their full lessons require membership.
Sources
- Python documentation: venv — isolation, disposal and recreation at a new location.
- pip documentation: Repeatable Installs — version pins, artifact hashes and platform-specific installation bundles.
- NumPy documentation: Random compatibility policy — the conditions for stream reproduction.
- Python documentation: math.isclose — absolute and relative comparison bounds.