Add plugin for GROMACS

README.md

@@ -60,7 +60,7 @@ Please follow our [GitHub](https://github.com/deepmodeling/deepmd-kit) webpage t
 
 DeePMD-kit offers multiple installation methods. It is recommend using easily methods like [offline packages](doc/install/easy-install.md#offline-packages), [conda](doc/install/easy-install.md#with-conda) and [docker](doc/install/easy-install.md#with-docker). 
 
-One may manually install DeePMD-kit by following the instuctions on [installing the Python interface](doc/install/install-from-source.md#install-the-python-interface) and [installing the C++ interface](doc/install/install-from-source.md#install-the-c-interface). The C++ interface is necessary when using DeePMD-kit with LAMMPS and i-PI.
+One may manually install DeePMD-kit by following the instuctions on [installing the Python interface](doc/install/install-from-source.md#install-the-python-interface) and [installing the C++ interface](doc/install/install-from-source.md#install-the-c-interface). The C++ interface is necessary when using DeePMD-kit with LAMMPS, i-PI or GROMACS.
 
 
 # Use DeePMD-kit
@@ -71,7 +71,7 @@ A quick-start on using DeePMD-kit can be found as follows:
 - [Training a model](doc/train/training.md)
 - [Freeze a model](doc/freeze/freeze.md)
 - [Test a model](doc/test/test.md)
-- [Running MD with LAMMPS](doc/third-party/lammps.md)
+- [Run MD with LAMMPS](doc/third-party/lammps.md)
 
 A full [document](doc/train/train-input-auto.rst) on options in the training input script is available.
 
@@ -113,10 +113,10 @@ A full [document](doc/train/train-input-auto.rst) on options in the training inp
     - [C++ interface](doc/inference/cxx.md)
 - [Integrate with third-party packages](doc/third-party/index.rst)
     - [Use deep potential with ASE](doc/third-party/ase.md)
-    - [Running MD with LAMMPS](doc/third-party/lammps.md)
+    - [Run 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
 The code is organized as follows:
@@ -135,6 +135,8 @@ The code is organized as follows:
 
 * `source/lmp`: source code of Lammps module.
 
+* `source/gmx`: source code of Gromacs plugin.
+
 * `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-from-source.md

@@ -146,7 +146,7 @@ Check the compiler version on your machine
 gcc --version
 ```
 
-The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is noticed that the I-Pi support is only compiled with gcc >= 4.9.
+The C++ interface of DeePMD-kit was tested with compiler gcc >= 4.8. It is noticed that the I-Pi support is only compiled with gcc >= 4.8.
 
 First the C++ interface of Tensorflow should be installed. It is noted that the version of Tensorflow should be in consistent with the python interface. You may follow [the instruction](install-tf.2.3.md) to install the corresponding C++ interface.
 

doc/install/install-gromacs.md

@@ -0,0 +1,31 @@
+# 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
+export PATH=$PATH:$deepmd_kit_root/bin
+dp_gmx_patch -d $gromacs_root -v $version -p
+```
+where `deepmd_kit_root` is the directory where the latest version of deepmd-kit is installed, and `gromacs_root` refers to source code directory of gromacs. 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. 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
+
+cmake3 .. -DCMAKE_CXX_STANDARD=14 \ # not required, but c++14 seems to be more compatible with higher version of tensorflow
+          -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 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
+```
++ `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

@@ -3,6 +3,7 @@
 Note that the model for inference is required to be compatible with the DeePMD-kit package. See [Model compatibility](../troubleshooting/model-compatability.html) for details.
 
 - [Use deep potential with ASE](ase.md)
-- [Running MD with LAMMPS](lammps.md)
+- [Run 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)
+- [Run 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

doc/third-party/lammps.md

@@ -1,4 +1,4 @@
-# Running MD with LAMMPS
+# Run MD with LAMMPS
 
 Running an MD simulation with LAMMPS is simpler. In the LAMMPS input file, one needs to specify the pair style as follows
 

doc/troubleshooting/installation.md

@@ -1,13 +1,11 @@
 # Installation
 ## Inadequate versions of gcc/g++
-Sometimes you may use a gcc/g++ of version <4.9. If you have a gcc/g++ of version > 4.9, say, 7.2.0, you may choose to use it by doing 
+Sometimes you may use a gcc/g++ of version < 4.8. In this way, you can still compile all the parts of TensorFlow and most of the parts of DeePMD-kit, but i-Pi and GROMACS plugin will be disabled automatically. Or if you have a gcc/g++ of version > 4.8, say, 7.2.0, you may choose to use it by doing 
 ```bash
 export CC=/path/to/gcc-7.2.0/bin/gcc
 export CXX=/path/to/gcc-7.2.0/bin/g++
 ```
 
-If, for any reason, for example, you only have a gcc/g++ of version 4.8.5, you can still compile all the parts of TensorFlow and most of the parts of DeePMD-kit. i-Pi will be disabled automatically.
-
 ## Build files left in DeePMD-kit
 When you try to build a second time when installing DeePMD-kit, files produced before may contribute to failure. Thus, you may clear them by
 ```bash

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
+}