3.7. Packages with extra build options

When building with some packages, additional steps may be required, in addition to

CMake build

Traditional make

$ cmake -D PKG_NAME=yes
$ make yes-name

as described on the Build_package page.

For a CMake build there may be additional optional or required variables to set. For a build with make, a provided library under the lammps/lib directory may need to be built first. Or an external library may need to exist on your system or be downloaded and built. You may need to tell LAMMPS where it is found on your system.

This is the list of packages that may require additional steps.

COMPRESS

GPU

KIM

KOKKOS

LATTE

MESSAGE

MLIAP

MSCG

OPT

POEMS

PYTHON

VORONOI

USER-ADIOS

USER-ATC

USER-AWPMD

USER-COLVARS

USER-H5MD

USER-HDNNP

USER-INTEL

USER-MDI

USER-MESONT

USER-MOLFILE

USER-NETCDF

USER-PACE

USER-PLUMED

USER-OMP

USER-QMMM

USER-QUIP

USER-SCAFACOS

USER-SMD

USER-VTK


3.7.1. COMPRESS package

To build with this package you must have the zlib compression library available on your system to build dump styles with a ‘/gz’ suffix. There are also styles using the Zstandard library which have a ‘/zstd’ suffix.

If CMake cannot find the zlib library or include files, you can set these variables:

-D ZLIB_INCLUDE_DIR=path    # path to zlib.h header file
-D ZLIB_LIBRARY=path        # path to libz.a (.so) file

Support for Zstandard compression is auto-detected and for that CMake depends on the pkg-config tool to identify the necessary flags to compile with this library, so the corresponding libzstandard.pc file must be in a folder where pkg-config can find it, which may require adding it to the PKG_CONFIG_PATH environment variable.


3.7.2. GPU package

To build with this package, you must choose options for precision and which GPU hardware to build for. The GPU package currently supports three different types of backends: OpenCL, CUDA and HIP.

CMake build

-D GPU_API=value             # value = opencl (default) or cuda or hip
-D GPU_PREC=value            # precision setting
                             # value = double or mixed (default) or single
-D GPU_ARCH=value            # primary GPU hardware choice for GPU_API=cuda
                             # value = sm_XX, see below
                             # default is sm_50
-D HIP_ARCH=value            # primary GPU hardware choice for GPU_API=hip
                             # value depends on selected HIP_PLATFORM
                             # default is 'gfx906' for HIP_PLATFORM=amd and 'sm_50' for HIP_PLATFORM=nvcc
-D HIP_USE_DEVICE_SORT=value # enables GPU sorting
                             # value = yes (default) or no
-D CUDPP_OPT=value           # use GPU binning on with CUDA (should be off for modern GPUs)
                             # enables CUDA Performance Primitives, must be "no" for CUDA_MPS_SUPPORT=yes
                             # value = yes or no (default)
-D CUDA_MPS_SUPPORT=value    # enables some tweaks required to run with active nvidia-cuda-mps daemon
                             # value = yes or no (default)
-D USE_STATIC_OPENCL_LOADER=value  # downloads/includes OpenCL ICD loader library, no local OpenCL headers/libs needed
                                   # value = yes (default) or no

GPU_ARCH settings for different GPU hardware is as follows:

  • sm_12 or sm_13 for GT200 (supported by CUDA 3.2 until CUDA 6.5)

  • sm_20 or sm_21 for Fermi (supported by CUDA 3.2 until CUDA 7.5)

  • sm_30 for Kepler (supported since CUDA 5 and until CUDA 10.x)

  • sm_35 or sm_37 for Kepler (supported since CUDA 5 and until CUDA 11.x)

  • sm_50 or sm_52 for Maxwell (supported since CUDA 6)

  • sm_60 or sm_61 for Pascal (supported since CUDA 8)

  • sm_70 for Volta (supported since CUDA 9)

  • sm_75 for Turing (supported since CUDA 10)

  • sm_80 for Ampere (supported since CUDA 11)

A more detailed list can be found, for example, at Wikipedia’s CUDA article

CMake can detect which version of the CUDA toolkit is used and thus will try to include support for all major GPU architectures supported by this toolkit. Thus the GPU_ARCH setting is merely an optimization, to have code for the preferred GPU architecture directly included rather than having to wait for the JIT compiler of the CUDA driver to translate it.

