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. 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.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 |
|
|
|
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-minimalumbrella_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. |
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.