Add plugin for gromacs

README.md

@@ -82,6 +82,7 @@ A full [document](doc/train/train-input-auto.rst) on options in the training inp
     - [Install from source code](doc/install/install-from-source.md)
     - [Install LAMMPS](doc/install/install-lammps.md)
     - [Install i-PI](doc/install/install-ipi.md)
+    - [Install GROMACS](doc/install/install-gromacs.md)
     - [Building conda packages](doc/install/build-conda.md)
 - [Data](doc/data/index.md)
     - [Data conversion](doc/data/data-conv.md)
@@ -116,6 +117,7 @@ A full [document](doc/train/train-input-auto.rst) on options in the training inp
     - [Running MD with LAMMPS](doc/third-party/lammps.md)
     - [LAMMPS commands](doc/third-party/lammps-command.md)
     - [Run path-integral MD with i-PI](doc/third-party/ipi.md)
+    - [Run MD with GROMACS](doc/third-party/gromacs.md)
 
 
 # Code structure
@@ -135,6 +137,8 @@ The code is organized as follows:
 
 * `source/lmp`: source code of Lammps module.
 
+* `source/gmx`: source code of Gromacs plugin and patches.
+
 * `source/op`: tensorflow op implementation. working with library.
 
 

doc/install/index.md

@@ -4,4 +4,5 @@
 - [Install from source code](install-from-source.md)
 - [Install LAMMPS](install-lammps.md)
 - [Install i-PI](install-ipi.md)
+- [Install GROMACS](install-gromacs.md)
 - [Building conda packages](build-conda.md)

doc/install/index.rst

@@ -8,4 +8,5 @@ Installation
    install-from-source
    install-lammps
    install-ipi
+   install-gromacs
    build-conda

doc/install/install-gromacs.md

