Examples¶

Welcome to the PyRETIS examples library. The source distribution keeps user-facing material under examples/tutorials/ and consistency checks under examples/tests/.

The pages are grouped by topic, with a short note on what each tutorial covers so you can pick the one that matches the question you have. If you are new to PyRETIS, we recommend the “Getting started” tutorials first. If you are adapting the examples with help from an LLM, start with PyRETIS quick guide for users and LLMs so the assistant follows the same folder, command, and verification conventions as the website. The runnable checks behind these tutorials are tracked in Example test status.

Potentials¶

These examples are a good place to start when the main question is which model system to use. They run with the internal PyRETIS engine unless noted otherwise, and each entry links to the matching tutorial source folder in the repository.

TIS in a 1D double-well potential – the van Erp double-well benchmark and the initial-flux workflow. Source.
Triple-well RETIS with zero_left – a three-state potential showing how zero_left avoids wasted [0^-] trajectories. Source.
Hysteresis on a 2D potential – a richer internal landscape where order-parameter choice matters. Source.
Breaking a bond with RETIS – the WCA bond-breaking model from van Erp, Moroni and Bolhuis (2003). Source.

Sampling methods¶

These examples focus on the sampling algorithm or the way initial paths are generated.

RETIS in a 1D potential – replica exchange between path ensembles for the double-well benchmark. Source.
Subtrajectory moves on a 1D potential – stone skipping, web throwing and wire fencing from Riccardi, Dahlen and van Erp (2017) and Zhang, Riccardi and van Erp (2023). Source.
Infinite swapping – the asynchronous, highly parallel replica-exchange sampler of Zhang, Baldauf, Roet, Lervik and van Erp (2024), driven by the [runner] worker pool. Source.
Partial path TIS (REPPTIS) – replica exchange partial path TIS for long permeation timescales, from Vervust, Zhang, van Erp and Ghysels (2023). Source.
Exploring the order parameter – the explore task for scouting the order-parameter space and seeding initial paths (see Getting the initial path). Source.
Umbrella sampling – free-energy estimation alongside the rate-constant workflows. Source.
Permeability calculation – using permeability = True instead of, or together with, TIS. Source.
PSO-based initial path optimisation – particle-swarm assisted initialisation. Source.

External engines¶

These tutorials replace the internal Langevin engine with one of the standard MD codes, or with compiled extension modules. They require the corresponding engine or compiler to be installed and reachable on your PATH.

GROMACS hydrate – methane transport in an sI hydrate with a custom Python order parameter. Source.
CP2K hydrogen – a small ab initio hydrogen bond-breaking setup. Source.
LAMMPS WCA – the 2D WCA bond-breaking model driven by LAMMPS. Source.
OpenMM argon – RETIS with OpenMM handling the molecular dynamics. Source.
Compiled external components – C and FORTRAN extensions for custom integrators, potentials and order parameters. Source.

Analysis¶

These examples show how to start, seed, analyse and visualise runs with pyretis run, pyretis analyse and PyVisA.

Plain MD – input-file (Molecular dynamics using an input file) and library-based (Molecular dynamics using the PyRETIS library) ways to run a Lennard-Jones simulation. Source.
Forward/backward MD and initial flux – handy when you need to seed initial paths for TIS. Source.
pyvisa GUI and pyvisa analysis – visualise and post-process your trajectories. Source.

How the examples are organised¶

The pages below describe the contract between tutorial pages and heavy checks, the rules for adding new examples, the current verification status, and the LLM-oriented quick reference.

PyRETIS quick guide for users and LLMs – compact rules for choosing examples, running commands, and avoiding common setup mistakes.
Migration guide – moving a project off the deprecated pyretisrun/pyretisanalyse commands, the .rst input format, and the infretis-flavour TOML dialect onto the unified pyretis CLI (all removed in PyRETIS 5).
Example organization – folder contract, tutorial authoring rules, and how tutorials link to the heavy suite.
Using heavy checks as tutorials – one-shot table of which test fixture to copy when starting a new setup.
Example test status – the current verification matrix and per-suite refresh dates.
Interactive examples – planned notebook front ends for the lightweight tutorials.

The examples/ folder has two subfolders:

examples/tutorials/ for user-facing setup guides;
examples/tests/ for heavy consistency checks.

To run all heavy example checks from the repository root:

./test-heavy.sh

To run a single check, cd into its directory and execute its run.sh:

cd examples/tests/test-internal/retis
./run.sh

run.sh cleans the directory, calls pyretis run and pyretis analyse, then runs compare.py to validate the output against the reference data in results/.