updates and corrections to building LAMMPS as a library and using the USER-QMMM package

doc/src/Build_extras.rst

@@ -1191,9 +1191,9 @@ See src/MAKE/OPTIONS/Makefile.omp for an example.
 
 .. parsed-literal::
 
-   CCFLAGS: -fopenmp               # for GNU Compilers
+   CCFLAGS: -fopenmp               # for GNU and CLang Compilers 
    CCFLAGS: -qopenmp -restrict     # for Intel compilers on Linux
-   LINKFLAGS: -fopenmp             # for GNU Compilers
+   LINKFLAGS: -fopenmp             # for GNU and CLang Compilers
    LINKFLAGS: -qopenmp             # for Intel compilers on Linux
 
 For other platforms and compilers, please consult the documentation
@@ -1209,22 +1209,40 @@ how to address compatibility :ref:`issues with the 'default(none)' directive <de
 USER-QMMM package
 ---------------------------------
 
-.. note::
+For using LAMMPS to do QM/MM simulations via the USER-QMMM package you
-
+need to build LAMMPS as a library.  A LAMMPS executable with fix qmmm
-   The LAMMPS executable these steps produce is not yet functional
+included can be built, but will not be able to do a QM/MM simulation
-   for a QM/MM simulation.  You must also build Quantum ESPRESSO and
+on as such.  You must also build a QM code - currently only Quantum
-   create a new executable (pwqmmm.x) which links LAMMPS and Quantum
+ESPRESSO (QE) is supported - and create a new executable which links
-   ESPRESSO together.  These are steps 3 and 4 described in the
+LAMMPS and the QM code together.  Details are given in the
-   lib/qmmm/README file.  This requires a compatible Quantum espresso
+lib/qmmm/README file.  It is also recommended to read the instructions
-   and LAMMPS version.  The current interface and makefiles have
+for :doc:`linking with LAMMPS as a library <Build_link>` for
-   last been verified to work in February 2020 with Quantum Espresso
+background information.  This requires compatible Quantum Espresso
-   versions 6.3 to 6.5.
+and LAMMPS versions.  The current interface and makefiles have last
+been verified to work in February 2020 with Quantum Espresso versions
+6.3 to 6.5.
 
 **CMake build**\ :
 
-The CMake build system currently does not support building the full
+When using CMake, building a LAMMPS library is required and it is
-QM/MM-capable hybrid executable of LAMMPS and QE called pwqmmm.x.
+recommended to build a shared library, since any libraries built from
-You must use the traditional make build for this package.
+the sources in the *lib* folder (including the essential libqmmm.a)
+are not included in the static LAMMPS library and (currently) not
+installed, while their code is included in the shared LAMMPS library.
+Thus a typical command line to configure building LAMMPS for USER-QMMM
+would be:
+
+.. code-block:: bash
+
+    cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \
+            -D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake
+
+After completing the LAMMPS build and also configuring and compiling
+Quantum ESPRESSO with external library support (via "make couple"),
+go back to the lib/qmmm folder and follow the instructions on the
+README file to build the combined LAMMPS/QE QM/MM executable
+(pwqmmm.x) in the lib/qmmm folder.  You need to make certain, that
+
 
 **Traditional make**\ :
 
@@ -1252,10 +1270,10 @@ a corresponding Makefile.lammps.machine file.
 
 You can then install QMMM package and build LAMMPS in the usual
 manner.  After completing the LAMMPS build and compiling Quantum
-ESPRESSO with external library support, go back to the lib/qmmm folder
+ESPRESSO with external library support (via "make couple"), go back to
-and follow the instructions on the README file to build the combined
+the lib/qmmm folder and follow the instructions in the README file to
-LAMMPS/QE QM/MM executable (pwqmmm.x) in the lib/qmmm folder.
+build the combined LAMMPS/QE QM/MM executable (pwqmmm.x) in the
-
+lib/qmmm folder.
 
 ----------
 

doc/src/Build_link.rst

@@ -3,8 +3,9 @@ Link LAMMPS as a library to another code
 
 LAMMPS can be used as a library by another application, including
 Python scripts.  The files src/library.cpp and library.h define the
-C-style API for using LAMMPS as a library.  See the :doc:`Howto library <Howto_library>` doc page for a description of the
+C-style API for using LAMMPS as a library.  See the :doc:`Howto
-interface and how to extend it for your needs.
+library <Howto_library>` doc page for a description of the interface
+and how to extend it for your needs.
 
 The :doc:`Build basics <Build_basics>` doc page explains how to build
 LAMMPS as either a shared or static library.  This results in one of
@@ -15,6 +16,18 @@ these 2 files:
    liblammps.so      # shared library
    liblammps.a       # static library
 
+.. note::
+
+   Care should be taken to use the same MPI library for the calling
+   code and the LAMMPS library.  The library.h file includes mpi.h and
+   uses definitions from it so those need to be available and
+   consistent.  When LAMMPS is compiled with the MPI STUBS library,
+   then its mpi.h file needs to be included.  While it is technically
+   possible to use a full MPI library in the calling code and link to
+   a serial LAMMPS library compiled with MPI STUBS, it is recommended
+   to use the *same* MPI library for both, and then use MPI\_Comm\_split()
+   in the calling code to pass a suitable communicator with a subset
+   of MPI ranks to the function creating the LAMMPS instance.
 
 ----------
 
@@ -22,8 +35,31 @@ these 2 files:
 **Link with LAMMPS as a static library**\ :
 
 The calling application can link to LAMMPS as a static library with
-a compilation and link command like this (assuming a code written in
+compilation and link commands as in the examples shown below.  These
-C in the file *caller.c*):
+are examples for a code written in C in the file *caller.c*.
+The benefit of linking to a static library is, that the resulting
+executable is independent of that library since all required
+executable code from the library is copied into the calling executable.
+
+*CMake build*\ :
+
+This assumes that LAMMPS has been configured with "-D BUILD_LIB=yes"
+and installed with "make install" and the PKG\_CONFIG\_PATH environment
+variable updated to include the *liblammps.pc* file installed into the
+configured destination folder, if needed.  The commands to compile and
+link the coupled executable are then:
+
+.. code-block:: bash
+
+   mpicc -c -O $(pkgconf liblammps --cflags) caller.c
+   mpicxx -o caller caller.o -$(pkgconf --libs)
+
+
+*Traditional make*\ :
+
+This assumes that LAMMPS has been compiled in the folder
+"${HOME}/lammps/src" with "make mode=lib mpi". The commands to compile
+and link the coupled executable are then:
 
 .. code-block:: bash
 
@@ -36,24 +72,40 @@ interface.  The *-L* argument is the path to where the *liblammps.a*
 file is located.  The *-llammps* argument is shorthand for telling the
 compiler to link the file *liblammps.a*\ .
 
-The benefit of linking ot a static library is, that the resulting
+However, it is only as simple as shown above for the case of a plain
-executable is independent of that library since all used executable
+LAMMPS library without any optional packages that depend on libraries
-code is copied into the calling executable.  However, it is only as
+(bundled or external).  Otherwise, you need to include all flags,
-simple as shown for the case of a plain LAMMPS library without any
+libraries, and paths for the coupled executable, that are also
-optional packages and libraries.  Otherwise, you need to include all
+required to link the LAMMPS executable.
-flags, libraries, and paths that are required to link the LAMMPS
+
-executable.  Assuming you have compiled LAMMPS using the conventional
+*CMake build*\ :
-build system with "make serial" and also have the POEMS package
+
-installed, the command changes to:
+When using CMake, additional libraries with sources in the lib folder
+are built, but not included in liblammps.a and (currently) not
+installed with "make install" and not included in the *pkgconfig*
+configuration file.  They can be found in the top level build folder,
+but you have to determine the necessary link flags manually.  It is
+therefore recommended to either use the traditional make procedure to
+build and link with a static library or build and link with a shared
+library instead.
+
+*Traditional make*\ :
+
+After you have compiled a static LAMMPS library using the conventional
+build system for example with "make mode=lib serial". And you also
+have installed the POEMS package after building its bundled library in
+lib/poems. Then the commands to build and link the coupled executable
+change to:
 
 .. code-block:: bash
 
    gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
-   mpicxx -o caller caller.o -L${HOME}/lammps/src/../lib/poems \
+   g++ -o caller caller.o -L${HOME}/lammps/src/../lib/poems \
      -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps -lpoems -lmpi_stubs 
 
-You can display the currently applied settings for the "serial" machine
+Note, that you need to link with "g++" instead of "gcc", since LAMMPS
-target by using the command:
+is C++ code.  You can display the currently applied settings for building
+LAMMPS for the "serial" machine target by using the command:
 
 .. code-block:: bash
 
@@ -74,23 +126,46 @@ Which should output something like:
    # Libraries: 
    LDLIBS=-L${HOME}/lammps/lib/poems -L${HOME}/lammps/src/STUBS -lpoems -lmpi_stubs
 
+From this you can gather the necessary paths and flags.  With
+makefiles for other *machine* configurations you need to do the
+equivalent and replace "serial" with the corresponding *machine* name
+of the makefile.
+
 ----------
 
 **Link with LAMMPS as a shared library**\ :
 
-When linking to a shared library, the situation becomes much simpler,
+When linking to LAMMPS built as a shared library, the situation
-as all dependent libraries and objects are included in the shared
+becomes much simpler, as all dependent libraries and objects are
-library, which is - technically speaking - very similar to a regular
+included in the shared library, which is - technically speaking -
-LAMMPS executable that is missing the `main()` function. Thus those
+effectively a regular LAMMPS executable that is missing the `main()`
-libraries need not to be specified when linking the calling
+function.  Thus those libraries need not to be specified when linking
-executable.  So the example case from above of the serial version
+the calling executable.  Only the *-I* flags are needed.  So the
-library with the POEMS package installed becomes:
+example case from above of the serial version static LAMMPS library
+with the POEMS package installed becomes:
+
+*CMake build*\ :
+
+The commands with a shared LAMMPS library compiled with the CMake
+build process are the same as for the static library.
+
+.. code-block:: bash
+
+   mpicc -c -O $(pkgconf liblammps --cflags) caller.c
+   mpicxx -o caller caller.o -$(pkgconf --libs)
+
+*Traditional make*\ :
+
+The commands with a shared LAMMPS library compiled with the
+traditional make build using "make mode=shlib serial" becomes:
 
 .. code-block:: bash
 
    gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
-   mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps
+   g++ -o caller caller.o -L${HOME}/lammps/src -llammps
 
+*Locating liblammps.so at runtime*\ :
+   
 However, now the `liblammps.so` file is required at runtime and needs
 to be in a folder, where the shared linker program of the operating
 system can find it.  This would be either a folder like "/usr/local/lib64"

doc/src/Packages_details.rst

@@ -2018,27 +2018,33 @@ USER-QMMM package
 
 **Contents:**
 
-A :doc:`fix qmmm <fix_qmmm>` command which allows LAMMPS to be used in a
+A :doc:`fix qmmm <fix_qmmm>` command which allows LAMMPS to be used as
-QM/MM simulation, currently only in combination with the `Quantum ESPRESSO <espresso_>`_ package.
+the MM code in a QM/MM simulation.  This is currently only available
+in combination with the `Quantum ESPRESSO <espresso_>`_ package.
 
 .. _espresso: http://www.quantum-espresso.org
 
+To use this package you must have Quantum ESPRESSO (QE) available on
+your system and include its coupling library in the compilation and
+then compile LAMMPS as a library.  For QM/MM calculations you then
+build a custom binary with MPI support, that sets up 3 partitions with
+MPI sub-communicators (for inter- and intra-partition communication)
+and then calls the corresponding library interfaces on each partition
+(2x LAMMPS and 1x QE).
 
+The current implementation supports an ONIOM style mechanical coupling
+and a multi-pole based electrostatic coupling to the Quantum ESPRESSO
+plane wave DFT package.  The QM/MM interface has been written in a
+manner that coupling to other QM codes should be possible without
+changes to LAMMPS itself.
 
-To use this package you must have Quantum ESPRESSO available on your
+**Authors:** Axel Kohlmeyer (Temple U). Mariella Ippolito and Carlo Cavazzoni (CINECA, Italy)
-system.
 
-The current implementation only supports an ONIOM style mechanical
-coupling to the Quantum ESPRESSO plane wave DFT package.
-Electrostatic coupling is in preparation and the interface has been
-written in a manner that coupling to other QM codes should be possible
-without changes to LAMMPS itself.
-
-**Author:** Axel Kohlmeyer (Temple U).
 
 **Install:**
 
-This package has :ref:`specific installation instructions <user-qmmm>` on the :doc:`Build extras <Build_extras>` doc page.
+This package has :ref:`specific installation instructions <user-qmmm>`
+on the :doc:`Build extras <Build_extras>` doc page.
 
 **Supporting info:**
 

doc/utils/sphinx-config/false_positives.txt

@@ -315,6 +315,7 @@ Caswell
 Cates
 cauchy
 cauchystat
+Cavazzoni
 Cavium
 Cawkwell
 cbecker
@@ -1238,6 +1239,7 @@ iostreams
 iparam
 ipi
 ipp
+Ippolito
 IPv
 IPython
 Isele
@@ -1617,6 +1619,7 @@ manybody
 MANYBODY
 Maras
 Marchetti
+Mariella
 Marrink
 Marroquin
 Marsaglia
@@ -2611,6 +2614,7 @@ Shenderova
 Shi
 Shiga
 Shinoda
+shlib
 shockvel
 si
 SiC