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, start with a minimal input file. If you are adapting the examples with help from an AI agent, start with the Agent-TIS quick start so the agent follows the same folder, command, and verification conventions as the website. The runnable checks behind these tutorials are tracked in Example test status.

Start here¶

A minimal input file – the shortest input that runs a complete RETIS simulation, and what PyRETIS fills in when you leave everything optional out. The best first read if you have never written a PyRETIS input. Source.
A minimal input file with an external engine – the same, driving OpenMM: the engine owns the system, so the input shrinks to what to sample, which engine to drive, and how to measure it. Source.

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.
Both rates in one run (biretis) – the rates of A to B and of B to A, and the equilibrium constant, from one bidirectional RETIS simulation on an asymmetric double well, checked against two one-way RETIS runs and brute-force dynamics. 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 – a RETIS run with [simulation] permeability = true and the mirror and target-swap moves; pyretis analyse then also computes the permeability. 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 – a Lennard-Jones MD run, with the potential written in Python, C or FORTRAN, whose velocities are reversed after a number of steps so that the run retraces its way back to the initial configuration. Source.
Initial flux – the md-flux run that measures the flux through the first interface; with the crossing probability from TIS it gives the rate constant. Source.
pyvisa GUI and pyvisa analysis – visualise and post-process your trajectories. Source.
Transmission coefficient – compute the reactive-flux transmission coefficient from a finished run’s per-path order series. Source.
Combine data – pool several independent runs’ pathensemble.txt into a single crossing matrix for one WHAM analysis. 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.

Agent-TIS quick start: PyRETIS for users and AI agents – 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 legacy-runner TOML schema 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 with -C:

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

run.sh removes the output of an earlier run (pyretis tools clean), calls pyretis run and pyretis analyse, and leaves the results in place. -C also compares them with the reference data in results/, -c removes them afterwards, and -cc does both; a plain ./run.sh compares nothing (see Example organization).