forked from lijiext/lammps
288 lines
11 KiB
Plaintext
288 lines
11 KiB
Plaintext
QM/MM support library
|
|
=====================
|
|
|
|
Axel Kohlmeyer, akohlmey@gmail.com
|
|
Temple University, Philadelphia and ICTP, Trieste
|
|
|
|
with contributions by
|
|
Mariella Ippolito & Carlo Cavazzoni
|
|
Cineca, Italy
|
|
|
|
This library provides the basic glue code to combine LAMMPS with the
|
|
Quantum ESPRESSO package plane wave density functional theory code for
|
|
performing QM/MM molecular dynamics simulations. More information on
|
|
Quantum ESPRESSO can be found at: http://www.quantum-espresso.org
|
|
|
|
The interface code itself is designed so it can also be combined with
|
|
other QM codes, however coupling to Quantum ESPRESSO is currently the
|
|
only available option. Adding support for a different QM code will
|
|
require to write a new version of the top-level wrapper code, pwqmmm.c,
|
|
and also an interface layer into the QM code similar to the one in QE.
|
|
|
|
LAMMPS has support for two build systems, the traditional make based
|
|
one and a newer one based on CMake. You have to build LAMMPS as a
|
|
library with the USER-QMMM package included and for that you need to
|
|
also build the libqmmm.a library in this folder.
|
|
|
|
Below you will find some description of the steps needed in either case.
|
|
However you build LAMMPS and the liblammps and libqmmm libraries, you
|
|
will need to perform the remaining steps manually, as outlined below.
|
|
|
|
-------------------------------------------------
|
|
|
|
WARNING: This is code depending on two software packages that are
|
|
independently maitained and are under continuous active development.
|
|
It is thus much easier to break the QM/MM interface without noticing.
|
|
Thus please test *very* carefully before using this software for
|
|
production calculations.
|
|
|
|
At this point, both mechanical and multipole based electrostatic
|
|
coupling have been successfully tested on a cluster of water
|
|
molecules as included in the two example folders.
|
|
|
|
-------------------------------------------------
|
|
|
|
Building the QM/MM executable has to be done in multiple stages
|
|
|
|
Building with CMake for LAMMPS
|
|
==============================
|
|
|
|
Step 1)
|
|
|
|
Go to the top-level folder of the LAMMPS source code and create
|
|
a custom build folder (e.g. build-qmmm) and create a suitable
|
|
build configuration with CMake:
|
|
|
|
mkdir build-qmmm
|
|
cd build-qmmm
|
|
cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \
|
|
-D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake
|
|
make
|
|
make install
|
|
|
|
This will build a LAMMPS executable "lmp" and a shared library
|
|
"liblammps.so" and install them and additional configuration and
|
|
supporting files into the ${HOME}/.local directory tree (unless
|
|
you set -D CMAKE_INSTALL_PREFIX to a different location). If the
|
|
installation is not into a system folder, you need to update
|
|
the LD_LIBRARY_PATH and PKG_CONFIG_PATH environment variables.
|
|
|
|
LD_LIBRARY_PATH=${LD_LIBRARY_PATH-/usr/lib64}:${HOME}/.local/lib64
|
|
PKG_CONFIG_PATH=${PKG_CONFIG_PATH-/usr/lib64/pkgconfig}:${HOME}/.local/lib64/pkgconfig
|
|
export LD_LIBRARY_PATH PKG_CONFIG_PATH
|
|
|
|
The standalone LAMMPS executable is not capable of doing QM/MM
|
|
calculations itself, but it will be needed to run all MM calculations
|
|
for equilibration and testing and also to confirm that the classical
|
|
part of the code is set up correctly.
|
|
|
|
Step 2)
|
|
|
|
Build a standalone pw.x executable from source code in the Quantum
|
|
ESPRESSO directory and also make the "couple" target. This is typically
|
|
done with:
|
|
|
|
./configure
|
|
make pw couple
|
|
|
|
You may need to review and edit the make.inc file created by configure.
|
|
Make certain, that both LAMMPS and QE use the same MPI library and
|
|
compatible compilers. In the examples here we assume GNU compilers
|
|
(gfortran, gcc, g++) and OpenMPI.
|
|
|
|
Building the standalone pw.x binary is needed to confirm that
|
|
corresponding QM input is working correctly and to run test calculations
|
|
on the QM atoms only.
|
|
|
|
Step 3)
|
|
|
|
Go back to this folder (lib/qmmm) and now review the file
|
|
Makefile.gfortran-cmake and make adjustments to the makefile variables
|
|
according to the comments in the file. You probably need to adjust
|
|
the QETOPDIR variable to point to the location of your QE
|
|
compilation/installation.
|
|
Please also check that the command "pkgconf liblammps --libs" works.
|
|
Then you should be able to compile the QM/MM executable with:
|
|
|
|
make -f Makefile.gfortran-cmake pwqmmm.x
|
|
|
|
If this is successful, you should be able to run a QM/MM calculation
|
|
and can try the examples in the example-mc and example-ec folders:
|
|
|
|
mpirun -np 4 ../pwqmmm.x qmmm.inp 2
|
|
|
|
|
|
Building with traditional make for LAMMPS
|
|
=========================================
|
|
|
|
|
|
Step 1)
|
|
|
|
Go to src folder under the top-level folder of the LAMMPS source code
|
|
and build the qmmm coupling library in this directory using one of
|
|
the provided Makefile.<compiler> files. E.g. for use with GNU fortran:
|
|
|
|
make lib-qmmm args="-m gfortran"
|
|
|
|
This file is specific to your compiler and system. You may need to
|
|
create a specific one for your choice of compilers, MPI, and OS.
|
|
When you are done building this library, two new files should
|
|
exist in this directory (lib/qmmm):
|
|
|
|
libqmmm.a the library LAMMPS will link against
|
|
Makefile.lammps settings the LAMMPS Makefile will import
|
|
|
|
Makefile.lammps is created by the make command by simply copying the
|
|
Makefile.lammps.empty file. Currently no additional dependencies for
|
|
this library exist.
|
|
|
|
Step 2)
|
|
|
|
Build a standalone LAMMPS executable as described in the LAMMPS
|
|
documentation and include the USER-QMMM package. This executable
|
|
is not functional for QM/MM, but it will usually be needed to
|
|
run all MM calculations for equilibration and testing and also
|
|
to confirm that the classical part of the code is set up correctly.
|
|
Also build a the LAMMPS library. This can be a static library
|
|
or a shared library. For example for a static library with the
|
|
minimum set of packages required for the examples here:
|
|
|
|
make yes-molecule yes-kspace yes-rigid yes-user-qmmm
|
|
make mpi
|
|
make mode=lib mpi
|
|
|
|
Step 3)
|
|
|
|
Build a standalone pw.x executable from source code in the Quantum
|
|
ESPRESSO directory and also make the "couple" target. This is typically
|
|
done with:
|
|
|
|
./configure
|
|
make pw couple
|
|
|
|
You may need to review and edit the make.inc file created by configure.
|
|
Make certain, that both LAMMPS and QE use the same MPI library and
|
|
compatible compilers. In the examples here we assume GNU compilers
|
|
(gfortran, gcc, g++) and OpenMPI.
|
|
|
|
Building the standalone pw.x binary is needed to confirm that
|
|
corresponding QM input is working correctly and to run test calculations
|
|
on the QM atoms only.
|
|
|
|
Step 4)
|
|
|
|
To compile and link the final QM/MM executable, which combines the
|
|
compiled code from both packages, you have to return to the lib/qmmm
|
|
directory and now edit the Makefile.<compiler> for the Makefile
|
|
configuration used to compile LAMMPS and also update the directory
|
|
and library settings for the Quantum ESPRESSO installation.
|
|
|
|
The makefile variable MPILIBS needs to be set to include all linker
|
|
flags that will need to be used in addition to the various libraries
|
|
from _both_ packages. Please see the provided example(s).
|
|
|
|
"make -f Makefile.<compiler> all" will now recurse through both the
|
|
Quantum ESPRESSO and LAMMPS directories to compile all files that
|
|
require recompilation and then link the combined QM/MM executable.
|
|
|
|
If you want to only update the local objects and the QM/MM executable,
|
|
you can use "make -f Makefile.<compiler> pwqmmm.x"
|
|
|
|
Please refer to the specific LAMMPS and Quantum ESPRESSO documentation
|
|
for details on how to set up compilation for each package and make
|
|
sure you have a set of settings and flags that allow you to build
|
|
each package successfully, so that it can run on its own.
|
|
|
|
-------------------------------------------------
|
|
|
|
How it works.
|
|
|
|
This directory has the source files for an interface layer and a
|
|
toplevel code that combines objects/libraries from the QM code and
|
|
LAMMPS to build a QM/MM executable. LAMMPS will act as the MD "driver"
|
|
and will delegate computation of forces for the QM subset of the QM
|
|
code, i.e. Quantum ESPRESSO currently. While the code is combined into
|
|
a single executable, this executable can only act as either "QM slave",
|
|
"MM slave" or "MM master" and information between those is done solely
|
|
via MPI. Thus MPI is required to make it work, and both codes have
|
|
to be configured to use the same MPI library.
|
|
|
|
The toplevel code provided here will split the total number of cpus
|
|
into three partitions: the first for running a DFT calculation, the
|
|
second for running the "master" classical MD calculation, and the
|
|
third for a "slave" classical MD calculation. Each calculation will
|
|
have to be run in its own subdirectory with its own specific input
|
|
data and will write its output there as well. This and other settings
|
|
are provided in the QM/MM input file that is mandatory argument to the
|
|
QM/MM executable. The number of MM cpus is provided as the optional
|
|
second argument. The MM "slave" partition is always run with only 1
|
|
cpu thus the minimum required number of MM CPU is 2, which is also
|
|
the default. Therefore a QM/MM calculation with this code requires at
|
|
least 3 processes.
|
|
|
|
Thus the overall calling sequence is like this:
|
|
|
|
mpirun -np <total #cpus> ./pwqmmm.x <QM/MM input> [<#cpus for MM>]
|
|
|
|
A commented example QM/MM input file is given below.
|
|
|
|
-------------------------------------------------
|
|
|
|
To run a QM/MM calculation, you need to set up 4 inputs, each is
|
|
best placed in a separate subdirectory:
|
|
|
|
1: the total system as classical MD input. this becomes the MM master
|
|
and in addition to the regular MD setup it needs to define a group,
|
|
e.g. "wat" for the atoms that are treated as QM atoms and then add
|
|
the QM/MM fix like this:
|
|
|
|
fix 1 wat qmmm
|
|
|
|
2: the QM system as classical MD input
|
|
This system must only contain the atom (and bonds, angles, etc) for
|
|
the subsystem that is supposed to be treated with the QM code. This
|
|
will become the MM slave run and here the QM/MM fix needs to be
|
|
applied to all atoms:
|
|
|
|
fix 1 all qmmm
|
|
|
|
3: the QM system as QM input
|
|
This needs to be a cluster calculation for the QM subset, i.e. the
|
|
same atoms as in the MM slave configuration. For Quantum ESPRESSO
|
|
this is a regular input which in addition contains the line
|
|
|
|
tqmmm = .true.
|
|
|
|
in the &CONTROL namelist. This will make the include QE code
|
|
connect to the LAMMPS code and receive updated positions while
|
|
it sends QM forces back to the MM code.
|
|
|
|
4: the fourth input is the QM/MM configuration file which tells the
|
|
QM/MM wrapper code where to find the other 3 inputs, where to place
|
|
the corresponding output of the partitions and how many MD steps are
|
|
to run with this setup.
|
|
|
|
-------------------------------------------------
|
|
|
|
# configuration file for QMMM wrapper
|
|
|
|
mode mech # coupling choices: o(ff), m(echanical), e(lectrostatic)
|
|
steps 20 # number of QM/MM (MD) steps
|
|
verbose 1 # verbosity level (0=no QM/MM output during run)
|
|
restart water.restart # checkpoint/restart file to write out at end
|
|
|
|
# QM system config
|
|
qmdir qm-pw # directory to run QM system in
|
|
qminp water.in # input file for QM code
|
|
qmout NULL # output file for QM code (or NULL to print to screen)
|
|
|
|
# MM master config
|
|
madir mm-master # directory to run MM master in
|
|
mainp water.in # input file for MM master
|
|
maout water.out # output file for MM master (or NULL to print to screen)
|
|
|
|
# MM slave config
|
|
sldir mm-slave # directory to run MM slave in
|
|
slinp water_single.in # input file for MM slave
|
|
slout water_single.out # output file for MM slave (or NULL to print to screen)
|