Example test status

This page is the canonical map between tutorial folders, documentation pages, and heavy-test fixtures. Every runnable tutorial should either have a passing check here or a clear reason why it is treated as an optional engine-dependent check. The same information is referenced (but not duplicated) by Agent-TIS quick start: PyRETIS for users and AI agents and the examples/tutorials/README.rst README, so updating this page keeps the other two in sync.

Last refreshed

examples/run-tutorials.sh writes a refresh stamp (the date, the numbers of tutorials passed, failed and skipped, and the timeout per case) to docs/_static/examples/tutorials-last-refresh.txt when it is run with PYRETIS_WRITE_REFRESH_STAMP=1. The stamp below dates from 2026-05-17 and has not been rewritten since; tutorials and checks added after that date are not in it:

Last refresh: 2026-05-17 00:00 UTC
Tutorials passed: 14 / 14 attempted
Tutorials failed: 0
Tutorials skipped (optional): engine-dependent cases when binaries missing
Runner: examples/run-tutorials.sh
Hard timeout per case: 10s
PyRETIS version: 4.0.0.dev0+4fa4079, Python 3.12.13

The status pills on the individual tutorial pages (“passing”, “engine”, “smoke”, “manual”) mirror the Status column of the tutorial map below.

The repository-level heavy entry point is:

./test-heavy.sh

It runs the internal, GROMACS, PyVisA, CP2K, OpenMM and LAMMPS example-test suites (examples/run-tests.sh, the GROMACS suite beside the others), then the tutorials (examples/run-tutorials.sh with PYRETIS_TUTORIAL_TIMEOUT=2s and PYRETIS_TUTORIAL_STEPS=20), then the tests of test/ marked heavy, which ./test-easy.sh leaves out, then the documentation build and its checks (devtools/docs/run_checks.py; see testing your installation for the Python they need). The GROMACS suite runs all of its cases; set PYRETIS_GROMACS_SCOPE=smoke for the quick 6-case subset. Its output is printed after the other suites; set PYRETIS_SUITES_PARALLEL=0 to run every suite in turn, each printing as it runs. When CUDA is available (nvidia-smi lists a GPU and CUDA_VISIBLE_DEVICES leaves one to the CUDA programs) and the CUDA build of GROMACS, LAMMPS or OpenMM is installed, the cases listed under What the CUDA passes cover also run on an NVIDIA GPU; PYRETIS_TEST_DEVICE=cpu runs the CPU passes only. To run the example-test suites alone:

examples/run-tests.sh

To run the tutorials alone:

examples/run-tutorials.sh

Run this way, every tutorial runs to completion, as it would for a user. The runner copies each tutorial to /tmp/pyretis-tutorial-run, which it empties first (set PYRETIS_TUTORIAL_WORKDIR for another folder), and starts its documented command. With PYRETIS_TUTORIAL_TIMEOUT=2s, a tutorial still running after 2 s without errors counts as started. With PYRETIS_TUTORIAL_STEPS=20, the path-sampling tutorials the runner shortens run 20 cycles to completion and are analysed with pyretis analyse, within PYRETIS_TUTORIAL_RUN_CAP (default 900s); the runner reports them as “ran 20 cycles and analysed them”. Early crashes, tracebacks, or PyRETIS ERROR/CRITICAL log messages are reported as failures. Optional external-engine and FORTRAN cases are skipped when the required commands are not available unless PYRETIS_TUTORIAL_STRICT=1 is set.

Tutorial map

The table below is the canonical mapping between tutorial folders under examples/tutorials/, their rendered documentation pages, and the heavy-test fixtures that exercise the same workflow. Tutorial READMEs and the LLM quick start refer to this table rather than repeating it.

The Status column uses four labels:

  • passing – covered by a heavy fixture that was passing on the last refresh, or by a test of ./test-easy.sh that runs the tutorial’s own input.

  • engine – covered by a heavy fixture but the suite requires an external program (gmx, cp2k, lmp, openmm) that may not be available locally.

  • smoke – not yet covered by a dedicated fixture. ./test-heavy.sh runs the tutorial and checks only that it runs without an error: 20 cycles and their analysis for the path-sampling tutorials the runner shortens, the first 2 s for the others (gromacs-hydrate-retis-cuda: until its first mdrun on the GPU has ended).

  • manual – requires a GUI, interactive session, or other manual step.

