OpenMM Plugin for Deep Potential Model

This is a plugin for OpenMM that allows DeepPotential model to be used for defining forces. It is implemented with DeePMD-kit C API interface. To use it, you need a trained Deep Potential model with DeePMD-kit that takes particle positions as input and produces forces and energy as output. This plugin uses the Deep Potential model to apply forces to particles during a simulation.

Installation

Install with conda

The conda package is only compatible with Linux system

conda create -n omm_dp
conda activate omm_dp
conda install -c conda-forge ye-ding::openmm_deepmd_plugin

Install from source

This plugin requires the library of OpenMM, DeePMD-kit C API package. Compile the plugin from the source with the following steps.

1. Prepare a conda environment by running the following commands:

   conda create -n dp_openmm
   conda activate dp_openmm
   conda install -c conda-forge openmm
   

2. Download and install the DeePMD-kit C API library by running the following command:

   wget https://github.com/deepmodeling/deepmd-kit/releases/latest/download/libdeepmd_c.tar.gz
   # Extract the C API library of Deepmd-kit to the directory of your choice.
   tar -xf libdeepmd_c.tar.gz -C ${LIBDEEPMD_C_INSTALLED_DIR}

3. Clone this repository and create a directory in which to build the plugin.

   git clone https://github.com/JingHuangLab/openmm_deepmd_plugin.git
   cd openmm_deepmd_plugin && mkdir build && cd build

4. Run cmake command with the required parameters.

   cmake .. -DOPENMM_DIR=${OPENMM_INSTALLED_DIR} -DDEEPMD_DIR=${LIBDEEPMD_C_INSTALLED_DIR}

   OPENMM_INSTALLED_DIR is the directory where OpenMM is installed. If you installed OpenMM from conda, it is the directory of the location of environment dp_openmm. LIBDEEPMD_C_INSTALLED_DIR is the directory where the DeePMD-kit C API library is installed.

5. Compile the shared library.

   make && make install

   It will install the plugin to the subdirectory of OPENMM_DIR automatically.

6. Test the plugin C interface and install the Python module of this plugin into conda environment by running the following commands:

   make test
   make PythonInstall
   export LD_LIBRARY_PATH=${LIBDEEPMD_C_INSTALLED_DIR}/lib:$LD_LIBRARY_PATH
   python -m OpenMMDeepmdPlugin.tests.test_dp_plugin_nve
   python -m OpenMMDeepmdPlugin.tests.test_dp_plugin_nve --platform CUDA

Usage of DeepPotentialModel class

To make the plugin more user-friendly, we have created a Python class called DeepPotentialModel. This class wraps the C++ interface and raw force object DeepmdForce, and provides several methods to facilitate the use of the plugin.

Creating a DeepPotentialModel object

To create a DeepPotentialModel object, use the following code:

dp_model = DeepPotentialModel(dp_model_file, Lambda=1.0)

Here, dp_model_file refers to the path of the Deep Potential model file. The parameter Lambda is used for interpolating the Deep Potential model. The output forces and energy values from the Deep Potential model are multiplied by Lambda before being added into the OpenMM context. By default, the value of Lambda is set to 1.0.

Setting the unit transformation coefficients

To set the unit transformation coefficients, use the following code:

dp_model.setUnitTransformCoefficients(coord_coefficient, force_coefficient, energy_coefficient)

In OpenMM, the units for coordinates, forces, and energy are nanometers, kJ/(mol*nm), and kJ/mol, respectively. However, the Deep Potential models have their own units, which are determined by the training data. To make the Deep Potential model compatible with OpenMM, three coefficients are needed for transforming the units.

• coord_coefficient: This coefficient transforms the input coordinates from the OpenMM context to the Deep Potential model. The values of the coordinates in OpenMM (in nanometers) will be multiplied by coord_coefficient as the input values to the Deep Potential model.
• force_coefficient: This coefficient transforms the output forces from the Deep Potential model to units that are compatible with OpenMM (i.e., kJ/(mol*nm)). The output force values will be multiplied by force_coefficient and added into the OpenMM context.
• energy_coefficient: This coefficient transforms the output energy values from the Deep Potential model to units that are compatible with OpenMM (i.e., kJ/mol). The output energy values will be multiplied by energy_coefficient and added into the OpenMM context.

Creating an OpenMM System object with the Deep Potential model

