collapse multiple empty lines into a single empty line

alternative you can download a package with pre-built executables

as described on the :doc:`Install <Install>` doc page.

.. toctree::

   :maxdepth: 1

* :ref:`Build the LAMMPS documentation <doc>`

* :ref:`Install LAMMPS after a build <install>`

----------

.. _serial:

Serial vs parallel build

   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, create a folder Obj\_machine with all objects and

generated files and an executable called *lmp\_machine*\ .  The standard

'src/USER-OMP/hack\_openmp\_for\_pgi\_gcc9.sh' can be used to automate

this conversion.

----------

.. _compile:

Choice of compiler and compile/link options

   -D CMAKE_C_FLAGS=string               # flags to use with C compiler

   -D CMAKE_Fortran_FLAGS=string         # flags to use with Fortran compiler

A few example command lines are:

.. code-block:: bash

shared library version of the auxiliary library.  The build instructions

for the library should tell you how to do this.

As an example, here is how to build and install the `MPICH library

<mpich_>`_, a popular open-source version of MPI, as a shared library

in the default /usr/local/lib location:

----------

.. _doc:

Build the LAMMPS documentation

  make package_check # check for complete and consistent package lists

  make spelling      # spell-check the manual

Thus "make html" will create a "doc/html" directory with the HTML format

manual pages so that you can browse them with a web browser locally on

your system.

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

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

**CMake build option**\ :

It is also possible to create the HTML version of the manual within

   -D BUILD_DOC=value       # yes or no (default)

----------

.. _tools:

Build LAMMPS tools

**CMake build3**\ :

.. code-block:: bash

   -D BUILD_TOOLS=value       # yes or no (default)

**Traditional make**\ :

.. code-block:: bash

   cd lammps/tools

   make micelle2d        # build only micelle2d tool

   make thermo_extract   # build only thermo_extract tool

----------

.. _install:

Install LAMMPS after a build

**CMake build**\ :

.. code-block:: bash

   cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake

for how to use CMake to build LAMMPS.  If you are new to CMake it is a

good place to start.

----------

Building LAMMPS with CMake is a two-step process.  First you use CMake

to create a build environment in a new directory.  On Linux systems,

this will be based on makefiles for use with make.  Then you use the

make command to build LAMMPS, which uses the created

Makefile(s). Example:

.. code-block:: bash

   cd lammps                        # change to the LAMMPS distribution directory

After compilation, you may optionally install the LAMMPS executable into

your system with:

.. code-block:: bash

   make install    # optional, copy LAMMPS executable & library elsewhere

tree is set by the CMake variable "CMAKE\_INSTALL\_PREFIX" which defaults

to ${HOME}/.local

----------

There are 3 variants of CMake: a command-line version (cmake), a text mode

UI version (ccmake), and a graphical GUI version (cmake-GUI).  You can use

any of them interchangeably to configure and create the LAMMPS build

various options; see details below.  Or you can remove the entire build

folder, recreate the directory and start over.

----------

**Command-line version of CMake**\ :

.. code-block:: bash

   cmake [options ...] /path/to/lammps/cmake  # build from any dir

The argument can be preceeded or followed by various CMake

command-line options.  Several useful ones are:

.. code-block:: bash

   -D CMAKE_INSTALL_PREFIX=path  # where to install LAMMPS executable/lib if desired

files/directories in the build directory, or start with a fresh build

directory.

----------

**Curses version (terminal-style menu) of CMake**\ :

.. code-block:: bash

   ccmake ../cmake

in between.  Please see the `ccmake manual <https://cmake.org/cmake/help/latest/manual/ccmake.1.html>`_ for

more information.

----------

**GUI version of CMake**\ :

.. code-block:: bash

   cmake-gui ../cmake

Please see the `cmake-gui manual <https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html>`_

for more information.

----------

**Installing CMake**

Check if your machine already has CMake installed:

.. code-block:: bash

   which cmake             # do you have it?

On clusters or supercomputers which use environment modules to manage

software packages, do this:

.. code-block:: bash

   module list            # is a module for cmake already loaded?

The CMake build of LAMMPS has a few extra options which are useful during

development,  testing or debugging.

----------

.. _compilation:

Verify compilation flags

generated by the CMake build. To enable a more verbose output during

compilation you can use the following option.

.. code-block:: bash

   -D CMAKE_VERBOSE_MAKEFILE=value    # value = no (default) or yes

Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:

.. code-block:: bash

   make VERBOSE=1

----------

.. _sanitizer:

Address, Undefined Behavior, and Thread Sanitizer Support

it. Please note that they come with a performance hit. However, they are

usually faster than using tools like Valgrind.

.. code-block:: bash

   -D ENABLE_SANITIZE_ADDRESS=value    # enable Address Sanitizer, value = no (default) or yes

   -D ENABLE_SANITIZE_UNDEFINED=value  # enable Undefined Behaviour Sanitizer, value = no (default) or yes

   -D ENABLE_SANITIZE_THREAD=value     # enable Thread Sanitizer, value = no (default) or yes

----------

.. _testing:

Code Coverage and Testing

   this is incomplete and only represents a small subset of tests that we run

.. code-block:: bash

   -D ENABLE_TESTING=value               # enable simple run tests of LAMMPS, value = no (default) or yes

If you enable testing in the CMake build it will create an additional target called "test". You can run them with:

.. code-block:: bash

   make test

You can also collect code coverage metrics while running the tests by enabling

coverage support during building.

.. code-block:: bash

   -D ENABLE_COVERAGE=value  # enable coverage measurements, value = no (default) or yes

This will also add the following targets to generate coverage reports after running the LAMMPS executable:

.. code-block:: bash

   make test               # run tests first!

These reports require GCOVR to be installed. The easiest way to do this to install it via pip:

.. code-block:: bash

   pip install git+https://github.com/gcovr/gcovr.git

When building with some packages, additional steps may be required,

in addition to:

.. code-block:: bash

   $ cmake -D PKG_NAME=yes

----------

.. _compress:

COMPRESS package

If CMake cannot find the library, you can set these variables:

.. code-block:: bash

   -D ZLIB_INCLUDE_DIR=path    # path to zlib.h header file

lib/compress/Makefile.lammps to specify the paths and library

name.

----------

.. _gpu:

GPU package

**CMake build**\ :

.. code-block:: bash

   -D GPU_API=value          # value = opencl (default) or cuda

using a command like these, which simply invoke the lib/gpu/Install.py

script with the specified args:

.. code-block:: bash

  $ make lib-gpu               # print help message

   package uses the library settings from the lib/gpu/Makefile.machine

   used to build the GPU library.

----------

.. _kim:

KIM package

**CMake build**\ :

.. code-block:: bash

   -D DOWNLOAD_KIM=value           # download OpenKIM API v2 for build, value = no (default) or yes

step from the lammps/src dir, using a command like these, which simply

invoke the lib/kim/Install.py script with the specified args.

.. code-block:: bash

  $ make lib-kim              # print help message

----------

.. _kokkos:

KOKKOS package

For multicore CPUs using OpenMP, set these 2 variables.

.. code-block:: bash

   -D KOKKOS_ARCH=archCPU         # archCPU = CPU from list above

For Intel KNLs using OpenMP, set these 2 variables:

.. code-block:: bash

   -D KOKKOS_ARCH=KNL

For NVIDIA GPUs using CUDA, set these 4 variables:

.. code-block:: bash

   -D KOKKOS_ARCH="archCPU;archGPU"   # archCPU = CPU from list above that is hosting the GPU

Kokkos library: lib/kokkos/bin/nvcc\_wrapper.  The setting should

include the full path name to the wrapper, e.g.