Tutorial folder

Docs page

Heavy-test fixture

Status

path_sampling/internal/1D-double-well/tis

TIS in a 1D potential

test-internal/tis-multiple, tis-restart

passing

path_sampling/internal/1D-double-well/retis

RETIS in a 1D potential

test-internal/retis, retis-restart, retis-restart-cv, retis-load-sparse

passing

path_sampling/internal/1D-double-well/submoves

Subtrajectory moves in a 1D potential

test-internal/retis-ss-wt-wf

passing

path_sampling/internal/1D-double-well/repptis

Partial path TIS (REPPTIS) in a 1D potential

test-internal/partial-path, test-gromacs/test-repptis

smoke

path_sampling/internal/1D-double-well/biretis

Bi-Retis

(none)

smoke

path_sampling/internal/1D-double-well/flux

Creating and running the initial flux simulation with PyRETIS

test-internal/mdflux-restart

passing

path_sampling/internal/1D-double-well/tis-multiple

TIS in a 1D potential

test-internal/tis-multiple

passing

path_sampling/internal/1D-double-well/minimal

A minimal input file

test/integration/test_minimal_input.py (runs the tutorial input)

passing

path_sampling/internal/1D-double-well/explore

Exploring the order parameter (explore task)

test-internal/explorer (representative)

smoke

path_sampling/internal/1D-triple-well

RETIS in a 1D triple-well: the zero_left shortcut

test-internal/retis-zero-left

passing

path_sampling/internal/2D-hysteresis

RETIS in a 2D potential

test-internal/explorer (representative)

smoke

path_sampling/internal/2D-wca

Breaking a bond with RETIS

test-lammps/test-retis (representative)

smoke

path_sampling/lammps/2D-wca

Breaking a bond with RETIS and LAMMPS

test-lammps (including test-load-sparse)

engine

path_sampling/lammps/H2/infinite_swapping

Infinite swapping (parallel replica exchange)

tutorial run (lammps-h2-infinite-swapping)

smoke

path_sampling/gromacs/hydrate

Transport of methane in a sI hydrate

test-gromacs, test-pyvisa

engine

path_sampling/cp2k/H2/retis

Dissociation of Hydrogen with CP2K

test-cp2k

engine

path_sampling/openmm/argon

Running a PyRETIS simulation with OpenMM

test-openmm/test-retis, test-openmm/test-load-sparse

engine

path_sampling/openmm/argon-minimal

A minimal input file with an external engine

tutorial run (openmm-argon-minimal)

smoke

path_sampling/gromacs/hydrate (retis-cuda.toml)

Transport of methane in a sI hydrate

tutorial run (gromacs-hydrate-retis-cuda), with a CUDA build of GROMACS

smoke

path_sampling/lammps/2D-wca (retis-cuda.toml)

Breaking a bond with RETIS and LAMMPS

tutorial run (lammps-wca-retis-cuda), with a CUDA build of LAMMPS

smoke

path_sampling/openmm/argon (retis-cuda.toml)

Running a PyRETIS simulation with OpenMM

tutorial run (openmm-argon-retis-cuda), with the OpenMM CUDA platform

smoke

path_sampling/internal/permeability

Studying permeability with PyRETIS

test-internal/permeability

passing

molecular_dynamics/md_nve/from_settings

Molecular dynamics using an input file

test-internal/md-restart

passing

molecular_dynamics/md_nve

Molecular dynamics using the PyRETIS library

test-internal/md-restart

passing

molecular_dynamics/md_nve/forward_backward

Molecular dynamics in PyRETIS with C or FORTRAN

test-internal/compare-internal-with-lammps

passing

umbrella_sampling

Umbrella Sampling

(none)

smoke

extending/order-parameter

examples-2d-hysteresis (representative)

test-internal (representative)

smoke

extending/lennard-jones

Using C or FORTRAN

test-internal/compare-internal-with-lammps

smoke

other/particle_swarm

Particle Swarm Optimization

(none)

smoke

Tutorials without a heavy check

