lijiext
/
lammps
mirror of https://github.com/lammps/lammps.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

update/refactor a few more build documentation files for using tabs

This commit is contained in:
Axel Kohlmeyer 2020-09-08 11:40:21 -04:00
parent 88cc673f78
commit 5df3deb8e6
No known key found for this signature in database
GPG Key ID: D9B44E93BF0C375A
3 changed files with 680 additions and 637 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

478
doc/src/Build_basics.rst
View File

@ -32,74 +32,80 @@ LAMMPS are also written with support for shared memory parallelization
using the `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_ threading
standard. A more detailed discussion of that is below.
**CMake build**\ :
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no
-D BUILD_OMP=value # yes or no, default is yes if a compatible compiler is detected
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
.. code-block:: bash
The executable created by CMake (after running make) is named ``lmp`` unless
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.
-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no
-D BUILD_OMP=value # yes or no, default is yes if a compatible compiler is detected
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
**Traditional make**\ :
The executable created by CMake (after running make) is named
``lmp`` unless 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.
The build with traditional makefiles has to be done inside the source folder ``src``.
.. tab:: Traditional make
.. code-block:: bash
The build with traditional makefiles has to be done inside the source folder ``src``.
make mpi # parallel build, produces lmp_mpi using Makefile.mpi
make serial # serial build, produces lmp_serial using Makefile/serial
make mybox # uses Makefile.mybox to produce lmp_mybox
.. code-block:: bash
Any ``make machine`` command will look up the make settings from a file
``Makefile.machine`` in the folder ``src/MAKE`` or one of its
sub-directories ``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.
make mpi # parallel build, produces lmp_mpi using Makefile.mpi
make serial # serial build, produces lmp_serial using Makefile/serial
make mybox # uses Makefile.mybox to produce lmp_mybox
For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
Any ``make machine`` command will look up the make settings from a
file ``Makefile.machine`` in the folder ``src/MAKE`` or one of its
sub-directories ``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.
.. code-block:: make
For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
CC = g++
LINK = g++
MPI_INC = -I../STUBS
MPI_PATH = -L../STUBS
MPI_LIB = -lmpi_stubs
.. code-block:: make
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 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.
CC = g++
LINK = g++
MPI_INC = -I../STUBS
MPI_PATH = -L../STUBS
MPI_LIB = -lmpi_stubs
.. note::
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 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.
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()``
rolls over after an hour or so, and is therefore insufficient for
timing long LAMMPS simulations.
.. note::
**MPI and OpenMP support info**\ :
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()`` rolls over after an hour or
so, and is therefore insufficient for timing long LAMMPS
simulations.
MPI and OpenMP support in LAMMPS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are installing MPI yourself to build a parallel LAMMPS
executable, we recommend either MPICH or OpenMPI which are regularly
@ -145,18 +151,19 @@ please refer to its documentation.
.. _default-none-issues:
**OpenMP Compiler compatibility info**\ :
OpenMP Compiler compatibility
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some compilers do not fully support the ``default(none)`` directive
and others (e.g. GCC version 9 and beyond, Clang version 10 and later)
may implement strict OpenMP 4.0 and later semantics, which are incompatible
Some compilers do not fully support the ``default(none)`` directive and
others (e.g. GCC version 9 and beyond, Clang version 10 and later) may
implement strict OpenMP 4.0 and later semantics, which are incompatible
with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility
with compiler versions in use. If compilation with OpenMP enabled fails
because of your compiler requiring strict OpenMP 4.0 semantic, you can
change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the ``LMP_INC``
variable in your makefile, or add it to the command line while configuring
with CMake. CMake will detect the suitable setting for the GNU, Clang,
and Intel compilers.
change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the
``LMP_INC`` variable in your makefile, or add it to the command line
while configuring with CMake. CMake will detect the suitable setting for
the GNU, Clang, and Intel compilers.
----------
@ -185,131 +192,139 @@ for their compile/link environments, you can often access different
compilers by simply loading the appropriate module before building
LAMMPS.
**CMake build**\ :
.. tabs::
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.
.. tab:: CMake build
You can tell CMake to look for a specific compiler with setting CMake
variables (listed below) 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 (applied to compilation only), to be used
for adding compiler or host specific optimization flags in addition to
the "flags" variables listed below. You may 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:
By default CMake will use the 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. CMake will
check if the detected or selected compiler is compatible with the
C++ support requirements of LAMMPS and stop with an error, if this
is not the case.
.. code-block:: bash
You can tell CMake to look for a specific compiler with setting
CMake variables (listed below) 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 (applied to
compilation only), to be used for adding compiler or host specific
optimization flags in addition to the "flags" variables listed
below. You may 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:
-D CMAKE_CXX_COMPILER=name # name of C++ compiler
-D CMAKE_C_COMPILER=name # name of C compiler
-D CMAKE_Fortran_COMPILER=name # name of Fortran compiler
.. code-block:: bash
-D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler
-D CMAKE_C_FLAGS=string # flags to use with C compiler
-D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler
-D CMAKE_CXX_COMPILER=name # name of C++ compiler
-D CMAKE_C_COMPILER=name # name of C compiler
-D CMAKE_Fortran_COMPILER=name # name of Fortran compiler
A few example command lines are:
-D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler
-D CMAKE_C_FLAGS=string # flags to use with C compiler
-D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler
.. code-block:: bash
A few example command lines are:
# Building with GNU Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
# Building with Intel Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
# Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
.. code-block:: bash
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
# Building with GNU Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
# Building with Intel Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
# Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. By
default this variable is empty.
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 compiler
toolchain to the Intel compilers.
.. note::
In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. By
default this variable is empty.
When the cmake command completes, it prints a summary to the screen
which compilers it is using and what flags and settings will be used
for the compilation. Note that if the top-level compiler is mpicxx,
it is simply a wrapper on a real compiler. The underlying compiler
info is what CMake will try to determine and report. You should check
to confirm you are using the compiler and optimization flags you want.
.. note::
**Makefile.machine settings for traditional make**\ :
When the cmake command completes, it prints a summary to the
screen which compilers it is using and what flags and settings
will be used for the compilation. Note that if the top-level
compiler is mpicxx, it is simply a wrapper on a real compiler.
The underlying compiler info is what CMake will try to
determine and report. You should check to confirm you are
using the compiler and optimization flags you want.
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.
.. tab:: Makefile.machine settings for traditional make
Parallel build (see ``src/MAKE/Makefile.mpi``):
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.
.. code-block:: bash
Parallel build (see ``src/MAKE/Makefile.mpi``):
CC = mpicxx
CCFLAGS = -g -O3
LINK = mpicxx
LINKFLAGS = -g -O
.. code-block:: bash
Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
CC = mpicxx
CCFLAGS = -g -O3
LINK = mpicxx
LINKFLAGS = -g -O
.. code-block:: make
Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
CC = g++
CCFLAGS = -g -O3
LINK = g++
LINKFLAGS = -g -O
.. code-block:: make
CC = g++
CCFLAGS = -g -O3
LINK = g++
LINKFLAGS = -g -O
.. note::
.. note::
If compilation stops with a message like the following:
If compilation stops with a message like the following:
.. code-block::
.. code-block::
g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp
In file included from ../pointers.h:24:0,
from ../input.h:17,
from ../main.cpp:16:
../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp
In file included from ../pointers.h:24:0,
from ../input.h:17,
from ../main.cpp:16:
../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
then you have either an unsupported (old) compiler or you have to
turn on C++11 mode. The latter applies to GCC 4.8.x shipped with
RHEL 7.x and CentOS 7.x. For those compilers, you need to add the
``-std=c++11`` flag. Otherwise, you would have to install a newer
compiler that supports C++11; either as a binary package or through
compiling from source.
then you have either an unsupported (old) compiler or you have
to turn on C++11 mode. The latter applies to GCC 4.8.x shipped
with RHEL 7.x and CentOS 7.x. For those compilers, you need to
add the ``-std=c++11`` flag. Otherwise, you would have to
install a newer compiler that supports C++11; either as a
binary package or through compiling from source.
If you build LAMMPS with any :doc:`Speed_packages` included, there may
be specific compiler or linker flags
that are either required or recommended to enable required features and
to achieve optimal performance. You need to include these in the
CCFLAGS and LINKFLAGS settings above. For details, see the individual
package doc pages listed on the :doc:`Speed_packages`
page. Or examine these files in the src/MAKE/OPTIONS directory.
They correspond to each of the 5 accelerator packages and their hardware
variants:
If you build LAMMPS with any :doc:`Speed_packages` included,
there may be specific compiler or linker flags that are either
required or recommended to enable required features and to
achieve optimal performance. You need to include these in the
CCFLAGS and LINKFLAGS settings above. For details, see the
individual package doc pages listed on the
:doc:`Speed_packages` page. Or examine these files in the
src/MAKE/OPTIONS directory. They correspond to each of the 5
accelerator packages and their hardware variants:
.. code-block:: bash
.. code-block:: bash
Makefile.opt # OPT package
Makefile.omp # USER-OMP package
Makefile.intel_cpu # USER-INTEL package for CPUs
Makefile.intel_coprocessor # USER-INTEL package for KNLs
Makefile.gpu # GPU package
Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs
Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP)
Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP)
Makefile.opt # OPT package
Makefile.omp # USER-OMP package
Makefile.intel_cpu # USER-INTEL package for CPUs
Makefile.intel_coprocessor # USER-INTEL package for KNLs
Makefile.gpu # GPU package
Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs
Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP)
Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP)
----------
@ -328,51 +343,56 @@ 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**\ :
.. tabs::
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.
.. tab:: CMake build
.. code-block:: bash
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.
-D BUILD_SHARED_LIBS=value # yes or no (default)
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
.. code-block:: bash
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``.
-D BUILD_SHARED_LIBS=value # yes or no (default)
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
**Traditional make**\ :
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``.
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=static`` is the default.
.. tab:: Traditional make
.. code-block:: bash
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=static`` is the default.
make machine # build LAMMPS executable lmp_machine
make mode=static machine # same as "make machine"
make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead
.. code-block:: bash
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.
make machine # build LAMMPS executable lmp_machine
make mode=static machine # same as "make machine"
make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead
CMake and make info
^^^^^^^^^^^^^^^^^^^
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.
Additional information
^^^^^^^^^^^^^^^^^^^^^^
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
@ -462,8 +482,8 @@ tool. The actual translation is then done via make commands.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _sphinx: https://www.sphinx-doc.org
Documentation make option
^^^^^^^^^^^^^^^^^^^^^^^^^
Documentation makefile options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following make commands can be issued in the doc folder of the
LAMMPS source distribution.
@ -490,15 +510,16 @@ your system.
current LAMMPS version (HTML and PDF files), from the website
`download page <https://lammps.sandia.gov/download.html>`_.
CMake build option
^^^^^^^^^^^^^^^^^^
CMake build options
^^^^^^^^^^^^^^^^^^^
It is also possible to create the HTML version of the manual within
the :doc:`CMake build directory <Build_cmake>`. The reason for this
option is to include the installation of the HTML manual pages into
the "install" step when installing LAMMPS after the CMake build via
``make install``. The documentation build is included in the default
build target, but can also be requested independently with ``make doc``.
It is also possible to create the HTML version (and only the HTML
version) of the manual within the :doc:`CMake build directory
<Build_cmake>`. The reason for this option is to include the
installation of the HTML manual pages into the "install" step when
installing LAMMPS after the CMake build via ``make install``. The
documentation build is included in the default build target, but can
also be requested independently with ``make doc``.
.. code-block:: bash
@ -514,27 +535,27 @@ Build LAMMPS tools
Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly
using CMake or Make.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D BUILD_TOOLS=value # yes or no (default)
.. code-block:: bash
The generated binaries will also become part of the LAMMPS installation
(see below).
-D BUILD_TOOLS=value # yes or no (default)
Traditional make
^^^^^^^^^^^^^^^^
The generated binaries will also become part of the LAMMPS installation
(see below).
.. code-block:: bash
.. tab:: Traditional make
cd lammps/tools
make all # build all binaries of tools
make binary2txt # build only binary2txt tool
make chain # build only chain tool
make micelle2d # build only micelle2d tool
make thermo_extract # build only thermo_extract tool
.. code-block:: bash
cd lammps/tools
make all # build all binaries of tools
make binary2txt # build only binary2txt tool
make chain # build only chain tool
make micelle2d # build only micelle2d tool
make thermo_extract # build only thermo_extract tool
----------
@ -549,18 +570,19 @@ a globally visible place on your system, for others to access. Note
that you may need super-user privileges (e.g. sudo) if the directory
you want to copy files to is protected.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
make # perform make after CMake command
make install # perform the installation into prefix
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
make # perform make after CMake command
make install # perform the installation into prefix
There is no "install" option in the ``src/Makefile`` for LAMMPS. If
you wish to do this you will need to first build LAMMPS, then manually
copy the desired LAMMPS files to the appropriate system directories.
.. tab:: Traditional make
There is no "install" option in the ``src/Makefile`` for LAMMPS.
If you wish to do this you will need to first build LAMMPS, then
manually copy the desired LAMMPS files to the appropriate system
directories.

