diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 9b3f3adb56..1448c06ecd 100644 --- a/doc/src/Build_extras.rst +++ b/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 ` for +background information. This requires compatible Quantum Espresso +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 -QM/MM-capable hybrid executable of LAMMPS and QE called pwqmmm.x. -You must use the traditional make build for this package. +When using CMake, building a LAMMPS library is required and it is +recommended to build a shared library, since any libraries built from +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 -and follow the instructions on the README file to build the combined -LAMMPS/QE QM/MM executable (pwqmmm.x) in the lib/qmmm folder. - +ESPRESSO with external library support (via "make couple"), go back to +the lib/qmmm folder and follow the instructions in the README file to +build the combined LAMMPS/QE QM/MM executable (pwqmmm.x) in the +lib/qmmm folder. ---------- diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst index d037292381..d1234f4261 100644 --- a/doc/src/Build_link.rst +++ b/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 ` doc page for a description of the -interface and how to extend it for your needs. +C-style API for using LAMMPS as a library. See the :doc:`Howto +library ` doc page for a description of the interface +and how to extend it for your needs. The :doc:`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 -C in the file *caller.c*): +compilation and link commands as in the examples shown below. These +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 -executable is independent of that library since all used executable -code is copied into the calling executable. However, it is only as -simple as shown for the case of a plain LAMMPS library without any -optional packages and libraries. Otherwise, you need to include all -flags, libraries, and paths that are required to link the LAMMPS -executable. Assuming you have compiled LAMMPS using the conventional -build system with "make serial" and also have the POEMS package -installed, the command changes to: +However, it is only as simple as shown above for the case of a plain +LAMMPS library without any optional packages that depend on libraries +(bundled or external). Otherwise, you need to include all flags, +libraries, and paths for the coupled executable, that are also +required to link the LAMMPS executable. + +*CMake build*\ : + +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 -target by using the command: +Note, that you need to link with "g++" instead of "gcc", since LAMMPS +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, -as all dependent libraries and objects are included in the shared -library, which is - technically speaking - very similar to a regular -LAMMPS executable that is missing the `main()` function. Thus those -libraries need not to be specified when linking the calling -executable. So the example case from above of the serial version -library with the POEMS package installed becomes: +When linking to LAMMPS built as a shared library, the situation +becomes much simpler, as all dependent libraries and objects are +included in the shared library, which is - technically speaking - +effectively a regular LAMMPS executable that is missing the `main()` +function. Thus those libraries need not to be specified when linking +the calling executable. Only the *-I* flags are needed. So the +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" diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index bfadf87251..37d9fe2ba3 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -2018,27 +2018,33 @@ USER-QMMM package **Contents:** -A :doc:`fix qmmm ` command which allows LAMMPS to be used in a -QM/MM simulation, currently only in combination with the `Quantum ESPRESSO `_ package. +A :doc:`fix qmmm ` command which allows LAMMPS to be used as +the MM code in a QM/MM simulation. This is currently only available +in combination with the `Quantum 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 -system. +**Authors:** Axel Kohlmeyer (Temple U). Mariella Ippolito and Carlo Cavazzoni (CINECA, Italy) -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 ` on the :doc:`Build extras ` doc page. +This package has :ref:`specific installation instructions ` +on the :doc:`Build extras ` doc page. **Supporting info:** diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 668db0f64a..6761730ce5 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/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