1QM/MM support library 2===================== 3 4Axel Kohlmeyer, akohlmey@gmail.com 5Temple University, Philadelphia and ICTP, Trieste 6 7with contributions by 8Mariella Ippolito & Carlo Cavazzoni 9Cineca, Italy 10 11This library provides the basic glue code to combine LAMMPS with the 12Quantum ESPRESSO package plane wave density functional theory code for 13performing QM/MM molecular dynamics simulations. More information on 14Quantum ESPRESSO can be found at: http://www.quantum-espresso.org 15 16The interface code itself is designed so it can also be combined with 17other QM codes, however coupling to Quantum ESPRESSO is currently the 18only available option. Adding support for a different QM code will 19require to write a new version of the top-level wrapper code, pwqmmm.c, 20and also an interface layer into the QM code similar to the one in QE. 21 22LAMMPS has support for two build systems, the traditional make based 23one and a newer one based on CMake. You have to build LAMMPS as a 24library with the QMMM package included and for that you need to 25also build the libqmmm.a library in this folder. 26 27Below you will find some description of the steps needed in either case. 28However you build LAMMPS and the liblammps and libqmmm libraries, you 29will need to perform the remaining steps manually, as outlined below. 30 31------------------------------------------------- 32 33WARNING: This is code depending on two software packages that are 34independently maitained and are under continuous active development. 35It is thus much easier to break the QM/MM interface without noticing. 36Thus please test *very* carefully before using this software for 37production calculations. 38 39At this point, both mechanical and multipole based electrostatic 40coupling have been successfully tested on a cluster of water 41molecules as included in the two example folders. 42 43------------------------------------------------- 44 45Building the QM/MM executable has to be done in multiple stages 46 47Building with CMake for LAMMPS 48============================== 49 50Step 1) 51 52Go to the top-level folder of the LAMMPS source code and create 53a custom build folder (e.g. build-qmmm) and create a suitable 54build configuration with CMake: 55 56 mkdir build-qmmm 57 cd build-qmmm 58 cmake -C ../cmake/presets/basic.cmake -D PKG_QMMM=yes \ 59 -D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake 60 make 61 make install 62 63This will build a LAMMPS executable "lmp" and a shared library 64"liblammps.so" and install them and additional configuration and 65supporting files into the ${HOME}/.local directory tree (unless 66you set -D CMAKE_INSTALL_PREFIX to a different location). If the 67installation is not into a system folder, you need to update 68the LD_LIBRARY_PATH and PKG_CONFIG_PATH environment variables. 69 70 LD_LIBRARY_PATH=${LD_LIBRARY_PATH-/usr/lib64}:${HOME}/.local/lib64 71 PKG_CONFIG_PATH=${PKG_CONFIG_PATH-/usr/lib64/pkgconfig}:${HOME}/.local/lib64/pkgconfig 72 export LD_LIBRARY_PATH PKG_CONFIG_PATH 73 74The standalone LAMMPS executable is not capable of doing QM/MM 75calculations itself, but it will be needed to run all MM calculations 76for equilibration and testing and also to confirm that the classical 77part of the code is set up correctly. 78 79Step 2) 80 81Build a standalone pw.x executable from source code in the Quantum 82ESPRESSO directory and also make the "couple" target. This is typically 83done with: 84 85 ./configure 86 make pw couple 87 88You may need to review and edit the make.inc file created by configure. 89Make certain, that both LAMMPS and QE use the same MPI library and 90compatible compilers. In the examples here we assume GNU compilers 91(gfortran, gcc, g++) and OpenMPI. 92 93Building the standalone pw.x binary is needed to confirm that 94corresponding QM input is working correctly and to run test calculations 95on the QM atoms only. 96 97Step 3) 98 99Go back to this folder (lib/qmmm) and now review the file 100Makefile.gfortran-cmake and make adjustments to the makefile variables 101according to the comments in the file. You probably need to adjust 102the QETOPDIR variable to point to the location of your QE 103compilation/installation. 104Please also check that the command "pkgconf liblammps --libs" works. 105Then you should be able to compile the QM/MM executable with: 106 107 make -f Makefile.gfortran-cmake pwqmmm.x 108 109If this is successful, you should be able to run a QM/MM calculation 110and can try the examples in the example-mc and example-ec folders: 111 112 mpirun -np 4 ../pwqmmm.x qmmm.inp 2 113 114 115Building with traditional make for LAMMPS 116========================================= 117 118 119Step 1) 120 121Go to src folder under the top-level folder of the LAMMPS source code 122and build the qmmm coupling library in this directory using one of 123the provided Makefile.<compiler> files. E.g. for use with GNU fortran: 124 125 make lib-qmmm args="-m gfortran" 126 127This file is specific to your compiler and system. You may need to 128create a specific one for your choice of compilers, MPI, and OS. 129When you are done building this library, two new files should 130exist in this directory (lib/qmmm): 131 132libqmmm.a the library LAMMPS will link against 133Makefile.lammps settings the LAMMPS Makefile will import 134 135Makefile.lammps is created by the make command by simply copying the 136Makefile.lammps.empty file. Currently no additional dependencies for 137this library exist. 138 139Step 2) 140 141Build a standalone LAMMPS executable as described in the LAMMPS 142documentation and include the QMMM package. This executable 143is not functional for QM/MM, but it will usually be needed to 144run all MM calculations for equilibration and testing and also 145to confirm that the classical part of the code is set up correctly. 146Also build a the LAMMPS library. This can be a static library 147or a shared library. For example for a static library with the 148minimum set of packages required for the examples here: 149 150 make yes-molecule yes-kspace yes-rigid yes-qmmm 151 make mpi 152 make mode=lib mpi 153 154Step 3) 155 156Build a standalone pw.x executable from source code in the Quantum 157ESPRESSO directory and also make the "couple" target. This is typically 158done with: 159 160 ./configure 161 make pw couple 162 163You may need to review and edit the make.inc file created by configure. 164Make certain, that both LAMMPS and QE use the same MPI library and 165compatible compilers. In the examples here we assume GNU compilers 166(gfortran, gcc, g++) and OpenMPI. 167 168Building the standalone pw.x binary is needed to confirm that 169corresponding QM input is working correctly and to run test calculations 170on the QM atoms only. 171 172Step 4) 173 174To compile and link the final QM/MM executable, which combines the 175compiled code from both packages, you have to return to the lib/qmmm 176directory and now edit the Makefile.<compiler> for the Makefile 177configuration used to compile LAMMPS and also update the directory 178and library settings for the Quantum ESPRESSO installation. 179 180The makefile variable MPILIBS needs to be set to include all linker 181flags that will need to be used in addition to the various libraries 182from _both_ packages. Please see the provided example(s). 183 184"make -f Makefile.<compiler> all" will now recurse through both the 185Quantum ESPRESSO and LAMMPS directories to compile all files that 186require recompilation and then link the combined QM/MM executable. 187 188If you want to only update the local objects and the QM/MM executable, 189you can use "make -f Makefile.<compiler> pwqmmm.x" 190 191Please refer to the specific LAMMPS and Quantum ESPRESSO documentation 192for details on how to set up compilation for each package and make 193sure you have a set of settings and flags that allow you to build 194each package successfully, so that it can run on its own. 195 196------------------------------------------------- 197 198How it works. 199 200This directory has the source files for an interface layer and a 201toplevel code that combines objects/libraries from the QM code and 202LAMMPS to build a QM/MM executable. LAMMPS will act as the MD "driver" 203and will delegate computation of forces for the QM subset of the QM 204code, i.e. Quantum ESPRESSO currently. While the code is combined into 205a single executable, this executable can only act as either "QM slave", 206"MM slave" or "MM master" and information between those is done solely 207via MPI. Thus MPI is required to make it work, and both codes have 208to be configured to use the same MPI library. 209 210The toplevel code provided here will split the total number of cpus 211into three partitions: the first for running a DFT calculation, the 212second for running the "master" classical MD calculation, and the 213third for a "slave" classical MD calculation. Each calculation will 214have to be run in its own subdirectory with its own specific input 215data and will write its output there as well. This and other settings 216are provided in the QM/MM input file that is mandatory argument to the 217QM/MM executable. The number of MM cpus is provided as the optional 218second argument. The MM "slave" partition is always run with only 1 219cpu thus the minimum required number of MM CPU is 2, which is also 220the default. Therefore a QM/MM calculation with this code requires at 221least 3 processes. 222 223Thus the overall calling sequence is like this: 224 225mpirun -np <total #cpus> ./pwqmmm.x <QM/MM input> [<#cpus for MM>] 226 227A commented example QM/MM input file is given below. 228 229------------------------------------------------- 230 231To run a QM/MM calculation, you need to set up 4 inputs, each is 232best placed in a separate subdirectory: 233 2341: the total system as classical MD input. this becomes the MM master 235and in addition to the regular MD setup it needs to define a group, 236e.g. "wat" for the atoms that are treated as QM atoms and then add 237the QM/MM fix like this: 238 239fix 1 wat qmmm 240 2412: the QM system as classical MD input 242This system must only contain the atom (and bonds, angles, etc) for 243the subsystem that is supposed to be treated with the QM code. This 244will become the MM slave run and here the QM/MM fix needs to be 245applied to all atoms: 246 247fix 1 all qmmm 248 2493: the QM system as QM input 250This needs to be a cluster calculation for the QM subset, i.e. the 251same atoms as in the MM slave configuration. For Quantum ESPRESSO 252this is a regular input which in addition contains the line 253 254tqmmm = .true. 255 256in the &CONTROL namelist. This will make the include QE code 257connect to the LAMMPS code and receive updated positions while 258it sends QM forces back to the MM code. 259 2604: the fourth input is the QM/MM configuration file which tells the 261QM/MM wrapper code where to find the other 3 inputs, where to place 262the corresponding output of the partitions and how many MD steps are 263to run with this setup. 264 265------------------------------------------------- 266 267# configuration file for QMMM wrapper 268 269mode mech # coupling choices: o(ff), m(echanical), e(lectrostatic) 270steps 20 # number of QM/MM (MD) steps 271verbose 1 # verbosity level (0=no QM/MM output during run) 272restart water.restart # checkpoint/restart file to write out at end 273 274# QM system config 275qmdir qm-pw # directory to run QM system in 276qminp water.in # input file for QM code 277qmout NULL # output file for QM code (or NULL to print to screen) 278 279# MM master config 280madir mm-master # directory to run MM master in 281mainp water.in # input file for MM master 282maout water.out # output file for MM master (or NULL to print to screen) 283 284# MM slave config 285sldir mm-slave # directory to run MM slave in 286slinp water_single.in # input file for MM slave 287slout water_single.out # output file for MM slave (or NULL to print to screen) 288