forked from lijiext/lammps
updates and corrections to building LAMMPS as a library and using the USER-QMMM package
This commit is contained in:
Axel Kohlmeyer
parent
5a8eaed13b
commit
febb381880
|
|
@ -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::
|
||||
|
||||
The LAMMPS executable these steps produce is not yet functional
|
||||
for a QM/MM simulation. You must also build Quantum ESPRESSO and
|
||||
create a new executable (pwqmmm.x) which links LAMMPS and Quantum
|
||||
ESPRESSO together. These are steps 3 and 4 described in the
|
||||
lib/qmmm/README file. This requires a compatible Quantum espresso
|
||||
and LAMMPS version. The current interface and makefiles have
|
||||
last been verified to work in February 2020 with Quantum Espresso
|
||||
versions 6.3 to 6.5.
|
||||
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
|
||||
included can be built, but will not be able to do a QM/MM simulation
|
||||
on as such. You must also build a QM code - currently only Quantum
|
||||
ESPRESSO (QE) is supported - and create a new executable which links
|
||||
LAMMPS and the QM code together. Details are given in the
|
||||
lib/qmmm/README file. It is also recommended to read the instructions
|
||||
for :doc:`linking with LAMMPS as a library <Build_link>` 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.
|
||||
|
||||
----------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
interface and how to extend it for your needs.
|
||||
C-style API for using LAMMPS as a library. See the :doc:`Howto
|
||||
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
|
||||
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"
|
||||
|
|
|
|||
|
|
@ -2018,27 +2018,33 @@ USER-QMMM package
|
|||
|
||||
**Contents:**
|
||||
|
||||
A :doc:`fix qmmm <fix_qmmm>` command which allows LAMMPS to be used in a
|
||||
QM/MM simulation, currently only in combination with the `Quantum ESPRESSO <espresso_>`_ package.
|
||||
A :doc:`fix qmmm <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 <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 <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:**
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue