Skip to content
Quantum Mechanics

Running an Experiment

A computational experiment starts with a question, an executable model, and a criterion for agreement. Begin by reading the lab’s assumptions and expected results. A successful program exit confirms only that its execution completed; the physical and numerical checks determine what its output supports.

The experiment package

Section titled “The experiment package”

The three introductory packages contain a single entry command, the required code or notebook, requirements.txt, a README, numerical acceptance checks, and a notice identifying reuse terms. They run without a repository checkout. Existing investigations elsewhere in the collection also provide individual scripts and retained datasets; use the particular instructions and dependencies on those pages.

Extract a package into a new directory. Keep generated results separate from the supplied source and reference material. For the introductory packages, Python 3.12 and NumPy 2.3.5 are the recorded execution environment; compatibility with another version is a separate check.

Create an isolated Python environment

Section titled “Create an isolated Python environment”

In the extracted directory:

Terminal window
python -m venv .venv

On Windows PowerShell, use the environment’s executable directly:

Terminal window
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe run.py --output-dir results

On macOS or Linux:

Terminal window
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python run.py --output-dir results

These commands avoid reliance on an activated shell. Install only the package’s declared dependencies. The dependency installation may need internet access; the three introductory calculations themselves use local inputs and do not contact a network service. Reuse a compatible environment when appropriate, but record its actual versions.

Read the checks before changing the model

Section titled “Read the checks before changing the model”

Inspect results/summary.json and the experiment’s other output files. The report identifies the tested parameters, source files and named checks. Compare its numerical values with the explanation on the lab page. Source hashes establish which implementation ran; they do not establish scientific correctness.

Some investigations test an exact solution; others check conservation, residuals, independent implementations, or several refinement limits. Floating-point results need justified tolerances. A stochastic calculation additionally needs a sampling specification and statistical uncertainty; a fixed random seed alone is not an error estimate.

Once the supplied case passes, change one physical or numerical parameter at a time. Keep its outputs in a separate directory. The recorded verification applies to the declared fixture, not to every possible parameter choice. A study of a new regime needs its own domain, truncation and convergence checks.

Execution problems and scientific failures

Section titled “Execution problems and scientific failures”

An import failure normally indicates an environment problem. A missing input indicates an incomplete download or an incorrect working directory. A failed assertion can indicate an implementation defect, an unsupported regime, or an overly strict platform-dependent tolerance; inspect the measured quantity before relaxing the criterion.

Programs may refuse to overwrite existing outputs. Choose a fresh result directory rather than deleting a previous result that is still needed for comparison. Use Reproducibility Checklist for the broader error-budget and evidence questions, and Reproducing a Figure when reconstructing a visual result.

References

Section titled “References”