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

Merge pull request #2348 from akohlmey/use-tabs-with-html 

Enable sphinx-tabs extension with the html version of the documentation
This commit is contained in:
Axel Kohlmeyer 2020-09-08 12:02:43 -04:00 committed by GitHub
parent d995ed0d87 5df3deb8e6
commit 9f8b8529b1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 1489 additions and 1349 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.

1561
doc/src/Build_extras.rst
View File

File diff suppressed because it is too large Load Diff

194
doc/src/Build_link.rst
View File

@ -41,42 +41,45 @@ The benefit of linking to a static library is, that the resulting
executable is independent of that library since all required
executable code from the library is copied into the calling executable.
CMake build
^^^^^^^^^^^
.. tabs::
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:
.. tab:: CMake build
.. code-block:: bash
This assumes that LAMMPS has been configured without setting a
``LAMMPS_MACHINE`` name, installed with "make install", and the
``PKG_CONFIG_PATH`` environment variable has been updated to
include the ``liblammps.pc`` file installed into the configured
destination folder. The commands to compile and link a coupled
executable are then:
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
This assumes that LAMMPS has been compiled in the folder
``${HOME}/lammps/src`` with "make mpi". The commands to compile and link
a coupled executable are then:
.. tab:: Traditional make
.. code-block:: bash
This assumes that LAMMPS has been compiled in the folder
``${HOME}/lammps/src`` with "make mpi". The commands to compile
and link a coupled executable are then:
mpicc -c -O -I${HOME}/lammps/src caller.c
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
.. code-block:: bash
The *-I* argument is the path to the location of the ``library.h``
header file containing the interface to the LAMMPS C-style library
interface. The *-L* argument is the path to where the ``liblammps_mpi.a``
file is located. The *-llammps_mpi* argument is shorthand for telling the
compiler to link the file ``liblammps_mpi.a``. If LAMMPS has been
built as a shared library, then the linker will use ``liblammps_mpi.so``
instead. If both files are available, the linker will usually prefer
the shared library. In case of a shared library, you may need to update
the ``LD_LIBRARY_PATH`` environment variable or running the ``caller``
executable will fail since it cannot find the shared library at runtime.
mpicc -c -O -I${HOME}/lammps/src caller.c
mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
The *-I* argument is the path to the location of the ``library.h``
header file containing the interface to the LAMMPS C-style library
interface. The *-L* argument is the path to where the
``liblammps_mpi.a`` file is located. The *-llammps_mpi* argument
is shorthand for telling the compiler to link the file
``liblammps_mpi.a``. If LAMMPS has been built as a shared
library, then the linker will use ``liblammps_mpi.so`` instead.
If both files are available, the linker will usually prefer the
shared library. In case of a shared library, you may need to
update the ``LD_LIBRARY_PATH`` environment variable or running the
``caller`` executable will fail since it cannot find the shared
library at runtime.
However, it is only as simple as shown above for the case of a plain
LAMMPS library without any optional packages that depend on libraries
@ -84,61 +87,62 @@ LAMMPS library without any optional packages that depend on libraries
need to include all flags, libraries, and paths for the coupled
executable, that are also required to link the LAMMPS executable.
CMake build
^^^^^^^^^^^
.. tabs::
When using CMake, additional libraries with sources in the lib folder
are built, but not included in ``liblammps.a`` and (currently) not
installed with ``make install`` and not included in the ``pkgconfig``
configuration file. They can be found in the top level build folder,
but you have to determine the necessary link flags manually. It is
therefore recommended to either use the traditional make procedure to
build and link with a static library or build and link with a shared
library instead.
.. tab:: CMake build
Traditional make
^^^^^^^^^^^^^^^^
When using CMake, additional libraries with sources in the lib
folder are built, but not included in ``liblammps.a`` and
(currently) not installed with ``make install`` and not included
in the ``pkgconfig`` configuration file. They can be found in the
top level build folder, but you have to determine the necessary
link flags manually. It is therefore recommended to either use
the traditional make procedure to build and link with a static
library or build and link with a shared library instead.
After you have compiled a static LAMMPS library using the conventional
build system for example with "make mode=static serial". And you also
have installed the ``POEMS`` package after building its bundled library
in ``lib/poems``. Then the commands to build and link the coupled executable
change to:
.. tab:: Traditional make
.. code-block:: bash
After you have compiled a static LAMMPS library using the
conventional build system for example with "make mode=static
serial". And you also have installed the ``POEMS`` package after
building its bundled library in ``lib/poems``. Then the commands
to build and link the coupled executable change to:
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps_serial -lpoems -lmpi_stubs
.. code-block:: bash
Note, that you need to link with ``g++`` instead of ``gcc`` even if you have
written your code in C, since LAMMPS itself is C++ code. You can display the
currently applied settings for building LAMMPS for the "serial" machine target
by using the command:
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
-L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \
-llammps_serial -lpoems -lmpi_stubs
.. code-block:: bash
Note, that you need to link with ``g++`` instead of ``gcc`` even
if you have written your code in C, since LAMMPS itself is C++
code. You can display the currently applied settings for building
LAMMPS for the "serial" machine target by using the command:
make mode=print serial
.. code-block:: bash
Which should output something like:
make mode=print serial
.. code-block:: bash
Which should output something like:
# Compiler:
CXX=g++
# Linker:
LD=g++
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
# Linking:
LDFLAGS=-g -O
# Libraries:
LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
.. code-block:: bash
From this you can gather the necessary paths and flags. With
makefiles for other *machine* configurations you need to do the
equivalent and replace "serial" with the corresponding "machine" name
of the makefile.
# Compiler:
CXX=g++
# Linker:
LD=g++
# Compilation:
CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
# Linking:
LDFLAGS=-g -O
# Libraries:
LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
From this you can gather the necessary paths and flags. With
makefiles for other *machine* configurations you need to do the
equivalent and replace "serial" with the corresponding "machine"
name of the makefile.
Link with LAMMPS as a shared library
------------------------------------
@ -151,35 +155,36 @@ 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
^^^^^^^^^^^
.. tabs::
The commands with a shared LAMMPS library compiled with the CMake
build process are the same as for the static library.
.. tab:: CMake build
.. code-block:: bash
The commands with a shared LAMMPS library compiled with the CMake
build process are the same as for the static library.
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
mpicxx -o caller caller.o -$(pkgconf --libs)
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
mpicc -c -O $(pkgconf liblammps --cflags) caller.c
mpicxx -o caller caller.o -$(pkgconf --libs)
The commands with a shared LAMMPS library compiled with the
traditional make build using ``make mode=shared serial`` becomes:
.. tab:: Traditional make
.. code-block:: bash
The commands with a shared LAMMPS library compiled with the
traditional make build using ``make mode=shared serial`` becomes:
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
.. code-block:: bash
*Locating liblammps.so at runtime*\ :
gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
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``
environment variable. You can type
Locating liblammps.so at runtime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Unlike with a static link, 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`` environment variable. You can type
.. code-block:: bash
@ -187,9 +192,10 @@ 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
version of the shared library is always available to programs that use it.
Or you can add the LAMMPS src directory or the directory you performed a
CMake style build in to your ``LD_LIBRARY_PATH`` environment variable,
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 ``${HOME}/.profile`` file:

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.
----------

