OpenMM

Jupyter notebook tutorials

A set of tutorials that demonstrate how to use NanoVer to run interactive molecular dynamics simulations using OpenMM directly.

The Jupyter notebook tutorials that demonstrate how to run interactive molecular dynamics simulations by interfacing NanoVer with OpenMM directly can be found in the examples folder of the GitHub repository. It contains:

  • openmm_polyalanine: A notebook that demonstrates how to set up an interactive OpenMM simulation from scratch with NanoVer, use features of OpenMM in conjunction with NanoVer, and record & playback simulations directly using NanoVer.

  • openmm_nanotube: A notebook that demonstrates how to interact with an OpenMM NanoVer simulation using a python client.

  • openmm_neuraminidase: A notebook that demonstrates how to set up an interactive OpenMM simulation from scratch with NanoVer and change the visualisations of different atom selections for a protein-ligand system.


NanoVer OpenMM XML files

File format

The NanoVer OpenMM XML file format described herein is used for saving and loading NanoVer OpenMM simulations. These files consist of a root element, <OpenMMSimulation>, which contains three mandatory components and an optional fourth:

  1. Starting structure: enclosed in either <pdbx> or <pdb> tags

  2. OpenMM serialized System: enclosed in the <System> tag

  3. OpenMM serialized Integrator: enclosed in the <Integrator> tag

  4. OpenMM serialized State: enclosed in the <State> tag (optional)

E.g. a file that includes the OpenMM serialized State will have the following structure:

<OpenMMSimulation>
    <pdbx>
        <!-- Content of the PDBx file -->
    </pdbx>
    <System ...>
        <!-- XML content of the OpenMM serialized System -->
    </System>
    <Integrator ...>
        <!-- XML content of the OpenMM serialized Integrator -->
    </Integrator>
    <State ...>
        <!-- XML content of the OpenMM serialized State -->
    </State>
</OpenMMSimulation>

Note

XML files used by OpenMM differ from those used to run OpenMM via NanoVer. Although the serialized objects contained in the NanoVer OpenMM XML files are identical to those defined by OpenMM, the overall contents and structure of the files are specific to NanoVer and cannot be read by OpenMM directly.

Expand the following dropdowns for further details of each component:

1. Starting structure

  • Tag: <pdbx> (preferred) or <pdb> (for backward compatibility)

  • Content: the entire PDBx or PDB file content

2. OpenMM serialized System

Within this tag, you’ll find:

Particles: each particle is represented with a <Particle> tag, containing:

  • Mass

  • Charge (if using a NonbondedForce)

Forces: the force components, each represented by specific tags (a detailed list can be found in this link), for example:

  • <HarmonicBondForce>: for bond stretching

  • <HarmonicAngleForce>: for angle bending

  • <PeriodicTorsionForce>: for dihedral angles

  • <NonbondedForce>: for electrostatic and van der Waals interactions

  • <CustomNonbondedForce>: for user-defined nonbonded interactions

Each force tag contains parameters specific to that force type. For example:

<HarmonicBondForce>
  <Bond p1="0" p2="1" length="0.1" k="1000"/>
</HarmonicBondForce>

Constraints: If present, constraints are listed under the <Constraints> tag:

<Constraints>
  <Constraint p1="0" p2="1" distance="0.1"/>
</Constraints>
3. OpenMM serialized Integrator

The <Integrator> tag contains parameters that specify the integration method to be used to simulate dynamics, such as the type of integrator, simulation time step, and temperature:

<Integrator type="LangevinIntegrator" constraintTolerance="1e-05" friction="4" randomSeed="0" stepSize=".0005" temperature="300" version="1" />

More details on integrators can be found here.

4. OpenMM serialized State

The <State> tag contains the serialized state of the simulation, including:

  • Particle velocities, <Velocities>

  • Adjustable parameters that have been defined by Force objects in the System, <Parameters>

  • Periodic box vectors (if periodic boundary conditions are used), <PeriodicBoxVectors>

  • Integrator parameters, <IntegratorParameters>


Creation and usage

The nanover.openmm.serializer module provides the serialize_simulation and deserialize_simulation functions which allow saving and loading OpenMM simulations to/from XML files. The serialization captures by default the complete simulation including:

  • Structure coordinates and topology (as PDBx/PDB)

  • OpenMM System definition

  • Integrator configuration

  • Serialized State (optional)

Serializing a simulation

To save a simulation to a NanoVer OpenMM XML using Python:

xml_string = nanover.openmm.serializer.serialize_simulation(simulation)

with open("sim.xml", "w") as f:
    f.write(xml_string)

The serialize_simulation function accepts optional arguments:

  • save_state: whether to include the serialized state in the XML (default: False)

Deserializing a simulation

To load a simulation from a NanoVer OpenMM XML using Python:

with open("sim.xml", "r") as f:
    simulation = nanover.openmm.serializer.deserialize_simulation(f.read())

The deserialize_simulation function accepts optional arguments:

  • imd_force: a CustomExternalForce for interactive molecular dynamics

  • platform_name: the parallel computing platform for OpenMM to use (e.g. “CUDA”, “OpenCL”)

  • ignore_state: whether to ignore the serialized state in the XML (default: False)

For example:

simulation = nanover.openmm.serializer.deserialize_simulation(
    xml_string,
    platform_name="CUDA"
)

For more details, refer to our example notebook on saving OpenMM systems to NanoVer OpenMM XML files.