.. code-block:: bash

   -D CMAKE_CXX_COMPILER=/home/username/lammps/lib/kokkos/bin/nvcc_wrapper

For multicore CPUs using OpenMP:

.. code-block:: make

   KOKKOS_DEVICES = OpenMP

For Intel KNLs using OpenMP:

.. code-block:: make

   KOKKOS_DEVICES = OpenMP

For NVIDIA GPUs using CUDA:

.. code-block:: make

   KOKKOS_DEVICES = Cuda

compiling CUDA files and use a C++ compiler for non-Kokkos, non-CUDA

files.

.. code-block:: make

   KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)

   export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper

   CC =            mpicxx

----------

.. _latte:

LATTE package

**CMake build**\ :

.. code-block:: bash

   -D DOWNLOAD_LATTE=value    # download LATTE for build, value = no (default) or yes

simply invokes the lib/latte/Install.py script with the specified

args:

.. code-block:: bash

  $ make lib-latte                          # print help message

also check that the Makefile.lammps file you create is appropriate for

the compiler you use on your system to build LATTE.

----------

.. _message:

MESSAGE package

**CMake build**\ :

.. code-block:: bash

   -D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes

one step from the lammps/src dir, using a command like these, which

simply invoke the lib/message/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-message               # print help message

existing Makefile.lammps.\* and has settings to link with the ZeroMQ

library if requested in the build.

----------

.. _mscg:

MSCG package

**CMake build**\ :

.. code-block:: bash

   -D DOWNLOAD_MSCG=value    # download MSCG for build, value = no (default) or yes

step from the lammps/src dir, using a command like these, which simply

invoke the lib/mscg/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-mscg             # print help message

When LAMMPS is built in src it will use these links.  You should not

need to edit the lib/mscg/Makefile.lammps file.

----------

.. _opt:

OPT package

line of your Makefile.machine.  See src/MAKE/OPTIONS/Makefile.opt for

an example.

----------

.. _poems:

POEMS package

dir, using a command like these, which simply invoke the

lib/poems/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-poems                   # print help message

for your system, which should define an EXTRAMAKE variable to specify

a corresponding Makefile.lammps.machine file.

----------

.. _python:

PYTHON package

**CMake build**\ :

.. code-block:: bash

   -D PYTHON_EXECUTABLE=path   # path to Python executable to use

Makefile.lammps.\* file (and copy it to Makefile.lammps) if the LAMMPS

build fails.

----------

.. _voronoi:

VORONOI package

.. _voro-home: http://math.lbl.gov/voro++

**CMake build**\ :

.. code-block:: bash

   -D DOWNLOAD_VORO=value    # download Voro++ for build, value = no (default) or yes

simply invoke the lib/voronoi/Install.py script with the specified

args:

.. code-block:: bash

  $ make lib-voronoi                          # print help message

builds in src it will use these links.  You should not need to edit

the lib/voronoi/Makefile.lammps file.

----------

.. _user-adios:

USER-ADIOS package

**CMake build**\ :

.. code-block:: bash

   -D ADIOS2_DIR=path        # path is where ADIOS 2.x is installed

Turn on the USER-ADIOS package before building LAMMPS. If the ADIOS 2.x software is installed in PATH, there is nothing else to do:

.. code-block:: bash

  $ make yes-user-adios

otherwise, set ADIOS2\_DIR environment variable when turning on the package:

.. code-block:: bash

  $ ADIOS2_DIR=path make yes-user-adios   # path is where ADIOS 2.x is installed

----------

.. _user-atc:

USER-ATC package

dir, using a command like these, which simply invoke the

lib/atc/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-atc                      # print help message

lib/linalg.  In the latter case you also need to build the library in

lib/linalg with a command like these:

.. code-block:: bash

  $ make lib-linalg                     # print help message

  $ make lib-linalg args="-m mpi"       # build with default MPI Fortran compiler (settings as with "make mpi")

  $ make lib-linalg args="-m gfortran"  # build with GNU Fortran compiler

