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 PyRETIS quick guide for users and LLMs and the examples/tutorials/README.rst README, so updating this page keeps the other two in sync.

Last refreshed

The most recent automated refresh stamp is written by examples/run-tutorials.sh (when invoked with PYRETIS_WRITE_REFRESH_STAMP=1) and is embedded below:

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 internal-engine suite was run on the date above from a temporary copy of the repository so that generated files in the working tree were not modified. The status pills on the individual tutorial pages (“passing”, “engine”, “smoke”, “manual”) reflect the same run.

The repository-level heavy entry point is:

./test-heavy.sh

It is a thin wrapper around examples/run-tests.sh and now also runs the tutorial smoke checks (examples/run-tutorials.sh) at the end. To run the tutorial smoke checks on their own:

examples/run-tutorials.sh

To skip the tutorial smoke checks inside the heavy suite:

PYRETIS_RUN_TESTS_SKIP_TUTORIALS=1 ./test-heavy.sh

This copies tutorial inputs to /tmp, starts each documented command, and intentionally stops long-running tutorials after a timeout. A timeout without errors counts as a successful startup; 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.

It runs the internal, GROMACS, PyVisA, CP2K, OpenMM, and LAMMPS example-test suites. The GROMACS part defaults to a smoke scope; set PYRETIS_GROMACS_SCOPE=full to run the full GROMACS matrix.

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.
  • 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; only the tutorial smoke runner checks that the command starts cleanly.
  • manual – requires a GUI, interactive session, or other manual step.
Tutorial folder Docs page Heavy-test fixture Status
path_sampling/1D-double-well/tis TIS in a 1D potential test-internal/tis-multiple, tis-restart passing
path_sampling/1D-double-well/retis RETIS in a 1D potential test-internal/retis, retis-restart, retis-load-sparse passing
path_sampling/1D-double-well/submoves Subtrajectory moves in a 1D potential test-internal/retis-ss-wt-wf passing
path_sampling/1D-double-well/repptis Partial path TIS (REPPTIS) in a 1D potential test-internal/partial-path, test-gromacs/test-repptis smoke
path_sampling/1D-double-well/flux Creating and running the initial flux simulation with PyRETIS test-internal/mdflux-restart passing
path_sampling/1D-double-well/tis-multiple TIS in a 1D potential test-internal/tis-multiple passing
path_sampling/1D-triple-well RETIS in a 1D triple-well: the zero_left shortcut test-internal/retis-zero-left passing
path_sampling/2D-hysteresis RETIS in a 2D potential test-internal/explorer (representative) smoke
path_sampling/2D-wca Breaking a bond with RETIS test-lammps/test-retis (representative) smoke
path_sampling/2D-wca-lammps Breaking a bond with RETIS and LAMMPS test-lammps engine
path_sampling/gromacs-hydrate Transport of methane in a sI hydrate test-gromacs, test-pyvisa engine
path_sampling/cp2k-hydrogen Dissociation of Hydrogen with CP2K test-cp2k engine
path_sampling/openmm-argon Running a PyRETIS simulation with OpenMM test-openmm/test-retis engine
path_sampling/permeability Studying permeability with PyRETIS tutorial smoke (permeability-retis) smoke
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/2D-hysteresis
  • path_sampling/2D-wca
  • path_sampling/permeability
  • 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 or cp2k.psmp.
OpenMM examples Attempted 2026-05-17 ./test-heavy.sh or examples/tests/test-openmm/run-all-openmm.sh openmm was importable locally, but the temp-copy run did not complete within the time allowed for this documentation pass.
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 TIS in a 1D potential Loading frames for free-energy landscape exploration and checking path, order, energy, and swap consistency.
partial-path RETIS in a 1D potential REPPTIS-style partial paths, analysis report generation, and trajectory consistency checks.
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-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.

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
cd docs && make html

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 usually caught by the Sphinx build before it becomes a broken website page; treat warnings as actionable.