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.