When building with CMake, you must NOT build the GPU library in lib/gpu using the traditional build procedure. CMake will detect files generated by that process and will terminate with an error and a suggestion for how to remove them.

If you are compiling for OpenCL, the default setting is to download, build, and link with a static OpenCL ICD loader library and standard OpenCL headers. This way no local OpenCL development headers or library needs to be present and only OpenCL compatible drivers need to be installed to use OpenCL. If this is not desired, you can set USE_STATIC_OPENCL_LOADER to no.

If you are compiling with HIP, note that before running CMake you will have to set appropriate environment variables. Some variables such as HCC_AMDGPU_TARGET (for ROCm <= 4.0) or CUDA_PATH are necessary for hipcc and the linker to work correctly.

# AMDGPU target (ROCm <= 4.0)
export HIP_PLATFORM=hcc
export HCC_AMDGPU_TARGET=gfx906
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
# AMDGPU target (ROCm >= 4.1)
export HIP_PLATFORM=amd
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
# CUDA target (not recommended, use GPU_ARCH=cuda)
# !!! DO NOT set CMAKE_CXX_COMPILER !!!
export HIP_PLATFORM=nvcc
export CUDA_PATH=/usr/local/cuda
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=sm_70 ..
make -j 4

Traditional make

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 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 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 script with the specified args:

$ make lib-gpu               # print help message
$ make lib-gpu args="-b"     # build GPU library with default Makefile.linux
$ make lib-gpu args="-m xk7 -p single -o xk7.single"  # create new Makefile.xk7.single, altered for single-precision
$ make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi

Note that this procedure starts with a Makefile.machine in lib/gpu, as specified by the “-m” switch. For your convenience, machine makefiles for “mpi” and “serial” are provided, which have the same settings as the corresponding machine makefiles in the main LAMMPS source folder. In addition you can alter 4 important settings in the Makefile.machine you start from via the corresponding -c, -a, -p, -e 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

The file Makefile.cuda is set up to include support for multiple GPU architectures as supported by the CUDA toolkit in use. This is done through using the “–gencode ” flag, which can be used multiple times and thus support all GPU architectures supported by your CUDA compiler.

To enable GPU binning via CUDA performance primitives set the Makefile variable CUDPP_OPT = -DUSE_CUDPP -Icudpp_mini. This should not be used with most modern GPUs.

To support the CUDA multiprocessor server you can set the define -DCUDA_PROXY. Please note that in this case you must not use the CUDA performance primitives and thus set the variable CUDPP_OPT to empty.

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 your machine are not correct, the LAMMPS build will fail, and lib/gpu/Makefile.lammps may need to be edited.

Note

If you re-build the GPU library in lib/gpu, you should always un-install the GPU package in lammps/src, then re-install it and re-build LAMMPS. This is because the compilation of files in the GPU package uses the library settings from the lib/gpu/Makefile.machine used to build the GPU library.


3.7.3. KIM package

To build with this package, the KIM library with API v2 must be downloaded and built on your system. It must include the KIM models that you want to use with LAMMPS.

If you would like to use the kim query command, you also need to have libcurl installed with the matching development headers and the curl-config tool.

If you would like to use the kim property command, you need to build LAMMPS with the PYTHON package installed and linked to Python 3.6 or later. See the PYTHON package build info for more details on this. After successfully building LAMMPS with Python, you also need to 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 conda install kim-property if LAMMPS is built in Conda. More detailed information is available at: kim-property installation.

In addition to installing the KIM API, it is also necessary to install the library of KIM models (interatomic potentials). See Obtaining KIM Models to learn how to install a pre-build binary of the OpenKIM Repository of Models. See the list of all KIM models here: https://openkim.org/browse/models

(Also note that when downloading and installing from source the KIM API library with all its models, may take a long time (tens of minutes to hours) to build. Of course you only need to do that once.)

-D DOWNLOAD_KIM=value           # download OpenKIM API v2 for build, value = no (default) or yes
-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
-D KIM_EXTRA_UNITTESTS=value    # enables extra unit tests, value = no (default) or yes

