ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation for the changes to the build procedure

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-04-09 15:43:05 -04:00
parent bd7a906838
commit 3d2d2cb668
2 changed files with 205 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
doc/src/Build_basics.rst
View File

@ -6,7 +6,7 @@ CMake and make:
* :ref:`Serial vs parallel build <serial>`
* :ref:`Choice of compiler and compile/link options <compile>`
* :ref:`Build LAMMPS as an executable or a library <exe>`
* :ref:`Build the LAMMPS executable and library <exe>`
* :ref:`Build the LAMMPS documentation <doc>`
* :ref:`Install LAMMPS after a build <install>`
@ -28,8 +28,8 @@ MPI STUBS library.
Independent of the distributed memory MPI parallelization, parts of
LAMMPS are also written with support for shared memory parallelization
using the OpenMP threading standard. A more detailed discussion of that
is below.
using the `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_ threading
standard. A more detailed discussion of that is below.
**CMake build**\ :
@ -41,7 +41,7 @@ is below.
# no default value
The executable created by CMake (after running make) is named ``lmp`` unless
the LAMMPS_MACHINE option is set. When setting ``LAMMPS_MACHINE=name``
the ``LAMMPS_MACHINE`` option is set. When setting ``LAMMPS_MACHINE=name``
the executable will be called ``lmp_name``. Using ``BUILD_MPI=no`` will
enforce building a serial executable using the MPI STUBS library.
@ -55,18 +55,20 @@ The build with traditional makefiles has to be done inside the source folder ``s
make serial # serial build, produces lmp_serial using Makefile/serial
make mybox # uses Makefile.mybox to produce lmp_mybox
Any "make machine" command will look up the make settings from a file
Makefile.machine, create a folder Obj_machine with all objects and
generated files and an executable called ``lmp_machine``\ . The standard
parallel build with ``make mpi`` assumes a standard MPI installation with
MPI compiler wrappers where all necessary compiler and linker flags to
get access and link with the suitable MPI headers and libraries are set
by the wrapper programs. For other cases or the serial build, you have
to adjust the make file variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB``
as well as ``CC`` and ``LINK``\ . To enable OpenMP threading usually
a compiler specific flag needs to be added to the compile and link
commands. For the GNU compilers, this is ``-fopenmp``\ , which can be
added to the ``CC`` and ``LINK`` makefile variables.
Any ``make machine`` command will look up the make settings from a file
``Makefile.machine`` in the folder ``src/MAKE`` or one of its
subdirectories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a folder
``Obj_machine`` with all objects and generated files and an executable
called ``lmp_machine``\ . The standard parallel build with ``make mpi``
assumes a standard MPI installation with MPI compiler wrappers where all
necessary compiler and linker flags to get access and link with the
suitable MPI headers and libraries are set by the wrapper programs. For
other cases or the serial build, you have to adjust the make file
variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and
``LINK``\ . To enable OpenMP threading usually a compiler specific flag
needs to be added to the compile and link commands. For the GNU
compilers, this is ``-fopenmp``\ , which can be added to the ``CC`` and
``LINK`` makefile variables.
For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
@ -80,18 +82,19 @@ For the serial build the following make variables are set (see src/MAKE/Makefile
You also need to build the STUBS library for your platform before making
LAMMPS itself. A ``make serial`` build does this for you automatically,
otherwise, type ``make mpi-stubs`` from the src directory, or ``make`` from
the src/STUBS dir. If the build fails, you will need to edit the
STUBS/Makefile for your platform. The stubs library does not provide
MPI/IO functions required by some LAMMPS packages, e.g. MPIIO or USER-LB,
and thus is not compatible with those packages.
otherwise, type ``make mpi-stubs`` from the src directory, or ``make``
from the ``src/STUBS`` dir. If the build fails, you may need to edit
the ``STUBS/Makefile`` for your platform. The stubs library does not
provide MPI/IO functions required by some LAMMPS packages,
e.g. ``MPIIO`` or ``USER-LB``, and thus is not compatible with those
packages.
.. note::
The file ``src/STUBS/mpi.c`` provides a CPU timer function called
MPI_Wtime() that calls gettimeofday() . If your operating system
does not support gettimeofday() , you will need to insert code to
call another timer. Note that the ANSI-standard function clock()
``MPI_Wtime()`` that calls ``gettimeofday()``. If your operating system
does not support ``gettimeofday()``, you will need to insert code to
call another timer. Note that the ANSI-standard function ``clock()``
rolls over after an hour or so, and is therefore insufficient for
timing long LAMMPS simulations.
@ -111,20 +114,22 @@ self-installed MPICH or OpenMPI, so you should study the provided
documentation to find out how to build and link with it.
The majority of OpenMP (threading) support in LAMMPS is provided by the
USER-OMP package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The USER-INTEL package also includes OpenMP threading (it is
compatible with USER-OMP) and adds vectorization support when compiled
with compatible compilers, in particular the Intel compilers on top of
OpenMP. Also, the KOKKOS package can be compiled to include OpenMP
threading.
``USER-OMP`` package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The ``USER-INTEL`` package also includes OpenMP threading (it
is compatible with ``USER-OMP`` and will usually fall back on styles
from that package, if a ``USER-INTEL`` does not exist) and adds
vectorization support when compiled with compatible compilers, in
particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
package can be compiled to include OpenMP threading.
In addition, there are a few commands in LAMMPS that have native OpenMP
support included as well. These are commands in the MPIIO, SNAP,
USER-DIFFRACTION, and USER-DPD packages. In addition some packages
support OpenMP threading indirectly through the libraries they interface
to: e.g. LATTE and USER-COLVARS. See the :doc:`Packages details
<Packages_details>` doc page for more info on these packages and the doc
pages for their respective commands for OpenMP threading info.
support included as well. These are commands in the ``MPIIO``,
``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages. In addition
some packages support OpenMP threading indirectly through the libraries
they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``.
See the :doc:`Packages details <Packages_details>` doc page for more
info on these packages and the doc pages for their respective commands
for OpenMP threading info.
For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
and turn on their native OpenMP support and turn on their native OpenMP
@ -158,15 +163,18 @@ this conversion.
Choice of compiler and compile/link options
---------------------------------------------------------
The choice of compiler and compiler flags can be important for
The choice of compiler and compiler flags can be important for maximum
performance. Vendor provided compilers for a specific hardware can
produce faster code than open-source compilers like the GNU compilers.
On x86 hardware most popular compilers are quite similar in performance
of C/C++ code at high optimization levels. When using the USER-INTEL
package, there is a distinct advantage in using the `Intel C++ compiler
<intel_>`_ due to much improved vectorization through SSE and AVX
instructions on compatible hardware as the source code includes changes
and compiler directives to enable high degrees of vectorization.
On the most common x86 hardware most popular C++ compilers are quite
similar in performance of C/C++ code at high optimization levels. When
using the ``USER-INTEL`` package, there is a distinct advantage in using
the `Intel C++ compiler <intel_>`_ due to much improved vectorization
through SSE and AVX instructions on compatible hardware as the source
code includes changes and Intel compiler specific directives to enable
high degrees of vectorization. This may change over time as equivalent
vectorization directives are included into OpenMP standard revisions and
other compilers adopt them.
.. _intel: https://software.intel.com/en-us/intel-compilers
@ -177,17 +185,20 @@ LAMMPS.
**CMake build**\ :
By default CMake will use a compiler it finds and it will add
optimization flags appropriate to that compiler and any
:doc:`accelerator packages <Speed_packages>` you have included in the
build.
By default CMake will use a compiler it finds according to internal
preferences and it will add optimization flags appropriate to that
compiler and any :doc:`accelerator packages <Speed_packages>` you have
included in the build.
You can tell CMake to look for a specific compiler with these variable
settings. Likewise you can specify the corresponding ``CMAKE_*_FLAGS``
variables if you want to experiment with alternate optimization flags.
You should specify all 3 compilers, so that the small number of LAMMPS
source files written in C or Fortran are built with a compiler consistent
with the one used for all the C++ files:
You can tell CMake to look for a specific compiler with setting CMake
variable during configuration. For a few common choices, there are also
presets in the ``cmake/presets`` folder. For convenience, there is a
``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler
options. More on that below, but you can also specify the corresponding
``CMAKE_*_FLAGS`` variables individually if you want to experiment with
alternate optimization flags. You should specify all 3 compilers, so
that the (few) LAMMPS source files written in C or Fortran are built
with a compiler consistent with the one used for the C++ files:
.. code-block:: bash
@ -210,16 +221,17 @@ A few example command lines are:
# Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
For compiling with the Clang/LLVM compilers a special CMake preset is
included that can be loaded with `-C ../cmake/presets/clang.cmake`.
For compiling with the Clang/LLVM compilers a CMake preset is provided that
can be loaded with `-C ../cmake/presets/clang.cmake`. Similarly,
`-C ../cmake/presets/intel.cmake` should switch the
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add compiler
flags to tune for optimal performance on given hosts. By default these are
initialized to some compiler specific flags, where known, to optimize the
LAMMPS executable with optimizations and instructions available on the host
where LAMMPS is compiled. For example, for Intel compilers this would be
``-xHost`` and for GNU compilers this would be ``-march=native``. To turn
these flags off, set ``-D CMAKE_TUNE_FLAGS=``.
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. By
default these are initialized to some compiler specific flags, to
optimize the LAMMPS executable with optimizations and instructions
available on the host where LAMMPS is compiled. For example, for Intel
compilers this would be ``-xHost`` and for GNU compilers this would be
``-march=native``. To turn these flags off, do ``-D CMAKE_TUNE_FLAGS=``.
.. note::
@ -235,11 +247,11 @@ these flags off, set ``-D CMAKE_TUNE_FLAGS=``.
The "compiler/linker settings" section of a Makefile.machine lists
compiler and linker settings for your C++ compiler, including
optimization flags. For a parallel build it is recommended to use
mpicxx or mpiCC, since these compiler wrappers will include a variety of
settings appropriate for your MPI installation and thus avoiding the
guesswork of finding the right flags.
``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a
variety of settings appropriate for your MPI installation and thus
avoiding the guesswork of finding the right flags.
Parallel build (see src/MAKE/Makefile.mpi):
Parallel build (see ``src/MAKE/Makefile.mpi``):
.. code-block:: bash
@ -248,7 +260,7 @@ Parallel build (see src/MAKE/Makefile.mpi):
LINK = mpicxx
LINKFLAGS = -g -O
Serial build (see src/MAKE/Makefile.serial):
Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
.. code-block:: make
@ -284,69 +296,74 @@ Serial build (see src/MAKE/Makefile.serial):
.. _exe:
Build LAMMPS as an executable or a library
----------------------------------------------------
Build the LAMMPS executable and library
---------------------------------------
LAMMPS can be built as either an executable or as a static or shared
library. The LAMMPS library can be called from another application or
a scripting language. See the :doc:`Howto couple <Howto_couple>` doc
LAMMPS is always built as a library of C++ classes plus an executable.
The executable is a simple ``main()`` function that sets up MPI and then
creates a LAMMPS class instance from the LAMMPS library, which
will then process commands provided via a file or from the console
input. The LAMMPS library can also be called from another application
or a scripting language. See the :doc:`Howto couple <Howto_couple>` doc
page for more info on coupling LAMMPS to other codes. See the
:doc:`Python <Python_head>` doc page for more info on wrapping and
running LAMMPS from Python via its library interface.
**CMake build**\ :
For CMake builds, you can select through setting CMake variables which
files the compilation produces during the configuration step. If none
are set, defaults are applied.
For CMake builds, you can select through setting CMake variables between
building a shared or a static LAMMPS library and what kind of suffix is
added to them (in case you want to concurrently install multiple variants
of binaries with different settings). If none are set, defaults are applied.
.. code-block:: bash
-D BUILD_EXE=value # yes (default) or no
-D BUILD_LIB=value # yes or no (default)
-D BUILD_SHARED_LIBS=value # yes or no (default)
-D LAMMPS_LIB_SUFFIX=name # name = mpi, serial, mybox, titan, laptop, etc
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
Setting ``BUILD_EXE=no`` will not produce an executable. Setting
``BUILD_LIB=yes`` will produce a static library named ``liblammps.a``\ .
Setting both ``BUILD_LIB=yes`` and ``BUILD_SHARED_LIBS=yes`` will produce a
shared library named ``liblammps.so`` instead. If ``LAMMPS_LIB_SUFFIX=name``
is set in addition, the name of the generated libraries will be changed to
either ``liblammps_name.a`` or ``liblammps_name.so``\ , respectively.
The compilation will always produce a LAMMPS library and an executable
linked to it. By default this will be a static library named
``liblammps.a`` and an executable named ``lmp`` Setting
``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called
``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending
on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name
of the generated libraries will be changed to either
``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the
executable will be called ``lmp_name``.
**Traditional make**\ :
With the traditional makefile based build process, the choice of
the generated executable or library depends on the "mode" setting.
Several options are available and ``mode=exe`` is the default.
Several options are available and ``mode=static`` is the default.
.. code-block:: bash
make machine # build LAMMPS executable lmp_machine
make mode=exe machine # same as "make machine"
make mode=lib machine # build LAMMPS static lib liblammps_machine.a
make mode=shlib machine # build LAMMPS shared lib liblammps_machine.so
make mode=shexe machine # same as "mode=exe" but uses objects from "mode=shlib"
make mode=static machine # same as "make machine"
make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead
The two "exe" builds will generate and executable ``lmp_machine``\ ,
while the two library builds will create a file ``liblammps_machine.a``
or ``liblammps_machine.so``\ . They will also create generic soft links,
named ``liblammps.a`` and ``liblammps.so``\ , which point to the specific
The "static" build will generate a static library called
``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while
the "shared" build will generate a shared library
``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to
it. The build step will also create generic soft links, named
``liblammps.a`` and ``liblammps.so``\ , which point to the specific
``liblammps_machine.a/so`` files.
**CMake and make info**\ :
Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries. This will be the case for libraries included with LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
the lib/packages directory, since they are always built in a shared
library compatible way using the ``-fPIC`` switch. However, if a library
like MPI or FFTW does not exist as a shared library, the shared library
build may generate an error. This means you will need to install a
shared library version of the auxiliary library. The build instructions
for the library should tell you how to do this.
Note that for creating a shared library, all the libraries it depends on
must be compiled to be compatible with shared libraries. This should be
the case for libraries included with LAMMPS, such as the dummy MPI
library in ``src/STUBS`` or any package libraries in the ``lib``
directory, since they are always built in a shared library compatible
way using the ``-fPIC`` compiler switch. However, if an auxiliary
library (like MPI or FFTW) does not exist as a compatible format, the
shared library linking step may generate an error. This means you will
need to install a compatible version of the auxiliary library. The
build instructions for that library should tell you how to do this.
As an example, here is how to build and install the `MPICH library
<mpich_>`_, a popular open-source version of MPI, as a shared library
@ -360,10 +377,12 @@ in the default /usr/local/lib location:
make
make install
You may need to use ``sudo make install`` in place of the last line if you
do not have write privileges for ``/usr/local/lib``. The end result should
be the file ``/usr/local/lib/libmpich.so``. On many Linux installations the
folder ``${HOME}/.local`` is an alternative to using ``/usr/local`` and does
You may need to use ``sudo make install`` in place of the last line if
you do not have write privileges for ``/usr/local/lib`` or use the
``--prefix`` configuration option to select an installation folder,
where you do have write access. The end result should be the file
``/usr/local/lib/libmpich.so``. On many Linux installations the folder
``${HOME}/.local`` is an alternative to using ``/usr/local`` and does
not require superuser or sudo access. In that case the configuration
step becomes:
@ -371,7 +390,7 @@ step becomes:
./configure --enable-shared --prefix=${HOME}/.local
Avoiding using "sudo" for custom software installation (i.e. from source
Avoiding to use "sudo" for custom software installation (i.e. from source
and not through a package manager tool provided by the OS) is generally
recommended to ensure the integrity of the system software installation.

137
doc/src/Build_link.rst
View File

@ -1,33 +1,35 @@
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
LAMMPS is designed as a library of C++ objects and can thus 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 :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
these 2 files:
.. code-block:: bash
liblammps.so # shared library
liblammps.a # static library
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 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.
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.
----------
@ -42,11 +44,11 @@ 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:
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:
.. code-block:: bash
@ -56,30 +58,35 @@ link the coupled executable are then:
*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:
``${HOME}/lammps/src`` with "make mpi". The commands to compile and link
a coupled executable are then:
.. code-block:: bash
mpicc -c -O -I${HOME}/lammps/src caller.c
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
The *-I* argument is the path to the location of the *library.h*
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.a*
file is located. The *-llammps* argument is shorthand for telling the
compiler to link the file *liblammps.a*\ .
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). Otherwise, you need to include all flags,
libraries, and paths for the coupled executable, that are also
required to link the LAMMPS executable.
(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
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
@ -87,23 +94,26 @@ 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.
.. TODO: this needs to be updated to reflect that latest CMake changes after they are complete.
*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
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:
.. code-block:: bash
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 -lpoems -lmpi_stubs
-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", since LAMMPS
is C++ code. You can display the currently applied settings for building
LAMMPS for the "serial" machine target by using the command:
Note, that you need to link with "g++" instead of "gcc", since the
LAMMPS library 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
@ -118,11 +128,11 @@ Which should output something like:
# Linker:
LD=g++
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/lammps/lib/poems -I${HOME}/lammps/src/STUBS
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}/lammps/lib/poems -L${HOME}/lammps/src/STUBS -lpoems -lmpi_stubs
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
@ -133,14 +143,13 @@ of the makefile.
**Link with LAMMPS as a shared library**\ :
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:
When linking to LAMMPS built as a shared library, the situation becomes
much simpler, as all dependent libraries and objects are either included
in the shared library or registered as a dependent library in the shared
library file. 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*\ :
@ -155,19 +164,19 @@ build process are the same as for the static library.
*Traditional make*\ :
The commands with a shared LAMMPS library compiled with the
traditional make build using "make mode=shlib serial" becomes:
traditional make build using "make mode=shared serial" becomes:
.. code-block:: bash
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/src -llammps
g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
*Locating liblammps.so at runtime*\ :
However, now the `liblammps.so` file is required at runtime and needs
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"
or "${HOME}/.local/lib64" or a folder pointed to by the LD_LIBRARY_PATH
system can find it. This would be either a folder like ``/usr/local/lib64``
or ``${HOME}/.local/lib64`` or a folder pointed to by the ``LD_LIBRARY_PATH``
environment variable. You can type
.. code-block:: bash
@ -177,11 +186,11 @@ environment variable. You can type
to see what directories are in that list.
Or you can add the LAMMPS src directory (or the directory you performed
a CMake style build in) to your LD_LIBRARY_PATH, so that the current
a CMake style build in) to your ``LD_LIBRARY_PATH``, so that the current
version of the shared library is always available to programs that use it.
For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you
would add something like this to your ~/.profile file:
would add something like this to your ``${HOME}/.profile`` file:
.. code-block:: bash
@ -189,14 +198,14 @@ would add something like this to your ~/.profile file:
export LD_LIBRARY_PATH
For the csh or tcsh shells, you would equivalently add something like this
to your ~/.cshrc file:
to your ``${HOME}/.cshrc`` file:
.. code-block:: csh
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
You can verify whether all required shared libraries are found with the
`ldd` tool. Example:
``ldd`` tool. Example:
.. code-block:: bash
@ -229,20 +238,20 @@ If a required library is missing, you would get a 'not found' entry:
Either flavor of library (static or shared) allows one or more LAMMPS
objects to be instantiated from the calling program. When used from a
C++ program, most of the symbols and functions in LAMMPS are wrapped
in a LAMMPS_NS namespace; you can safely use any of its classes and
in a ``LAMMPS_NS`` namespace; you can safely use any of its classes and
methods from within the calling code, as needed, and you will not incur
conflicts with functions and variables in your code that share the name.
This, however, does not extend to all additional libraries bundled with
LAMMPS in the lib folder and some of the low-level code of some packages.
To be compatible with C, Fortran, Python programs, the library has a simple
C-style interface, provided in src/library.cpp and src/library.h.
C-style interface, provided in ``src/library.cpp`` and ``src/library.h``.
See the :doc:`Python library <Python_library>` doc page for a
description of the Python interface to LAMMPS, which wraps the C-style
interface from a shared library through the `ctypes python module <ctypes_>`_.
See the sample codes in examples/COUPLE/simple for examples of C++ and
See the sample codes in ``examples/COUPLE/simple`` for examples of C++ and
C and Fortran codes that invoke LAMMPS through its library interface.
Other examples in the COUPLE directory use coupling ideas discussed on
the :doc:`Howto couple <Howto_couple>` doc page.