Agent-TIS quick start: PyRETIS for users and AI agents¶

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 AI agents (LLM and coding agents) can find the correct pattern quickly. The agent skills and the rules for agents are described in Agent-TIS: AI agents for PyRETIS path sampling.

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 the NNN/ ensemble directories (000/, 001/, each holding generate/ / accepted/ / archive/) or report/ 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.toml -p`	`pyretis.log`, `output.toml`, ensemble folders, trajectory and energy files.
Analyse one completed run	`pyretis analyse -i input.toml`	`report/` and the generated analysis figures/tables.
Split a TIS setup into ensemble inputs	`pyretis run -i tis.toml`	Generated files such as `tis-001.toml`, `tis-002.toml`.
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/internal/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.
Run the changed setup with pyretis run -i ... -p in a new directory, or after pyretis tools clean in this one, and inspect pyretis.log and output.toml before doing a long run. A changed setup is a new simulation, and pyretis run refuses to start one with method = "kick" or "load" where the ensemble directories hold sampled cycles. To add cycles to a run without changing its setup, set method = "restart" and raise steps (see the restart method).
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 AI agents¶

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.