\(\renewcommand{\AA}{\text{Å}}\)
3.3. Link LAMMPS as a library to another code
LAMMPS is designed as a library of C++ objects that can be integrated
into other applications, including Python scripts. The files
src/library.cpp
and src/library.h
define a C-style API for using
LAMMPS as a library. See the Library interface to LAMMPS page for a
description of the interface and how to use it for your needs.
The Basic build options page explains how to build LAMMPS as either a
shared or static library. This results in a file in the compilation
folder called liblammps.a
or liblammps_<name>.a
in case of
building a static library. In case of a shared library, the name is the
same only that the suffix is going to be either .so
or .dylib
or
.dll
instead of .a
depending on the OS. In some cases, the
.so
file may be a symbolic link to a file with the suffix .so.0
(or some other number).
Note
Care should be taken to use the same MPI library for the calling code and the LAMMPS library, unless LAMMPS is to be compiled without (real) MPI support using the included STUBS MPI library.
3.3.1. Link with LAMMPS as a static library
The calling application can link to LAMMPS as a static library with
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.
This assumes that LAMMPS has been configured without setting a
LAMMPS_MACHINE
name, installed with make install
, and the
PKG_CONFIG_PATH
environment variable has been updated to
include the liblammps.pc
file installed into the configured
destination folder. The commands to compile and link a coupled
executable are then:
mpicc -c -O $(pkg-config --cflags liblammps) caller.c
mpicxx -o caller caller.o -$(pkg-config --libs liblammps)
This assumes that LAMMPS has been compiled in the folder
${HOME}/lammps/src
with “make mpi”. The commands to compile
and link a coupled executable are then:
mpicc -c -O -I${HOME}/lammps/src caller.c
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
The -I
argument is the path to the location of the library.h
header file containing the interface to the LAMMPS C-style library
interface. The -L
argument is the path to where the
liblammps_mpi.a
file is located. The -llammps_mpi
argument
is shorthand for telling the compiler to link the file
liblammps_mpi.a
. If LAMMPS has been built as a shared
library, then the linker will use liblammps_mpi.so
instead.
If both files are available, the linker will usually prefer the
shared library. In case of a shared library, you may need to
update the LD_LIBRARY_PATH
environment variable or running the
caller
executable will fail since it cannot find the shared
library at runtime.
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) or when using a shared library. Otherwise, you need to include all flags, libraries, and paths for the coupled executable, that are also required to link the LAMMPS executable.
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.
After you have compiled a static LAMMPS library using the
conventional build system for example with “make mode=static
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:
gcc -c -O -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \
-llammps_serial -lpoems -lmpi_stubs
Note, that you need to link with g++
instead of gcc
even
if you have written your code in C, since LAMMPS itself is C++
code. You can display the currently applied settings for building
LAMMPS for the “serial” machine target by using the command:
make mode=print serial
Which should output something like:
# Compiler:
CXX=g++
# Linker:
LD=g++
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
# Linking:
LDFLAGS=-g -O
# Libraries:
LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/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.