Merge pull request #2341 from akohlmey/doc-updates

documentation to find out how to build and link with it.

documentation to find out how to build and link with it.

The majority of OpenMP (threading) support in LAMMPS is provided by the

The majority of OpenMP (threading) support in LAMMPS is provided by the

``USER-OMP`` package; see the :doc:`Speed omp <Speed_omp>` doc page for

``USER-OMP`` package; see the :doc:`Speed_omp`

details. The ``USER-INTEL`` package also includes OpenMP threading (it

page for details. The ``USER-INTEL`` package also includes OpenMP

is compatible with ``USER-OMP`` and will usually fall back on styles

threading (it is compatible with ``USER-OMP`` and will usually fall

from that package, if a ``USER-INTEL`` does not exist) and adds

back on styles from that package, if a ``USER-INTEL`` does not exist)

vectorization support when compiled with compatible compilers, in

and adds vectorization support when compiled with compatible compilers,

particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``

in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``

package can be compiled to include OpenMP threading.

package can be compiled to include OpenMP threading.

In addition, there are a few commands in LAMMPS that have native OpenMP

In addition, there are a few commands in LAMMPS that have native OpenMP

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

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

   compiling from source.

   compiling from source.

If you build LAMMPS with any :doc:`accelerator packages

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

<Speed_packages>` included, there may be specific optimization flags

be specific compiler or linker flags

that are either required or recommended to enable required features and

that are either required or recommended to enable required features and

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

to 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 individual

package doc pages listed on the :doc:`Speed packages <Speed_packages>`

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

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

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

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

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

variants:

variants:

.. _debug:

.. _debug:

Excluding or removing debug support

Including or removing debug support

-----------------------------------

-----------------------------------

By default the compilation settings will include the *-g* flag which

By default the compilation settings will include the *-g* flag which

tool.  The actual translation is then done via make commands.

tool.  The actual translation is then done via make commands.

.. _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://sphinx-doc.org

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

Documentation make option

Documentation make option

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

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

which use different sanitizer libraries to detect problems in the code

which use different sanitizer libraries to detect problems in the code

during run-time. They can detect issues like:

during run-time. They can detect issues like:

 - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_

 - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html#memory-leak-detection>`_

 - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_

 - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_

 - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_

 - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_

Please note that this kind of instrumentation usually comes with a

Please note that this kind of instrumentation usually comes with a

