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

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

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

standard. A more detailed discussion of that is below.

standard. A more detailed discussion of that is below.

**CMake build**\ :

.. tabs::

   .. tab:: CMake build

      .. code-block:: bash

      .. code-block:: bash

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

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

                                   # no default value

                                   # no default value

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

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

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

      ``lmp`` unless the ``LAMMPS_MACHINE`` option is set.  When setting

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

      ``LAMMPS_MACHINE=name`` the executable will be called

enforce building a serial executable using the MPI STUBS library.

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

      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 serial             # serial build, produces lmp_serial using Makefile/serial

         make mybox              # uses Makefile.mybox to produce lmp_mybox

         make mybox              # uses Makefile.mybox to produce lmp_mybox

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

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

``Makefile.machine`` in the folder ``src/MAKE`` or one of its

      file ``Makefile.machine`` in the folder ``src/MAKE`` or one of its

sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a folder

      sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a

``Obj_machine`` with all objects and generated files and an executable

      folder ``Obj_machine`` with all objects and generated files and an

called ``lmp_machine``\ .  The standard parallel build with ``make mpi``

      executable called ``lmp_machine``\ .  The standard parallel build

assumes a standard MPI installation with MPI compiler wrappers where all

      with ``make mpi`` assumes a standard MPI installation with MPI

necessary compiler and linker flags to get access and link with the

      compiler wrappers where all necessary compiler and linker flags to

suitable MPI headers and libraries are set by the wrapper programs.  For

      get access and link with the suitable MPI headers and libraries

other cases or the serial build, you have to adjust the make file

      are set by the wrapper programs.  For other cases or the serial

variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and

      build, you have to adjust the make file variables ``MPI_INC``,

``LINK``\ .  To enable OpenMP threading usually a compiler specific flag

      ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and ``LINK``\ .  To

needs to be added to the compile and link commands.  For the GNU

      enable OpenMP threading usually a compiler specific flag needs to

compilers, this is ``-fopenmp``\ , which can be added to the ``CC`` and

      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.

      ``LINK`` makefile variables.

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

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

         MPI_PATH =      -L../STUBS

         MPI_PATH =      -L../STUBS

         MPI_LIB =       -lmpi_stubs

         MPI_LIB =       -lmpi_stubs

You also need to build the STUBS library for your platform before making

      You also need to build the STUBS library for your platform before

LAMMPS itself.  A ``make serial`` build does this for you automatically,

      making LAMMPS itself.  A ``make serial`` build does this for you

otherwise, type ``make mpi-stubs`` from the src directory, or ``make``

      automatically, otherwise, type ``make mpi-stubs`` from the src

from the ``src/STUBS`` dir.  If the build fails, you may need to edit

      directory, or ``make`` from the ``src/STUBS`` dir.  If the build

the ``STUBS/Makefile`` for your platform.  The stubs library does not

      fails, you may need to edit the ``STUBS/Makefile`` for your

provide MPI/IO functions required by some LAMMPS packages,

      platform.  The stubs library does not provide MPI/IO functions

e.g. ``MPIIO`` or ``USER-LB``, and thus is not compatible with those

      required by some LAMMPS packages, e.g. ``MPIIO`` or ``USER-LB``,

packages.

      and thus is not compatible with those packages.

      .. note::

      .. note::

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

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

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

         called ``MPI_Wtime()`` that calls ``gettimeofday()``.  If your

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

         operating system does not support ``gettimeofday()``, you will

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

         need to insert code to call another timer.  Note that the

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

         ANSI-standard function ``clock()`` rolls over after an hour or

   timing long LAMMPS simulations.

         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

If you are installing MPI yourself to build a parallel LAMMPS

executable, we recommend either MPICH or OpenMPI which are regularly

executable, we recommend either MPICH or OpenMPI which are regularly

.. _default-none-issues:

.. _default-none-issues:

**OpenMP Compiler compatibility info**\ :

OpenMP Compiler compatibility

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

Some compilers do not fully support the ``default(none)`` directive

Some compilers do not fully support the ``default(none)`` directive and

and others (e.g. GCC version 9 and beyond, Clang version 10 and later)

others (e.g. GCC version 9 and beyond, Clang version 10 and later) may

may implement strict OpenMP 4.0 and later semantics, which are incompatible

implement strict OpenMP 4.0 and later semantics, which are incompatible

