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.shthat 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.shruns 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 firstmdrunon the GPU has ended).manual– requires a GUI, interactive session, or other manual step.
Tutorial folder |
Docs page |
Heavy-test fixture |
Status |
|---|---|---|---|
|
|
passing |
|
|
|
passing |
|
|
|
passing |
|
|
|
smoke |
|
|
(none) |
smoke |
|
|
Creating and running the initial flux simulation with PyRETIS |
|
passing |
|
|
passing |
|
|
|
passing |
|
|
|
smoke |
|
|
|
passing |
|
|
|
smoke |
|
|
|
smoke |
|
|
|
engine |
|
|
tutorial run ( |
smoke |
|
|
|
engine |
|
|
|
engine |
|
|
|
engine |
|
|
tutorial run ( |
smoke |
|
|
tutorial run ( |
smoke |
|
|
tutorial run ( |
smoke |
|
|
tutorial run ( |
smoke |
|
|
|
passing |
|
|
|
passing |
|
|
|
passing |
|
|
|
passing |
|
|
(none) |
smoke |
|
|
examples-2d-hysteresis (representative) |
|
smoke |
|
|
smoke |
|
|
(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/explorepath_sampling/internal/1D-double-well/repptispath_sampling/internal/1D-double-well/biretispath_sampling/internal/2D-hysteresispath_sampling/internal/2D-wcapath_sampling/lammps/H2/infinite_swappingpath_sampling/openmm/argon-minimalthe CUDA inputs
retis-cuda.tomlofpath_sampling/gromacs/hydrate,path_sampling/lammps/2D-wcaandpath_sampling/openmm/argonumbrella_samplingextending/order-parameterextending/lennard-jonesother/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 |
|
Covers pure-Python MD, flux, TIS/RETIS, restart, sparse load, partial paths, explorer, and sub-move style workflows. |
LAMMPS examples |
Engine available locally |
|
Requires |
GROMACS examples |
Engine available locally |
|
Requires |
CP2K examples |
Engine available locally |
|
Requires |
OpenMM examples |
Validated 2026-07-15 |
|
OpenMM 8.5.1 source revision |
PyVisA analysis examples |
Optional GUI/analysis check |
|
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 |
|---|---|---|
|
Internal Lennard-Jones MD agrees with saved LAMMPS reference thermodynamic output. |
|
|
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, |
|
|
REPPTIS-style partial paths, analysis report generation, and the structural validity of the REPPTIS run. |
|
|
The permeability RETIS run ( |
|
|
A PPTIS run without the \([0^-]\) and \([0^+]\) ensembles, its analysis, and the structural validity of the run. |
|
|
Creating and running the initial flux simulation with PyRETIS |
MD-flux runs and restart equivalence. |
|
NVE restart equivalence for Langevin and Velocity Verlet engines. |
|
|
A small RETIS run, analysis, and comparison against saved reference data. |
|
|
Loading sparse paths from trajectories and from individual frames. |
|
|
RETIS restart behavior and output reproducibility. |
|
|
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. |
|
|
Stone skipping, web throwing, and wire fencing moves. |
|
|
Multiple TIS ensembles and analysis output. |
|
|
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 |
|---|---|
|
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. |
|
The energies of the engine against its own |
|
The structure of the run. |
|
The accepted paths are valid in their ensembles, and each accepted zero swap joins the frames of the paths it started from. |
|
The run on the CUDA platform in double precision with
deterministic forces against its CUDA references
( |
|
The relaxed paths. |
|
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
|
|
The relaxed paths. |
|
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.