The following tutorials are currently flagged smoke only. Before a release relies on their numerical output, add a shortened fixture under examples/tests/ and link it back to the corresponding docs page:

  • path_sampling/internal/1D-double-well/explore

  • path_sampling/internal/1D-double-well/repptis

  • path_sampling/internal/1D-double-well/biretis

  • path_sampling/internal/2D-hysteresis

  • path_sampling/internal/2D-wca

  • path_sampling/lammps/H2/infinite_swapping

  • path_sampling/openmm/argon-minimal

  • the CUDA inputs retis-cuda.toml of path_sampling/gromacs/hydrate, path_sampling/lammps/2D-wca and path_sampling/openmm/argon

  • umbrella_sampling

  • extending/order-parameter

  • extending/lennard-jones

  • other/particle_swarm

A “Verification status” line at the top of each docs page (see examples-*.rst) mirrors this column so the LLM rule “do not claim an example is fully verified unless it is listed as passing” has a single source of truth.

Suite

Status

Command

Notes

Internal engine examples

Passed 2026-05-17

./test-heavy.sh or examples/tests/test-internal/run-all-internal.sh

Covers pure-Python MD, flux, TIS/RETIS, restart, sparse load, partial paths, explorer, and sub-move style workflows.

LAMMPS examples

Engine available locally

./test-heavy.sh or examples/tests/test-lammps/run-all-lammps.sh

Requires lmp on PATH and a compatible LAMMPS build.

GROMACS examples

Engine available locally

./test-heavy.sh or examples/tests/test-gromacs/run-all-gromacs.sh

Requires gmx and the bundled reference input files.

CP2K examples

Engine available locally

./test-heavy.sh or examples/tests/test-cp2k/run-all-cp2k.sh

Requires cp2k on PATH (expose cp2k.psmp under that name, for example with a symbolic link).

OpenMM examples

Validated 2026-07-15

./test-heavy.sh or examples/tests/test-openmm/run-all-openmm.sh

OpenMM 8.5.1 source revision f7fa0c27 on the Reference platform; two clean runs were byte-identical and finite potential energy is checked.

PyVisA analysis examples

Optional GUI/analysis check

./test-heavy.sh or examples/tests/test-pyvisa/run-all-pyvisa.sh

Exercises the analysis helpers used by the PyVisA documentation.

What the internal suite covers

The internal suite is the main quick check because it does not depend on external molecular-dynamics programs. It should be run before every documentation release and after changes to examples, input parsing, path ensembles, internal engines, or analysis output.

Test directory

Related documentation

What it validates

compare-internal-with-lammps

Molecular dynamics examples

Internal Lennard-Jones MD agrees with saved LAMMPS reference thermodynamic output.

explorer

Exploring the order parameter (explore task)

Loading frames for free-energy landscape exploration, and the structural validity of the explore run: the ensemble directory layout, the path length and order-parameter rules, order.txt in lockstep with pathensemble.txt, and committed (non-loaded) moves.

partial-path

Partial path TIS (REPPTIS) in a 1D potential

REPPTIS-style partial paths, analysis report generation, and the structural validity of the REPPTIS run.

permeability

Studying permeability with PyRETIS

The permeability RETIS run (zero_left, mirror and target-swap moves) and comparison against saved reference data.

pptis

the pptis task

A PPTIS run without the \([0^-]\) and \([0^+]\) ensembles, its analysis, and the structural validity of the run.

mdflux-restart

Creating and running the initial flux simulation with PyRETIS

MD-flux runs and restart equivalence.

md-restart

Molecular dynamics examples

NVE restart equivalence for Langevin and Velocity Verlet engines.

retis

RETIS in a 1D potential

A small RETIS run, analysis, and comparison against saved reference data.

retis-load-sparse

RETIS in a 1D potential

Loading sparse paths from trajectories and from individual frames.

retis-restart

RETIS in a 1D potential

RETIS restart behavior and output reproducibility.

retis-restart-cv

Adding collective variables when you restart

Adding a collective variable to a running simulation: the new column is recorded from the restart on, and the sampling is unchanged relative to a restart without it.

retis-ss-wt-wf

Subtrajectory moves in a 1D potential

Stone skipping, web throwing, and wire fencing moves.

tis-multiple

TIS in a 1D potential

Multiple TIS ensembles and analysis output.

tis-restart

TIS in a 1D potential

TIS restart behavior and output reproducibility.

What the CUDA passes cover

