OpenMMTools

OpenMMTools is a Python library designed as a high-level toolkit for the OpenMM molecular simulation engine. It provides advanced tools for building molecular simulation packages, specifically focusing on GPU-accelerated workflows.

Key capabilities include:

• Advanced Integrators: High-quality Langevin integrators (e.g., g-BAOAB, VVVR) and nonequilibrium integrators for free energy calculations or nonequilibrium candidate Monte Carlo (NCMC).
• Sampling Frameworks: An extensible Markov chain Monte Carlo (MCMC) framework and enhanced sampling methods like replica-exchange (REMD) and self-adjusted mixture sampling (SAMS).
• Alchemical Transformations: Alchemical factories for generating systems for absolute and relative free energy calculations.
• Development Tools: A suite of test systems for benchmarking and debugging, and a user-friendly storage interface layer.

The openmmtools.testsystems module provides a wide variety of pre-defined test systems designed for benchmarking, validation, testing, and debugging molecular dynamics workflows. These systems range from simple analytically tractable models to complex biological systems.

Available categories include:

• Analytically tractable systems: Simple models like HarmonicOscillator, IdealGas, and LennardJonesPair where properties can be calculated analytically.
• Clusters and simple fluids: Systems such as LennardJonesFluid, WCAFluid, and various Toluene implicit/explicit models.
• Solids: e.g., SodiumChlorideCrystal.
• Water boxes: Various water models including PMEWaterBox, FlexibleWaterBox, and DischargedWaterBox.
• Peptide and protein systems: e.g., AlanineDipeptide (Vacuum, Implicit, Explicit) and LysozymeImplicit.
• Complexes: Host-guest systems in vacuum, implicit, or explicit solvent.
• Polarizable test systems: Systems compatible with polarizable force fields like AMOEBAIonBox and AMOEBAProteinBox.

The openmmtools.states module provides classes to manage and manipulate the state of an OpenMM simulation. It distinguishes between the physical properties of the system and the dynamic state of the simulation during integration:

• ThermodynamicState: Used to represent and manipulate the thermodynamic properties (like temperature and pressure) of an OpenMM System and Context.
• SamplerState: Used to represent and cache the dynamic state of the simulation (such as positions and velocities) that changes as the System is integrated.
• CompoundThermodynamicState: An extension of ThermodynamicState that implements IComposableState to handle additional parameters beyond just temperature and pressure.
• GlobalParameterState: A specialized IComposableState designed to control the global parameters of OpenMM forces.
• GlobalParameterFunction: Allows you to enslave a global parameter to specific variables or mathematical expressions.

You can build complex enhanced-sampling algorithms by leveraging OpenMMTools' specialized classes. A typical replica exchange implementation requires three components:

1. Thermodynamic States: A list of states (e.g., different temperatures or alchemical parameters) that the replicas will inhabit.
2. Sampler States: The actual configurations (positions, velocities) of the replicas.
3. MCMC Move: The mechanism used to propagate the replicas (e.g., Langevin dynamics or Monte Carlo moves).

The framework's design follows the single responsibility principle, allowing you to focus on the swapping logic while the framework handles the underlying physics and state management.

class ReplicaExchange:
    def __init__(self, thermodynamic_states, sampler_states, mcmc_move):
        self._thermodynamic_states = thermodynamic_states
        self._replicas_sampler_states = sampler_states
        self._mcmc_move = mcmc_move

    def run(self, n_iterations=1):
        for iteration in range(n_iterations):
            self._mix_replicas()
            self._propagate_replicas()

    def _propagate_replicas(self):
        for thermo_state, sampler_state in zip(self._thermodynamic_states, self._replicas_sampler_states):
            self._mcmc_move.apply(thermo_state, sampler_state)

    def _mix_replicas(self, n_attempts=1):
        # Logic for swapping thermodynamic states between replicas based on energy
        pass

When computing the potential energy of a single configuration at multiple thermodynamic states, you can optimize performance by only computing the terms of the Hamiltonian that change. This is achieved by assigning changing forces to specific OpenMM force groups.

Use openmmtools.states.reduced_potential_at_states() to leverage this. For the optimization to work, your composable states must implement _find_force_groups_to_update(self, context, current_context_state, memo), which returns the force groups that require energy updates when transitioning from current_context_state to self.

# Example of setting a force group
force = openmm.CustomBondForce('(K/2)*(r-r0)^2;')
force.setForceGroup(5)

# Using the utility to compute reduced potentials efficiently
reduced_potentials = states.reduced_potential_at_states(
    sampler_state, 
    compound_states, 
    cache.global_context_cache
)