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

using the `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_ threading

standard. A more detailed discussion of that is below.

**CMake build**\ :

.. tabs::

   .. tab:: CMake build

      .. code-block:: bash

         -D LAMMPS_MACHINE=name    # name = mpi, serial, mybox, titan, laptop, etc

                                   # no default value

The executable created by CMake (after running make) is named ``lmp`` unless

the ``LAMMPS_MACHINE`` option is set.  When setting ``LAMMPS_MACHINE=name``

the executable will be called ``lmp_name``.  Using ``BUILD_MPI=no`` will

enforce building a serial executable using the MPI STUBS library.

      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.

**Traditional make**\ :

   .. tab:: Traditional make

      The build with traditional makefiles has to be done inside the source folder ``src``.

         make serial             # serial build, produces lmp_serial using Makefile/serial

         make mybox              # uses Makefile.mybox to produce lmp_mybox

Any ``make machine`` command will look up the make settings from a file

``Makefile.machine`` 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

      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.

      For the serial build the following make variables are set (see src/MAKE/Makefile.serial):

         MPI_PATH =      -L../STUBS

         MPI_LIB =       -lmpi_stubs

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.

      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.

      .. note::

   The file ``src/STUBS/mpi.c`` provides a CPU timer function called

   ``MPI_Wtime()`` that calls ``gettimeofday()``.  If your operating system

   does not support ``gettimeofday()``, you will need to insert code to

   call another timer.  Note that the ANSI-standard function ``clock()``

   rolls over after an hour or so, and is therefore insufficient for

   timing long LAMMPS simulations.

         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 info**\ :

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

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

----------

compilers by simply loading the appropriate module before building

LAMMPS.

**CMake build**\ :

By default CMake will use a compiler it finds according to internal

preferences and it will add optimization flags appropriate to that

compiler and any :doc:`accelerator packages <Speed_packages>` you have

included in the build.

You can tell CMake to look for a specific compiler with 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:

.. tabs::

   .. tab:: CMake build

      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.

      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:

      .. code-block:: bash

         # Building with LLVM/Clang Compilers:

         cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang

For compiling with the Clang/LLVM compilers a CMake preset is provided that

can be loaded with `-C ../cmake/presets/clang.cmake`.  Similarly,

`-C ../cmake/presets/intel.cmake` should switch the

      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.

      In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add

      compiler flags to tune for optimal performance on given hosts. By

      .. note::

   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.

         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.

**Makefile.machine settings for traditional make**\ :

   .. tab:: Makefile.machine settings for traditional make

      The "compiler/linker settings" section of a Makefile.machine lists

      compiler and linker settings for your C++ compiler, including

      optimization flags.  For a parallel build it is recommended to use

``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a

variety of settings appropriate for your MPI installation and thus

avoiding the guesswork of finding the right flags.

      ``mpicxx`` or ``mpiCC``, since these compiler wrappers will

      include a variety of settings appropriate for your MPI

      installation and thus avoiding the guesswork of finding the right

      flags.

      Parallel build (see ``src/MAKE/Makefile.mpi``):

         LINK =          g++

         LINKFLAGS =     -g -O

      .. note::

         If compilation stops with a message like the following:

                       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.

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:

         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:

         .. code-block:: bash

:doc:`Python <Python_head>` doc page for more info on wrapping and

running LAMMPS from Python via its library interface.

**CMake build**\ :

.. tabs::

   .. tab:: CMake build

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.

      For CMake builds, you can select through setting CMake variables

      between building a shared or a static LAMMPS library and what kind

      of suffix is added to them (in case you want to concurrently

      install multiple variants of binaries with different settings). If

      none are set, defaults are applied.

      .. code-block:: bash

         -D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc

                                      # no default value

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

      The compilation will always produce a LAMMPS library and an

      executable linked to it.  By default this will be a static library

      named ``liblammps.a`` and an executable named ``lmp`` Setting

      ``BUILD_SHARED_LIBS=yes`` will instead produce a shared library

      called ``liblammps.so`` (or ``liblammps.dylib`` or

      ``liblammps.dll`` depending on the platform) If

      ``LAMMPS_MACHINE=name`` is set in addition, the name of the

      generated libraries will be changed to either ``liblammps_name.a``

      or ``liblammps_name.so``\ , respectively and the executable will

      be called ``lmp_name``.

**Traditional make**\ :

   .. tab:: Traditional make

      With the traditional makefile based build process, the choice of

      the generated executable or library depends on the "mode" setting.

         make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead

      The "static" build will generate a static library called

``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while

the "shared" build will generate a shared library

``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to

it.  The build step will also create generic soft links, named

``liblammps.a`` and ``liblammps.so``\ , which point to the specific

``liblammps_machine.a/so`` files.

CMake and make info

^^^^^^^^^^^^^^^^^^^

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

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

   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

Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly

using CMake or Make.

CMake build

^^^^^^^^^^^

.. tabs::

   .. tab:: CMake build

      .. code-block:: bash

      The generated binaries will also become part of the LAMMPS installation

      (see below).

Traditional make

^^^^^^^^^^^^^^^^

   .. tab:: Traditional make

      .. code-block:: bash

that you may need super-user privileges (e.g. sudo) if the directory

you want to copy files to is protected.

CMake build

^^^^^^^^^^^

.. tabs::

   .. tab:: CMake build

      .. code-block:: bash

         make                        # perform make after CMake command

         make install                # perform the installation into prefix

Traditional make

^^^^^^^^^^^^^^^^

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

      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.