If DOWNLOAD_KIM is set to yes (or on), the KIM API library will be downloaded and built inside the CMake build directory. If the KIM library is already installed on your system (in a location where CMake cannot find it), you may need to set the PKG_CONFIG_PATH environment variable so that libkim-api can be found, or run the command source kim-api-activate.

Extra unit tests can only be available if they are explicitly requested (KIM_EXTRA_UNITTESTS is set to yes (or on)) and the prerequisites are met. See KIM Extra unit tests for more details on this.

Debugging OpenKIM web queries in LAMMPS

If LMP_DEBUG_CURL is set, the libcurl verbose mode will be turned 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 library 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 communicate with that server, you can set LMP_NO_SSL_CHECK to override that behavior. When LAMMPS is compiled with LMP_NO_SSL_CHECK set, libcurl does not verify the peer and connection attempts will succeed 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 environment variable.

KIM Extra unit tests (CMake only)

During development, testing, or debugging, if unit testing is enabled in LAMMPS, one can also enable extra tests on KIM commands by setting the KIM_EXTRA_UNITTESTS to yes (or on).

Enabling the extra unit tests have some requirements,

  • It requires to have internet access.

  • It requires to have libcurl installed with the matching development headers and the curl-config tool.

  • It requires to build LAMMPS with the PYTHON package installed and linked to Python 3.6 or later. See the PYTHON package build info for more details on this.

  • It requires to have kim-property Python package installed, which can be easily done using 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 information is available at: kim-property installation.

  • It is also necessary to install EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000, EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005, and LennardJones612_UniversalShifted__MO_959249795837_003 KIM models. See Obtaining KIM Models to learn how to install a pre-built binary of the OpenKIM Repository of Models or see Installing KIM Models to learn how to install the specific KIM models.


3.7.4. KOKKOS package

Using the KOKKOS package requires choosing several settings. You have to select whether you want to compile with parallelization on the host and whether you want to include offloading of calculations to a device (e.g. a GPU). The default setting is to have no host parallelization and no device offloading. In addition, you can select the hardware architecture to select the instruction set. Since most hardware is backward compatible, you may choose settings for an older architecture to have an executable that will run on this and newer architectures.

Note

If you run Kokkos on a different GPU architecture than what LAMMPS was compiled with, there will be a delay during device initialization while the just-in-time compiler is recompiling all GPU kernels for the new hardware. This is, however, only supported for GPUs of the same major hardware version and different minor hardware versions, e.g. 5.0 and 5.2 but not 5.2 and 6.0. LAMMPS will abort with an error message indicating a mismatch, if that happens.

The settings discussed below have been tested with LAMMPS and are confirmed to work. Kokkos is an active project with ongoing improvements and projects working on including support for additional architectures. More information on Kokkos can be found on the Kokkos GitHub project.

Available Architecture settings

These are the possible choices for the Kokkos architecture ID. They must be specified in uppercase.

Arch-ID

HOST or GPU

Description

AMDAVX

HOST

AMD 64-bit x86 CPU (AVX 1)

ZEN

HOST

AMD Zen class CPU (AVX 2)

ZEN2

HOST

AMD Zen2 class CPU (AVX 2)

ZEN3

HOST

AMD Zen3 class CPU (AVX 2)

ARMV80

HOST

ARMv8.0 Compatible CPU

ARMV81

HOST

ARMv8.1 Compatible CPU

ARMV8_THUNDERX

HOST

ARMv8 Cavium ThunderX CPU

ARMV8_THUNDERX2

HOST

ARMv8 Cavium ThunderX2 CPU

A64FX

HOST

ARMv8.2 with SVE Support

WSM

HOST

Intel Westmere CPU (SSE 4.2)

SNB

HOST

Intel Sandy/Ivy Bridge CPU (AVX 1)

HSW

HOST

Intel Haswell CPU (AVX 2)

BDW

HOST

Intel Broadwell Xeon E-class CPU (AVX 2 + transactional mem)

SKX

HOST

Intel Sky Lake Xeon E-class HPC CPU (AVX512 + transactional mem)

KNC

HOST

Intel Knights Corner Xeon Phi

KNL

HOST

Intel Knights Landing Xeon Phi

BGQ

HOST

IBM Blue Gene/Q CPU

POWER7

HOST

IBM POWER7 CPU

POWER8

HOST

IBM POWER8 CPU

