# PyRETIS > PyRETIS is Python software for rare-event molecular simulation, path > sampling, transition interface sampling (TIS), replica exchange transition > interface sampling (RETIS), molecular dynamics workflows, and trajectory > analysis. This file is a compact guide for LLMs and search agents. Prefer the develop documentation when answering questions about the PyRETIS develop branch and PyRETIS 4.dev. Stable PyRETIS 3.0.6 documentation is maintained separately. ## Core Links - Develop documentation: https://www.pyretis.org/dev/ - Stable PyRETIS 3.0.6 documentation: https://www.pyretis.org/current/ - Full documentation text in one file: https://www.pyretis.org/dev/llms-full.txt - Source repository: https://gitlab.com/pyretis/pyretis - License: https://www.pyretis.org/dev/about/license.html ## User Documentation - [The PyRETIS analysis application](https://www.pyretis.org/dev/user/analyse.html): The PyRETIS analysis application, pyretis analyse, is used to analyse the results from PyRETIS simulations. - [The PyRETIS application](https://www.pyretis.org/dev/user/application.html): PyRETIS ships a single command, pyretis, with sub-commands: - [Cleaning run artifacts](https://www.pyretis.org/dev/user/clean.html): A PyRETIS run leaves a number of generated files and directories behind – log files, the regenerated out.toml / out.rst, restart files, the NNN ensemble… - [Creating custom engines](https://www.pyretis.org/dev/user/engine.html): The Engines are used to propagate the equations of motion or alter the state of the system in some other way. - [Some common PyRETIS errors](https://www.pyretis.org/dev/user/errors.html): In this section, we describe some of the most common PyRETIS warning or error messages and how these errors can be resolved. - [CECAM workshop: A single particle in a 1D potential](https://www.pyretis.org/dev/user/exercises/examples-cecam-2016.html): This is a short user guide for running the 1D potential example with the RETIS algorithm for the CECAM school “Multiscale Simulations of Soft Matter with… - [Molecular modelling: Introduction to RETIS](https://www.pyretis.org/dev/user/exercises/examples-molmod-2016.html): In this exercise, you will explore a rare event with the Replica Exchange Transition Interface Sampling (RETIS) algorithm. - [PyRETIS exercises](https://www.pyretis.org/dev/user/exercises/index.html): Here, we list some exercises in which PyRETIS has been used to demonstrate some different simulation methods. - [User Guide](https://www.pyretis.org/dev/user/index.html): The guide is ordered as a workflow: first the background and entry points, then how to prepare and run simulations, then analysis, visualisation and… - [Getting the initial path](https://www.pyretis.org/dev/user/initial-paths.html): Before a TIS, RETIS or REPPTIS simulation can start, every path ensemble needs one valid initial path — a trajectory that already satisfies the ensemble’s… - [Running PyRETIS](https://www.pyretis.org/dev/user/input.html): PyRETIS is executed using the pyretis run application and a PyRETIS input file: - [Obtaining and installing PyRETIS](https://www.pyretis.org/dev/user/install.html): PyRETIS and its requirements can be installed using pip or using conda as described below. - [Introduction to PyRETIS and rare event methods](https://www.pyretis.org/dev/user/intro.html): PyRETIS is a computational library for performing molecular simulations of rare events with a focus on transition interface sampling (TIS) 1 and replica… - [Introduction to the PyRETIS library](https://www.pyretis.org/dev/user/intro-api.html): This page gives a compact map of the main classes and functions in the PyRETIS library. For the full method-level description, see the API documentation. - [Running LAMMPS with PyRETIS](https://www.pyretis.org/dev/user/lammps.html): This page describes how to use the LAMMPS Molecular Dynamics Simulator with PyRETIS. - [AI-assisted path-sampling workflows](https://www.pyretis.org/dev/user/llms.html): PyRETIS provides structured guidance for language-model agents used in path-sampling workflows. - [Monitoring a running simulation](https://www.pyretis.org/dev/user/monitor.html): A path-sampling run is long, and the useful question during it is not “what is the rate” – that is the last thing to converge – but “is this run doing… - [Monte Carlo moves](https://www.pyretis.org/dev/user/moves.html): In TIS and RETIS simulations, every Monte Carlo cycle proposes a new trajectory (a path) from the current one using a move, and then accepts or rejects it. - [Creating custom order parameters](https://www.pyretis.org/dev/user/orderparameters.html): Often, you will find the need to create custom order parameters for your path sampling simulation(s). - [Published applications of PyRETIS](https://www.pyretis.org/dev/user/our-results.html): This collection highlights peer-reviewed applications of PyRETIS across molecular kinetics, condensed-phase chemistry, biomolecular transitions, and… - [Simulation outputs](https://www.pyretis.org/dev/user/output.html): A PyRETIS run leaves behind a directory of plain-text files, and pyretis analyse turns those into a report of tables and figures. - [Path types and rejection reasons](https://www.pyretis.org/dev/user/path-types-rejections.html): During a PyRETIS simulation, each Monte Carlo cycle generates (or loads) a path and records two short codes in the output: - [The PyVisA application](https://www.pyretis.org/dev/user/pyvisa.html): PyVisA is the analysis and visualization tool for PyRETIS simulations. It consists of two components: - [Quickstart](https://www.pyretis.org/dev/user/quickstart.html): After installing PyRETIS, you can run simulations by using a text based input file or by using the PyRETIS library explicitly. - [Calculating the rate](https://www.pyretis.org/dev/user/rate.html): Everything a path-sampling run does is in service of one number: the rate constant k_{AB} at which the system leaves state A for state B. - [The Analysis section](https://www.pyretis.org/dev/user/section/analysis.html): The analysis section defines parameters for the analysis. - [The Box section](https://www.pyretis.org/dev/user/section/box.html): The box section defines the simulation box. This is useful, for instance, if periodic boundary conditions are needed. - [The Engine section](https://www.pyretis.org/dev/user/section/engine.html): The engine section specifies the engine to use for the dynamics. - [The Forcefield section](https://www.pyretis.org/dev/user/section/forcefield.html): The forcefield section defines the force field to use for the simulation. - [The initial-path section](https://www.pyretis.org/dev/user/section/initial.html): The initial-path section specifies how the initial path for a TIS/RETIS simulation should be generated. - [The orderparameter section](https://www.pyretis.org/dev/user/section/orderparameter.html): The orderparameter section defines which order parameter to use for a path sampling simulation. - [The Output section](https://www.pyretis.org/dev/user/section/output.html): The output section defines settings for how PyRETIS should create output files. - [The Particles section](https://www.pyretis.org/dev/user/section/particles.html): Particles are added to a simulation in the particles section: - [The Potential section](https://www.pyretis.org/dev/user/section/potential.html): The potential section specifies a single potential function to add to the force field. - [The RETIS section](https://www.pyretis.org/dev/user/section/retis.html): The RETIS section specifies settings for RE(PP)TIS simulations. Note that the section for TIS also needs to be defined for a RE(PP)TIS simulation. - [The Runner section (infinite swapping)](https://www.pyretis.org/dev/user/section/runner.html): The [runner] section configures the infinite-swapping sampler – the asynchronous, parallel reformulation of replica exchange described in the moves guide. - [Input file sections](https://www.pyretis.org/dev/user/section/sections.html): The PyRETIS input file described in detail in the user guide. The short version is: - [The simulation section](https://www.pyretis.org/dev/user/section/simulation.html): The simulation section defines and selects the simulation PyRETIS will run. - [The System section](https://www.pyretis.org/dev/user/section/system.html): The system section defines some properties of the system. - [The TIS section](https://www.pyretis.org/dev/user/section/tis.html): The TIS section defines settings for (PP)TIS and (PP)RETIS simulations. - [The unit-system section](https://www.pyretis.org/dev/user/section/unitsystem.html): The unit-system section is used in combination with the units keyword from the system section for defining custom system of units. - [Tutorials](https://www.pyretis.org/dev/user/tutorials.html): In addition to reading the documentation, we have prepared several examples to highlight the usage and capabilities of PyRETIS. - [PyRETIS units](https://www.pyretis.org/dev/user/units.html): PyRETIS simulations are always carried out with a consistent set of units. ## Examples And Tutorials - [Example organization](https://www.pyretis.org/dev/examples/example-organization.html): The examples tree has exactly two top-level subfolders: examples/tutorials and examples/tests. - [Example test status](https://www.pyretis.org/dev/examples/example-test-status.html): This page is the canonical map between tutorial folders, documentation pages, and heavy-test fixtures. - [RETIS in a 2D potential](https://www.pyretis.org/dev/examples/examples-2d-hysteresis.html): In this example, you will explore a rare event with the Replica Exchange Transition Interface Sampling (RETIS) algorithm. - [Dissociation of Hydrogen with CP2K](https://www.pyretis.org/dev/examples/examples-cp2k-hydrogen.html): In this example, we are going to study dissociation of hydrogen using CP2K. - [Exploring the order parameter (explore task)](https://www.pyretis.org/dev/examples/examples-explore.html): This example shows the explore task on the 1D double well. - [Using heavy checks as tutorials](https://www.pyretis.org/dev/examples/examples-from-tests.html): The directories under examples/tests/ are consistency checks, but they are also useful minimal setups. This page translates them into user-facing recipes. - [Transport of methane in a sI hydrate](https://www.pyretis.org/dev/examples/examples-gromacs-hydrate.html): In this example, we are going to study the transport of methane in a sI hydrate structure. The initial configuration is shown in fig_gromacs_hydrate. - [Infinite swapping (parallel replica exchange)](https://www.pyretis.org/dev/examples/examples-infswap.html): This example shows how to run the infinite-swapping sampler – the asynchronous, highly parallel reformulation of replica exchange of Zhang, Baldauf, Roet… - [Breaking a bond with RETIS and LAMMPS](https://www.pyretis.org/dev/examples/examples-lammps-wca.html): In this example, you will explore bond breaking in a simple model system with the Replica Exchange Transition Interface Sampling (RETIS) algorithm. - [Molecular dynamics examples](https://www.pyretis.org/dev/examples/examples-md.html): In this example, we will perform a MD simulation of a Lennard-Jones fluid. - [Molecular dynamics in PyRETIS with C or FORTRAN](https://www.pyretis.org/dev/examples/examples-md-fb.html): In this example, we will implement a Lennard-Jones potential in C or FORTRAN and use this to run a MD simulation with PyRETIS for a simple system. - [Migration guide: legacy commands and inputs to the unified CLI](https://www.pyretis.org/dev/examples/examples-migration.html): PyRETIS 4 unifies every entry point behind a single pyretis command and standardises on TOML input. - [A minimal input file](https://www.pyretis.org/dev/examples/examples-minimal.html): This is the shortest complete PyRETIS simulation: a RETIS run of a single particle in a double well, written with no optional settings at all. - [A minimal input file with an external engine](https://www.pyretis.org/dev/examples/examples-minimal-openmm.html): The minimal input file tutorial uses PyRETIS’ own internal integrator, so the input has to describe the system: the potential, the dimensionality, the… - [Running a PyRETIS simulation with OpenMM](https://www.pyretis.org/dev/examples/examples-openmm.html): In this example, we show the interface between OpenMM and PyRETIS. - [Studying permeability with PyRETIS](https://www.pyretis.org/dev/examples/examples-permeability.html): This example shows how to set up a permeability simulation with PyRETIS. - [Particle Swarm Optimization](https://www.pyretis.org/dev/examples/examples-pso.html): In this example, we will perform a task that PyRETIS is NOT intended to do. - [PyVisA: Visualization and analysis of path sampling results](https://www.pyretis.org/dev/examples/examples-pyvisa.html): In this example, we become familiar with PyVisA. Every example on the website can be used to generate data for the analysis. - [Post-processing and visualization with PyVisA](https://www.pyretis.org/dev/examples/examples-pyvisa-analysis.html): In this example, we perform post-processing on the methane hydrate system from one of the previous examples called “Using GROMACS”. - [Partial path TIS (REPPTIS) in a 1D potential](https://www.pyretis.org/dev/examples/examples-repptis.html): This example shows how to run REPPTIS – Replica Exchange Partial Path Transition Interface Sampling – on the 1D double-well benchmark. - [RETIS in a 1D potential](https://www.pyretis.org/dev/examples/examples-retis-1d.html): In this example, you will explore a rare event with the Replica Exchange Transition Interface Sampling (RETIS) algorithm. - [RETIS in a 1D triple-well: the zero_left shortcut](https://www.pyretis.org/dev/examples/examples-retis-triple-well.html): This example shows how a left interface for the [0:math:^-] ensemble (set with the zero_left keyword) can make a RETIS simulation a lot cheaper, without… - [Breaking a bond with RETIS](https://www.pyretis.org/dev/examples/examples-retis-wca.html): In this example, you will explore bond breaking in a simple model system with the Replica Exchange Transition Interface Sampling (RETIS) algorithm. - [Subtrajectory moves in a 1D potential](https://www.pyretis.org/dev/examples/examples-submoves-1d.html): This example shows how to use the subtrajectory monte carlo moves Stone Skipping (SS), Web Throwing (WT) 1 and Wire Fencing (WF) 2 in (Replica Exchange)… - [TIS in a 1D potential](https://www.pyretis.org/dev/examples/examples-tis-1d.html): In this example, you will explore a rare event with the Transition Interface Sampling (TIS) algorithm. - [Umbrella Sampling](https://www.pyretis.org/dev/examples/examples-umbrella.html): This example will simply calculate the free energy profile in a given, known, potential using umbrella sampling. - [Using C or FORTRAN](https://www.pyretis.org/dev/examples/examples-vvexternal.html): In this section, we will show some examples on how C or FORTRAN can be used together with Python and PyRETIS. We show examples on: - [Examples](https://www.pyretis.org/dev/examples/index.html): Welcome to the PyRETIS examples library. The source distribution keeps user-facing material under examples/tutorials/ and consistency checks under… - [Interactive examples](https://www.pyretis.org/dev/examples/interactive-examples.html): Interactive examples are a good fit for PyRETIS, but they should be introduced in a way that does not make the normal documentation build fragile. - [PyRETIS quick guide for users and LLMs](https://www.pyretis.org/dev/examples/llm-quickstart.html): This page is a compact orientation guide for anyone trying to set up a PyRETIS simulation from the documentation. ## Developer Documentation - [Documentation Terminology](https://www.pyretis.org/dev/developer/docs-style.html): This page records a few naming and wording conventions for user-facing documentation. - [Cross-engine validation: water-dimer dissociation](https://www.pyretis.org/dev/developer/engine-validation.html): This page records a reproducibility check that the external molecular-dynamics engines driven by PyRETIS reproduce the same rare-event kinetics on one… - [Extending and validating PyRETIS](https://www.pyretis.org/dev/developer/extending-pyretis.html): This page is for developers adding a new Monte Carlo path move or a new engine to PyRETIS, and – just as importantly – checking that the addition… - [Developer Guide](https://www.pyretis.org/dev/developer/index.html): PyRETIS welcomes new contributors: the code style and docstring guidelines, running the test gates, reporting bugs, and submitting merge requests. - [Infinite-swapping integration status](https://www.pyretis.org/dev/developer/merge_status.html): The infinite-swapping source-tree merge was completed on 2026-07-06. - [Method-equivalence validation: the double-well on one engine](https://www.pyretis.org/dev/developer/method-validation.html): This page records a reproducibility check that every sampling strategy and every code path in PyRETIS reproduces the same crossing probability and rate… - [Scientific evidence matrix](https://www.pyretis.org/dev/developer/scientific-evidence-matrix.html): This matrix records why a numerical result is believed, not merely where its implementation is exercised. - [Trustworthiness workplan](https://www.pyretis.org/dev/developer/trustworthiness-workplan.html): A green test is evidence only when the test demonstrably inspected the quantity it claims to validate. This workplan turns that rule into executable gates. ## About - [About PyRETIS](https://www.pyretis.org/dev/about/index.html): PyRETIS is a Python library for rare event molecular simulations with emphasis on methods based on transition interface sampling and replica exchange… - [PyRETIS License (GNU Lesser General Public License v2.1+)](https://www.pyretis.org/dev/about/license.html): This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free… ## API Reference - [The PyRETIS library](https://www.pyretis.org/dev/api/pyretis.html): This is the documentation for the PyRETIS library and usage of the application programming interface (API). - [pyretis.analysis package](https://www.pyretis.org/dev/api/pyretis.analysis.html): This package defines analysis tools for the PyRETIS program. - [pyretis.bin](https://www.pyretis.org/dev/api/pyretis.bin.html): Here, the PyRETIS executables can be found. These are: - [pyretis.core](https://www.pyretis.org/dev/api/pyretis.core.html): The core tools are intended to define classes which are used in simulations. - [pyretis.engines package](https://www.pyretis.org/dev/api/pyretis.engines.html): This package defines engines for PyRETIS. The engines are responsible for carrying out dynamics for a system. - [pyretis.forcefield package](https://www.pyretis.org/dev/api/pyretis.forcefield.html): Definition of force field classes and potential functions. - [pyretis.forcefield.potentials package](https://www.pyretis.org/dev/api/pyretis.forcefield.potentials.html): This package defines some potential functions. These potential functions can be used to create force fields. - [pyretis.forcefield.potentials.pairpotentials package](https://www.pyretis.org/dev/api/pyretis.forcefield.potentials.pairpotentials.html): This package defines different pair potentials for use with an internal calculation in PyRETIS. - [pyretis.initiation package](https://www.pyretis.org/dev/api/pyretis.initiation.html): This package defines methods for initiating path ensembles. - [pyretis.inout package](https://www.pyretis.org/dev/api/pyretis.inout.html): The sub-package handles input and output for PyRETIS. - [pyretis.inout.analysisio package](https://www.pyretis.org/dev/api/pyretis.inout.analysisio.html): This package contains functions for input/output for the analysis. - [pyretis.inout.formats package](https://www.pyretis.org/dev/api/pyretis.inout.formats.html): This sub-package handles data formats for PyRETIS. - [pyretis.inout.plotting package](https://www.pyretis.org/dev/api/pyretis.inout.plotting.html): This package contains functions for setting up plotters. - [pyretis.inout.report package](https://www.pyretis.org/dev/api/pyretis.inout.report.html): This package contains methods for generating reports. - [pyretis.orderparameter package](https://www.pyretis.org/dev/api/pyretis.orderparameter.html): This package defines order parameters for use with PyRETIS. - [pyretis.pyvisa package](https://www.pyretis.org/dev/api/pyretis.pyvisa.html): The sub-package with tools for visualizing simulation results for PyRETIS. - [pyretis.setup package](https://www.pyretis.org/dev/api/pyretis.setup.html): This package handles set-up of simulations from settings. - [pyretis.simulation package](https://www.pyretis.org/dev/api/pyretis.simulation.html): This package defines different simulations for use with PyRETIS. - [pyretis.testing package](https://www.pyretis.org/dev/api/pyretis.testing.html): This package defines common methods which are used for testing. - [pyretis.tools package](https://www.pyretis.org/dev/api/pyretis.tools.html): This package defines some simple tools which may be useful for creating simulations. ## Conventions For Generated Answers - Treat https://www.pyretis.org/dev/ as PyRETIS 4.dev/develop unless the user explicitly asks for stable PyRETIS 3.0.6. - Prefer documented runnable examples before inventing new input files. - Use `pyretis run` for input-file workflows and `pyretis analyse` for analysis. The older `pyretisrun` / `pyretisanalyse` commands still work but are deprecated. - The canonical input format is TOML (`retis.toml`). The `.rst` input format is deprecated and slated for removal in PyRETIS 5. - When adapting tutorials, preserve the documented folder layout and source links from the examples pages. - Mention required external engines, such as GROMACS, CP2K, LAMMPS, or OpenMM, when an example depends on them. - Cite PyRETIS as J. Comput. Chem. 2017 (doi:10.1002/jcc.24900), 2019 (doi:10.1002/jcc.26112) and 2024 (doi:10.1002/jcc.27319).