410
doc/src/Build_settings.rst
View File

@ -44,74 +44,71 @@ require use of an FFT library to compute 1d FFTs. The KISS FFT
library is included with LAMMPS but other libraries can be faster.
LAMMPS can use them if they are available on your system.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy
.. code-block:: bash
.. note::
-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy
The values for the FFT variable must be in upper-case. This is
an exception to the rule that all CMake variables can be specified
with lower-case values.
.. note::
Usually these settings are all that is needed. If FFTW3 is selected,
then CMake will try to detect, if threaded FFTW libraries are available
and enable them by default. This setting is independent of whether
OpenMP threads are enabled and a packages like KOKKOS or USER-OMP is
used. If CMake cannot detect the FFT library, you can set these variables
to assist:
The values for the FFT variable must be in upper-case. This is
an exception to the rule that all CMake variables can be specified
with lower-case values.
.. code-block:: bash
Usually these settings are all that is needed. If FFTW3 is
selected, then CMake will try to detect, if threaded FFTW
libraries are available and enable them by default. This setting
is independent of whether OpenMP threads are enabled and a
packages like KOKKOS or USER-OMP is used. If CMake cannot detect
the FFT library, you can set these variables to assist:
-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
-D FFTW3_LIBRARIES=path # path to FFTW3 libraries
-D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries
-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARIES=path
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
-D FFTW3_LIBRARIES=path # path to FFTW3 libraries
-D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries
-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARIES=path
To change the FFT library to be used and its options, you have to edit
your machine Makefile. Below are examples how the makefile variables
could be changed.
.. tab:: Traditional make
.. code-block:: make
To change the FFT library to be used and its options, you have to edit
your machine Makefile. Below are examples how the makefile variables
could be changed.
FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
# default is KISS if not specified
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries
FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
.. code-block:: make
# default is FFT_PACK_ARRAY if not specified
FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
# default is KISS if not specified
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries
FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
# default is FFT_PACK_ARRAY if not specified
.. code-block:: make
.. code-block:: make
FFT_INC = -I/usr/local/include
FFT_PATH = -L/usr/local/lib
FFT_LIB = -lfftw3 # FFTW3 double precision
FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS)
FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision
FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler, serial interface
FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface
FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface
FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface
FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs
FFT_INC = -I/usr/local/include
FFT_PATH = -L/usr/local/lib
FFT_LIB = -lfftw3 # FFTW3 double precision
FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS)
FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision
FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler, serial interface
FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface
FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface
FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface
FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs
As with CMake, you do not need to set paths in ``FFT_INC`` or ``FFT_PATH``, if
the compiler can find the FFT header and library files in its default search path.
You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link.
CMake build
^^^^^^^^^^^
As with CMake, you do not need to set paths in ``FFT_INC`` or
``FFT_PATH``, if the compiler can find the FFT header and library
files in its default search path. You must specify ``FFT_LIB``
with the appropriate FFT libraries to include in the link.
The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
distribution. It is portable across all platforms. Depending on the size
@ -177,76 +174,104 @@ ARRAY mode.
.. _size:
Size of LAMMPS integer types
------------------------------------
Size of LAMMPS integer types and size limits
--------------------------------------------
LAMMPS has a few integer data types which can be defined as either
4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time.
This has an impact on the size of a system that can be simulated
or how large counters can become before "rolling over".
The default setting of "smallbig" is almost always adequate.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
With CMake the choice of integer types is made via setting a
variable during configuration.
Traditional build
^^^^^^^^^^^^^^^^^
.. code-block:: bash
If you want a setting different from the default, you need to edit your
machine Makefile.
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
.. code-block:: make
If the variable is not set explicitly, "smallbig" is used.
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
.. tab:: Traditional build
The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
If you want a setting different from the default, you need to edit the
``LMP_INC`` variable setting your machine Makefile.
CMake and make info
^^^^^^^^^^^^^^^^^^^
.. code-block:: make
The default "smallbig" setting allows for simulations with:
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
* total atom count = 2\^63 atoms (about 9e18)
* total timesteps = 2\^63 (about 9e18)
* atom IDs = 2\^31 (about 2 billion)
* image flags = roll over at 512
The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
The "bigbig" setting increases the latter two limits. It allows for:
LAMMPS system size restrictions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* total atom count = 2\^63 atoms (about 9e18)
* total timesteps = 2\^63 (about 9e18)
* atom IDs = 2\^63 (about 9e18)
* image flags = roll over at about 1 million (2\^20)
.. list-table::
:header-rows: 1
:widths: auto
:align: center
The "smallsmall" setting is only needed if your machine does not
support 8-byte integers. It allows for:
* -
- smallbig
- bigbig
- smallsmall
* - Total atom count
- :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{31}` atoms (= :math:`2.147 \cdot 10^9`)
* - Total timesteps
- :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{31}` steps (= :math:`2.147 \cdot 10^9`)
* - Atom ID values
- :math:`1 \le i \le 2^{31} (= 2.147 \dot 10^9)`
- :math:`1 \le i \le 2^{63} (= 9.223 \cdot 10^{18})`
- :math:`1 \le i \le 2^{31} (= 2.147 \dot 10^9)`
* - Image flag values
- :math:`-512 \le i \le 511`
- :math:`- 1\,048\,576 \le i \le 1\,048\,575`
- :math:`-512 \le i \le 511`
* total atom count = 2\^31 atoms (about 2 billion)
* total timesteps = 2\^31 (about 2 billion)
* atom IDs = 2\^31 (about 2 billion)
* image flags = roll over at 512 (2\^9)
The "bigbig" setting increases the size of image flags and atom IDs over
"smallbig" and the "smallsmall" setting is only needed if your machine
does not support 64-bit integers or incurs performance penalties when
using them.
These are limits for the core of the LAMMPS code, specific features or
some styles may impose additional limits. The :ref:`USER-ATC
<PKG-USER-ATC>` package cannot be compiled with the "bigbig" setting.
Also, there are limitations when using the library interface where some
functions with known issues have been replaced by dummy calls printing a
corresponding error message rather than crashing randomly or corrupting
data.
Atom IDs are not required for atomic systems which do not store bond
topology information, though IDs are enabled by default. The
:doc:`atom_modify id no <atom_modify>` command will turn them off. Atom
IDs are required for molecular systems with bond topology (bonds,
angles, dihedrals, etc). Thus if you model a molecular system with
more than 2 billion atoms, you need the "bigbig" setting.
angles, dihedrals, etc). Similarly, some force or compute or fix styles
require atom IDs. Thus if you model a molecular system or use one of
those styles with more than 2 billion atoms, you need the "bigbig"
setting.
Image flags store 3 values per atom which count the number of times an
atom has moved through the periodic box in each dimension. See the
:doc:`dump <dump>` doc page for a discussion. If an atom moves through
the periodic box more than this limit, the value will "roll over",
e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the :doc:`compute msd <compute_msd>` command, to be faulty.
Regardless of the total system size limits, the maximum number of atoms
per MPI rank (local + ghost atoms) is limited to 2 billion for atomic
systems and 500 million for systems with bonds (the additional
restriction is due to using the 2 upper bits of the local atom index
in neighbor lists for storing special bonds info).
Image flags store 3 values per atom in a single integer which count the
number of times an atom has moved through the periodic box in each
dimension. See the :doc:`dump <dump>` doc page for a discussion. If an
atom moves through the periodic box more than this limit, the value will
"roll over", e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the :doc:`compute msd
<compute_msd>` command, to be faulty.
Note that the USER-ATC package and the USER-INTEL package are currently
not compatible with the "bigbig" setting. Also, there are limitations
when using the library interface. Some functions with known issues
have been replaced by dummy calls printing a corresponding error rather
than crashing randomly or corrupting data.
Also note that the GPU package requires its lib/gpu library to be
compiled with the same size setting, or the link will fail. A CMake
@ -265,54 +290,51 @@ PNG image files. Likewise the :doc:`dump movie <dump_image>` command
outputs movie files in MPEG format. Using these options requires the
following settings:
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D WITH_JPEG=value # yes or no
# default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
.. code-block:: bash
Usually these settings are all that is needed. If CMake cannot find
the graphics header, library, executable files, you can set these
variables:
-D WITH_JPEG=value # yes or no
# default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
.. code-block:: bash
Usually these settings are all that is needed. If CMake cannot
find the graphics header, library, executable files, you can set
these variables:
-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file
-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARIES=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file
-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARIES=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
.. code-block:: make
.. tab:: Traditional make
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
.. code-block:: make
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
JPG_LIB = -ljpeg -lpng -lz # library names
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
if make can find the graphics header and library files. You must
specify ``JPG_LIB``
with a list of graphics libraries to include in the link. You must
insure ffmpeg is in a directory where LAMMPS can find it at runtime,
that is a directory in your PATH environment variable.
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
JPG_LIB = -ljpeg -lpng -lz # library names
CMake and make info
^^^^^^^^^^^^^^^^^^^
As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
if make can find the graphics header and library files. You must
specify ``JPG_LIB`` with a list of graphics libraries to include
in the link. You must insure ffmpeg is in a directory where
LAMMPS can find it at runtime, that is a directory in your PATH
environment variable.
Using ``ffmpeg`` to output movie files requires that your machine
supports the "popen" function in the standard runtime library.
@ -335,37 +357,34 @@ If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including
:doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
.. code-block:: make
.. tab:: Traditional make
LMP_INC = -DLAMMPS_GZIP
.. code-block:: make
CMake and make info
^^^^^^^^^^^^^^^^^^^
LMP_INC = -DLAMMPS_GZIP
This option requires that your machine supports the "popen()" function
in the standard runtime library and that a gzip executable can be
This option requires that your operating system fully supports the "popen()"
function in the standard runtime library and that a ``gzip`` executable can be
found by LAMMPS during a run.
.. note::
On some clusters with high-speed networks, using the fork()
library call (required by popen()) can interfere with the fast
communication library and lead to simulations using compressed output
or input to hang or crash. For selected operations, compressed file
I/O is also available using a compression library instead, which is
what the :ref:`COMPRESS package <PKG-COMPRESS>` enables.
On some clusters with high-speed networks, using the "fork()" library
call (required by "popen()") can interfere with the fast communication
library and lead to simulations using compressed output or input to
hang or crash. For selected operations, compressed file I/O is also
available using a compression library instead, which is what the
:ref:`COMPRESS package <PKG-COMPRESS>` enables.
----------
@ -374,65 +393,66 @@ found by LAMMPS during a run.
Memory allocation alignment
---------------------------------------
This setting enables the use of the posix_memalign() call instead of
malloc() when LAMMPS allocates large chunks or memory. This can make
vector instructions on CPUs more efficient, if dynamically allocated
memory is aligned on larger-than-default byte boundaries.
On most current systems, the malloc() implementation returns
This setting enables the use of the "posix_memalign()" call instead of
"malloc()" when LAMMPS allocates large chunks or memory. Vector
instructions on CPUs may become more efficient, if dynamically allocated
memory is aligned on larger-than-default byte boundaries. On most
current operating systems, the "malloc()" implementation returns
pointers that are aligned to 16-byte boundaries. Using SSE vector
instructions efficiently, however, requires memory blocks being
aligned on 64-byte boundaries.
instructions efficiently, however, requires memory blocks being aligned
on 64-byte boundaries.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default)
.. code-block:: bash
Use a ``LAMMPS_MEMALIGN`` value of 0 to disable using posix_memalign()
and revert to using the malloc() C-library function instead. When
compiling LAMMPS for Windows systems, malloc() will always be used
and this setting ignored.
-D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default)
Traditional make
^^^^^^^^^^^^^^^^
Use a ``LAMMPS_MEMALIGN`` value of 0 to disable using
"posix_memalign()" and revert to using the "malloc()" C-library
function instead. When compiling LAMMPS for Windows systems,
"malloc()" will always be used and this setting is ignored.
.. code-block:: make
.. tab:: Traditional make
LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64
.. code-block:: make
Do not set ``-DLAMMPS_MEMALIGN``, if you want to have memory allocated
with the malloc() function call instead. ``-DLAMMPS_MEMALIGN`` **cannot**
be used on Windows, as it does use different function calls for
allocating aligned memory, that are not compatible with how LAMMPS
manages its dynamical memory.
LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64
Do not set ``-DLAMMPS_MEMALIGN``, if you want to have memory
allocated with the "malloc()" function call
instead. ``-DLAMMPS_MEMALIGN`` **cannot** be used on Windows, as
Windows different function calls with different semantics for
allocating aligned memory, that are not compatible with how LAMMPS
manages its dynamical memory.
----------
.. _longlong:
Workaround for long long integers
------------------------------------------------
---------------------------------
If your system or MPI version does not recognize "long long" data
types, the following setting will be needed. It converts "long long"
to a "long" data type, which should be the desired 8-byte integer on
those systems:
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default)
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default)
.. code-block:: make
.. tab:: Traditional make
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
.. code-block:: make
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
----------
@ -447,19 +467,19 @@ Instead, the call stack is unwound and control returns to the caller,
e.g. to Python. Of course, the calling code has to be set up to
*catch* exceptions thrown from within LAMMPS.
CMake build
^^^^^^^^^^^
.. tabs::
.. code-block:: bash
.. tab:: CMake build
-D LAMMPS_EXCEPTIONS=value # yes or no (default)
.. code-block:: bash
Traditional make
^^^^^^^^^^^^^^^^
-D LAMMPS_EXCEPTIONS=value # yes or no (default)
.. code-block:: make
.. tab:: Traditional make
LMP_INC = -DLAMMPS_EXCEPTIONS
.. code-block:: make
LMP_INC = -DLAMMPS_EXCEPTIONS
.. note::