POWER9

HOST

IBM POWER9 CPU

KEPLER30

GPU

NVIDIA Kepler generation CC 3.0 GPU

KEPLER32

GPU

NVIDIA Kepler generation CC 3.2 GPU

KEPLER35

GPU

NVIDIA Kepler generation CC 3.5 GPU

KEPLER37

GPU

NVIDIA Kepler generation CC 3.7 GPU

MAXWELL50

GPU

NVIDIA Maxwell generation CC 5.0 GPU

MAXWELL52

GPU

NVIDIA Maxwell generation CC 5.2 GPU

MAXWELL53

GPU

NVIDIA Maxwell generation CC 5.3 GPU

PASCAL60

GPU

NVIDIA Pascal generation CC 6.0 GPU

PASCAL61

GPU

NVIDIA Pascal generation CC 6.1 GPU

VOLTA70

GPU

NVIDIA Volta generation CC 7.0 GPU

VOLTA72

GPU

NVIDIA Volta generation CC 7.2 GPU

TURING75

GPU

NVIDIA Turing generation CC 7.5 GPU

AMPERE80

GPU

NVIDIA Ampere generation CC 8.0 GPU

AMPERE86

GPU

NVIDIA Ampere generation CC 8.6 GPU

VEGA900

GPU

AMD GPU MI25 GFX900

VEGA906

GPU

AMD GPU MI50/MI60 GFX906

VEGA908

GPU

AMD GPU MI100 GFX908

INTEL_GEN

GPU

Intel GPUs Gen9+

This list was last updated for version 3.4.1 of the Kokkos library.

For multicore CPUs using OpenMP, set these 2 variables.

-D Kokkos_ARCH_HOSTARCH=yes  # HOSTARCH = HOST from list above
-D Kokkos_ENABLE_OPENMP=yes
-D BUILD_OMP=yes

Please note that enabling OpenMP for KOKKOS requires that OpenMP is also enabled for the rest of LAMMPS.

For Intel KNLs using OpenMP, set these variables:

-D Kokkos_ARCH_KNL=yes
-D Kokkos_ENABLE_OPENMP=yes

For NVIDIA GPUs using CUDA, set these variables:

-D Kokkos_ARCH_HOSTARCH=yes   # HOSTARCH = HOST from list above
-D Kokkos_ARCH_GPUARCH=yes    # GPUARCH = GPU from list above
-D Kokkos_ENABLE_CUDA=yes
-D Kokkos_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper

This will also enable executing FFTs on the GPU, either via the internal KISSFFT library, or - by preference - with the cuFFT library bundled with the CUDA toolkit, depending on whether CMake can identify its location. The wrapper value for CMAKE_CXX_COMPILER variable is the path to the CUDA nvcc compiler wrapper provided in the Kokkos library: lib/kokkos/bin/nvcc_wrapper. The setting should include the full path name to the wrapper, e.g.

-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper

To simplify compilation, three preset files are included in the cmake/presets folder, kokkos-serial.cmake, kokkos-openmp.cmake, and kokkos-cuda.cmake. They will enable the KOKKOS package and enable some hardware choice. So to compile with OpenMP host parallelization, CUDA device parallelization (for GPUs with CC 5.0 and up) with some common packages enabled, you can do the following:

mkdir build-kokkos-cuda
cd build-kokkos-cuda
cmake -C ../cmake/presets/minimal.cmake -C ../cmake/presets/kokkos-cuda.cmake ../cmake
cmake --build .

Advanced KOKKOS compilation settings

There are other allowed options when building with the KOKKOS package that can improve performance or assist in debugging or profiling. Below are some examples that may be useful in combination with LAMMPS. For the full list (which keeps changing as the Kokkos package itself evolves), please consult the Kokkos library documentation.

As alternative to using multi-threading via OpenMP (-DKokkos_ENABLE_OPENMP=on or KOKKOS_DEVICES=OpenMP) it is also possible to use Posix threads directly (-DKokkos_ENABLE_PTHREAD=on or KOKKOS_DEVICES=Pthread). While binding of threads to individual or groups of CPU cores is managed in OpenMP with environment variables, you need assistance from either the “hwloc” or “libnuma” library for the Pthread thread parallelization option. To enable use with CMake: -DKokkos_ENABLE_HWLOC=on or -DKokkos_ENABLE_LIBNUMA=on; and with conventional make: KOKKOS_USE_TPLS=hwloc or KOKKOS_USE_TPLS=libnuma.

