3.4. Basic build options

The following topics are covered on this page, for building both with CMake and make:


3.4.1. Serial vs parallel build

LAMMPS is written to use the ubiquitous MPI (Message Passing Interface) library API for distributed memory parallel computation. You need to have such a library installed for building and running LAMMPS in parallel using a domain decomposition parallelization. It is compatible with the MPI standard version 2.x and later. LAMMPS can also be built into a “serial” executable for use with a single processor using the bundled MPI STUBS library.

Independent of the distributed memory MPI parallelization, parts of LAMMPS are also written with support for shared memory parallelization using the OpenMP threading standard. A more detailed discussion of that is below.

CMake build:

-D BUILD_MPI=value        # yes or no, default is yes if CMake finds MPI, else no
-D BUILD_OMP=value        # yes or no, default is yes if a compatible compiler is detected
-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 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.

make mpi                # parallel build, produces lmp_mpi using Makefile.mpi
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 in the folder src/MAKE or one of its sub-directories MINE, MACHINES, or OPTIONS, 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 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.

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

CC =            g++
LINK =          g++
MPI_INC =       -I../STUBS
MPI_PATH =      -L../STUBS
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 the src/STUBS dir. If the build fails, you may 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, and thus is not compatible with those packages.

Note

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() rolls over after an hour or so, and is therefore insufficient for timing long LAMMPS simulations.

MPI and OpenMP support info:

If you are installing MPI yourself to build a parallel LAMMPS executable, we recommend either MPICH or OpenMPI which are regularly used and tested with LAMMPS by the LAMMPS developers. MPICH can be downloaded from the MPICH home page and OpenMPI can be downloaded correspondingly from the OpenMPI home page. Other MPI packages should also work. No specific vendor provided and standard compliant MPI library is currently known to be incompatible with LAMMPS. If you are running on a large parallel machine, your system admins or the vendor should have already installed a version of MPI, which is likely to be faster than a self-installed MPICH or OpenMPI, so you should study the provided documentation to find out how to build and link with it.

The majority of OpenMP (threading) support in LAMMPS is provided by the USER-OMP package; see the Speed omp doc page for details. The USER-INTEL package also includes OpenMP threading (it is compatible with USER-OMP and will usually fall back on styles from that package, if a USER-INTEL does not exist) and adds vectorization support when compiled with compatible compilers, in particular the Intel compilers on top of OpenMP. Also, the KOKKOS package can be compiled to include OpenMP threading.

In addition, there are a few commands in LAMMPS that have native OpenMP support included as well. These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and USER-DPD packages. In addition some packages support OpenMP threading indirectly through the libraries they interface to: e.g. LATTE, KSPACE, and USER-COLVARS. See the 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 variable before you launch LAMMPS.

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, please refer to its documentation.

OpenMP Compiler compatibility info:

Some compilers do not fully support the default(none) directive and others (e.g. GCC version 9 and beyond, Clang version 10 and later) may implement strict OpenMP 4.0 and later semantics, which are incompatible with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility with compiler versions in use. If compilation with OpenMP enabled fails because of your compiler requiring strict OpenMP 4.0 semantic, you can change the behavior by adding -D LAMMPS_OMP_COMPAT=4 to the LMP_INC variable in your makefile, or add it to the command line while configuring with CMake. CMake will detect the suitable setting for the GNU, Clang, and Intel compilers.


3.4.3. Build the LAMMPS executable and library

LAMMPS is always built as a library of C++ classes plus an executable. The executable is a simple main() function that sets up MPI and then creates a LAMMPS class instance from the LAMMPS library, which will then process commands provided via a file or from the console input. The LAMMPS library can also be called from another application or a scripting language. See the Howto couple doc page for more info on coupling LAMMPS to other codes. See the Python doc page for more info on wrapping and running LAMMPS from Python via its library interface.

CMake build:

For CMake builds, you can select through setting CMake variables between building a shared or a static LAMMPS library and what kind of suffix is added to them (in case you want to concurrently install multiple variants of binaries with different settings). If none are set, defaults are applied.

-D BUILD_SHARED_LIBS=value   # yes or no (default)
-D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc
                             # no default value

The compilation will always produce a LAMMPS library and an executable linked to it. By default this will be a static library named liblammps.a and an executable named lmp Setting BUILD_SHARED_LIBS=yes will instead produce a shared library called liblammps.so (or liblammps.dylib or liblammps.dll depending on the platform) If LAMMPS_MACHINE=name is set in addition, the name of the generated libraries will be changed to either liblammps_name.a or liblammps_name.so, respectively and the executable will be called lmp_name.

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

