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 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/basic.cmake -D PKG_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 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-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)