The CMake option -DKokkos_ENABLE_LIBRT=on or the makefile setting KOKKOS_USE_TPLS=librt enables the use of a more accurate timer mechanism on many Unix-like platforms for internal profiling.

The CMake option -DKokkos_ENABLE_DEBUG=on or the makefile setting KOKKOS_DEBUG=yes enables printing of run-time debugging information that can be useful. It also enables runtime bounds checking on Kokkos data structures. As to be expected, enabling this option will negatively impact the performance and thus is only recommended when developing a Kokkos-enabled style in LAMMPS.

The CMake option -DKokkos_ENABLE_CUDA_UVM=on or the makefile setting KOKKOS_CUDA_OPTIONS=enable_lambda,force_uvm enables the use of CUDA “Unified Virtual Memory” (UVM) in Kokkos. UVM allows to transparently use RAM on the host to supplement the memory used on the GPU (with some performance penalty) and thus enables running larger problems that would otherwise not fit into the RAM on the GPU.

Please note, that the LAMMPS KOKKOS package must always be compiled with the enable_lambda option when using GPUs. The CMake configuration will thus always enable it.


3.7.5. LATTE package

To build with this package, you must download and build the LATTE library.

-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 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, not the directory the library file is in.


3.7.6. MESSAGE package

This package can optionally include support for messaging via sockets, using the open-source ZeroMQ library, which must be installed on your system.

-D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes
-D ZMQ_LIBRARY=path     # ZMQ library file (only needed if a custom location)
-D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom location)

3.7.7. MLIAP package

Building the MLIAP package requires including the SNAP package. There will be an error message if this requirement is not satisfied. Using the mliappy model also requires enabling Python support, which in turn requires the PYTHON package and requires you have the cython software installed and with it a working cythonize command. This feature requires compiling LAMMPS with Python version 3.6 or later.

-D MLIAP_ENABLE_PYTHON=value   # enable mliappy model (default is autodetect)

Without this setting, CMake will check whether it can find a suitable Python version and the cythonize command and choose the default accordingly. During the build procedure the provided .pyx file(s) will be automatically translated to C++ code and compiled. Please do not run cythonize manually in the src/MLIAP folder, as that can lead to compilation errors if Python support is not enabled. If you did by accident, please remove the generated .cpp and .h files.


3.7.8. MSCG package

To build with this package, you must download and build the MS-CG 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.

-D DOWNLOAD_MSCG=value    # download MSCG for build, value = no (default) or yes
-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 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 filename (plus path) of the MSCG library file, not the directory the library file is in. MSCG_INCLUDE_DIR is the directory the MSCG include file is in.


3.7.9. OPT package

No additional settings are needed besides -D PKG_OPT=yes


3.7.10. POEMS package

No additional settings are needed besides -D PKG_OPT=yes


3.7.11. PYTHON package

Building with the PYTHON package requires you have a the Python development headers and library available on your system, which needs to be a Python 2.7 version or a Python 3.x version. Since support for Python 2.x has ended, using Python 3.x is strongly recommended. See lib/python/README for additional details.

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

Without this setting, CMake will guess the default Python version on your system. To use a different Python version, you can either create a virtualenv, activate it and then run cmake. Or you can set the PYTHON_EXECUTABLE variable to specify which Python interpreter should be used. Note note that you will also need to have the development headers installed for this version, e.g. python2-devel.


3.7.12. VORONOI package

To build with this package, you must download and build the Voro++ library or install a binary package provided by your operating system.

-D DOWNLOAD_VORO=value    # download Voro++ for build, value = no (default) or yes
-D VORO_LIBRARY=path      # Voro++ library file (only needed if at custom location)
-D VORO_INCLUDE_DIR=path  # Voro++ include directory (only needed if at custom location)

If DOWNLOAD_VORO is set, the Voro++ library will be downloaded and built inside the CMake build directory. If the Voro++ library is already on your system (in a location CMake cannot find it), VORO_LIBRARY is the filename (plus path) of the Voro++ library file, not the directory the library file is in. VORO_INCLUDE_DIR is the directory the Voro++ include file is in.