To create an OpenMM System object with the Deep Potential model, use the following code:

dp_system = dp_model.createSystem(topology)

• topology is an OpenMM Topology object of the system.

The returned dp_system is an OpenMM System object with the Deep Potential model.

Passing part of the system to the Deep Potential model

To pass part of the system to the Deep Potential model, use the following code:

dp_force = dp_model.addParticlesToDPRegion(dp_particles, topology, particleNameLabeler="element")

• dp_particles is a list of particles to be passed to the Deep Potential model (e.g., ligand particles in a protein-ligand system).
• topology is the OpenMM Topology object of the whole system.
• particleNameLabeler is the labeler used to identify the atom type of the input particles in the topology. It is optional and can be set to either "element" (default) or "atom_name".

The returned dp_force is the Force object that can be added to the simulation system.

Adapting the selection of particles to be passed to the Deep Potential model

To adaptively select the particles to be passed to the Deep Potential model, use the following code:

dp_force = dp_model.addCenterParticlesToAdaptiveDPRegion(center_particles, topology, sel_num4each_type=None, radius=0.35, atom_names_to_add_forces=None, extend_residues=True)

Here, addCenterParticlesToAdaptiveDPRegion dynamically selects the center_particles and their surrounding particles (within a distance less than radius) to the Deep Potential models.

• center_particles are the center particles of the adaptively selected DP region.

• topology is the OpenMM Topology object of the whole system.

• sel_num4each_type is a list of the maximum number for each particle type.

• radius is the distance (in nanometers) used to select other particles in the adaptive DP region based on their proximity to center_particles.

• atom_names_to_add_forces is a list of the atom names that will add DP forces. If it is None or an empty list, all selected particles in the adaptive DP region will have forces added from the DP model (default).

• extend_residues is a boolean value indicating whether or not to extend the selected particles to their belonged residues. It is set to True by default.

The returned dp_force is the Force object that can be added to the simulation system.

Application Scenarios

Conventional Simulations with Deep Potential

To construct a DP simulation with OpenMM, use the following three lines of code:

dp_model = DeepPotentialModel(dp_model_file)
dp_model.setUnitTransformCoefficients(coord_coeffi, force_coeffi, energy_coeffi)
dp_system = dp_model.createSystem(topology)

Here, dp_model_file is the path to the Deep Potential model file. coord_coeffi, force_coeffi, and energy_coeffi are the coefficients for unit transformation between the DP model and OpenMM. topology is the OpenMM Topology object of the whole system.

For more practical examples, refer to the provided simulation scripts:

• test_deepmd_nvt.py
• test_deepmd_nve.py
• test_deepmd_npt.py

DP/MM or DP+MM Simulations

To perform DP/MM simulations with fixed or adaptive DP regions, use the methods addParticlesToDPRegion and addCenterParticlesToAdaptiveDPRegion.

For example, to include ligand intramolecular interactions governed by the DP models, use addParticlesToDPRegion. If we select the ligand particles as the center particles in addCenterParticlesToAdaptiveDPRegion, the adaptively selected DP region could include protein residues and water molecules that directly interacted with the ligand.

For more practical usage of these two methods, refer to the provided simulation scripts:

• test_deepmd_dp_region.py
• test_deepmd_dp_adaptive_region.py
• test_deepmd_multi_dp_adaptive_region.py

Alchemical Simulations with Deep Potential

To perform alchemical simulations with the DP models based, combine lambda and addParticlesToDPRegion. A detailed description about the alchemical simulations protocol with the DP models could be refered to the paper.

For an example script about alchemical simulation for water's hydration-free energy calculation, refer to test_deepmd_alchemical.py.

Citing OpenMM Deepmd Plugin

To cite this repository:

@article{ding2024dp,
  title={DP/MM: A Hybrid Model for Zinc--Protein Interactions in Molecular Dynamics},
  author={Ding, Ye and Huang, Jing},
  journal={The Journal of Physical Chemistry Letters},
  volume={15},
  number={2},
  pages={616--627},
  year={2024},
  publisher={ACS Publications}
}

@article{ding2024implementation,
  title={Implementation and validation of an openmm plugin for the deep potential representation of potential energy},
  author={Ding, Ye and Huang, Jing},
  journal={International Journal of Molecular Sciences},
  volume={25},
  number={3},
  pages={1448},
  year={2024},
  publisher={MDPI}
}