some more typesetting improvements

   -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 :code:`LAMMPS_MACHINE=name`

the executable will be named *lmp_name*\.  Using :code:`BUILD_MPI=no` will

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

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

.. code-block:: bash

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

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

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.

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

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 will 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,

.. note::

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

   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()

<Packages_details>` doc page for more info on these packages and the doc

pages for their respective commands for OpenMP threading info.

For CMake, if you use BUILD_OMP=yes, you can use these packages and

turn on their native OpenMP support and turn on their native OpenMP

support at run time, by setting the OMP_NUM_THREADS environment

For CMake, if you use ``BUILD_OMP=yes``, you can use these packages

and turn on their native OpenMP support and turn on their native OpenMP

support at run time, by setting the ``OMP_NUM_THREADS`` environment

variable before you launch LAMMPS.

For building via conventional make, the CCFLAGS and LINKFLAGS

For building via conventional make, the ``CCFLAGS`` and ``LINKFLAGS``

variables in Makefile.machine need to include the compiler flag that

enables OpenMP. For GNU compilers it is -fopenmp.  For (recent) Intel

compilers it is -qopenmp.  If you are using a different compiler,

enables OpenMP. For GNU compilers it is ``-fopenmp``\ .  For (recent) Intel

compilers it is ``-qopenmp``\ .  If you are using a different compiler,

please refer to its documentation.

.. _default-none-issues:

**OpenMP Compiler compatibility info**\ :

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

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

and others (e.g. GCC version 9 and beyond) may implement OpenMP 4.0

semantics, which are incompatible with the OpenMP 3.1 directives used

semantics, which are incompatible with the OpenMP 3.1 semantics used

in LAMMPS (for maximal compatibility with compiler versions in use).

In those case, all 'default(none)' directives (which aid in detecting

incorrect and unwanted sharing) can be replaced with 'default(shared)'

while dropping all 'shared()' directives. The script

In those case, all ``default(none)`` directives (which aid in detecting

incorrect and unwanted sharing) can be replaced with ``default(shared)``

while dropping all ``shared()`` directives. The script

'src/USER-OMP/hack_openmp_for_pgi_gcc9.sh' can be used to automate

this conversion.

build.

You can tell CMake to look for a specific compiler with these variable

settings.  Likewise you can specify the FLAGS variables if you want to

experiment with alternate optimization flags.  You should specify all

3 compilers, so that the small number of LAMMPS source files written

in C or Fortran are built with a compiler consistent with the one used

for all the C++ files:

settings.  Likewise you can specify the corresponding ``CMAKE_*_FLAGS``

variables if you want to experiment with alternate optimization flags.

You should specify all 3 compilers, so that the small number of LAMMPS

source files written in C or Fortran are built with a compiler consistent

with the one used for all the C++ files:

.. code-block:: bash

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

                                # no default value

Setting BUILD_EXE=no will not produce an executable.  Setting

BUILD_LIB=yes will produce a static library named *liblammps.a*\ .

Setting both BUILD_LIB=yes and BUILD_SHARED_LIBS=yes will produce a

shared library named *liblammps.so* instead. If LAMMPS_LIB_SUFFIX is

set to *name* in addition, the name of the generated libraries will be

changed to either *liblammps_name.a* or *liblammps_name.so*\ ,

respectively.

Setting ``BUILD_EXE=no`` will not produce an executable.  Setting

``BUILD_LIB=yes`` will produce a static library named ``liblammps.a``\ .

Setting both ``BUILD_LIB=yes`` and ``BUILD_SHARED_LIBS=yes`` will produce a

shared library named ``liblammps.so`` instead. If ``LAMMPS_LIB_SUFFIX=name``

is set in addition, the name of the generated libraries will be changed to

either ``liblammps_name.a`` or ``liblammps_name.so``\ , respectively.

**Traditional make**\ :

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=exe" is the default.

Several options are available and ``mode=exe`` is the default.

.. code-block:: bash

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

   make mode=shexe machine    # same as "mode=exe" but uses objects from "mode=shlib"

The two "exe" builds will generate and executable *lmp_machine*\ ,

while the two library builds will create a file *liblammps_machine.a*

or *liblammps_machine.so*\ . They will also create generic soft links,

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

*liblammps_machine.a/so* files.

The two "exe" builds will generate and executable ``lmp_machine``\ ,

while the two library builds will create a file ``liblammps_machine.a``

or ``liblammps_machine.so``\ . They 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**\ :

libraries.  This will be the case for libraries included with LAMMPS,

such as the dummy MPI library in src/STUBS or any package libraries in

the lib/packages directory, since they are always built in a shared

library compatible way using the -fPIC switch.  However, if a library

library compatible way using the ``-fPIC`` switch.  However, if a library

like MPI or FFTW does not exist as a shared library, the shared library

build may generate an error.  This means you will need to install a

shared library version of the auxiliary library.  The build instructions

   make

   make install

You may need to use "sudo make install" in place of the last line if you

do not have write privileges for /usr/local/lib.  The end result should

be the file /usr/local/lib/libmpich.so.  On many Linux installations the

folder "${HOME}/.local" is an alternative to using /usr/local and does

You may need to use ``sudo make install`` in place of the last line if you

do not have write privileges for ``/usr/local/lib``.  The end result should

be the file ``/usr/local/lib/libmpich.so``.  On many Linux installations the

folder ``${HOME}/.local`` is an alternative to using ``/usr/local`` and does

not require superuser or sudo access.  In that case the configuration

step becomes:

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

``make install``.

.. code-block:: bash

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

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.

**Traditional make**\ :

Before building LAMMPS, you must build the GPU library in lib/gpu.

Before building LAMMPS, you must build the GPU library in ``lib/gpu``\ .

You can do this manually if you prefer; follow the instructions in

lib/gpu/README.  Note that the GPU library uses MPI calls, so you must

``lib/gpu/README``.  Note that the GPU library uses MPI calls, so you must

use the same MPI library (or the STUBS library) settings as the main

LAMMPS code.  This also applies to the -DLAMMPS_BIGBIG,

-DLAMMPS_SMALLBIG, or -DLAMMPS_SMALLSMALL settings in whichever

LAMMPS code.  This also applies to the ``-DLAMMPS_BIGBIG``\ ,

``-DLAMMPS_SMALLBIG``\ , or ``-DLAMMPS_SMALLSMALL`` settings in whichever

Makefile you use.

You can also build the library in one step from the lammps/src dir,

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

You can also build the library in one step from the ``lammps/src`` dir,

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

script with the specified args:

.. code-block:: bash

switches (as in the examples above), and also save a copy of the new

Makefile if desired:

* CUDA_HOME = where NVIDIA CUDA software is installed on your system

* CUDA_ARCH = sm_XX, what GPU hardware you have, same as CMake GPU_ARCH above

* CUDA_PRECISION = precision (double, mixed, single)

* EXTRAMAKE = which Makefile.lammps.\* file to copy to Makefile.lammps

* ``CUDA_HOME`` = where NVIDIA CUDA software is installed on your system

* ``CUDA_ARCH`` = sm_XX, what GPU hardware you have, same as CMake GPU_ARCH above

* ``CUDA_PRECISION`` = precision (double, mixed, single)

* ``EXTRAMAKE`` = which Makefile.lammps.\* file to copy to Makefile.lammps

The file Makefile.linux_multi is set up to include support for multiple

GPU architectures as supported by the CUDA toolkit in use. This is done

thus support all GPU architectures supported by your CUDA compiler.

If the library build is successful, 3 files should be created:

lib/gpu/libgpu.a, lib/gpu/nvc_get_devices, and

lib/gpu/Makefile.lammps.  The latter has settings that enable LAMMPS

to link with CUDA libraries.  If the settings in Makefile.lammps for

``lib/gpu/libgpu.a``\ , ``lib/gpu/nvc_get_devices``\ , and

``lib/gpu/Makefile.lammps``\ .  The latter has settings that enable LAMMPS

to link with CUDA libraries.  If the settings in ``Makefile.lammps`` for

your machine are not correct, the LAMMPS build will fail, and

lib/gpu/Makefile.lammps may need to be edited.

``lib/gpu/Makefile.lammps`` may need to be edited.

.. note::

   -D LMP_DEBUG_CURL=value         # set libcurl verbose mode on/off, value = off (default) or on

   -D LMP_NO_SSL_CHECK=value       # tell libcurl to not verify the peer, value = no (default) or yes

If DOWNLOAD_KIM is set, the KIM library will be downloaded and built

If ``DOWNLOAD_KIM`` is set, the KIM library will be downloaded and built

inside the CMake build directory.  If the KIM library is already on

your system (in a location CMake cannot find it), set the PKG_CONFIG_PATH

your system (in a location CMake cannot find it), set the ``PKG_CONFIG_PATH``

environment variable so that libkim-api can be found.

*For using OpenKIM web queries in LAMMPS*\ :

If LMP_DEBUG_CURL is set, the libcurl verbose mode will be on, and any

libcurl calls within the KIM web query display a lot of information about

libcurl operations. You hardly ever want this set in production use, you will

almost always want this when you debug/report problems.

If the ``LMP_DEBUG_CURL`` environment variable is set, the libcurl verbose

mode will be on, and any libcurl calls within the KIM web query display a

lot of information about libcurl operations.  You hardly ever want this

set in production use, you will almost always want this when you debug or

report problems.

The libcurl performs peer SSL certificate verification by default. This

verification is done using a CA certificate store that the SSL library can

use to make sure the peer's server certificate is valid. If SSL reports an

error ("certificate verify failed") during the handshake and thus refuses

further communication with that server, you can set LMP_NO_SSL_CHECK.

If LMP_NO_SSL_CHECK is set, libcurl does not verify the peer and connection

further communication with that server, you can set ``LMP_NO_SSL_CHECK``\ .

If ``LMP_NO_SSL_CHECK`` is set, libcurl does not verify the peer and connection

succeeds regardless of the names in the certificate. This option is insecure.

As an alternative, you can specify your own CA cert path by setting the

environment variable CURL_CA_BUNDLE to the path of your choice. A call to the

KIM web query would get this value from the environmental variable.

environment variable ``CURL_CA_BUNDLE`` to the path of your choice. A call

to the KIM web query would get this value from the environmental variable.

**Traditional make**\ :

You can download and build the KIM library manually if you prefer;

follow the instructions in lib/kim/README.  You can also do it in one

follow the instructions in ``lib/kim/README``\ .  You can also do it in one

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

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

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

.. code-block:: bash

  $ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver

Settings for OpenKIM web queries discussed above need to be applied by adding

them to the LMP_INC variable through editing the Makefile.machine you are

them to the ``LMP_INC`` variable through editing the Makefile.machine you are

using.  For example:

.. code-block:: make

or GPUs (NVIDIA Cuda).

For a CMake or make build, these are the possible choices for the

KOKKOS_ARCH settings described below.  Note that for CMake, these are

``KOKKOS_ARCH`` settings described below.  Note that for CMake, these are

really Kokkos variables, not LAMMPS variables.  Hence you must use

case-sensitive values, e.g. BDW, not bdw.

   -D CMAKE_CXX_COMPILER=wrapper      # wrapper = full path to Cuda nvcc wrapper

The wrapper value is the Cuda nvcc compiler wrapper provided in the

Kokkos library: lib/kokkos/bin/nvcc_wrapper.  The setting should

Kokkos library: ``lib/kokkos/bin/nvcc_wrapper``\ .  The setting should

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

.. code-block:: bash

**Traditional make**\ :

Choose which hardware to support in Makefile.machine via

KOKKOS_DEVICES and KOKKOS_ARCH settings.  See the

src/MAKE/OPTIONS/Makefile.kokkos\* files for examples.

Choose which hardware to support in ``Makefile.machine`` via

``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings.  See the

``src/MAKE/OPTIONS/Makefile.kokkos\*`` files for examples.

For multicore CPUs using OpenMP:

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

   -D LATTE_LIBRARY=path      # LATTE library file (only needed if a custom location)

If DOWNLOAD_LATTE is set, the LATTE library will be downloaded and

If ``DOWNLOAD_LATTE`` is set, the LATTE library will be downloaded and

built inside the CMake build directory.  If the LATTE library is

already on your system (in a location CMake cannot find it),

LATTE_LIBRARY is the filename (plus path) of the LATTE library file,

``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library file,

not the directory the library file is in.

**Traditional make**\ :

You can download and build the LATTE library manually if you prefer;

follow the instructions in lib/latte/README.  You can also do it in

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

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

follow the instructions in ``lib/latte/README``\ .  You can also do it in

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

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

args:

.. code-block:: bash

**Traditional make**\ :

Before building LAMMPS, you must build the CSlib library in

lib/message.  You can build the CSlib library manually if you prefer;

follow the instructions in lib/message/README.  You can also do it in

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:

``lib/message``\ .  You can build the CSlib library manually if you prefer;

follow the instructions in ``lib/message/README``\ .  You can also do it in

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 args="-m -z"  # build with MPI and socket (ZMQ) support

  $ make lib-message args="-s"     # build as serial lib with no ZMQ support

The build should produce two files: lib/message/cslib/src/libmessage.a

and lib/message/Makefile.lammps.  The latter is copied from an

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

The build should produce two files: ``lib/message/cslib/src/libmessage.a``

and ``lib/message/Makefile.lammps``\ .  The latter is copied from an

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

library if requested in the build.

----------

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

To build with this package, you must download and build the MS-CG

library.  Building the MS-CG library and using it from LAMMPS requires

a C++11 compatible compiler and that the GSL (GNU Scientific Library)

headers and libraries are installed on your machine.  See the

lib/mscg/README and MSCG/Install files for more details.

library.  Building the MS-CG library requires that the GSL

(GNU Scientific Library) headers and libraries are installed on your

machine.  See the ``lib/mscg/README`` and ``MSCG/Install`` files for

more details.

**CMake build**\ :

   -D MSCG_LIBRARY=path      # MSCG library file (only needed if a custom location)

   -D MSCG_INCLUDE_DIR=path  # MSCG include directory (only needed if a custom location)

If DOWNLOAD_MSCG is set, the MSCG library will be downloaded and built

If ``DOWNLOAD_MSCG`` is set, the MSCG library will be downloaded and built

inside the CMake build directory.  If the MSCG library is already on

your system (in a location CMake cannot find it), MSCG_LIBRARY is the

your system (in a location CMake cannot find it), ``MSCG_LIBRARY`` is the

filename (plus path) of the MSCG library file, not the directory the

library file is in.  MSCG_INCLUDE_DIR is the directory the MSCG

library file is in.  ``MSCG_INCLUDE_DIR`` is the directory the MSCG

include file is in.

**Traditional make**\ :

You can download and build the MS-CG library manually if you prefer;

follow the instructions in lib/mscg/README.  You can also do it in one

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

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

follow the instructions in ``lib/mscg/README``\ .  You can also do it in one

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 args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release

Note that 2 symbolic (soft) links, "includelink" and "liblink", will

be created in lib/mscg to point to the MS-CG src/installation dir.

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

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

be created in ``lib/mscg`` to point to the MS-CG ``src/installation``

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

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

----------

**CMake build**\ :

No additional settings are needed besides "-D PKG_OPT=yes".

No additional settings are needed besides ``-D PKG_OPT=yes``

**Traditional make**\ :

**CMake build**\ :

No additional settings are needed besides "-D PKG_OPT=yes".

No additional settings are needed besides ``-D PKG_OPT=yes``

**Traditional make**\ :

Before building LAMMPS, you must build the POEMS library in lib/poems.

Before building LAMMPS, you must build the POEMS library in ``lib/poems``\ .

You can do this manually if you prefer; follow the instructions in

lib/poems/README.  You can also do it in one step from the lammps/src

``lib/poems/README``\ .  You can also do it in one step from the ``lammps/src``

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

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

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

.. code-block:: bash

  $ make lib-poems args="-m mpi"     # build with default MPI C++ compiler (settings as with "make mpi")

  $ make lib-poems args="-m icc"     # build with Intel icc compiler

The build should produce two files: lib/poems/libpoems.a and

lib/poems/Makefile.lammps.  The latter is copied from an existing

Makefile.lammps.\* and has settings needed to build LAMMPS with the

The build should produce two files: ``lib/poems/libpoems.a`` and

``lib/poems/Makefile.lammps``\ .  The latter is copied from an existing

``Makefile.lammps.\*`` and has settings needed to build LAMMPS with the

POEMS library (though typically the settings are just blank).  If

necessary, you can edit/create a new lib/poems/Makefile.machine file

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

a corresponding Makefile.lammps.machine file.

necessary, you can edit/create a new ``lib/poems/Makefile.machine`` file

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

a corresponding ``Makefile.lammps.machine`` file.

----------

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

Building with the PYTHON package requires you have a Python shared

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

version, 2.6 or later.  Python 3 is not yet supported.  See

lib/python/README for more details.

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

details.

**CMake build**\ :

**Traditional make**\ :

The build uses the lib/python/Makefile.lammps file in the compile/link

The build uses the ``lib/python/Makefile.lammps`` file in the compile/link

process to find Python.  You should only need to create a new

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

build fails.

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

the LAMMPS build fails.

----------

GitHub.  For people still using subversion (svn), GitHub also

provides `limited support for subversion clients <svn_>`_.

.. warning::

.. note::

   As of October 2016, the official home of public LAMMPS development is

   on GitHub.  The previously advertised LAMMPS git repositories on