3.7.13. USER-ADIOS package

The USER-ADIOS package requires the ADIOS I/O library, version 2.3.1 or newer. Make sure that you have ADIOS built either with or without MPI to match if you build LAMMPS with or without MPI. ADIOS compilation settings for LAMMPS are automatically detected, if the PATH and LD_LIBRARY_PATH environment variables have been updated for the local ADIOS installation and the instructions below are followed for the respective build systems.

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

3.7.14. USER-ATC package

The USER-ATC package requires the MANYBODY package also be installed.

No additional settings are needed besides -D PKG_USER-ATC=yes and -D PKG_MANYBODY=yes.


3.7.15. USER-AWPMD package

No additional settings are needed besides -D PKG_USER-AQPMD=yes.


3.7.16. USER-COLVARS package

This package includes the Colvars library into the LAMMPS distribution, which can be built for the most part with all major versions of the C++ language.

This is the recommended build procedure for using Colvars in LAMMPS. No additional settings are normally needed besides -D PKG_USER-COLVARS=yes.


3.7.17. USER-PACE package

This package requires a library that can be downloaded and built in lib/pace or somewhere else, which must be done before building LAMMPS with this package. The code for the library can be found at: https://github.com/ICAMS/lammps-user-pace/

By default the library will be downloaded from the git repository and built automatically when the USER-PACE package is enabled with -D PKG_USER-PACE=yes. The location for the sources may be customized by setting the variable PACELIB_URL when configuring with CMake (e.g. to use a local archive on machines without internet access). Since CMake checks the validity of the archive with md5sum you may also need to set PACELIB_MD5 if you provide a different library version than what is downloaded automatically.


3.7.18. USER-PLUMED package

Before building LAMMPS with this package, you must first build PLUMED. PLUMED can be built as part of the LAMMPS build or installed separately from LAMMPS using the generic PLUMED installation instructions. 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 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 independent from the PLUMED installation, but you have to rebuild/relink it in order to update the PLUMED code inside it. With the “shared” linkage mode, LAMMPS is linked to a shared library that contains the PLUMED code. This library should preferably be installed in a globally accessible location. When PLUMED is linked in this way the same library can be used by multiple MD packages. Furthermore, the PLUMED library LAMMPS uses can be updated without the need for a recompile of LAMMPS for as long as the shared PLUMED library is ABI-compatible.

The third linkage mode is “runtime” which allows the user to specify which PLUMED kernel should be used at runtime by using the PLUMED_KERNEL environment variable. This variable should point to the location of the libplumedKernel.so dynamical shared object, which is then loaded at runtime. This mode of linking is particularly convenient for doing PLUMED development and comparing multiple PLUMED versions as these sorts of comparisons can be done without recompiling the hosting MD code. All three linkage modes are supported by LAMMPS on selected operating systems (e.g. Linux) and using either CMake or traditional make build. The “static” mode should be the most portable, while the “runtime” mode support in LAMMPS makes the most assumptions about operating system and compiler environment. If one mode does not work, try a different one, switch to a different build system, consider a global PLUMED installation or consider downloading PLUMED during the LAMMPS build.

When the -D PKG_USER-PLUMED=yes flag is included in the cmake command you must ensure that GSL is installed in locations that are specified in your environment. There are then two additional variables that control the manner in which PLUMED is obtained and linked into LAMMPS.

-D DOWNLOAD_PLUMED=value   # download PLUMED for build, value = no (default) or yes
-D PLUMED_MODE=value       # Linkage mode for PLUMED, value = static (default), shared, or runtime

If DOWNLOAD_PLUMED is set to “yes”, the PLUMED library will be downloaded (the version of PLUMED that will be downloaded is hard-coded to a vetted version of PLUMED, usually a recent stable release version) and built inside the CMake build directory. If DOWNLOAD_PLUMED is set to “no” (the default), CMake will try to detect and link to an installed version of PLUMED. For this to work, the PLUMED library has to be installed into a location where the pkg-config tool can find it or the PKG_CONFIG_PATH environment variable has to be set up accordingly. PLUMED should be installed in such a location if you compile it using the default make; make install commands.

