OpenMM Python Wrapper

Common errors

• ImportError: DLL load failed while importing _openmm: The specified module could not be found.

  cause This error commonly occurs on Windows when OpenMM's C++ libraries or their dependencies are not correctly found by the Python environment, often due to issues with PATH or a corrupted `conda` environment.
  fix Try creating a new, clean `conda` environment and reinstalling OpenMM: `conda create -c conda-forge --name openmm_env python=3.9 openmm` then `conda activate openmm_env`. Also ensure system PATH includes necessary OpenMM library directories if installed from standalone installers.

• OpenMMException: Expected a Quantity object but got a float/int.

  cause A numerical value (float or int) was provided where OpenMM expected a `openmm.unit.Quantity` object with a specified unit.
  fix Append a unit from `openmm.unit` to the numerical value, e.g., change `300` to `300*unit.kelvin` or `1.0` to `1.0*unit.nanometers`.

• OpenMMException: Platform 'CUDA' is not available.

  cause The OpenMM `CUDA` platform could not be initialized. This typically means NVIDIA CUDA Toolkit or compatible drivers are not installed, not correctly configured, or not visible to OpenMM.
  fix Install the latest NVIDIA GPU drivers and the CUDA Toolkit appropriate for your system. Verify installation with `python -m openmm.testInstallation`.

Warnings

• breaking The `simtk` namespace was removed in OpenMM 8.x. All imports previously under `simtk.openmm` or `simtk.unit` should now be directly imported from `openmm` or `openmm.unit` respectively.
  Fix: Change `import simtk.openmm.app as app` to `import openmm.app as app` and similarly for other `simtk` imports.
• gotcha OpenMM extensively uses a `unit` system. Omitting unit specifications (e.g., `300` instead of `300*unit.kelvin`) for physical quantities will lead to `OpenMMException` or incorrect behavior, as OpenMM expects `openmm.unit.Quantity` objects.
  Fix: Always use quantities from `openmm.unit` (e.g., `300*unit.kelvin`, `1.0*unit.nanometers`) when defining physical parameters.
• gotcha For GPU acceleration (CUDA or OpenCL platforms), appropriate drivers must be installed on your system. Without them, OpenMM will fall back to the slower CPU platform or fail to initialize the specified GPU platform.
  Fix: Ensure you have the latest NVIDIA CUDA drivers (for CUDA platform) or OpenCL drivers (for OpenCL platform) installed and correctly configured for your operating system and hardware.
• breaking OpenMM 8.x introduced `PythonForce` to support machine learning potentials, which has higher overhead than traditional custom forces. If a force can be implemented with existing custom forces, that is generally more performant.
  Fix: For optimal performance, evaluate if a custom force can be implemented using OpenMM's built-in `CustomForce` classes before resorting to `PythonForce`.

Install

• pip install openmm PyPI
• conda install -c conda-forge openmm Conda

Imports

• openmm

  import openmm

• openmm.app
  wrong:

  import simtk.openmm.app as app

  correct:

  from openmm.app import *

  The 'simtk' prefix was deprecated and removed in OpenMM 8.x. Direct import from 'openmm.app' is the correct modern approach.
• openmm.unit
  wrong:

  import simtk.unit as unit

  correct:

  from openmm.unit import *

  The 'simtk' prefix was deprecated and removed in OpenMM 8.x. Direct import from 'openmm.unit' is the correct modern approach.

Quickstart

This quickstart demonstrates a basic molecular dynamics simulation using OpenMM. It loads a PDB file, applies a force field to create a system, sets up a Langevin integrator, performs energy minimization, and then runs a short simulation, saving trajectory and state data. A `protein.pdb` file is required in the execution directory for this example to run.

import openmm.app as app
import openmm as mm
import openmm.unit as unit

# This example assumes a 'protein.pdb' file exists in the same directory.
# A minimal PDB can be generated or downloaded, e.g., from RCSB PDB (e.g., 1AKI).
# For a real simulation, ensure your PDB is properly prepared (e.g., with PDBFixer).
try:
    pdb = app.PDBFile('protein.pdb')
except FileNotFoundError:
    print("Error: 'protein.pdb' not found. Please provide a PDB file for the quickstart.")
    exit()

# Create a force field for the system
forcefield = app.ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')

# Create a system from the PDB topology and force field
system = forcefield.createSystem(pdb.topology,
                                nonbondedMethod=app.PME,
                                nonbondedCutoff=1.0*unit.nanometers,
                                constraints=app.HBonds)

# Create an integrator for advancing the simulation
integrator = mm.LangevinMiddleIntegrator(300*unit.kelvin, 1/unit.picosecond, 0.004*unit.picoseconds)

# Create a simulation object
simulation = app.Simulation(pdb.topology, system, integrator)
simulation.context.setPositions(pdb.positions)

# Minimize energy to relieve bad contacts
print('Minimizing energy...')
simulation.minimizeEnergy()
print(f'Potential energy after minimization: {simulation.context.getState(getEnergy=True).getPotentialEnergy()}')

# Add reporters for output
simulation.reporters.append(app.PDBReporter('output.pdb', 1000))
simulation.reporters.append(app.StateDataReporter('data.csv', 1000, step=True, potentialEnergy=True, temperature=True, separator=','))

# Run the simulation
print('Running simulation...')
simulation.step(10000) # Run 10,000 steps
print('Simulation complete. Output saved to output.pdb and data.csv')