AI-assisted path-sampling workflows

PyRETIS provides structured guidance for language-model agents used in path-sampling workflows. The material captures PyRETIS-specific procedural knowledge: method selection, move choice, interface placement, engine validation, and the primary literature that supports those choices. It is intended to help an agent navigate the documentation and execute defined workflows; it does not replace convergence assessment, uncertainty analysis, or scientific judgement by the researcher.

Two task-specific skills are provided, together with a compact, machine-readable documentation index, llms.txt. The skills live in the repository. A skill is an agent-agnostic Markdown file installed in an agent’s skills directory and loaded when its task description applies. The .claude/skills/<name>/SKILL.md path is one installation example; the same files can guide any LLM agent that can read local files and use the required tools.

The user skill — run and analyse simulations

skills/pyretis-pathsampling/SKILL.md guides the configuration, execution, and interpretation of path-sampling calculations. It covers selection of a sampling task (TIS / RETIS / REPPTIS / permeability), MD-engine configuration (internal/TurtleMD, GROMACS, LAMMPS, CP2K, or OpenMM), definition of the order parameter and interface ladder, initial-path preparation, execution with pyretis run, and analysis of crossing probabilities and rates with pyretis analyse. It makes the following method choices explicit:

  • RETIS includes the initial-flux contribution and is the standard choice; use plain TIS only when a single ensemble or a custom flux treatment is intended.

  • Order-parameter quality and interface placement (target crossing probabilities of approximately 0.2–0.5 per interface) strongly determine sampling efficiency and convergence.

  • Subtrajectory moves (Wire Fencing, Stone Skipping, and Web Throwing) are considered for stiff, long, or diffusive barriers, subject to their additional computational cost.

  • REPPTIS is appropriate when long-lived intermediates or slow permeation make conventional path ensembles costly.

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

Example requests

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 — extend and validate PyRETIS

skills/pyretis-development/SKILL.md maps the codebase and records the deterministic-science conventions used in development. In particular, it defines build-version-sensitive engine reference validation: a non-reference engine build is classified as NOT VALIDATED after execution smoke testing rather than as a numerical failure; reference data are re-generated deliberately with OMP_NUM_THREADS=1 using the affected suite’s run.sh generate and checked with run.sh; and the heavy suite can be executed on a cluster through devtools/remote_validate.sh.

Example requests

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.

Choosing an LLM

Choose a model by demonstrated capabilities rather than parameter count or brand. Parameter count is not a reliable proxy for tool use, code quality, or scientific reasoning. In both cases, require the agent to retain the input files, commands, software versions, and analysis output needed to audit its result.

Table 54 Recommended model capabilities

Skill

Recommended model type

Minimum practical capability

User path-sampling skill

A general-purpose reasoning model that can use local tools, read scientific documentation, and generate TOML and Python reliably.

Follows multi-step instructions, preserves units and file paths, can run shell commands in the project environment, uses a context window of at least 16k tokens, and reports uncertainty rather than inventing a convergence claim.

Developer skill

A software-engineering or coding agent with shell access, repository navigation, patch generation, and test-debugging capability.

Reads a multi-file code change in context (at least 32k tokens), executes tests, interprets failures, and reports the exact validation performed. Prefer a stronger coding model for engine integrations or numerical-reference changes.

For either skill, a model should cite the method references below for scientific claims and should not present an unvalidated run as a converged physical result.

Method references

The user skill cites the following primary sources rather than attempting to reconstruct the theory, so an agent can attribute method-level claims to the relevant literature.

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 applicable SKILL.md into the agent’s skills directory and work from the project conda environment. Both skills assume the run-pyretis driver for environment, build, and smoke-test checks, so retain it alongside the selected skill. The agent may invoke pyretis run / pyretis analyse or the relevant test gates, but examples should always be copied to a scratch directory before execution to preserve the tracked source tree.