The PLUMED_MODE setting determines the linkage mode for the PLUMED library. The allowed values for this flag are “static” (default), “shared”, or “runtime”. If you want to switch the linkage mode, just re-run CMake with a different setting. For a discussion of PLUMED linkage modes, please see above. When DOWNLOAD_PLUMED is enabled the static linkage mode is recommended.


3.7.19. USER-H5MD package

To build with this package you must have the HDF5 software package installed on your system, which should include the h5cc compiler and the HDF5 library.

No additional settings are needed besides -D PKG_USER-H5MD=yes.

This should auto-detect the H5MD library on your system. Several advanced CMake H5MD options exist if you need to specify where it is installed. Use the ccmake (terminal window) or cmake-gui (graphical) tools to see these options and set them interactively from their user interfaces.


3.7.20. USER-HDNNP package

To build with the USER-HDNNP package it is required to download and build the external n2p2 library v2.1.4 (or higher). The LAMMPS build process offers an automatic download and compilation of n2p2 or allows you to choose the installation directory of n2p2 manually. Please see the boxes below for the CMake and traditional build system for detailed information.

In case of a manual installation of n2p2 you only need to build the n2p2 core library libnnp and interface library libnnpif. When using GCC it should suffice to execute make libnnpif in the n2p2 src directory. For more details please see lib/hdnnp/README and the n2p2 build documentation.

-D DOWNLOAD_N2P2=value    # download n2p2 for build, value = no (default) or yes
-D N2P2_DIR=path          # n2p2 base directory (only needed if a custom location)

If DOWNLOAD_N2P2 is set, the n2p2 library will be downloaded and built inside the CMake build directory. If the n2p2 library is already on your system (in a location CMake cannot find it), set the N2P2_DIR to path where n2p2 is located. If n2p2 is located directly in lib/hdnnp/n2p2 it will be automatically found by CMake.


3.7.21. USER-INTEL package

To build with this package, you must choose which hardware you want to build for, either x86 CPUs or Intel KNLs in offload mode. You should also typically install the USER-OMP package, as it can be used in tandem with the USER-INTEL package to good effect, as explained on the USER-INTEL package page.

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 improvements over regular styles and USER-OMP styles, but less so than with the Intel compilers. Please also note, that some compilers have been found to apply memory alignment constraints incompletely or incorrectly and thus can cause segmentation faults in otherwise correct code when using features from the USER-INTEL package.

-D INTEL_ARCH=value     # value = cpu (default) or knl
-D INTEL_LRT_MODE=value # value = threads, none, or c++11

In Long-range thread mode (LRT) a modified verlet style is used, that operates the Kspace calculation in a separate thread concurrently to other calculations. This has to be enabled in the package intel command at runtime. With the setting “threads” it used the pthreads library, while “c++11” will use the built-in thread support of C++11 compilers. The option “none” skips compilation of this feature. The default is to use “threads” if pthreads is available and otherwise “none”.

Best performance is achieved with Intel hardware, Intel compilers, as well as the Intel TBB and MKL libraries. However, the code also compiles, links, and runs with other compilers / hardware and without TBB and MKL.


3.7.22. USER-MDI package

-D DOWNLOAD_MDI=value    # download MDI Library for build, value = no (default) or yes

3.7.23. USER-MESONT package

This package includes a library written in Fortran 90 in the lib/mesont folder, so a working Fortran 90 compiler is required to compile it. Also, the files with the force field data for running the bundled examples are not included in the source distribution. Instead they will be downloaded the first time this package is installed.

No additional settings are needed besides -D PKG_USER-MESONT=yes


3.7.24. USER-MOLFILE package

-D MOLFILE_INCLUDE_DIR=path   # (optional) path where VMD molfile plugin headers are installed
-D PKG_USER-MOLFILE=yes

Using -D PKG_USER-MOLFILE=yes enables the package, and setting -D MOLFILE_INCLUDE_DIR allows to provide a custom location for the molfile plugin header files. These should match the ABI of the plugin files used, and thus one typically sets them to include folder of the local VMD installation in use. LAMMPS ships with a couple of default header files that correspond to a popular VMD version, usually the latest release.


3.7.25. USER-NETCDF package

To build with this package you must have the NetCDF library installed on your system.

No additional settings are needed besides -D PKG_USER-NETCDF=yes.

