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 Howto
library page for a description of the interface
and how to use it for your needs.
The Build basics doc 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. 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 included STUBS MPI
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.
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.
CMake build
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 $(pkgconf liblammps --cflags) caller.c
mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
Traditional make
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.
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=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/STUBS -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.