688
doc/src/Build_extras.rst
View File

@ -486,111 +486,115 @@ version 3.2 of the Kokkos library. They must be specified in uppercase.
- GPU
- Intel GPUs Gen9+
Basic CMake build settings:
^^^^^^^^^^^^^^^^^^^^^^^^^^^
For multicore CPUs using OpenMP, set these 2 variables.
.. tabs::
.. code-block:: bash
.. tab:: Basic CMake build settings:
-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above
-D Kokkos_ENABLE_OPENMP=yes
-D BUILD_OMP=yes
For multicore CPUs using OpenMP, set these 2 variables.
Please note that enabling OpenMP for KOKKOS requires that OpenMP is
also :ref:`enabled for the rest of LAMMPS <serial>`.
.. code-block:: bash
For Intel KNLs using OpenMP, set these variables:
-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above
-D Kokkos_ENABLE_OPENMP=yes
-D BUILD_OMP=yes
.. code-block:: bash
Please note that enabling OpenMP for KOKKOS requires that OpenMP is
also :ref:`enabled for the rest of LAMMPS <serial>`.
-D Kokkos_ARCH_KNL=yes
-D Kokkos_ENABLE_OPENMP=yes
For Intel KNLs using OpenMP, set these variables:
For NVIDIA GPUs using CUDA, set these variables:
.. code-block:: bash
.. code-block:: bash
-D Kokkos_ARCH_KNL=yes
-D Kokkos_ENABLE_OPENMP=yes
-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above
-D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above
-D Kokkos_ENABLE_CUDA=yes
-D Kokkos_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper
For NVIDIA GPUs using CUDA, set these variables:
This will also enable executing FFTs on the GPU, either via the internal
KISSFFT library, or - by preference - with the cuFFT library bundled
with the CUDA toolkit, depending on whether CMake can identify its
location. The *wrapper* value for ``CMAKE_CXX_COMPILER`` variable is
the path to the CUDA nvcc compiler wrapper provided in the Kokkos
library: ``lib/kokkos/bin/nvcc_wrapper``\ . The setting should include
the full path name to the wrapper, e.g.
.. code-block:: bash
.. code-block:: bash
-D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above
-D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above
-D Kokkos_ENABLE_CUDA=yes
-D Kokkos_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper
-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper
This will also enable executing FFTs on the GPU, either via the
internal KISSFFT library, or - by preference - with the cuFFT
library bundled with the CUDA toolkit, depending on whether CMake
can identify its location. The *wrapper* value for
``CMAKE_CXX_COMPILER`` variable is the path to the CUDA nvcc
compiler wrapper provided in the Kokkos library:
``lib/kokkos/bin/nvcc_wrapper``\ . The setting should include the
full path name to the wrapper, e.g.
To simplify the compilation, three preset files are included in the
``cmake/presets`` folder, ``kokkos-serial.cmake``, ``kokkos-openmp.cmake``,
and ``kokkos-cuda.cmake``. They will enable the KOKKOS package and
enable some hardware choice. So to compile with OpenMP host parallelization,
CUDA device parallelization (for GPUs with CC 5.0 and up) with some
common packages enabled, you can do the following:
.. code-block:: bash
.. code-block:: bash
-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper
mkdir build-kokkos-cuda
cd build-kokkos-cuda
cmake -C ../cmake/presets/minimal.cmake -C ../cmake/presets/kokkos-cuda.cmake ../cmake
cmake --build .
To simplify compilation, three preset files are included in the
``cmake/presets`` folder, ``kokkos-serial.cmake``,
``kokkos-openmp.cmake``, and ``kokkos-cuda.cmake``. They will
enable the KOKKOS package and enable some hardware choice. So to
compile with OpenMP host parallelization, CUDA device
parallelization (for GPUs with CC 5.0 and up) with some common
packages enabled, you can do the following:
Basic traditional make settings:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
Choose which hardware to support in ``Makefile.machine`` via
``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings. See the
``src/MAKE/OPTIONS/Makefile.kokkos*`` files for examples.
mkdir build-kokkos-cuda
cd build-kokkos-cuda
cmake -C ../cmake/presets/minimal.cmake -C ../cmake/presets/kokkos-cuda.cmake ../cmake
cmake --build .
For multicore CPUs using OpenMP:
.. tab:: Basic traditional make settings:
.. code-block:: make
Choose which hardware to support in ``Makefile.machine`` via
``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings. See the
``src/MAKE/OPTIONS/Makefile.kokkos*`` files for examples.
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = HOSTARCH # HOSTARCH = HOST from list above
For multicore CPUs using OpenMP:
For Intel KNLs using OpenMP:
.. code-block:: make
.. code-block:: make
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = HOSTARCH # HOSTARCH = HOST from list above
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNL
For Intel KNLs using OpenMP:
For NVIDIA GPUs using CUDA:
.. code-block:: make
.. code-block:: make
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNL
KOKKOS_DEVICES = Cuda
KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is hosting the GPU
KOKKOS_CUDA_OPTIONS = "enable_lambda"
# GPUARCH = GPU from list above
FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional)
FFT_LIB = -lcufft # link to cuFFT library
For NVIDIA GPUs using CUDA:
For GPUs, you also need the following lines in your ``Makefile.machine``
before the CC line is defined. They tell ``mpicxx`` to use an ``nvcc``
compiler wrapper, which will use ``nvcc`` for compiling CUDA files and a
C++ compiler for non-Kokkos, non-CUDA files.
.. code-block:: make
.. code-block:: make
KOKKOS_DEVICES = Cuda
KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is hosting the GPU
KOKKOS_CUDA_OPTIONS = "enable_lambda"
# GPUARCH = GPU from list above
FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional)
FFT_LIB = -lcufft # link to cuFFT library
# For OpenMPI
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
CC = mpicxx
For GPUs, you also need the following lines in your
``Makefile.machine`` before the CC line is defined. They tell
``mpicxx`` to use an ``nvcc`` compiler wrapper, which will use
``nvcc`` for compiling CUDA files and a C++ compiler for
non-Kokkos, non-CUDA files.
.. code-block:: make
.. code-block:: make
# For MPICH and derivatives
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
# For OpenMPI
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
CC = mpicxx
.. code-block:: make
# For MPICH and derivatives
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
Advanced KOKKOS compilation settings
@ -900,26 +904,26 @@ binary package provided by your operating system.
``VORO_INCLUDE_DIR`` is the directory the Voro++ include file is
in.
.. tab:: Traditional make
.. tab:: Traditional make
You can download and build the Voro++ library manually if you
prefer; follow the instructions in ``lib/voronoi/README``. You
can also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invoke the
``lib/voronoi/Install.py`` script with the specified args:
You can download and build the Voro++ library manually if you
prefer; follow the instructions in ``lib/voronoi/README``. You
can also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invoke the
``lib/voronoi/Install.py`` script with the specified args:
.. code-block:: bash
.. code-block:: bash
$ make lib-voronoi # print help message
$ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
$ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
$ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
$ make lib-voronoi # print help message
$ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
$ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
$ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
Note that 2 symbolic (soft) links, ``includelink`` and
``liblink``, are created in lib/voronoi to point to the Voro++
source dir. When LAMMPS builds in ``src`` it will use these
links. You should not need to edit the
``lib/voronoi/Makefile.lammps`` file.
Note that 2 symbolic (soft) links, ``includelink`` and
``liblink``, are created in lib/voronoi to point to the Voro++
source dir. When LAMMPS builds in ``src`` it will use these
links. You should not need to edit the
``lib/voronoi/Makefile.lammps`` file.
----------
@ -975,8 +979,8 @@ The USER-ATC package requires the MANYBODY package also be installed.
.. tab:: CMake build
No additional settings are needed besides "-D PKG_USER-ATC=yes"
and "-D PKG_MANYBODY=yes".
No additional settings are needed besides ``-D PKG_USER-ATC=yes``
and ``-D PKG_MANYBODY=yes``.
.. tab:: Traditional make
@ -1083,8 +1087,9 @@ be built for the most part with all major versions of the C++ language.
.. tab:: CMake build
This is the recommended build recipe: no additional settings are normally
needed besides ``-D PKG_USER-COLVARS=yes``.
This is the recommended build procedure for using Colvars in
LAMMPS. No additional settings are normally needed besides
``-D PKG_USER-COLVARS=yes``.
.. tab:: Traditional make
@ -1322,51 +1327,53 @@ incorrectly and thus can cause segmentation faults in otherwise correct
code when using features from the USER-INTEL package.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D INTEL_ARCH=value # value = cpu (default) or knl
-D INTEL_LRT_MODE=value # value = threads, none, or c++11
.. code-block:: bash
-D INTEL_ARCH=value # value = cpu (default) or knl
-D INTEL_LRT_MODE=value # value = threads, none, or c++11
.. tab:: Traditional make
Choose which hardware to compile for in Makefile.machine via the
following settings. See ``src/MAKE/OPTIONS/Makefile.intel_cpu*``
and ``Makefile.knl`` files for examples. and
``src/USER-INTEL/README`` for additional information.
For CPUs:
.. code-block:: make
OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc
For KNLs:
.. code-block:: make
OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc
In Long-range thread mode (LRT) a modified verlet style is used, that
operates the Kspace calculation in a separate thread concurrently to
other calculations. This has to be enabled in the :doc:`package intel <package>`
command at runtime. With the setting "threads" it used the pthreads
library, while c++11 will use the built-in thread support of C++11
compilers. The option "none" skips compilation of this feature. The
default is to use "threads" if pthreads is available and otherwise "none".
other calculations. This has to be enabled in the :doc:`package intel
<package>` command at runtime. With the setting "threads" it used the
pthreads library, while "c++11" will use the built-in thread support
of C++11 compilers. The option "none" skips compilation of this
feature. The default is to use "threads" if pthreads is available and
otherwise "none".
Best performance is achieved with Intel hardware, Intel compilers, as well as
the Intel TBB and MKL libraries. However, the code also compiles, links, and
runs with other compilers and without TBB and MKL.
Traditional make
^^^^^^^^^^^^^^^^
Choose which hardware to compile for in Makefile.machine via the
following settings. See ``src/MAKE/OPTIONS/Makefile.intel_cpu*`` and
``Makefile.knl`` files for examples. and ``src/USER-INTEL/README`` for
additional information.
For CPUs:
.. code-block:: make
OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc
For KNLs:
.. code-block:: make
OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc
Best performance is achieved with Intel hardware, Intel compilers, as
well as the Intel TBB and MKL libraries. However, the code also
compiles, links, and runs with other compilers / hardware and without
TBB and MKL.
----------
@ -1381,31 +1388,34 @@ compile it. Also, the files with the force field data for running the
bundled examples are not included in the source distribution. Instead
they will be downloaded the first time this package is installed.
**CMake build**\ :
.. tabs::
No additional settings are needed besides ``-D PKG_USER-MESONT=yes``
.. tab:: CMake build
**Traditional make**\ :
No additional settings are needed besides ``-D PKG_USER-MESONT=yes``
Before building LAMMPS, you must build the *mesont* library in ``lib/mesont``\ .
You can also do it in one step from the ``lammps/src`` dir, using a command like
these, which simply invoke the ``lib/mesont/Install.py`` script with the specified
args:
.. tab:: Traditional make
.. code-block:: bash
Before building LAMMPS, you must build the *mesont* library in
``lib/mesont``\ . You can also do it in one step from the
``lammps/src`` dir, using a command like these, which simply
invoke the ``lib/mesont/Install.py`` script with the specified
args:
$ make lib-mesont # print help message
$ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-mesont args="-m ifort" # build with Intel icc compiler
.. code-block:: bash
The build should produce two files: ``lib/mesont/libmesont.a`` and
``lib/mesont/Makefile.lammps``\ . The latter is copied from an existing
``Makefile.lammps.\*`` and has settings needed to build LAMMPS with the
*mesont* library (though typically the settings contain only the Fortran
runtime library). If necessary, you can edit/create a new
``lib/mesont/Makefile.machine`` file for your system, which should
define an ``EXTRAMAKE`` variable to specify a corresponding
``Makefile.lammps.machine`` file.
$ make lib-mesont # print help message
$ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-mesont args="-m ifort" # build with Intel icc compiler
The build should produce two files: ``lib/mesont/libmesont.a`` and
``lib/mesont/Makefile.lammps``\ . The latter is copied from an
existing ``Makefile.lammps.\*`` and has settings needed to build
LAMMPS with the *mesont* library (though typically the settings
contain only the Fortran runtime library). If necessary, you can
edit/create a new ``lib/mesont/Makefile.machine`` file for your
system, which should define an ``EXTRAMAKE`` variable to specify a
corresponding ``Makefile.lammps.machine`` file.
----------
@ -1414,35 +1424,36 @@ define an ``EXTRAMAKE`` variable to specify a corresponding
USER-MOLFILE package
---------------------------------------
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D MOLFILE_INCLUDE_DIRS=path # (optional) path where VMD molfile plugin headers are installed
-D PKG_USER-MOLFILE=yes
.. code-block:: bash
Using "-D PKG_USER-MOLFILE=yes" enables the package, and setting
"-D MOLFILE_INCLUDE DIRS" allows to provide a custom location for
the molfile plugin header files. These should match the ABI of the
plugin files used, and thus one typically sets them to include
folder of the local VMD installation in use. LAMMPS ships with a
couple of default header files that correspond to a popular VMD
version, usually the latest release.
-D MOLFILE_INCLUDE_DIRS=path # (optional) path where VMD molfile plugin headers are installed
-D PKG_USER-MOLFILE=yes
Traditional make
^^^^^^^^^^^^^^^^
Using ``-D PKG_USER-MOLFILE=yes`` enables the package, and setting
``-D MOLFILE_INCLUDE_DIRS`` allows to provide a custom location for
the molfile plugin header files. These should match the ABI of the
plugin files used, and thus one typically sets them to include
folder of the local VMD installation in use. LAMMPS ships with a
couple of default header files that correspond to a popular VMD
version, usually the latest release.
The ``lib/molfile/Makefile.lammps`` file has a setting for a dynamic
loading library libdl.a that is typically present on all systems. It
is required for LAMMPS to link with this package. If the setting is
not valid for your system, you will need to edit the Makefile.lammps
file. See ``lib/molfile/README`` and ``lib/molfile/Makefile.lammps`` for
details. It is also possible to configure a different folder with
the VMD molfile plugin header files. LAMMPS ships with a couple of
default headers, but these are not compatible with all VMD versions,
so it is often best to change this setting to the location of the
same include files of the local VMD installation in use.
.. tab:: Traditional make
The ``lib/molfile/Makefile.lammps`` file has a setting for a
dynamic loading library libdl.a that is typically present on all
systems. It is required for LAMMPS to link with this package. If
the setting is not valid for your system, you will need to edit
the Makefile.lammps file. See ``lib/molfile/README`` and
``lib/molfile/Makefile.lammps`` for details. It is also possible
to configure a different folder with the VMD molfile plugin header
files. LAMMPS ships with a couple of default headers, but these
are not compatible with all VMD versions, so it is often best to
change this setting to the location of the same include files of
the local VMD installation in use.
----------
@ -1454,24 +1465,26 @@ USER-NETCDF package
To build with this package you must have the NetCDF library installed
on your system.
CMake build
^^^^^^^^^^^
.. tabs::
No additional settings are needed besides ``-D PKG_USER-NETCDF=yes``.
.. tab:: CMake build
This should auto-detect the NETCDF library if it is installed on your
system at standard locations. Several advanced CMake NETCDF options
exist if you need to specify where it was installed. Use the ``ccmake``
(terminal window) or ``cmake-gui`` (graphical) tools to see these
options and set them interactively from their user interfaces.
No additional settings are needed besides ``-D PKG_USER-NETCDF=yes``.
Traditional make
^^^^^^^^^^^^^^^^
This should auto-detect the NETCDF library if it is installed on
your system at standard locations. Several advanced CMake NETCDF
options exist if you need to specify where it was installed. Use
the ``ccmake`` (terminal window) or ``cmake-gui`` (graphical)
tools to see these options and set them interactively from their
user interfaces.
The ``lib/netcdf/Makefile.lammps`` file has settings for NetCDF include
and library files which LAMMPS needs to build with this package. If
the settings are not valid for your system, you will need to edit the
``Makefile.lammps`` file. See ``lib/netcdf/README`` for details.
.. tab:: Traditional make
The ``lib/netcdf/Makefile.lammps`` file has settings for NetCDF
include and library files which LAMMPS needs to build with this
package. If the settings are not valid for your system, you will
need to edit the ``Makefile.lammps`` file. See
``lib/netcdf/README`` for details.
----------
@ -1480,30 +1493,31 @@ the settings are not valid for your system, you will need to edit the
USER-OMP package
-------------------------------
CMake build
^^^^^^^^^^^
.. tabs::
No additional settings are required besides ``-D PKG_USER-OMP=yes``. If
CMake detects OpenMP support, the USER-OMP code will be compiled with
multi-threading support enabled, otherwise as optimized serial code.
.. tab:: CMake build
Traditional make
^^^^^^^^^^^^^^^^
No additional settings are required besides ``-D
PKG_USER-OMP=yes``. If CMake detects OpenMP compiler support, the
USER-OMP code will be compiled with multi-threading support
enabled, otherwise as optimized serial code.
To enable multi-threading support in the USER-OMP package (and other
styles supporting OpenMP) the following compile and link flags must be
added to your Makefile.machine file. See
``src/MAKE/OPTIONS/Makefile.omp`` for an example.
.. tab:: Traditional make
.. parsed-literal::
To enable multi-threading support in the USER-OMP package (and
other styles supporting OpenMP) the following compile and link
flags must be added to your Makefile.machine file. See
``src/MAKE/OPTIONS/Makefile.omp`` for an example.
CCFLAGS: -fopenmp # for GNU and Clang Compilers
CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux
LINKFLAGS: -fopenmp # for GNU and Clang Compilers
LINKFLAGS: -qopenmp # for Intel compilers on Linux
.. parsed-literal::
For other platforms and compilers, please consult the documentation
about OpenMP support for your compiler.
CCFLAGS: -fopenmp # for GNU and Clang Compilers
CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux
LINKFLAGS: -fopenmp # for GNU and Clang Compilers
LINKFLAGS: -qopenmp # for Intel compilers on Linux
For other platforms and compilers, please consult the
documentation about OpenMP support for your compiler.
----------
@ -1525,58 +1539,60 @@ 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
^^^^^^^^^^^
.. tabs::
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:
.. tab:: CMake build
.. code-block:: bash
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:
cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \
-D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake
.. code-block:: bash
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
cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \
-D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake
Traditional make
^^^^^^^^^^^^^^^^
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.
Before building LAMMPS, you must build the QMMM library in ``lib/qmmm``.
You can do this manually if you prefer; follow the first two steps
explained in ``lib/qmmm/README``. You can also do it in one step from
the ``lammps/src`` dir, using a command like these, which simply invoke
the ``lib/qmmm/Install.py`` script with the specified args:
.. tab:: Traditional make
.. code-block:: bash
Before building LAMMPS, you must build the QMMM library in
``lib/qmmm``. You can do this manually if you prefer; follow the
first two steps explained in ``lib/qmmm/README``. You can also do
it in one step from the ``lammps/src`` dir, using a command like
these, which simply invoke the ``lib/qmmm/Install.py`` script with
the specified args:
$ make lib-qmmm # print help message
$ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
$ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
$ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
.. code-block:: bash
The build should produce two files: ``lib/qmmm/libqmmm.a`` and
``lib/qmmm/Makefile.lammps``. The latter is copied from an existing
``Makefile.lammps.*`` and has settings needed to build LAMMPS with the
QMMM library (though typically the settings are just blank). If
necessary, you can edit/create a new ``lib/qmmm/Makefile.<machine>`` file
for your system, which should define an ``EXTRAMAKE`` variable to
specify a corresponding ``Makefile.lammps.<machine>`` file.
$ make lib-qmmm # print help message
$ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
$ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
$ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
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 (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.
The build should produce two files: ``lib/qmmm/libqmmm.a`` and
``lib/qmmm/Makefile.lammps``. The latter is copied from an
existing ``Makefile.lammps.*`` and has settings needed to build
LAMMPS with the QMMM library (though typically the settings are
just blank). If necessary, you can edit/create a new
``lib/qmmm/Makefile.<machine>`` file for your system, which should
define an ``EXTRAMAKE`` variable to specify 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 (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.
----------
@ -1591,27 +1607,27 @@ potentials, additional files with specific licensing conditions need
to be downloaded and configured. See step 1 and step 1.1 in the
``lib/quip/README`` file for details on how to do this.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location)
.. code-block:: bash
CMake will not download and build the QUIP library. But once you have
done that, a CMake build of LAMMPS with ``-D PKG_USER-QUIP=yes`` should
work. Set QUIP_LIBRARY if CMake cannot find the QUIP library.
-D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location)
Traditional make
^^^^^^^^^^^^^^^^
CMake will **not** download and build the QUIP library. But once you have
done that, a CMake build of LAMMPS with ``-D PKG_USER-QUIP=yes`` should
work. Set the ``QUIP_LIBRARY`` variable if CMake cannot find the QUIP library.
The download/build procedure for the QUIP library, described in
``lib/quip/README`` file requires setting two environment variables,
QUIP_ROOT and QUIP_ARCH. These are accessed by the
lib/quip/Makefile.lammps file which is used when you compile and link
LAMMPS with this package. You should only need to edit
``Makefile.lammps`` if the LAMMPS build can not use its settings to
successfully build on your system.
.. tab:: Traditional make
The download/build procedure for the QUIP library, described in
``lib/quip/README`` file requires setting two environment
variables, ``QUIP_ROOT`` and ``QUIP_ARCH``. These are accessed by
the ``lib/quip/Makefile.lammps`` file which is used when you
compile and link LAMMPS with this package. You should only need
to edit ``Makefile.lammps`` if the LAMMPS build can not use its
settings to successfully build on your system.
----------
@ -1620,44 +1636,45 @@ successfully build on your system.
USER-SCAFACOS package
-----------------------------------------
To build with this package, you must download and build the `ScaFaCoS
Coulomb solver library <scafacos-home_>`_
To build with this package, you must download and build the
`ScaFaCoS Coulomb solver library <http://www.scafacos.de>`_
.. _scafacos-home: http://www.scafacos.de
.. tabs::
CMake build
^^^^^^^^^^^
.. tab:: CMake build
.. code-block:: bash
.. code-block:: bash
-D DOWNLOAD_SCAFACOS=value # download ScaFaCoS for build, value = no (default) or yes
-D SCAFACOS_LIBRARY=path # ScaFaCos library file (only needed if at custom location)
-D SCAFACOS_INCLUDE_DIR=path # ScaFaCoS include directory (only needed if at custom location)
-D DOWNLOAD_SCAFACOS=value # download ScaFaCoS for build, value = no (default) or yes
-D SCAFACOS_LIBRARY=path # ScaFaCos library file (only needed if at custom location)
-D SCAFACOS_INCLUDE_DIR=path # ScaFaCoS include directory (only needed if at custom location)
If DOWNLOAD_SCAFACOS is set, the ScaFaCoS library will be downloaded
and built inside the CMake build directory. If the ScaFaCoS library
is already on your system (in a location CMake cannot find it),
SCAFACOS_LIBRARY is the filename (plus path) of the ScaFaCoS library
file, not the directory the library file is in. SCAFACOS_INCLUDE_DIR
is the directory the ScaFaCoS include file is in.
If ``DOWNLOAD_SCAFACOS`` is set, the ScaFaCoS library will be
downloaded and built inside the CMake build directory. If the
ScaFaCoS library is already on your system (in a location CMake
cannot find it), ``SCAFACOS_LIBRARY`` is the filename (plus path) of
the ScaFaCoS library file, not the directory the library file is
in. ``SCAFACOS_INCLUDE_DIR`` is the directory the ScaFaCoS include
file is in.
Traditional make
^^^^^^^^^^^^^^^^
.. tab:: Traditional make
You can download and build the ScaFaCoS library manually if you
prefer; follow the instructions in ``lib/scafacos/README``. You can also
do it in one step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/scafacos/Install.py`` script with the
specified args:
You can download and build the ScaFaCoS library manually if you
prefer; follow the instructions in ``lib/scafacos/README``. You
can also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invoke the
``lib/scafacos/Install.py`` script with the specified args:
make lib-scafacos # print help message
make lib-scafacos args="-b" # download and build in lib/scafacos/scafacos-<version>
make lib-scafacos args="-p $HOME/scafacos # use existing ScaFaCoS installation in $HOME/scafacos
.. code-block:: bash
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, are
created in ``lib/scafacos`` to point to the ScaFaCoS src dir. When LAMMPS
builds in src it will use these links. You should not need to edit
the ``lib/scafacos/Makefile.lammps`` file.
make lib-scafacos # print help message
make lib-scafacos args="-b" # download and build in lib/scafacos/scafacos-<version>
make lib-scafacos args="-p $HOME/scafacos # use existing ScaFaCoS installation in $HOME/scafacos
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, are
created in ``lib/scafacos`` to point to the ScaFaCoS src dir. When LAMMPS
builds in src it will use these links. You should not need to edit
the ``lib/scafacos/Makefile.lammps`` file.
----------
@ -1669,37 +1686,39 @@ USER-SMD package
To build with this package, you must download the Eigen3 library.
Eigen3 is a template library, so you do not need to build it.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D DOWNLOAD_EIGEN3 # download Eigen3, value = no (default) or yes
-D EIGEN3_INCLUDE_DIR=path # path to Eigen library (only needed if a custom location)
.. code-block:: bash
If ``DOWNLOAD_EIGEN3`` is set, the Eigen3 library will be downloaded and
inside the CMake build directory. If the Eigen3 library is already on
your system (in a location where CMake cannot find it), set
``EIGEN3_INCLUDE_DIR`` to the directory the ``Eigen3`` include file is in.
-D DOWNLOAD_EIGEN3 # download Eigen3, value = no (default) or yes
-D EIGEN3_INCLUDE_DIR=path # path to Eigen library (only needed if a custom location)
Traditional make
^^^^^^^^^^^^^^^^
If ``DOWNLOAD_EIGEN3`` is set, the Eigen3 library will be
downloaded and inside the CMake build directory. If the Eigen3
library is already on your system (in a location where CMake
cannot find it), set ``EIGEN3_INCLUDE_DIR`` to the directory the
``Eigen3`` include file is in.
You can download the Eigen3 library manually if you prefer; follow the
instructions in ``lib/smd/README``. You can also do it in one step from
the ``lammps/src`` dir, using a command like these, which simply invoke
the ``lib/smd/Install.py`` script with the specified args:
.. tab:: Traditional make
.. code-block:: bash
You can download the Eigen3 library manually if you prefer; follow
the instructions in ``lib/smd/README``. You can also do it in one
step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/smd/Install.py`` script with the
specified args:
$ make lib-smd # print help message
$ make lib-smd args="-b" # download to lib/smd/eigen3
$ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
.. code-block:: bash
Note that a symbolic (soft) link named ``includelink`` is created in
``lib/smd`` to point to the Eigen dir. When LAMMPS builds it will use
this link. You should not need to edit the ``lib/smd/Makefile.lammps``
file.
$ make lib-smd # print help message
$ make lib-smd args="-b" # download to lib/smd/eigen3
$ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
Note that a symbolic (soft) link named ``includelink`` is created
in ``lib/smd`` to point to the Eigen dir. When LAMMPS builds it
will use this link. You should not need to edit the
``lib/smd/Makefile.lammps`` file.
----------
@ -1711,23 +1730,24 @@ USER-VTK package
To build with this package you must have the VTK library installed on
your system.
CMake build
^^^^^^^^^^^
.. tabs::
No additional settings are needed besides ``-D PKG_USER-VTK=yes``.
.. tab:: CMake build
This should auto-detect the VTK library if it is installed on your
system at standard locations. Several advanced VTK options exist if
you need to specify where it was installed. Use the ``ccmake`` (terminal
window) or ``cmake-gui`` (graphical) tools to see these options and set
them interactively from their user interfaces.
No additional settings are needed besides ``-D PKG_USER-VTK=yes``.
Traditional make
^^^^^^^^^^^^^^^^
This should auto-detect the VTK library if it is installed on your
system at standard locations. Several advanced VTK options exist
if you need to specify where it was installed. Use the ``ccmake``
(terminal window) or ``cmake-gui`` (graphical) tools to see these
options and set them interactively from their user interfaces.
The ``lib/vtk/Makefile.lammps`` file has settings for accessing VTK files
and its library, which LAMMPS needs to build with this package. If
the settings are not valid for your system, check if one of the other
``lib/vtk/Makefile.lammps.*`` files is compatible and copy it to
Makefile.lammps. If none of the provided files work, you will need to
edit the ``Makefile.lammps`` file. See ``lib/vtk/README`` for details.
.. tab:: Traditional make
The ``lib/vtk/Makefile.lammps`` file has settings for accessing
VTK files and its library, which LAMMPS needs to build with this
package. If the settings are not valid for your system, check if
one of the other ``lib/vtk/Makefile.lammps.*`` files is compatible
and copy it to Makefile.lammps. If none of the provided files
work, you will need to edit the ``Makefile.lammps`` file. See
``lib/vtk/README`` for details.

