Running a PyRETIS simulation with OpenMM

In this example, we show the interface between OpenMM and PyRETIS.

Verification status: engine – see Tutorial map.

Tutorial quick start

  • Best starting point: the OpenMM fixture under examples/tests/test-openmm/ and the files included below.
  • Requirements: openmm importable in Python and an OpenMM Simulation object defined in a Python module.
  • Edit first: the openmm_module and openmm_simulation settings in the Engine section.
  • Run: pyretisrun -i openmm_retis.rst -p.
  • Expected output: standard RETIS output folders, with propagation delegated to OpenMM.
  • Related check: examples/tests/test-openmm/; see Example test status.

First, we need to generate a file with an OpenMM Simulation object. We use the online tool OpenMM Script Builder to generate the example with this PDB file containing two water molecules.

from openmm import app
import openmm as mm
from openmm import unit

pdb = app.PDBFile('input.pdb')
forcefield = app.ForceField('amber99sbildn.xml', 'tip3p.xml')

system = forcefield.createSystem(pdb.topology, nonbondedMethod=app.PME,
                                 nonbondedCutoff=1.0*unit.nanometers,
                                 constraints=app.HBonds, rigidWater=True,
                                 ewaldErrorTolerance=0.0005)
integrator = mm.LangevinIntegrator(300*unit.kelvin,
                                   1.0/unit.picoseconds,
                                   2.0*unit.femtoseconds)
integrator.setConstraintTolerance(0.00001)

# Check with "python -m simtk.testInstallation" which platforms are available
# Here I use CUDA, but CPU is more commonly available
# platform = mm.Platform.getPlatformByName('CPU')
platform = mm.Platform.getPlatformByName('CUDA')
simulation = app.Simulation(pdb.topology, system, integrator, platform)
simulation.context.setPositions(pdb.positions)

With this simulation object, we can now construct the required .rst options in the engine section:

Engine
------
type = openmm
class = openmm
openmm_simulation = simulation
openmm_module = openmm_sim.py
subcycles = 10

Here we say that:

  • The engine type is openmm, which tells PyRETIS that it has a special system representation.
  • The engine class is also openmm to tell PyRETIS we want to use the OpenMM engine.
  • The openmm_module is the module from which we want to load the simulation. Here it is openmm_sim.py.
  • The openmm_simulation is the name of the object in that file. In this case it is simulation.

Finally, we give the number of subcycles, which indicates how many MD steps OpenMM performs before PyRETIS requests another frame. This value should be relatively high when using GPUs, as it determines how often PyRETIS communicates with the GPU. However, keep in mind that this also lowers the time resolution of your PyRETIS simulation.

After this, the setup can be run as a regular PyRETIS simulation using pyretisrun:

pyretisrun -i openmm_retis.rst -p

Tested by

OpenMM coverage is tracked through examples/tests/test-openmm/. This check is optional because it depends on the local OpenMM installation. See Example test status for the current run status before treating this example as verified on a given platform.