15
doc/src/_ext/tab_or_note.py Normal file
View File

@ -0,0 +1,15 @@
def replace_tabs_handler(app, docname, source):
""" When builder is not 'html', remove 'tabs' directive
and replace any 'tab' directive with 'admonition'"""
if app.builder.name != 'html':
for i in range(len(source)):
source[i] = source[i].replace('.. tabs::','').replace('.. tab::','.. admonition::')
def setup(app):
app.connect('source-read', replace_tabs_handler)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}

1
doc/utils/requirements.txt
View File

@ -1,5 +1,6 @@
Sphinx
sphinxcontrib-spelling
git+https://github.com/akohlmey/sphinx-fortran@parallel-read
sphinx_tabs
breathe
Pygments

2
doc/utils/sphinx-config/conf.py.in
View File

@ -47,7 +47,9 @@ extensions = [
'sphinx.ext.imgmath',
'sphinx.ext.autodoc',
'sphinxfortran.fortran_domain',
'sphinx_tabs.tabs',
'table_from_list',
'tab_or_note',
'breathe',
]
# 2017-12-07: commented out, since this package is broken with Sphinx 16.x

1
doc/utils/sphinx-config/false_positives.txt
View File

@ -3460,6 +3460,7 @@ zz
Zm
PowerShell
filesystems
Zstandard
Zstd
zstd
checksum

