# 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. AI agents working with PyRETIS start at **Agent-TIS** (https://www.pyretis.org/dev/user/agent-tis.html): the user skill (set up, run and analyse path-sampling simulations) and the developer skill (extend and validate the code), with the rules for agents and model choice. ## Core Links - Develop documentation: https://www.pyretis.org/dev/ - Agent-TIS, AI agents for PyRETIS: https://www.pyretis.org/dev/user/agent-tis.html - 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 - [Agent-TIS: AI agents for PyRETIS path sampling](https://www.pyretis.org/dev/user/agent-tis.html): Agent-TIS: run and develop PyRETIS path-sampling simulations (TIS, RETIS, REPPTIS) with AI agents. Agent skills, llms.txt, rules, model choice. - [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. - [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 REPPTIS and PPTIS sections](https://www.pyretis.org/dev/user/section/repptis.html): A partial-path simulation reads these settings from the section named after its task: task = "repptis" from [repptis] and task = "pptis" from [pptis]. - [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, and what… - [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. - [Agent-TIS quick start: PyRETIS for users and AI agents](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).