LLMs and agents

PyRETIS is built to be driven by LLM agents as well as by hand. The goal of the material here is to add the value an LLM does not already have: the PyRETIS-specific, non-obvious choices (which method, which move, how to place interfaces, how the engine reference validation works) and the authoritative papers, rather than generic path-sampling theory.

Three pieces support this:

  • a compact, machine-readable site guide at llms.txt (the llms.txt convention) pointing an agent at the canonical documentation;

  • two user-facing agent skills — one for capable assistants and one written explicitly for small / local models; and

  • a developer skill for working on the PyRETIS source.

All skills live in the repository under skills/ and build on the bundled run-pyretis smoke-test skill. A skill is a Markdown file you drop into your agent’s skills directory (for Claude Code, .claude/skills/<name>/SKILL.md); the agent loads it when a task matches its description.

Two model tiers

The same task — set up, run and interpret a path-sampling study — is served at two levels, because a smaller model needs the reasoning spelled out:

Capable assistants (frontier-class models) use skills/pyretis-pathsampling/SKILL.md: a dense workflow plus a “Choosing a method — the non-obvious calls” section the model reasons from.

Small and local models — emphasised. You do not need a frontier cloud model to drive PyRETIS. skills/pyretis-pathsampling/SKILL-local.md is written for a smaller or locally-hosted model (e.g. a Claude 4.5-class model, or an open model you run offline): a fixed step-by-step procedure, an explicit decision table mapping the user’s goal to a method, copy-paste retis.toml recipes with just four placeholders to fill, the two exact commands to run, and the two numbers to read off the report. It deliberately tells the model not to improvise the theory and to cite the papers instead. This makes a private, offline, low-cost PyRETIS assistant practical — which is the point: the lore is in the skill, so the model does not have to know it.

The user skill — run path-sampling simulations

Both user skills cover the same ground: choosing the sampling task (TIS / RETIS / REPPTIS / permeability), configuring the MD engine (internal, GROMACS, LAMMPS, CP2K, OpenMM), the order parameter and the interface ladder, initial paths (kick or load), running pyretisrun, and reading the crossing-probability and rate report from pyretisanalyse — with the non-obvious calls a model is most likely to get plausibly wrong:

  • RETIS is the default (it folds in the initial flux); use plain TIS only on purpose.

  • Order-parameter quality and interface placement (≈0.2–0.5 crossing probability per interface) dominate convergence.

  • Sub-trajectory moves (Wire Fencing / Stone Skipping / Web Throwing) are for stiff, long, diffusive barriers — at extra cost — not a default.

  • REPPTIS only pays off for long-lived intermediates / slow permeation.

  • Infinite swapping is for large parallel runs and is analysed with WHAM.

Sample prompts

Set up a RETIS simulation for the 1-D double well, run it, and report
the rate with its statistical error and the crossing-probability curve.

I have a GROMACS system for ligand unbinding. Help me pick an order
parameter and interface ladder, write the retis.toml, and launch RETIS.

My intermediate state is metastable and the permeation is very slow —
is REPPTIS the right method here, and what do I lose vs RETIS?

Analyse this finished run and tell me whether the crossing probabilities
overlap well or whether I need more steps or better-placed interfaces.

The developer skill — develop and maintain PyRETIS

skills/pyretis-development/SKILL.md maps the codebase, states the deterministic-science conventions, and — the part hardest to infer — explains the build-version-sensitive engine reference validation: why a non-reference engine build is graded NOT VALIDATED (execution-smoke) rather than failing, how to re-bless references deliberately with OMP_NUM_THREADS=1, and how to run the heavy suite on a cluster with devtools/remote_validate.sh.

Sample prompts

Add a new order-parameter class with a unit test, and run the fast gate.

My LAMMPS reference test fails — is it a real regression or a
build-version mismatch? Fix the version grading if needed.

Re-bless the CP2K references on my local CP2K 2025.2 build and confirm
run-all-cp2k.sh validates rather than smokes.

Add streaming support to the <engine> engine, mirroring the GROMACS
streaming/relaunch pair, and verify streaming == relaunch on the mock.

Method references

The skills cite these rather than explaining the theory; both user tiers carry the same list so a small model can point the user at the source.

Foundations

Moves and sampling

Memory reduction and long timescales

The PyRETIS software

See Scientific results for application papers (autoionization of water, DNA binding, atmospheric reactions, …).

Using a skill

Copy the chosen SKILL.md into your agent’s skills directory and start from the project’s conda environment. For a small or local model, prefer SKILL-local.md — it is self-contained and asks the model only to follow tables and recipes. The skills assume the run-pyretis driver for environment/build/smoke-testing, so keep it alongside. The agent runs the CLI (pyretisrun / pyretisanalyse) or the test gates and reports results, always copying examples to a scratch directory first so the tracked tree stays clean.