----------

.. _user-awpmd:

USER-AWPMD package

dir, using a command like these, which simply invoke the

lib/awpmd/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-awpmd                   # print help message

provided in lib/linalg.  In the latter case you also need to build the

library in lib/linalg with a command like these:

.. code-block:: bash

  $ make lib-linalg                     # print help message

  $ make lib-linalg args="-m mpi"       # build with default MPI Fortran compiler (settings as with "make mpi")

  $ make lib-linalg args="-m gfortran"  # build with GNU Fortran compiler

----------

.. _user-colvars:

USER-COLVARS package

command like these, which simply invoke the lib/colvars/Install.py script with

the specified args:

.. code-block:: bash

  $ make lib-colvars                      # print help message

lib/colvars/Makefile.lammps.  The latter is auto-generated, and normally does

not need to be edited.

----------

.. _user-plumed:

USER-PLUMED package

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.

PLUMED can be linked into MD codes in three different modes: static,

shared, and runtime.  With the "static" mode, all the code that PLUMED

requires is linked statically into LAMMPS. LAMMPS is then fully

your environment.  There are then two additional commands that control

the manner in which PLUMED is obtained and linked into LAMMPS.

.. code-block:: bash

   -D DOWNLOAD_PLUMED=value   # download PLUMED for build, value = no (default) or yes

Download/compilation/configuration of the plumed library can be done

from the src folder through the following make args:

.. code-block:: bash

  $ make lib-plumed                         # print help message

mode. After this step is completed, you can install the USER-PLUMED

package and compile LAMMPS in the usual manner:

.. code-block:: bash

  $ make yes-user-plumed

USER-PLUMED package with "make yes-user-plumed" to update the required

makefile settings with the changes in the lib/plumed folder.

----------

.. _user-h5md:

USER-H5MD package

dir, using a command like these, which simply invoke the

lib/h5md/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-h5md                     # print help message

EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine

file.

----------

.. _user-intel:

USER-INTEL package

**CMake build**\ :

.. code-block:: bash

   -D INTEL_ARCH=value     # value = cpu (default) or knl

For CPUs:

.. code-block:: make

   OPTFLAGS =      -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high

For KNLs:

.. code-block:: make

   OPTFLAGS =      -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits

   LINKFLAGS =     -g -qopenmp $(OPTFLAGS)

   LIB =           -ltbbmalloc

----------

.. _user-molfile:

USER-MOLFILE package

**CMake build**\ :

.. code-block:: bash

   -D MOLFILE_INCLUDE_DIRS=path   # (optional) path where VMD molfile plugin headers are installed

so it is often best to change this setting to the location of the

same include files of the local VMD installation in use.

----------

.. _user-netcdf:

USER-NETCDF package

the settings are not valid for your system, you will need to edit the

Makefile.lammps file.  See lib/netcdf/README for details.

----------

.. _user-omp:

USER-OMP package

be added to your Makefile.machine file.

See src/MAKE/OPTIONS/Makefile.omp for an example.

.. parsed-literal::

   CCFLAGS: -fopenmp               # for GNU and Clang Compilers

about OpenMP support for your compiler. Please see the note about

how to address compatibility :ref:`issues with the 'default(none)' directive <default-none-issues>` of some compilers.

----------

.. _user-qmmm:

USER-QMMM package

README file to build the combined LAMMPS/QE QM/MM executable

(pwqmmm.x) in the lib/qmmm folder.  You need to make certain, that

**Traditional make**\ :

Before building LAMMPS, you must build the QMMM library in lib/qmmm.

lammps/src dir, using a command like these, which simply invoke the

lib/qmmm/Install.py script with the specified args:

.. code-block:: bash

  $ make lib-qmmm                      # print help message

----------

.. _user-quip:

USER-QUIP package

**CMake build**\ :