@@ -0,0 +1,35 @@
+# Install GROMACS with DeepMD
+## Patch source code of GROMACS 
+Download source code of a supported gromacs version (2020.2) from https://manual.gromacs.org/2020.2/download.html. Run the following command:
+```bash
+cd $deepmd_root/source/gmx
+./patch.sh -d $gromacs_root -v $version -p
+```
+where `deepmd_root` and `gromacs_root` refer to source code directory of deepmd-kit and gromacs respectively. And `version` represents the version of gromacs, **only support 2020.2 now**. You may patch another version of gromacs but still setting `version` to `2020.2`. However, we cannot ensure that it works.
+
+<!-- ## Install C++ api of deepmd-kit and tensorflow
+The C++ interface of `deepmd-kit 2.x` and `tensorflow 2.x` are required. -->
+<!-- + Tips: C++ api of deepmd and tensorflow could be easily installed from the deepmd-kit offline packages. But before using tensorflow, you need to manually change the protobuf package to [version 3.9.2](https://github.com/protocolbuffers/protobuf/releases/tag/v3.9.2) in `$deepmd_env_dir/include/google/protobuf` (the offline package will install a version of 3.14, which will cause incompability). Here `deepmd_env_dir` refers to the directory of conda environment created by the deepmd-kit offline packages.  -->
+
+## Compile GROMACS with deepmd-kit
+The C++ interface of `deepmd-kit 2.x` and `tensorflow 2.x` are required. And be aware that only deepmd-kit with **high precision** is supported now, since we cannot ensure single precision is enough for a GROMACS simulation. Specify the installation path of tensorflow and deepmd using cmake options: `-DGMX_TENSORFLOW_ROOT` and `-DGMX_DEEPMD_ROOT`. Here is a sample compile scipt:
+```bash
+#!/bin/bash
+export CC=/usr/bin/gcc
+export CXX=/usr/bin/g++
+export CMAKE_PREFIX_PATH="/path/to/fftw-3.3.9" # fftw libraries
+mkdir build
+cd build
+TENSORFLOW_ROOT="/path/to/tensorflow"
+DEEPMD_ROOT="/path/to/deepmd"
+
+cmake3 .. -DCMAKE_CXX_STANDARD=14 \ # not required, but c++14 seems to be more compatible with higher version of tensorflow
+          -DGMX_TENSORFLOW_ROOT=${TENSORFLOW_ROOT} \
+          -DGMX_DEEPMD_ROOT=${DEEPMD_ROOT} \
+          -DGMX_MPI=ON \
+          -DGMX_GPU=CUDA \ # Gromacs on ROCm has not been fully developed yet
+          -DCUDA_TOOLKIT_ROOT_DIR=/path/to/cuda \
+          -DCMAKE_INSTALL_PREFIX=/path/to/gromacs-2020.2-deepmd
+make -j
+make install
+```

doc/third-party/gromacs.md

@@ -0,0 +1,120 @@
+# Running MD with GROMACS
+## DP/MM Simulation
+This part gives a simple tutorial on how to run a DP/MM simulation for methane in water, which means using DP for methane and TIP3P for water. All relevant files can be found in `examples/methane`.
+### Topology Preparation
+Similar to QM/MM simulation, the internal interactions (including bond, angle, dihedrals, LJ, Columb) of the region descibed by a neural network potential (NNP) have to be **turned off**. In GROMACS, bonded interactions can be turned off by modifying `[ bonds ]`, `[ angles ]`, `[ dihedrals ]` and `[ pairs ]` sections. And LJ and Columb interactions must be turned off by `[ exclusions ]` section.
+
+For example, if one wants to simulate ethane in water, using DeepPotential for methane and TIP3P for water, the topology of methane should be like the following (as presented in `examples/methane/methane.itp`):
+```
+[ atomtypes ]
+;name btype  mass  charge ptype    sigma  epsilon
+  c3    c3   0.0     0.0     A 0.339771 0.451035
+  hc    hc   0.0     0.0     A 0.260018 0.087027
+
+[ moleculetype ]
+;name            nrexcl
+ methane          3
+
+[ atoms ]
+; nr type  resnr residue atom  cgnr  charge   mass
+  1   c3      1     MOL   C1     1 -0.1068 12.010
+  2   hc      1     MOL   H1     2  0.0267  1.008
+  3   hc      1     MOL   H2     3  0.0267  1.008
+  4   hc      1     MOL   H3     4  0.0267  1.008
+  5   hc      1     MOL   H4     5  0.0267  1.008
+
+[ bonds ]
+; i  j  func  b0  kb
+ 1  2     5        
+ 1  3     5        
+ 1  4     5        
+ 1  5     5        
+
+[ exclusions ]
+; ai  aj1  aj2  aj3  aj4
+  1    2    3    4    5
+  2    1    3    4    5
+  3    1    2    4    5
+  4    1    2    3    5
+  5    1    2    3    4
+```
+For comparsion, the original topology file genearted by `acpype` will be:
+```
+; methane_GMX.itp created by acpype (v: 2021-02-05T22:15:50CET) on Wed Sep  8 01:21:53 2021
+
+[ atomtypes ]
+;name   bond_type     mass     charge   ptype   sigma         epsilon       Amb
+ c3       c3          0.00000  0.00000   A     3.39771e-01   4.51035e-01 ; 1.91  0.1078
+ hc       hc          0.00000  0.00000   A     2.60018e-01   8.70272e-02 ; 1.46  0.0208
+
+[ moleculetype ]
+;name            nrexcl
+ methane          3
+
+[ atoms ]
+;   nr  type  resi  res  atom  cgnr     charge      mass       ; qtot   bond_type
+     1   c3     1   MOL    C1    1    -0.106800     12.01000 ; qtot -0.107
+     2   hc     1   MOL    H1    2     0.026700      1.00800 ; qtot -0.080
+     3   hc     1   MOL    H2    3     0.026700      1.00800 ; qtot -0.053
+     4   hc     1   MOL    H3    4     0.026700      1.00800 ; qtot -0.027
+     5   hc     1   MOL    H4    5     0.026700      1.00800 ; qtot 0.000
+
+[ bonds ]
+;   ai     aj funct   r             k
+     1      2   1    1.0970e-01    3.1455e+05 ;     C1 - H1    
+     1      3   1    1.0970e-01    3.1455e+05 ;     C1 - H2    
+     1      4   1    1.0970e-01    3.1455e+05 ;     C1 - H3    
+     1      5   1    1.0970e-01    3.1455e+05 ;     C1 - H4    
+
+[ angles ]
+;   ai     aj     ak    funct   theta         cth
+     2      1      3      1    1.0758e+02    3.2635e+02 ;     H1 - C1     - H2    
+     2      1      4      1    1.0758e+02    3.2635e+02 ;     H1 - C1     - H3    
+     2      1      5      1    1.0758e+02    3.2635e+02 ;     H1 - C1     - H4    
+     3      1      4      1    1.0758e+02    3.2635e+02 ;     H2 - C1     - H3    
+     3      1      5      1    1.0758e+02    3.2635e+02 ;     H2 - C1     - H4    
+     4      1      5      1    1.0758e+02    3.2635e+02 ;     H3 - C1     - H4    
+```
+### DeepMD Settings
+Before running simulation, we need to tell GROMACS to use DeepPotential by setting environment variable `GMX_DEEPMD_INPUT_JSON`:
+```bash
+export GMX_DEEPMD_INPUT_JSON=input.json
+```
+Then, in your working directories, we have to write `input.json` file:
+```json
+{
+    "graph_file": "/path/to/graph.pb",
+    "type_file": "type.raw",
+    "index_file": "index.raw",
+    "lambda": 1.0,
+    "pbc": false
+}
+```
+Here is an explanation for these settings:
++ `graph_file` : The graph file (with suffix .pb) generated by `dp freeze` command
++ `type_file` : File to specify DP atom types (in space-sepreated format). Here, `type.raw` looks like
+```
+1 1 0 0 0 0 0 0
+```
++ `index_file` : File containing indices of DP atoms (in space-seperated format), which should be in consistent with indices' order in .gro file but **starting from zero**. Here, `index.raw` looks like
+```
+0 1 2 3 4 5 6 7
+```
++ `lambda`: Optional, default 1.0. Used in alchemical calculations.
++ `pbc`: Optional, default true. If true, the GROMACS peroidic condition is passed to DeepMD.
+
+### Run Simulation
+Finally, you can run GROMACS using `gmx mdrun` as usual.
+
+## All-atom DP Simulation
+This part gives an example on how to run a simulation with all atoms described by a DeepPotential with Gromacs, taking water as an example. Instead of using `[ exclusions ]` to turn off the non-bonded energies, we can simply do this by setting LJ parameters (i.e. epsilon and sigma) and partial charges to 0, as shown in `examples/water/gmx/water.top`:
+```
+[ atomtypes ]
+; name      at.num  mass     charge ptype  sigma      epsilon
+HW           1       1.008   0.0000  A   0.00000e+00  0.00000e+00
+OW           8      16.00    0.0000  A   0.00000e+00  0.00000e+00
+``` 
+As mentioned in the above section, `input.json` and relevant files (`index.raw`, `type.raw`) should also be created. Then, we can start the simulation under NVT ensemble and plot the radial distribution function (RDF) by `gmx rdf` command. We can see that the RDF given by Gromacs+DP matches perfectly with Lammps+DP, which further provides an evidence on the validity of our simulation.
+![rdf](../../examples/water/gmx/rdf.png)
+
+However, we still recommend you run all-atom DP simulation using LAMMPS since it is more stable and efficient.

doc/third-party/index.md

@@ -5,4 +5,5 @@ Note that the model for inference is required to be compatible with the DeePMD-k
 - [Use deep potential with ASE](ase.md)
 - [Running MD with LAMMPS](lammps.md)
 - [LAMMPS commands](lammps-command.md)
-- [Run path-integral MD with i-PI](ipi.md)
+- [Run path-integral MD with i-PI](ipi.md)
+- [Running MD with GROMACS](gromacs.md)

doc/third-party/index.rst

@@ -10,3 +10,4 @@ Note that the model for inference is required to be compatible with the DeePMD-k
    lammps
    lammps-command
    ipi
+   gromacs

examples/methane/index.raw

@@ -0,0 +1 @@
+0 1 2 3 4

examples/methane/input.json

@@ -0,0 +1,7 @@
+{
+    "graph_file": "frozen_model.pb",
+    "type_file": "type.raw",
+    "index_file": "index.raw",
+    "lambda": 1.0,
+    "pbc": false
+}