Collective Variable Package

Overview

Collective variables (CVs) are functions of the coordinates of a molecular system that project its conformational state onto a lower-dimensional space. Biasing the dynamics of a judiciously chosen set of CVs enhances the sampling of configuration space, including regions that are otherwise difficult to reach. The free energy of the system as a function of these CVs characterizes the relative stability of different states and the pathways connecting them.

CVPack provides ready-to-use CVs for the molecular dynamics engine OpenMM. Every CV is a subclass of OpenMM's Force class, so it can be added directly to a CustomCVForce or used to define a BiasVariable for Metadynamics. In addition, each CV:

• reports its value and its effective mass in OpenMM's MD unit system;
• can be serialized to and deserialized from YAML;
• can be reported during a simulation through cvpack.reporting.StateDataReporter.

Collective Variables

Installation

CVPack is available from the mdtools conda channel and from PyPI:

conda install -c conda-forge -c mdtools cvpack

pip install cvpack

CVPack requires OpenMM 8.4 or later. CompositeRMSD also requires version 0.2.0 or later of the openmm-cpp-forces package, which is available from the mdtools channel for OpenMM 8.4 to 8.6 (Linux and macOS) and from PyPI. Earlier versions compute wrong forces for groups of different sizes.

Quick Start

The example below computes the backbone dihedral angles of alanine dipeptide, using a test system from OpenMMTools:

import cvpack
import openmm
from openmmtools import testsystems

model = testsystems.AlanineDipeptideVacuum()
phi = cvpack.Torsion(4, 6, 8, 14, name="phi")
psi = cvpack.Torsion(6, 8, 14, 16, name="psi")
for cv in (phi, psi):
    cv.addToSystem(model.system)

context = openmm.Context(model.system, openmm.VerletIntegrator(0.001))
context.setPositions(model.positions)
print(phi.getValue(context), psi.getValue(context))

addToSystem puts each CV in its own force group, which makes evaluating it cheap. Note that a CV added to a system also contributes its value to the potential energy. To compute CVs without biasing the dynamics, integrate only the force groups of the physical forces (see openmm.Integrator.setIntegrationForceGroups).

Documentation

The documentation of the latest release and of the development version is available on GitHub Pages.

Related Packages

OpenMM-Colvars adds the Colvars library to OpenMM through a C++ Force with Python bindings. Colvars has its own set of CVs and enhanced-sampling methods, and it is also available in NAMD, LAMMPS, GROMACS, VMD and Tinker-HP.

Copyright

Copyright (c) 2023-2024 C. Abreu & Redesign Science

Acknowledgments

Initial project based on the CMS Cookiecutter version 1.1.