This should auto-detect the NETCDF library if it is installed on your system at standard locations. Several advanced CMake NETCDF options exist if you need to specify where it was installed. Use the ccmake (terminal window) or cmake-gui (graphical) tools to see these options and set them interactively from their user interfaces.


3.7.26. USER-OMP package

No additional settings are required besides -D PKG_USER-OMP=yes. If CMake detects OpenMP compiler support, the USER-OMP code will be compiled with multi-threading support enabled, otherwise as optimized serial code.


3.7.27. USER-QMMM package

For using LAMMPS to do QM/MM simulations via the USER-QMMM package you need to build LAMMPS as a library. A LAMMPS executable with fix qmmm included can be built, but will not be able to do a QM/MM simulation on as such. You must also build a QM code - currently only Quantum ESPRESSO (QE) is supported - and create a new executable which links LAMMPS and the QM code together. Details are given in the lib/qmmm/README file. It is also recommended to read the instructions for linking with LAMMPS as a library for background information. This requires compatible Quantum Espresso and LAMMPS versions. The current interface and makefiles have last been verified to work in February 2020 with Quantum Espresso versions 6.3 to 6.5.

When using CMake, building a LAMMPS library is required and it is recommended to build a shared library, since any libraries built from the sources in the lib folder (including the essential libqmmm.a) are not included in the static LAMMPS library and (currently) not installed, while their code is included in the shared LAMMPS library. Thus a typical command line to configure building LAMMPS for USER-QMMM would be:

cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \
    -D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake

After completing the LAMMPS build and also configuring and compiling Quantum ESPRESSO with external library support (via “make couple”), go back to the lib/qmmm folder and follow the instructions on the README file to build the combined LAMMPS/QE QM/MM executable (pwqmmm.x) in the lib/qmmm folder.


3.7.28. USER-QUIP package

To build with this package, you must download and build the QUIP library. It can be obtained from GitHub. For support of GAP potentials, additional files with specific licensing conditions need to be downloaded and configured. See step 1 and step 1.1 in the lib/quip/README file for details on how to do this.

-D QUIP_LIBRARY=path     # path to libquip.a (only needed if a custom location)

CMake will not download and build the QUIP library. But once you have done that, a CMake build of LAMMPS with -D PKG_USER-QUIP=yes should work. Set the QUIP_LIBRARY variable if CMake cannot find the QUIP library.


3.7.29. USER-SCAFACOS package

To build with this package, you must download and build the ScaFaCoS Coulomb solver library

-D DOWNLOAD_SCAFACOS=value    # download ScaFaCoS for build, value = no (default) or yes
-D SCAFACOS_LIBRARY=path      # ScaFaCos library file (only needed if at custom location)
-D SCAFACOS_INCLUDE_DIR=path  # ScaFaCoS include directory (only needed if at custom location)

If DOWNLOAD_SCAFACOS is set, the ScaFaCoS library will be downloaded and built inside the CMake build directory. If the ScaFaCoS library is already on your system (in a location CMake cannot find it), SCAFACOS_LIBRARY is the filename (plus path) of the ScaFaCoS library file, not the directory the library file is in. SCAFACOS_INCLUDE_DIR is the directory the ScaFaCoS include file is in.


3.7.30. USER-SMD package

To build with this package, you must download the Eigen3 library. Eigen3 is a template library, so you do not need to build it.

-D DOWNLOAD_EIGEN3            # download Eigen3, value = no (default) or yes
-D EIGEN3_INCLUDE_DIR=path    # path to Eigen library (only needed if a custom location)

If DOWNLOAD_EIGEN3 is set, the Eigen3 library will be downloaded and inside the CMake build directory. If the Eigen3 library is already on your system (in a location where CMake cannot find it), set EIGEN3_INCLUDE_DIR to the directory the Eigen3 include file is in.


3.7.31. USER-VTK package

To build with this package you must have the VTK library installed on your system.

No additional settings are needed besides -D PKG_USER-VTK=yes.

This should auto-detect the VTK library if it is installed on your system at standard locations. Several advanced VTK options exist if you need to specify where it was installed. Use the ccmake (terminal window) or cmake-gui (graphical) tools to see these options and set them interactively from their user interfaces.