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.

Getting started: path sampling in 1D

These tutorials introduce the basic PyRETIS input file using small one-dimensional model potentials. They run on a laptop in seconds to minutes when run briefly, but can be extended to much longer experience-building simulations.

• TIS in a 1D potential
• RETIS in a 1D potential
• Subtrajectory moves in a 1D potential
• RETIS in a 1D triple-well: the zero_left shortcut

• TIS in a 1D potential – your first TIS simulation, with a double-well potential and a Langevin engine.

• RETIS in a 1D potential – extends the TIS example with replica exchange moves.

• Sub-moves on a 1D potential – showcases stone skipping, wire fencing and web throwing.

• Triple-well RETIS with zero_left – tutorial showing how the zero_left keyword speeds up sampling without changing the rate constant.

Path-sampling tutorials in 2D

• RETIS in a 2D potential

• Hysteresis on a 2D potential – a richer landscape that makes the value of biased shooting moves more obvious.

Coupling PyRETIS with external engines

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

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

Pre-sampling and post-processing utilities

• Molecular dynamics examples
• Molecular dynamics in PyRETIS with C or FORTRAN
• Umbrella Sampling
• Studying permeability with PyRETIS
• Particle Swarm Optimization
• 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.

• Forward/backward MD and initial flux – handy when you need to seed initial paths for TIS.

• Umbrella sampling – free-energy estimation alongside the rate-constant work.

• Permeability calculation – using permeability = True instead of (or in addition to) TIS.

• PSO-based initial path optimisation – particle-swarm assisted initialisation.

• pyvisa GUI and pyvisa analysis – visualise and post-process your trajectories.

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