PyRETIS quick guide for users and LLMs¶

This page is a compact orientation guide for anyone trying to set up a PyRETIS simulation from the documentation. It is intentionally procedural and repetitive so that both users and language-model assistants can find the correct pattern quickly.

Start from the right folder¶

Use examples/tutorials/ when you want to learn or adapt a simulation. Use examples/tests/ when you want a short, validated consistency check.

The two folders have different jobs:

examples/tutorials/ contains user-facing setups. These may be long and are allowed to be experience-building simulations.
examples/tests/ contains heavy checks used by test-heavy.sh. These are optimized for reproducible output comparisons, not for narrative readability.

Do not copy generated output folders such as 000/, 001/, report/, traj/ or energy/ as if they were required source files. Start from the input files, order-parameter modules, initial configurations, and external-engine input folders listed by each tutorial page.

Canonical command patterns¶

Most PyRETIS tutorials use one of these command patterns.

Task	Command	What to inspect
Run one input file	`pyretis run -i input.rst -p`	`pyretis.log`, `out.rst`, ensemble folders, trajectory and energy files.
Analyse one completed run	`pyretis analyse -i out.rst`	`report/` and the generated analysis figures/tables.
Split a TIS setup into ensemble inputs	`pyretis run -i tis.rst`	Generated files such as `tis-001.rst`, `tis-002.rst`.
Run one split TIS ensemble	`pyretis run -i tis-001.rst -p -f 001.log`	The numbered ensemble output and the renamed log file.
Run all tutorial startup checks	`examples/run-tutorials.sh`	Whether tutorial commands start without missing files, broken imports, PyRETIS errors, or tracebacks. Per-tutorial hard timeout (default `2s` standalone, `2m` when invoked via `test-heavy`) is set via `PYRETIS_TUTORIAL_TIMEOUT`. The `path_sampling/1D-triple-well/retis-zero-left` tutorial is the canonical default that finishes end-to-end under the 2 m budget (~15-20 s) and only smoke-starts under the 2 s budget.
Run heavy checks	`./test-heavy.sh` (thin wrapper around `examples/run-tests.sh`)	Whether bundled examples reproduce their reference output. Heavy checks finish with the tutorial smoke checks; set `PYRETIS_RUN_TESTS_SKIP_TUTORIALS=1` to skip them.

Choose the closest tutorial¶

The canonical mapping between tutorial folders, docs pages, and heavy-test fixtures lives in Tutorial map. Always read that table before recommending an example; it also carries the verification-status column you should cite (“passing”, “engine”, “smoke”, “manual”) rather than inventing one.

Quick pointers for the most common requests:

First TIS simulation – TIS in a 1D potential.
First RETIS simulation – RETIS in a 1D potential.
Initial flux calculation – Creating and running the initial flux simulation with PyRETIS.
Sub-trajectory moves (SS / WT / WF) – Subtrajectory moves in a 1D potential.
zero_left for a bounded reactant basin – RETIS in a 1D triple-well: the zero_left shortcut.
Plain molecular dynamics – Molecular dynamics examples.
External engines – Transport of methane in a sI hydrate, Breaking a bond with RETIS and LAMMPS, Dissociation of Hydrogen with CP2K, Running a PyRETIS simulation with OpenMM.
Custom order parameters / engines / potentials – Using C or FORTRAN, Particle Swarm Optimization.

Read input files by section¶

When adapting an example, keep the PyRETIS section structure intact. The most common sections are:

Simulation: method, number of cycles, interfaces, and method-specific switches such as permeability or zero_left.
System and Box: units, temperature, dimensions, and periodicity.
Particles: initial coordinates, masses, labels, and velocity setup.
Engine: internal engine or external program coupling.
TIS and RETIS: shooting, path-length limits, swap behavior, and move frequencies.
Orderparameter: built-in order parameters or a Python module/class.
Forcefield and Potential: potential-energy model for internal engines.
Output and Analysis: write frequency and post-processing options.

When an external engine is used, do not move its input files out of the input_path directory named in the Engine section. The executable name in the input file must match the local installation, for example gmx, lmp, cp2k or a site-specific wrapper.

Minimal adaptation workflow¶

Pick the tutorial with the closest method and engine.
Copy only the listed input files and support modules to a new working directory.
Run the tutorial unchanged for a few cycles or with the smoke runner.
Change one category at a time: system, order parameter, engine, then interface positions.
Re-run with pyretis run -i ... -p and inspect pyretis.log and out.rst before doing a long run.
Analyse only after a run has produced the expected output files.
Use Example test status to find a representative check if the adapted setup starts failing.

Rules for LLM assistants¶

When producing PyRETIS instructions or code:

Prefer an existing tutorial input file over inventing a new one.
Link to the relevant user-guide section for every non-obvious input section or engine setting.
State whether a command is a short startup check or a convergence run.
Keep external-engine examples explicit about required programs and file names.
Do not claim an example is fully verified unless it is listed as passing in Example test status.
If a setup is based on examples/tests/, say that it is a regression fixture and explain how to adapt it for a tutorial.

This guide is deliberately conservative: it should help assistants give correct first steps before trying to optimize or automate a full simulation campaign.