performance hit (but much less than using tools like `Valgrind

performance hit (but much less than using tools like `Valgrind

<https://valgrind.org>`_ with a more low level approach).  The to enable

<https://valgrind.org>`_ with a more low level approach).  To enable

these features additional compiler flags need to be added to the

these features, additional compiler flags need to be added to the

compilation and linking stages.  This is done through setting the

compilation and linking stages.  This is done through setting the

``ENABLE_SANITIZER`` variable during configuration. Examples:

``ENABLE_SANITIZER`` variable during configuration. Examples:

The unit testing facility is integrated into the CMake build process

The unit testing facility is integrated into the CMake build process

of the LAMMPS source code distribution itself.  It can be enabled by

of the LAMMPS source code distribution itself.  It can be enabled by

setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.

setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.

It requires the `YAML <http://pyyaml.org/>`_ library and development

It requires the `PyYAML <http://pyyaml.org/>`_ library and development

headers to compile and will download and compile a recent version of the

headers to compile and will download and compile a recent version of the

`Googletest <https://github.com/google/googletest/>`_ C++ test framework

`Googletest <https://github.com/google/googletest/>`_ C++ test framework

for implementing the tests.

for implementing the tests.

development headers and the curl-config tool.

development headers and the curl-config tool.

If you would like to use the :doc:`kim_property <kim_commands>`

If you would like to use the :doc:`kim_property <kim_commands>`

command, you need to build LAMMPS with the Python 3.6 or later package

command, you need to build LAMMPS with the PYTHON package installed

installed. See the :doc:`Python <python>` doc page for more info on building

and linked to Python 3.6 or later. See the :ref:`PYTHON package build info <python>`

LAMMPS with the version of Python on your system.

for more details on this. After successfully building LAMMPS with Python, you

After successfully building LAMMPS with Python, you need to

also need to install the kim-property Python package, which can be easily done using

install the kim-property Python package, which can be easily done using

*pip* as ``pip install kim-property``, or from the *conda-forge* channel as

*pip* as ``pip install kim-property``, or from the *conda-forge* channel as

``conda install kim-property`` if LAMMPS is built in Conda. More detailed

``conda install kim-property`` if LAMMPS is built in Conda. More detailed

information is available at:

information is available at:

PYTHON package

PYTHON package

---------------------------

---------------------------

Building with the PYTHON package requires you have a Python shared

Building with the PYTHON package requires you have a the Python development

library available on your system, which needs to be a Python 2.7

headers and library available on your system, which needs to be a Python 2.7

version or a Python 3.x version.  See ``lib/python/README`` for more

version or a Python 3.x version.  Since support for Python 2.x has ended,

details.

using Python 3.x is strongly recommended. See ``lib/python/README`` for

additional details.

CMake build

CMake build

^^^^^^^^^^^

^^^^^^^^^^^

Before building LAMMPS with this package, you must first build PLUMED.

Before building LAMMPS with this package, you must first build PLUMED.

PLUMED can be built as part of the LAMMPS build or installed separately

PLUMED can be built as part of the LAMMPS build or installed separately

from LAMMPS using the generic `plumed installation instructions <plumedinstall_>`_.

from LAMMPS using the generic `PLUMED installation instructions <plumedinstall_>`_.

The USER-PLUMED package has been tested to work with Plumed versions

The USER-PLUMED package has been tested to work with Plumed versions

2.4.x, 2.5.x, and 2.6.x and will error out, when trying to run calculations

2.4.x, 2.5.x, and 2.6.x and will error out, when trying to run calculations

with a different version of the Plumed kernel.

with a different version of the Plumed kernel.

build for, either x86 CPUs or Intel KNLs in offload mode.  You should

build for, either x86 CPUs or Intel KNLs in offload mode.  You should

also typically :ref:`install the USER-OMP package <user-omp>`, as it can be

also typically :ref:`install the USER-OMP package <user-omp>`, as it can be

used in tandem with the USER-INTEL package to good effect, as explained

used in tandem with the USER-INTEL package to good effect, as explained

on the :doc:`Speed intel <Speed_intel>` doc page.

on the :doc:`Speed_intel` page.

When using Intel compilers version 16.0 or later is required.  You can

When using Intel compilers version 16.0 or later is required.  You can

also use the GNU or Clang compilers and they will provide performance

also use the GNU or Clang compilers and they will provide performance

LAMMPS is designed as a library of C++ objects that can be

LAMMPS is designed as a library of C++ objects that can be

integrated into other applications including Python scripts.

integrated into other applications including Python scripts.

The files ``src/library.cpp`` and ``src/library.h`` define a

The files ``src/library.cpp`` and ``src/library.h`` define a

C-style API for using LAMMPS as a library.  See the :doc:`Howto

C-style API for using LAMMPS as a library.  See the

library <Howto_library>` page for a description of the interface

:doc:`Howto_library` page

and how to use it for your needs.

for a description of the interface and how to use it for your needs.

The :doc:`Build basics <Build_basics>` doc page explains how to build

The :doc:`Build_basics` page explains how to build

LAMMPS as either a shared or static library.  This results in a file

LAMMPS as either a shared or static library.  This results in a file

in the compilation folder called ``liblammps.a`` or ``liblammps_<name>.a``

in the compilation folder called ``liblammps.a`` or ``liblammps_<name>.a``

in case of building a static library.  In case of a shared library

in case of building a static library.  In case of a shared library

package <Build_package>` doc page.  If a packages requires (provided or

package <Build_package>` doc page.  If a packages requires (provided or

external) libraries, you must configure and build those libraries

external) libraries, you must configure and build those libraries

**before** building LAMMPS itself and especially **before** enabling

**before** building LAMMPS itself and especially **before** enabling

such a package with ``make yes-<package>``.  Building :doc:`LAMMPS with

such a package with ``make yes-<package>``.  :doc:`Building LAMMPS with

CMake <Build_cmake>` can automate much of this for many types of

CMake <Build_cmake>` can automate much of this for many types of

machines, especially workstations, desktops, and laptops, so we suggest

machines, especially workstations, desktops, and laptops, so we suggest

you try it first when building LAMMPS in those cases.

you try it first when building LAMMPS in those cases.