with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility

with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility

with compiler versions in use.  If compilation with OpenMP enabled fails

with compiler versions in use.  If compilation with OpenMP enabled fails

because of your compiler requiring strict OpenMP 4.0 semantic, you can

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

change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the

variable in your makefile, or add it to the command line while configuring

``LMP_INC`` variable in your makefile, or add it to the command line

with CMake. CMake will detect the suitable setting for the GNU, Clang,

while configuring with CMake. CMake will detect the suitable setting for

and Intel compilers.

the GNU, Clang, and Intel compilers.

----------

----------

compilers by simply loading the appropriate module before building

compilers by simply loading the appropriate module before building

LAMMPS.

LAMMPS.

**CMake build**\ :

.. tabs::

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

   .. tab:: CMake build

preferences and it will add optimization flags appropriate to that

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

      By default CMake will use the compiler it finds according to

included in the build.

      internal preferences and it will add optimization flags

      appropriate to that compiler and any :doc:`accelerator packages

You can tell CMake to look for a specific compiler with setting CMake

      <Speed_packages>` you have included in the build.  CMake will

variables (listed below) during configuration.  For a few common

      check if the detected or selected compiler is compatible with the

choices, there are also presets in the ``cmake/presets`` folder.  For

      C++ support requirements of LAMMPS and stop with an error, if this

convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to

      is not the case.

apply global compiler options (applied to compilation only), to be used

for adding compiler or host specific optimization flags in addition to

      You can tell CMake to look for a specific compiler with setting

the "flags" variables listed below. You may also specify the

      CMake variables (listed below) during configuration.  For a few

corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to

      common choices, there are also presets in the ``cmake/presets``

experiment with alternate optimization flags.  You should specify all 3

      folder.  For convenience, there is a ``CMAKE_TUNE_FLAGS`` variable

compilers, so that the (few) LAMMPS source files written in C or Fortran

      that can be set to apply global compiler options (applied to

are built with a compiler consistent with the one used for the C++

      compilation only), to be used for adding compiler or host specific

files:

      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

      .. code-block:: bash

         # Building with LLVM/Clang Compilers:

         # Building with LLVM/Clang Compilers:

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

         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

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

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

      provided that can be loaded with

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

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

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

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

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

      .. note::

      .. note::

   When the cmake command completes, it prints a summary to the screen

         When the cmake command completes, it prints a summary to the

   which compilers it is using and what flags and settings will be used

         screen which compilers it is using and what flags and settings

   for the  compilation.  Note that if the top-level compiler is mpicxx,

         will be used for the compilation.  Note that if the top-level

   it is simply a wrapper on a real compiler.  The underlying compiler

         compiler is mpicxx, it is simply a wrapper on a real compiler.

   info is what CMake will try to determine and report.  You should check

         The underlying compiler info is what CMake will try to

   to confirm you are using the compiler and optimization flags you want.

         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

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

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

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

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

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

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

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

variety of settings appropriate for your MPI installation and thus

      include a variety of settings appropriate for your MPI

avoiding the guesswork of finding the right flags.

      installation and thus avoiding the guesswork of finding the right

      flags.

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

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

         LINK =          g++

         LINK =          g++

         LINKFLAGS =     -g -O

         LINKFLAGS =     -g -O

      .. note::

      .. note::

         If compilation stops with a message like the following:

         If compilation stops with a message like the following:

                       from ../main.cpp:16:

                       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.

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

         then you have either an unsupported (old) compiler or you have

   turn on C++11 mode.  The latter applies to GCC 4.8.x shipped with

         to turn on C++11 mode.  The latter applies to GCC 4.8.x shipped

   RHEL 7.x and CentOS 7.x.  For those compilers, you need to add the

         with RHEL 7.x and CentOS 7.x.  For those compilers, you need to

   ``-std=c++11`` flag.  Otherwise, you would have to install a newer

         add the ``-std=c++11`` flag.  Otherwise, you would have to

   compiler that supports C++11; either as a binary package or through

         install a newer compiler that supports C++11; either as a

   compiling from source.

         binary package or through compiling from source.

If you build LAMMPS with any :doc:`Speed_packages` included, there may

         If you build LAMMPS with any :doc:`Speed_packages` included,

be specific compiler or linker flags

         there may be specific compiler or linker flags that are either

