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 pyretis run -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.