151
doc/src/Build_package.rst
View File

@ -45,91 +45,92 @@ packages:
The mechanism for including packages is simple but different for CMake
versus make.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: csh
.. tab:: CMake build
-D PKG_NAME=value # yes or no (default)
.. code-block:: csh
Examples:
-D PKG_NAME=value # yes or no (default)
.. code-block:: csh
Examples:
-D PKG_MANYBODY=yes
-D PKG_USER-INTEL=yes
.. code-block:: csh
All standard and user packages are included the same way. Note that
USER packages have a hyphen between USER and the rest of the package
name, not an underscore.
-D PKG_MANYBODY=yes
-D PKG_USER-INTEL=yes
See the shortcut section below for how to install many packages at
once with CMake.
All standard and user packages are included the same way. Note
that USER packages have a hyphen between USER and the rest of the
package name, not an underscore.
See the shortcut section below for how to install many packages at
once with CMake.
.. note::
If you switch between building with CMake and make builds, no
packages in the src directory can be installed when you invoke
``cmake``. CMake will give an error if that is not the case,
indicating how you can un-install all packages in the src dir.
.. tab:: Traditional make
.. code-block:: bash
cd lammps/src
make ps # check which packages are currently installed
make yes-name # install a package with name
make no-name # un-install a package with name
make mpi # build LAMMPS with whatever packages are now installed
Examples:
.. code-block:: bash
make no-rigid
make yes-user-intel
All standard and user packages are included the same way.
See the shortcut section below for how to install many packages at
once with make.
.. note::
You must always re-build LAMMPS (via make) after installing or
un-installing a package, for the action to take effect. The
included dependency tracking will make certain only files that
are required to be rebuilt are recompiled.
.. note::
You cannot install or un-install packages and build LAMMPS in a
single make command with multiple targets, e.g. ``make
yes-colloid mpi``. This is because the make procedure creates
a list of source files that will be out-of-date for the build
if the package configuration changes within the same command.
You can include or exclude multiple packages in a single make
command, e.g. ``make yes-colloid no-manybody``.
Information for both build systems
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Almost all packages can be included or excluded in a LAMMPS build,
independent of the other packages. However, some packages include files
derived from files in other packages. LAMMPS checks for this and does
the right thing. Individual files are only included if their
dependencies are already included. Likewise, if a package is excluded,
other files dependent on that package are also excluded.
.. note::
If you toggle back and forth between building with CMake vs
make, no packages in the src directory can be installed when you
invoke cmake. CMake will give an error if that is not the case,
indicating how you can un-install all packages in the src dir.
Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: bash
cd lammps/src
make ps # check which packages are currently installed
make yes-name # install a package with name
make no-name # un-install a package with name
make mpi # build LAMMPS with whatever packages are now installed
Examples:
.. code-block:: bash
make no-rigid
make yes-user-intel
All standard and user packages are included the same way.
See the shortcut section below for how to install many packages at
once with make.
.. note::
You must always re-build LAMMPS (via make) after installing or
un-installing a package, for the action to take effect.
.. note::
You cannot install or un-install packages and build LAMMPS in a
single make command with multiple targets, e.g. make yes-colloid mpi.
This is because the make procedure creates a list of source files that
will be out-of-date for the build if the package configuration changes
within the same command. You can include or exclude multiple packages
in a single make command, e.g. make yes-colloid no-manybody.
CMake and make info
^^^^^^^^^^^^^^^^^^^
Any package can be included or excluded in a LAMMPS build, independent
of all other packages. However, some packages include files derived
from files in other packages. LAMMPS checks for this and does the
right thing. Individual files are only included if their dependencies
are already included. Likewise, if a package is excluded, other files
dependent on that package are also excluded.
When you download a LAMMPS tarball or download LAMMPS source files
from the git repository, no packages are pre-installed in the
src directory.
.. note::
Prior to Aug 2018, if you downloaded a tarball, 3 packages
(KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory.
That is no longer the case, so that CMake will build as-is without the
need to un-install those packages.
By default no package is installed. Prior to August 2018, however,
if you downloaded a tarball, 3 packages (KSPACE, MANYBODY, MOLECULE)
were pre-installed via the traditional make procedure in the ``src``
directory. That is no longer the case, so that CMake will build
as-is without needing to un-install those packages.
----------