The GROMACS, OpenMM and LAMMPS suites run these 12 cases a second time on an NVIDIA GPU when CUDA is available (nvidia-smi lists a GPU and CUDA_VISIBLE_DEVICES leaves one to the CUDA programs) and the CUDA build of their engine is installed (PYRETIS_TEST_DEVICE=auto, the default, which runs the CPU passes only when CUDA is not available; cuda fails an engine without a CUDA build, and every engine when CUDA is not available; cpu runs the CPU passes only). The CUDA build of GROMACS is the command of PYRETIS_GMX_CUDA (default gmx_cuda), that of LAMMPS the command of PYRETIS_LMP_CUDA (default lmp_cuda), and that of OpenMM its CUDA platform. With CUDA available, a CUDA build that does not run on the GPU fails the suite, and so does a PYRETIS_GMX_CUDA or PYRETIS_LMP_CUDA that is set and names neither an executable file nor a command on PATH. A CUDA pass that fails keeps its copy of the case (<case>-cuda-pass) and ends the suite with exit status 1. Cases that have no CUDA pass run on the CPU only. The CPU and CUDA passes of the engine suites describes the passes and their grading.

Case

What its CUDA pass checks

test-gromacs/test-gromacs

Each of the four runs over at most 50 MD steps: the order parameters within a mean squared error of 1e-9, the kinetic and potential energies within 3e-5 relative at every frame.

test-gromacs/test-integrate/gromacs, gromacs2

The energies of the engine against its own .edr (mean squared error 1e-5) and against an independent GPU mdrun (3e-5 relative at every frame).

test-gromacs/test-repptis

The structure of the run.

test-gromacs/test-retis

The accepted paths are valid in their ensembles, and each accepted zero swap joins the frames of the paths it started from.

test-openmm/test-retis

The run on the CUDA platform in double precision with deterministic forces against its CUDA references (openmm/results-cuda-double; relative 1e-5 plus absolute 2e-6). Validated on the OpenMM build of those references (8.5.1, revision f7fa0c2), not validated on another build. On another GPU the numbers differ in the last printed digits (up to 1.0e-6 in energy.txt and order.txt between a Quadro T2000 and a Quadro K2200).

test-openmm/test-load-sparse

The relaxed paths.

test-lammps/test-dump-phasepoint, test-integrate, test-modify-velocities

The CPU references, file by file and column by column within tolerances (dumps as text with the atoms in id order; energies and temperature relative 1e-5 plus the print resolution of energy.txt; order parameters absolute 1e-5; thermo.txt with the print resolution added, its temperature and energies up to step 25, its pressure at every step).

test-lammps/test-load-sparse

The relaxed paths.

test-lammps/test-streaming

The streaming engine against the relaunch engine.

The tutorial runner (examples/run-tutorials.sh) adds three CUDA tutorials, gromacs-hydrate-retis-cuda, lammps-wca-retis-cuda and openmm-argon-retis-cuda, which run the retis-cuda.toml of the tutorial. Under PYRETIS_TEST_DEVICE=auto, when CUDA is not available or without the CUDA build, they are skipped and listed apart, and PYRETIS_TUTORIAL_STRICT=1 does not count them as failures; under cuda they fail with CUDA REQUIRED.

How to refresh this page

Run the quick suite first:

cd examples/tests/test-internal
./run-all-internal.sh

Then run the optional engine suites in an environment where the corresponding programs are installed:

cd examples/tests/test-lammps
./run-all-lammps.sh

cd ../test-gromacs
./run-all-gromacs.sh

cd ../test-cp2k
./run-all-cp2k.sh

cd ../test-openmm
./run-all-openmm.sh

cd ../test-pyvisa
./run-all-pyvisa.sh

When a suite passes, update the status table with the date, platform, PyRETIS version, and any engine version that matters for reproducing the run.

Documentation build check

The examples pages use literalinclude directives to render input files. To avoid drift between the rendered docs and the runnable tutorials, run the sync helper before building:

python docs/sync_example_assets.py        # report drift only
python docs/sync_example_assets.py --fix  # update _static
PYTHONPATH=$PWD python devtools/docs/run_checks.py  # build and check

The helper copies a small manifest of input files from examples/tutorials/ into docs/_static/examples/. Add new entries to the MANIFEST list when a new tutorial page gains a literalinclude directive.

A missing example asset is caught by the build before it becomes a broken website page: run_checks.py builds with -W, so a warning fails it.