A minimal input file with an external engine

The minimal input file tutorial uses PyRETIS’ own internal integrator, so the input has to describe the system: the potential, the dimensionality, the starting configuration.

With an external engine even that goes away. The engine already owns the system – its particles, force field, box and starting configuration live in the engine’s own input – so PyRETIS only needs to be told three things: what to sample, which engine to drive, and how to measure progress along the reaction.

This tutorial runs RETIS on two argon atoms with OpenMM. The whole simulation is defined by an OpenMM setup module plus the short input below.

Verification status: passing – see Tutorial map.

Tutorial quick start

  • Best starting point: examples/tutorials/path_sampling/openmm/argon-minimal/.

  • Requires: the openmm Python package.

  • Edit first: minimal.toml; edit openmm_sim.py to change the physical system.

  • Run: pyretis run -i minimal.toml -p (under a minute).

  • Analyse: pyretis analyse -i minimal.toml.

The input file

# The smallest input that runs a RETIS simulation with an EXTERNAL
# engine. With an external engine the system itself -- particles, force
# field, box, starting configuration -- is defined by the engine's own
# input (here openmm_sim.py), so PyRETIS only needs to be told what to
# sample, which engine to drive, and how to measure progress.
[simulation]
task = "retis"
steps = 20
interfaces = [0.3, 0.35, 0.4]

[engine]
class = "openmm"
openmm_simulation = "simulation"
openmm_module = "openmm_sim.py"
# The OpenMM integrator defines the time step; stating it here lets
# "pyretis analyse" turn the sampled crossings into a rate per unit
# time. The engine cross-checks it against the integrator, so a wrong
# value is an error rather than a silently wrong rate.
timestep = 0.002

[orderparameter]
class = "Distance"
index = [0, 1]
periodic = false

# The one initiation choice this system needs: build each ensemble's
# first path by kicking off the PREVIOUS ensemble's path. A single kick
# from the starting configuration cannot reach the outermost interface
# here, so the default ("initial") would not find a path for [1^+].
[initial-path]
kick-from = "previous"

Where the system comes from

Nothing in that file describes argon. The system is built by openmm_sim.py, an ordinary OpenMM script that creates a Simulation object – two argon atoms, a Lennard-Jones force, an integrator, and the starting positions and velocities:

# Minimal 2-Argon-atom Lennard-Jones simulation for PyRETIS OpenMM testing.
#
# This module is loaded by the PyRETIS OpenMM engine via the
# openmm_module / openmm_simulation settings in retis.toml.
# It defines `simulation`, an app.Simulation object that PyRETIS uses to
# propagate the system.
#
# The integrator seed is fixed so that results are reproducible across runs.
try:
    import openmm as mm
    from openmm import app, unit
except ImportError:
    import simtk.openmm as mm  # legacy namespace
    from simtk.openmm import app
    from simtk import unit

import numpy as np

# ── System: two Argon atoms ──────────────────────────────────────────────────
system = mm.System()
for _ in range(2):
    system.addParticle(39.948 * unit.dalton)

# Lennard-Jones parameters for Ar (no electrostatics)
lj = mm.NonbondedForce()
lj.setNonbondedMethod(mm.NonbondedForce.NoCutoff)
for _ in range(2):
    lj.addParticle(0.0,
                   0.34 * unit.nanometer,
                   0.997 * unit.kilojoule_per_mole)
system.addForce(lj)

# ── Topology ─────────────────────────────────────────────────────────────────
topology = app.Topology()
chain = topology.addChain()
residue = topology.addResidue('AR', chain)
argon = app.Element.getByAtomicNumber(18)
for atom_name in ('Ar1', 'Ar2'):
    topology.addAtom(atom_name, argon, residue)

# ── Integrator & Simulation ──────────────────────────────────────────────────
integrator = mm.LangevinIntegrator(
    300 * unit.kelvin,
    1.0 / unit.picoseconds,
    2.0 * unit.femtoseconds,
)
# Fixed seed ensures deterministic thermal noise during propagation steps.
integrator.setRandomNumberSeed(42)

simulation = app.Simulation(topology, system, integrator)

# Initial positions: atoms placed near the LJ minimum (~0.38 nm)
positions = np.array([[0.0, 0.0, 0.0],
                      [0.38, 0.0, 0.0]]) * unit.nanometer
simulation.context.setPositions(positions)
simulation.context.setVelocitiesToTemperature(300 * unit.kelvin, 42)

The two [engine] keys openmm_module and openmm_simulation are what connect the two: they name the file to import and the variable inside it holding the Simulation. PyRETIS then drives that object, which is why no [system], [particles], [potential], [forcefield] or [box] section appears in the input.

What each section is for

[simulation]

What to sample: the retis task, how many Monte Carlo steps, and the interfaces – placed on the order parameter below, in the engine’s own units (nm here).

[engine]

Which engine to drive and where its system comes from. The timestep is the OpenMM integrator’s step size; the engine cross-checks it against the integrator and raises if they disagree, and the analysis needs it to express the rate per unit time.

[orderparameter]

How progress is measured – here the distance between the two atoms, which is what the interfaces are placed on.

[initial-path]

The one initiation choice this system needs. The default builds each ensemble’s first path by kicking off the starting configuration; for these interfaces a single kick cannot reach the outermost one, so kick-from = "previous" builds the ensembles up in turn instead.

Everything else is defaulted exactly as in the internal-engine tutorial: the move set, the path-length cap, the output frequencies, the RETIS swap frequencies.

Using a different external engine

The same shape applies to the other external engines – GROMACS, LAMMPS and CP2K. Those read their system from an input directory rather than a Python module, so instead of openmm_module they take an input_path pointing at the engine’s own input files. The rest of the input – what to sample, how to measure it – stays exactly as above. See the engine section for the keys each engine takes.

Where to go next

  • A minimal input file – the same idea with PyRETIS’ internal engine, where the input does define the system.

  • The engine section documents every engine and its settings.