make machine               # build LAMMPS executable lmp_machine
make mode=static machine   # same as "make machine"
make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead

The “static” build will generate a static library called liblammps_machine.a and an executable named lmp_machine, while the “shared” build will generate a shared library liblammps_machine.so instead and lmp_machine will be linked to it. The build step 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:

Note that for creating a shared library, all the libraries it depends on must be compiled to be compatible with shared libraries. This should be the case for libraries included with LAMMPS, such as the dummy MPI library in src/STUBS or any package libraries in the lib directory, since they are always built in a shared library compatible way using the -fPIC compiler switch. However, if an auxiliary library (like MPI or FFTW) does not exist as a compatible format, the shared library linking step may generate an error. This means you will need to install a compatible version of the auxiliary library. The build instructions for that library should tell you how to do this.

As an example, here is how to build and install the MPICH library, a popular open-source version of MPI, as a shared library in the default /usr/local/lib location:

./configure --enable-shared
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 or use the --prefix configuration option to select an installation folder, where you do have write access. 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:

./configure --enable-shared --prefix=${HOME}/.local

Avoiding to use “sudo” for custom software installation (i.e. from source and not through a package manager tool provided by the OS) is generally recommended to ensure the integrity of the system software installation.


3.4.4. Excluding or removing debug support

By default the compilation settings will include the -g flag which instructs the compiler to include debug information (e.g. which line of source code a particular instruction correspond to). This can be extremely useful in case LAMMPS crashes and can help to provide crucial information in tracking down the origin of a crash and help the LAMMPS developers fix bugs in the source code. However, this increases the storage requirements for object files, libraries, and the executable 3-5 fold.

If this is a concern, you can change the compilation settings or remove the debug information from the LAMMPS executable:

  • Traditional make: edit your Makefile.<machine> to remove the -g flag from the CCFLAGS and LINKFLAGS definitions

  • CMake: use -D CMAKE_BUILD_TYPE=Release or explicitly reset the applicable compiler flags (best done using the text mode or graphical user interface).

  • Remove debug info: If you are only concerned about the executable being too large, you can use the strip tool (e.g. strip lmp_serial) to remove the debug information from the executable file. Do not strip libraries or object files, as that will render them unusable.


3.4.5. Build the LAMMPS documentation

The LAMMPS manual is written in reStructuredText format which can be translated to different output format using the Sphinx document generator tool. Currently the translation to HTML and PDF (via LaTeX) are supported. For that to work a Python 3 interpreter and internet access is required. For the documentation build a python based virtual environment is set up in the folder doc/docenv and various python packages are installed into that virtual environment via the pip tool. The actual translation is then done via make commands.

Documentation make option:

The following make commands can be issued in the doc folder of the LAMMPS source distribution.

make html          # create HTML doc pages in html directory
make pdf           # create Developer.pdf and Manual.pdf in this directory
make fetch         # fetch HTML and PDF files from LAMMPS web site
make clean         # remove all intermediate files
make clean-all     # reset the entire doc build environment
make anchor_check  # scan for duplicate anchor labels
make style_check   # check for complete and consistent style lists
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.

Note

You can also download a tarball of the documentation for the current LAMMPS version (HTML and PDF files), from the website download page.

CMake build option:

It is also possible to create the HTML version of the manual within the CMake build directory. 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. The documentation build is included in the default build target, but can also be requested independently with make doc.

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

3.4.6. Build LAMMPS tools

Some tools described in Auxiliary tools can be built directly using CMake or Make.

CMake build3:

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

The generated binaries will also become part of the LAMMPS installation (see below).

Traditional make:

cd lammps/tools
make all              # build all binaries of tools
make binary2txt       # build only binary2txt tool
make chain            # build only chain tool
make micelle2d        # build only micelle2d tool
make thermo_extract   # build only thermo_extract tool

3.4.7. Install LAMMPS after a build

After building LAMMPS, you may wish to copy the LAMMPS executable of library, along with other LAMMPS files (library header, doc files) to a globally visible place on your system, for others to access. Note that you may need super-user privileges (e.g. sudo) if the directory you want to copy files to is protected.

CMake build:

cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
make                        # perform make after CMake command
make install                # perform the installation into prefix

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 copy the desired LAMMPS files to the appropriate system directories.