that are either required or recommended to enable required features and

         required or recommended to enable required features and to

to achieve optimal performance.  You need to include these in the

         achieve optimal performance.  You need to include these in the

CCFLAGS and LINKFLAGS settings above.  For details, see the individual

         CCFLAGS and LINKFLAGS settings above.  For details, see the

package doc pages listed on the :doc:`Speed_packages`

         individual package doc pages listed on the

page.  Or examine these files in the src/MAKE/OPTIONS directory.

         :doc:`Speed_packages` page.  Or examine these files in the

They correspond to each of the 5 accelerator packages and their hardware

         src/MAKE/OPTIONS directory.  They correspond to each of the 5

variants:

         accelerator packages and their hardware variants:

         .. code-block:: bash

         .. code-block:: bash

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

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

running LAMMPS from Python via its library interface.

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

      For CMake builds, you can select through setting CMake variables

building a shared or a static LAMMPS library and what kind of suffix is

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

added to them (in case you want to concurrently install multiple variants

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

of binaries with different settings). If none are set, defaults are applied.

      install multiple variants of binaries with different settings). If

      none are set, defaults are applied.

      .. code-block:: bash

      .. code-block:: bash

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

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

                                      # no default value

                                      # no default value

The compilation will always produce a LAMMPS library and an executable

      The compilation will always produce a LAMMPS library and an

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

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

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

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

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

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

``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending

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

on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name

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

of the generated libraries will be changed to either

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

``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the

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

executable will be called ``lmp_name``.

      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

      With the traditional makefile based build process, the choice of

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

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

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

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

      The "static" build will generate a static library called

      The "static" build will generate a static library called

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

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

the "shared" build will generate a shared library

      while the "shared" build will generate a shared library

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

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

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

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

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

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

``liblammps_machine.a/so`` files.

      specific ``liblammps_machine.a/so`` files.

CMake and make info

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

Additional information

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

Note that for creating a shared library, all the libraries it depends on

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

must be compiled to be compatible with shared libraries.  This should be

.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html

.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html

.. _sphinx: https://www.sphinx-doc.org

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

The following make commands can be issued in the doc folder of the

LAMMPS source distribution.

LAMMPS source distribution.

   current LAMMPS version (HTML and PDF files), from the website

   current LAMMPS version (HTML and PDF files), from the website

   `download page <https://lammps.sandia.gov/download.html>`_.

   `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

It is also possible to create the HTML version (and only the HTML

the :doc:`CMake build directory <Build_cmake>`.  The reason for this

version) of the manual within the :doc:`CMake build directory

option is to include the installation of the HTML manual pages into

<Build_cmake>`.  The reason for this option is to include the

the "install" step when installing LAMMPS after the CMake build via

installation of the HTML manual pages into the "install" step when

``make install``.  The documentation build is included in the default

installing LAMMPS after the CMake build via ``make install``.  The

build target, but can also be requested independently with ``make doc``.

documentation build is included in the default build target, but can

also be requested independently with ``make doc``.

.. code-block:: bash

.. code-block:: bash

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

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

using CMake or Make.

using CMake or Make.

CMake build

.. tabs::

^^^^^^^^^^^

   .. tab:: CMake build

      .. code-block:: bash

      .. code-block:: bash

      The generated binaries will also become part of the LAMMPS installation

      The generated binaries will also become part of the LAMMPS installation

      (see below).

      (see below).

Traditional make

   .. tab:: Traditional make

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

      .. code-block:: bash

      .. code-block:: bash

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

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

you want to copy files to is protected.

you want to copy files to is protected.

CMake build

.. tabs::

^^^^^^^^^^^

   .. tab:: CMake build

      .. code-block:: bash

      .. code-block:: bash

         make                        # perform make after CMake command

         make                        # perform make after CMake command

         make install                # perform the installation into prefix

         make install                # perform the installation into prefix

Traditional make

   .. tab:: Traditional make

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

There is no "install" option in the ``src/Makefile`` for LAMMPS.  If

      There is no "install" option in the ``src/Makefile`` for LAMMPS.

you wish to do this you will need to first build LAMMPS, then manually

      If you wish to do this you will need to first build LAMMPS, then

copy the desired LAMMPS files to the appropriate system directories.

      manually copy the desired LAMMPS files to the appropriate system

      directories.