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 potential
• RETIS in a 1D triple-well: the zero_left shortcut
• RETIS in a 2D potential
• Breaking a bond with RETIS

• 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
• Subtrajectory moves in a 1D potential
• Partial path TIS (REPPTIS) in a 1D potential
• Exploring the order parameter (explore task)
• Umbrella Sampling
• Studying permeability with PyRETIS
• Particle Swarm Optimization

• 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.
• 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.

• Transport of methane in a sI hydrate
• Dissociation of Hydrogen with CP2K
• Breaking a bond with RETIS and LAMMPS
• Running a PyRETIS simulation with OpenMM
• Using C or FORTRAN

• 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 pyretisrun, pyretisanalyse and PyVisA.

• Molecular dynamics examples
• Molecular dynamics in PyRETIS with C or FORTRAN
• PyVisA: Visualization and analysis of path sampling results
• Post-processing and visualization with 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
• Example organization
• Using heavy checks as tutorials
• Example test status
• Interactive examples

• PyRETIS quick guide for users and LLMs – compact rules for choosing examples, running commands, and avoiding common setup mistakes.
• 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 pyretisrun and pyretisanalyse, then runs compare.py to validate the output against the reference data in results/.