Using heavy checks as tutorials

The directories under examples/tests/ are consistency checks, but they are also useful minimal setups. This page translates them into user-facing recipes. The difference is intent:

• In examples/tests/, the goal is to reproduce reference output.
• In examples/tutorials/, the goal is to understand the input files well enough to adapt them to a new simulation.

The same recipes are shipped next to the code in examples/tutorials/from_tests/README.rst so they stay in sync with the heavy-test folder layout.

Internal engine

Start from examples/tests/test-internal/ when you want a small, dependency-free template.

Test fixture	What it is useful for	How to turn it into a tutorial setup
retis	Minimal RETIS with the internal Langevin engine.	Copy retis.rst and initial.xyz; then change interfaces, steps, and potential parameters.
tis-multiple	Splitting a multi-ensemble TIS setup into per-ensemble input files.	Start from tis-multiple.rst and inspect the generated tis-001.rst-style files.
md-restart	Restarting MD with Langevin or Velocity Verlet.	Use it to learn which restart files are created and which settings can be overridden.
mdflux-restart	Initial flux and flux restarts.	Use it before designing a TIS/RETIS workflow that needs a flux estimate.
retis-load-sparse	Loading paths from sparse trajectory data.	Use it when your starting trajectories come from another tool.
retis-ss-wt-wf	Stone skipping, web throwing, and wire fencing.	Use it after the 1D RETIS tutorial to understand sub-move choices.
retis-zero-left	Zero-left bounded reactant basin.	Pair it with RETIS in a 1D triple-well: the zero_left shortcut to see the zero_left shortcut.
compare-internal-with-lammps	Internal Lennard-Jones MD agreement with LAMMPS reference output.	Use it as a unit-conversion sanity check before swapping engines.
explorer	Loading frames for free-energy landscape exploration.	Use it after the 2D-hysteresis tutorial.
partial-path	REPPTIS-style partial paths.	Use it once you have a working REPPTIS input.

External engines

External-engine checks are best used as dependency-specific templates. First verify that the external program works in your environment, then copy the input folder and adapt one setting at a time.

Suite	Use it for	First adaptation
test-gromacs	GROMACS command execution, file staging, sparse loading, restart, RETIS, and REPPTIS.	Replace the GROMACS coordinate/topology files, then update the order parameter.
test-lammps	LAMMPS propagation, velocity modification, phase-point dumping, and RETIS.	Replace system.data and lammps.in while keeping order.in simple until propagation works.
test-cp2k	CP2K execution, integration, and loading RETIS results.	Start with the hydrogen input and change only the CP2K input file once the runner is configured.
test-openmm	OpenMM RETIS through the Python engine.	Confirm that openmm imports, then adapt the two-particle setup to your force field.
test-pyvisa	PyVisA post-processing for the GROMACS sparse-load output.	Use after a path-sampling run has produced order, energy, and path ensemble files.

Running a fixture briefly

For exploration, run a fixture in a temporary copy and stop early once the setup has passed initialization and produced a few cycles. For example:

cd examples/tests/test-internal/retis
timeout 30s pyretisrun -i retis.rst -p

For a real tutorial run, remove the timeout and increase the number of cycles only after you have checked the first log and the out.rst file.