add LAMMPS plugin (#945)

* add LAMMPS plugin

- Breaking changes: update fix_dplr to support lammps/lammps#2560. Old version may be not supported. No idea how to support both versions.
- Feature: support LAMMPS's new plugin package. See document for details.
- update document and examples for LAMMPS plugin. The old installation method will be still supported, although it's removed from documents.
- LAMMPS hasn't released a stable version, but I think it will be released in one or two months.

* fix include path

* add compatibility

* add `make install` to lammps document

* update document for built-in mode

* revert troublesome

* update docs

* Update source/install/build_cc.sh

.github/workflows/build_cc.yml

@@ -9,14 +9,8 @@ jobs:
     strategy:  
       matrix:
         include:
-        - float_prec: high
-          variant: cpu
-        - float_prec: low
-          variant: cpu
-        - float_prec: high
-          variant: cuda
-        - float_prec: low
-          variant: cuda
+        - variant: cpu
+        - variant: cuda
     steps:
     - uses: actions/checkout@master
       with:
@@ -26,12 +20,6 @@ jobs:
       if: matrix.variant == 'cuda'
     - run: source/install/build_cc.sh
       env:
-        FLOAT_PREC: ${{ matrix.float_prec }}
         DP_VARIANT: ${{ matrix.variant }}
         CC: gcc-7
         CXX: g++-7
-    - run: source/install/build_lammps.sh
-      env:
-        FLOAT_PREC: ${{ matrix.float_prec }}
-        CC: gcc-7
-        CXX: g++-7

doc/getting-started.md

@@ -417,6 +417,16 @@ Note that the model for MD simulations is required to be compatible with the Dee
 
 ### Run MD with LAMMPS
 
+#### Enable DeePMD-kit plugin (plugin mode)
+
+If you are using the plugin mode, enable DeePMD-kit package in LAMMPS with `plugin` command:
+
+```
+plugin load path/to/deepmd/lib/libdeepmd_lmp.so
+```
+
+The built-in mode doesn't need this step.
+
 #### pair_style `deepmd`
 
 The DeePMD-kit package provides the pair_style `deepmd`

doc/install.md

@@ -2,7 +2,7 @@
 
 - [Easy installation methods](#easy-installation-methods)
 - [Install from source code](#install-from-source-code)
-- [Install i-PI](#install-i-pi)
+- [Install third-party packages](#install-third-party-packages)
 - [Building conda packages](#building-conda-packages)
 
 ## Easy installation methods
@@ -204,6 +204,8 @@ One may add the following arguments to `cmake`:
 | -DCUDA_TOOLKIT_ROOT_DIR=<value> | Path         | Detected automatically | The path to the CUDA toolkit directory. |
 | -DUSE_ROCM_TOOLKIT=<value> | `TRUE` or `FALSE` | `FALSE`       | If `TRUE`, Build GPU support with ROCM toolkit. |
 | -DROCM_ROOT=<value> | Path         | Detected automatically | The path to the ROCM toolkit directory. |
+| -DLAMMPS_VERSION_NUMBER=<value> | Number         | `20201029` | Only neccessary for LAMMPS built-in mode. The version number of LAMMPS (yyyymmdd). |
+| -DLAMMPS_SOURCE_ROOT=<value> | Path         | - | Only neccessary for LAMMPS plugin mode. The path to the LAMMPS source code (later than 8Apr2021). If not assigned, the plugin mode will not be enabled. |
 
 If the cmake has executed successfully, then 
 ```bash
@@ -215,13 +217,15 @@ The option `-j4` means using 4 processes in parallel. You may want to use a diff
 If everything works fine, you will have the following executable and libraries installed in `$deepmd_root/bin` and `$deepmd_root/lib`
 ```bash
 $ ls $deepmd_root/bin
-dp_ipi
+dp_ipi      dp_ipi_low
 $ ls $deepmd_root/lib
-libdeepmd_ipi.so  libdeepmd_op.so  libdeepmd.so
+libdeepmd_cc_low.so  libdeepmd_ipi_low.so  libdeepmd_lmp_low.so  libdeepmd_low.so          libdeepmd_op_cuda.so  libdeepmd_op.so
+libdeepmd_cc.so      libdeepmd_ipi.so      libdeepmd_lmp.so      libdeepmd_op_cuda_low.so  libdeepmd_op_low.so   libdeepmd.so
 ```
 
-### Install LAMMPS's DeePMD-kit module
-DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS.
+## Install third-party packages
+### Install LAMMPS's DeePMD-kit module (built-in mode)
+DeePMD-kit provide module for running MD simulation with LAMMPS. Now make the DeePMD-kit module for LAMMPS. If you want to use the plugin mode instead of the built-in mode, you can directly go to the next section.
 ```bash
 cd $deepmd_source_dir/source/build
 make lammps
@@ -254,7 +258,33 @@ The DeePMD-kit module can be removed from LAMMPS source code by
 make no-user-deepmd
 ```
 
-## Install i-PI
+### Install LAMMPS (plugin mode)
+Starting from `8Apr2021`, LAMMPS also provides a plugin mode, allowing one build LAMMPS and a plugin separately. You can skip the section if you are using the built-in mode.
+
+Now download the LAMMPS code (`8Apr2021` or later), and uncompress it:
+```bash
+cd /some/workspace
+wget https://github.com/lammps/lammps/archive/patch_30Jul2021.tar.gz
+tar xf patch_30Jul2021.tar.gz
+```
+The source code of LAMMPS is stored in directory `lammps-patch_30Jul2021`. Now go into the LAMMPS code and create a directory called `build`
+```bash
+mkdir -p lammps-patch_30Jul2021/build/
+cd lammps-patch_30Jul2021/build/
+```
+Now build LAMMPS. Note that `PLUGIN` and `KSPACE` package must be enabled, and `BUILD_SHARED_LIBS` must be set to `yes`. You can install any other package you want.
+```bash
+cmake -D PKG_PLUGIN=ON -D PKG_KSPACE=ON -D LAMMPS_INSTALL_RPATH=ON -D BUILD_SHARED_LIBS=yes -D CMAKE_INSTALL_PREFIX=${deepmd_root} ../cmake
+make -j4
+make install
+```
+
+If everything works fine, you will end up with an executable `${deepmd_root}/lmp`.
+```bash
+${deepmd_root}/lmp -h
+```
+
+### Install i-PI
 The i-PI works in a client-server model. The i-PI provides the server for integrating the replica positions of atoms, while the DeePMD-kit provides a client named `dp_ipi` that computes the interactions (including energy, force and virial). The server and client communicates via the Unix domain socket or the Internet socket. A full instruction of i-PI can be found [here](http://ipi-code.org/). The source code and a complete installation instructions of i-PI can be found [here](https://github.com/i-pi/i-pi).
 To use i-PI with already existing drivers, install and update using Pip:
 ```bash

examples/water/lmp/in.lammps

@@ -12,7 +12,7 @@ mass 		1 16
 mass		2 2
 
 pair_style	deepmd frozen_model.pb
-pair_coeff	
+pair_coeff  * *	
 
 velocity        all create 330.0 23456789
 

examples/water/lmp/in.plugin.lammps

@@ -0,0 +1,28 @@
+# bulk water
+
+units           metal
+boundary        p p p
+atom_style      atomic
+
+neighbor        2.0 bin
+neigh_modify    every 10 delay 0 check no
+
+read_data	water.lmp
+mass 		1 16
+mass		2 2
+
+# load the plugin at <install_prefix>/lib/libdeepmd_lmp.so
+plugin load ../../../dp/lib/libdeepmd_lmp.so
+
+pair_style	deepmd frozen_model.pb
+pair_coeff  * *	
+
+velocity        all create 330.0 23456789
+
+fix             1 all nvt temp 330.0 330.0 0.5
+timestep        0.0005
+thermo_style    custom step pe ke etotal temp press vol
+thermo          100
+dump		1 all custom 100 water.dump id type x y z 
+
+run             1000

source/CMakeLists.txt

@@ -146,16 +146,6 @@ if (USE_TTM)
   set(TTM_DEF "-DUSE_TTM")
 endif (USE_TTM)
 
-# old pppm interface
-if(NOT DEFINED OLD_LMP_PPPM)
-  set(OLD_LMP_PPPM FALSE)
-endif(NOT DEFINED OLD_LMP_PPPM)
-if (OLD_LMP_PPPM)
-  set(OLD_LMP_PPPM_DEF "-DOLD_LMP_PPPM")
-  message(STATUS "Use old lammps pppm interface")
-endif()
-add_definitions (${OLD_LMP_PPPM_DEF})
-
 # define build type
 if ((NOT DEFINED CMAKE_BUILD_TYPE) OR CMAKE_BUILD_TYPE STREQUAL "")
    set (CMAKE_BUILD_TYPE release)

source/install/build_cc.sh

@@ -20,10 +20,9 @@ NPROC=$(nproc --all)
 BUILD_TMP_DIR=${SCRIPT_PATH}/../build
 mkdir -p ${BUILD_TMP_DIR}
 cd ${BUILD_TMP_DIR}
-cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DINSTALL_TENSORFLOW=TRUE ${CUDA_ARGS} ..
+cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -DINSTALL_TENSORFLOW=TRUE ${CUDA_ARGS} -DLAMMPS_VERSION=patch_30Jul2021 -DUSE_TTM=TRUE ..
 make -j${NPROC}
 make install
 
 #------------------
 echo "Congratulations! DeePMD-kit has been installed at ${INSTALL_PREFIX}"
-

source/install/build_lammps.sh

@@ -1,21 +1,5 @@
 set -e
 
-# You need to first run ./build_cc.sh
-
-if [ -z "$FLOAT_PREC" ]
-then
-  FLOAT_PREC=high
-fi
-
-if [ ${FLOAT_PREC} == "high" ]; then
-    PREC_DEF="-DHIGH_PREC"
-    PREC_SUFFIX=""
-else
-    PREC_DEF="-DLOW_PREC"
-    PREC_SUFFIX="_low"
-fi
-#------------------
-
 SCRIPT_PATH=$(dirname $(realpath -s $0))
 if [ -z "$INSTALL_PREFIX" ]
 then
@@ -25,33 +9,23 @@ mkdir -p ${INSTALL_PREFIX}
 echo "Installing LAMMPS to ${INSTALL_PREFIX}"
 NPROC=$(nproc --all)
 
-#------------------
-# copy lammps plugin
-BUILD_TMP_DIR2=${SCRIPT_PATH}/../build
-cd ${BUILD_TMP_DIR2}
-make lammps
-
 #------------------
 
 BUILD_TMP_DIR=${SCRIPT_PATH}/../build_lammps
 mkdir -p ${BUILD_TMP_DIR}
 cd ${BUILD_TMP_DIR}
 # download LAMMMPS
-LAMMPS_VERSION=stable_29Oct2020
+LAMMPS_VERSION=patch_30Jul2021
 if [ ! -d "lammps-${LAMMPS_VERSION}" ]
 then
 	curl -L -o lammps.tar.gz https://github.com/lammps/lammps/archive/refs/tags/${LAMMPS_VERSION}.tar.gz
 	tar vxzf lammps.tar.gz
 fi
-curl -L -o lammps.patch https://github.com/deepmd-kit-recipes/lammps-dp-feedstock/raw/fdd954a1af4fadabe5c0dd2f3bed260a484175a4/recipe/deepmd.patch
-cd ${BUILD_TMP_DIR}/lammps-${LAMMPS_VERSION}
-patch -f -p1 < ../lammps.patch || true 
-mkdir -p ${BUILD_TMP_DIR}/lammps-${LAMMPS_VERSION}/src/USER-DEEPMD
-cp -r ${BUILD_TMP_DIR2}/USER-DEEPMD/* ${BUILD_TMP_DIR}/lammps-${LAMMPS_VERSION}/src/USER-DEEPMD
 
+cd ${BUILD_TMP_DIR}/lammps-${LAMMPS_VERSION}
 mkdir -p ${BUILD_TMP_DIR}/lammps-${LAMMPS_VERSION}/build
 cd ${BUILD_TMP_DIR}/lammps-${LAMMPS_VERSION}/build
-cmake -C ../cmake/presets/all_off.cmake -D PKG_USER-DEEPMD=ON -D PKG_KSPACE=ON -D CMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} -D CMAKE_CXX_FLAGS="${PREC_DEF} -I${INSTALL_PREFIX}/include -L${INSTALL_PREFIX}/lib -Wl,--no-as-needed -lrt -ldeepmd_cc${PREC_SUFFIX} -ltensorflow_cc -ltensorflow_framework" ../cmake
+cmake -C ../cmake/presets/all_off.cmake -D PKG_PLUGIN=ON -D PKG_KSPACE=ON -D BUILD_SHARED_LIBS=yes -D LAMMPS_INSTALL_RPATH=ON -D CMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} ../cmake
 
 make -j${NPROC}
 make install

source/lmp/CMakeLists.txt

@@ -1,3 +1,10 @@
+add_subdirectory(plugin)
+if (NOT DEFINED LAMMPS_VERSION_NUMBER)
+    # set the default to 29 Oct 2020
+    set(LAMMPS_VERSION_NUMBER 20201029)
+endif()
+message(STATUS "LAMMPS version is ${LAMMPS_VERSION_NUMBER}")
+
 file(GLOB LMP_HEADER *.h)
 file(GLOB LMP_SRC *.cpp)
 file(GLOB LMP_SHSCRIPT *.sh)

source/lmp/compute_deeptensor_atom.h

@@ -9,7 +9,11 @@ ComputeStyle(deeptensor/atom,ComputeDeeptensorAtom)
 
 #include "compute.h"
 #include "pair_deepmd.h"
+#ifdef LMPPLUGIN
+#include "DeepTensor.h"
+#else
 #include "deepmd/DeepTensor.h"
+#endif
 
 namespace LAMMPS_NS {
 

source/lmp/env.sh.in

@@ -6,6 +6,6 @@ TF_INCLUDE_DIRS=`echo $TENSORFLOW_INCLUDE_DIRS | sed "s/;/ -I/g"`
 TF_LIBRARY_PATH=`echo $TENSORFLOW_LIBRARY_PATH | sed "s/;/ -L/g"`
 TF_RPATH=`echo $TENSORFLOW_LIBRARY_PATH | sed "s/;/ -Wl,-rpath=/g"`
 
-NNP_INC=" -std=c++11 -D@prec_def@ @TTM_DEF@ @OLD_LMP_PPPM_DEF@ -I$TF_INCLUDE_DIRS -I$DEEPMD_ROOT/include/ "
+NNP_INC=" -std=c++11 -D@prec_def@ @TTM_DEF@ -DLAMMPS_VERSION_NUMBER=@LAMMPS_VERSION_NUMBER@ -I$TF_INCLUDE_DIRS -I$DEEPMD_ROOT/include/ "
 NNP_PATH=" -L$TF_LIBRARY_PATH -L$DEEPMD_ROOT/lib"
 NNP_LIB=" -Wl,--no-as-needed -l@LIB_DEEPMD_CC@@variant_name@ -ltensorflow_cc -ltensorflow_framework -Wl,-rpath=$TF_RPATH -Wl,-rpath=$DEEPMD_ROOT/lib"

source/lmp/fix_dplr.cpp

@@ -41,7 +41,13 @@ FixDPLR::FixDPLR(LAMMPS *lmp, int narg, char **arg)
      efield_fsum_all(4, 0.0), 
      efield_force_flag(0)
 {
+#if LAMMPS_VERSION_NUMBER>=20210702
+  // lammps/lammps#2560
+  energy_global_flag = 1;
+  virial_global_flag = 1;
+#else
   virial_flag = 1;
+#endif
 
   if (strcmp(update->unit_style,"metal") != 0) {
     error->all(FLERR,"Pair deepmd requires metal unit, please set it by \"units metal\"");
@@ -117,7 +123,10 @@ FixDPLR::FixDPLR(LAMMPS *lmp, int narg, char **arg)
 int FixDPLR::setmask()
 {
   int mask = 0;
+#if LAMMPS_VERSION_NUMBER<20210702
+  // THERMO_ENERGY removed in lammps/lammps#2560
   mask |= THERMO_ENERGY;
+#endif
   mask |= POST_INTEGRATE;
   mask |= PRE_FORCE;
   mask |= POST_FORCE;

source/lmp/fix_dplr.h

@@ -10,8 +10,13 @@ FixStyle(dplr,FixDPLR)
 #include <stdio.h>
 #include "fix.h"
 #include "pair_deepmd.h"
+#ifdef LMPPLUGIN
+#include "DeepTensor.h"
+#include "DataModifier.h"
+#else
 #include "deepmd/DeepTensor.h"
 #include "deepmd/DataModifier.h"
+#endif
 
 #ifdef HIGH_PREC
 #define FLOAT_PREC double

source/lmp/pair_deepmd.h.in

@@ -8,7 +8,11 @@ PairStyle(deepmd,PairDeepMD)
 #define LMP_PAIR_NNP_H
 
 #include "pair.h"
+#ifdef LMPPLUGIN
+#include "DeepPot.h"
+#else
 #include "deepmd/DeepPot.h"
+#endif
 #include <iostream>
 #include <fstream>