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	pyretisrun -i input.rst -p	pyretis.log, out.rst, ensemble folders, trajectory and energy files.
Analyse one completed run	pyretisanalyse -i out.rst	report/ and the generated analysis figures/tables.
Split a TIS setup into ensemble inputs	pyretisrun -i tis.rst	Generated files such as tis-001.rst, tis-002.rst.
Run one split TIS ensemble	pyretisrun -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

1. Pick the tutorial with the closest method and engine.
2. Copy only the listed input files and support modules to a new working directory.
3. Run the tutorial unchanged for a few cycles or with the smoke runner.
4. Change one category at a time: system, order parameter, engine, then interface positions.
5. Re-run with pyretisrun -i ... -p and inspect pyretis.log and out.rst before doing a long run.
6. Analyse only after a run has produced the expected output files.
7. 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.