25
lib/compress/Makefile.lammps
View File

@ -1,21 +1,24 @@
# This file contains the settings to build and link LAMMPS with
# support for data compression libraries.
#
#
# When you build LAMMPS with the COMPRESS package installed, it will
# use the 3 settings in this file. They should be set as follows.
#
# The compress_SYSLIB setting is for linking the compression library.
# By default, the setting will point to zlib (-lz).
#
# The compress_SYSINC and compress_SYSPATH variables do not typically need
# to be set, as compression libraries are usually installed as packages
# in system locations. Otherwise, specify its directory via the
# compress_SYSPATH variable, e.g. -Ldir or compress_SYSINC variable( -Idir)
#
# The compress_SYSLIB setting is for linking the compression libraries.
# By default, the setting will point to zlib (-lz). For including
# Zstandard support add -DLAMMPS_ZSTD to compress_SYSINC and also
# add -lzstd to compress_SYSLIB to link to the library.
#
# The compress_SYSINC and compress_SYSPATH variables typically do not
# need any additional settings, as compression libraries are usually
# installed as packages in system locations. Otherwise, specify its
# library directory via the compress_SYSPATH variable, e.g. -Ldir or
# its include directory via the compress_SYSINC variable( -Idir)
# -----------------------------------------------------------
# Settings that the LAMMPS build will import when this package is installed
compress_SYSINC =
compress_SYSLIB = -lz
compress_SYSINC = # -DLAMMPS_ZSTD
compress_SYSLIB = -lz # -lzstd
compress_SYSPATH =