changes to replace Section_start.txt

"Previous Section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Run.html :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

Build LAMMPS :h2

LAMMPS can be built as an executable or library from source code via

either CMake or traditional make.  As an alternative you can download

a pre-built executable file as described on the "Install"_Install.html

doc page.

<!-- RST

.. toctree::

   Build_cmake

   Build_make

   Build_link

.. toctree::

   Build_basics

   Build_settings

   Build_package

   Build_extras

END_RST -->

<!-- HTML_ONLY -->

"Build LAMMPS with CMake"_Build_cmake.html

"Build LAMMPS with make"_Build_make.html

"Link LAMMPS as a library to another code"_Build_link.html :all(b)

Build options:

"Basic build options: serial/parallel, compilers, executable/library"_Build_basics.html

"Optional build settings"_Build_settings.html :all(b)

"Include packages in build"_Build_package.html

"Packages with extra build options"_Build_extras.html :all(b)

If you have problems building LAMMPS, it is often due to software

issues on your local machine.  If you can, find a local expert to

help.  If you're still stuck, send an email to the "LAMMPS mail

list"_http://lammps.sandia.gov/mail.html.

"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

Basic build options :h3

The following topics are covered on this page, for building both with

CMake and make:

"Serial vs parallel build"_#serial

"Choice of compiler and compile/link options"_#compile

"Build LAMMPS as an executable or a library"_#exe

"Build the LAMMPS documentation"_#doc

"Install LAMMPS after a build"_#install :ul

:line

:line

Serial vs parallel build :h3,link(serial)

LAMMPS can be built to run in parallel using the ubiquitous "MPI

(message-passing

interface)"_https://en.wikipedia.org/wiki/Message_Passing_Interface

library.  Or it can built to run on a single processor (serial)

without MPI.  It can also be built with support for OpenMP threading

(see more discussion below).

[CMake variables]:

-D BUILD_MPI=value        # yes or no, default is yes if CMake finds MPI, else no

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

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

                          # no default value :pre

The executable CMake creates (after running make) is lmp_name.  If the

LAMMPS_MACHINE variable is not specified, the executable is just lmp.

Using BUILD_MPI=no will produce a serial executable.

[Traditional make]:

cd lammps/src

make mpi                # parallel build, produces lmp_mpi using Makefile.mpi

make serial             # serial build, produces lmp_serial using Makefile/serial

make mybox :pre         # uses Makefile.mybox, produces lmp_mybox :pre

Serial build (see src/MAKE/Makefile.serial):

MPI_INC =       -I../STUBS 

MPI_PATH =      -L../STUBS

MPI_LIB =	-lmpi_stubs :pre

For a parallel build, if MPI is installed on your system in the usual

place (e.g. under /usr/local), you do not need to specify the 3

variables MPI_INC, MPI_PATH, MPI_LIB.  The MPI wrapper on the compiler

(e.g. mpicxx, mpiCC) knows where to find the needed include and

library files.  Failing this, these 3 variables can be used to specify

where the mpi.h file (MPI_INC), and the MPI library files (MPI_PATH)

are found, and the name of the library files (MPI_LIB).

For a serial build, you need to specify the 3 varaibles, as shown

above.

For a serial LAMMPS build, use the dummy MPI library provided in

src/STUBS.  You also need to build the STUBS library for your platform

before making LAMMPS itself.  A "make serial" build does this for.

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 file STUBS/mpi.c provides a CPU timer function called MPI_Wtime()

that calls gettimeofday() .  If your system doesn't support

gettimeofday() , you'll 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.

[CMake and make info]:

If you are installing MPI yourself, we recommend Argonne's MPICH2 or

OpenMPI.  MPICH can be downloaded from the "Argonne MPI

site"_http://www.mcs.anl.gov/research/projects/mpich2/.  OpenMPI can

be downloaded from the "OpenMPI site"_http://www.open-mpi.org.  Other

MPI packages should also work.  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 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"_Speed_omp.html doc page for

details.

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

support.  These are commands in the MPIIO, SNAP, USER-COLVARS, and

USER-DPD packages.  See the "Packages details"_Packages_details.html

doc page for more info on these packages and the doc pages for their

respective commands for OpenMP threading info.

TODO: is this the complete list of native OpenMP commands in LAMMPS?

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

and turn on their native OpenMP support at run time, by first setting

the OMP_NUM_THREADS environment variable.

For make, ...

TODO: how do we build LAMMPS with make, to include OpenMP support

(separate from USER-OMP package).  Akin to CMake with BUILD_OMP=yes.

:line

Choice of compiler and compile/link options :h3,link(compile)

The choice of compiler and compiler flags can be important for

performance.  Vendor compilers can produce faster code than

open-source compilers like GNU.  On boxes with Intel CPUs, we suggest

trying the "Intel C++ compiler"_intel.

:link(intel,https://software.intel.com/en-us/intel-compilers)

On parallel clusters or supercomputers which use "modules" for their

compile/link environments, you can often access different compilers by

simply loading the appropriate module before building LAMMPS.

[CMake variables]:

-D CMAKE_CXX_COMPILER=name            # name of C++ compiler

-D CMAKE_C_COMPILER=name              # name of C compiler

-D CMAKE_Fortran_COMPILER=name        # name of Fortran compiler :pre

-D CMAKE_CXX_FlAGS=string             # flags to use with C++ compiler

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

-D CMAKE_Fortran_FlAGS=string         # flags to use with Fortran compiler :pre

By default CMake will use a compiler it finds and it will use

optimization flags appropriate to that compiler and any "accelerator

packages"_Speed_packages.html you have included in the build.

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

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:

Building with GNU Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran

Building with Intel Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort

Building with LLVM/Clang Compilers:

cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang :pre

NOTE: When the cmake command completes, it prints info to the screen

as to what compilers it is using, and what flags will be used in the

compilation.  Note that if the top-level compiler is mpicxx, it is

simply a wrapper on a real compiler.  The low-level compiler info is

also in the output.  You should check to insure you are using the

compiler and optimization flags that are the ones you want.

[Makefile.machine settings]:

Parallel build (see src/MAKE/Makefile.mpi):

CC =		mpicxx

CCFLAGS =	-g -O3 

LINK =		mpicxx

LINKFLAGS =	-g -O :pre

Serial build (see src/MAKE/Makefile.serial):

CC =		g++

CCFLAGS =	-g -O3

LINK =		g++

LINKFLAGS =	-g -O :pre

The "compiler/linker settings" section of a Makefile.machine lists

compiler and linker settings for your C++ compiler, including

optimization flags.  You should always use mpicxx or mpiCC for

a parallel build, since these compiler wrappers will include

a variety of settings appropriate for your MPI installation.

NOTE: If you build LAMMPS with any "accelerator

packages"_Speed_packages.html included, they have specific

optimization flags that are either required or recommended for optimal

performance.  You need to include these in the CCFLAGS and LINKFLAGS

settings above.  For details, see the individual package doc pages

listed on the "Speed packages"_Speed_packages.html doc page.  Or

examine these files in the src/MAKE/OPTIONS directory.  They

correspond to each of the 5 accelerator packages and their hardware

variants:

Makefile.opt                   # OPT package

Makefile.omp                   # USER-OMP package

Makefile.intel_cpu             # USER-INTEL package for CPUs

Makefile.intel_coprocessor     # USER-INTEL package for KNLs

Makefile.gpu                   # GPU package

Makefile.kokkos_cuda_mpi       # KOKKOS package for GPUs

Makefile.kokkos_omp            # KOKKOS package for CPUs (OpenMP)

Makefile.kokkos_phi            # KOKKOS package for KNLs (OpenMP) :pre

NOTE: When you build LAMMPS for the first time, a long list of *.d

files will be printed out rapidly.  This is not an error; it is the

Makefile doing its normal creation of dependencies.

:line

Build LAMMPS as an executable or a library :h3,link(exe)

LAMMPS can be built as either an executable or as a static or shared

library.  The library can be called from another application or a

scripting language.  See the "Howto couple"_Howto_couple.html doc page

for more info on coupling LAMMPS to other codes.  See the

"Python"_Python doc page for more info on wrapping and running LAMMPS

from Python.

[CMake variables]:

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

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

-D BUILD_SHARED_LIBS=value   # yes or no (default) :pre

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

static library named liblammps.so.

[Traditional make]:

cd lammps/src

make machine               # build LAMMPS executable lmp_machine

make mode=lib machine      # build LAMMPS static lib liblammps_machine.a

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

The two library builds also create generic links liblammps.a and

liblammps.so which point to the liblammps_machine files.

[CMake and make info]:

Note that for a shared library to be usable by a calling program, all

the auxiliary libraries it depends on must also exist as shared

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

lib/packages, since they are always built as shared libraries using

the -fPIC switch.  However, if a library like MPI or FFTW does not

exist as a shared library, the shared library build will generate an

error.  This means you will need to install a 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, distributed by

Argonne National Labs, as a shared library in the default

/usr/local/lib location:

:link(mpich,http://www-unix.mcs.anl.gov/mpi)

./configure --enable-shared

make

make install :pre

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.

:line

Build the LAMMPS documentation :h3,link(doc)

[CMake variable]:

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

This will create the HTML doc pages within the CMake build dir.  The

reason to do this is if you want to "install" LAMMPS on a system after

the CMake build, and include the doc pages in the install.

[Traditional make]:

cd lammps/doc

make html       # html doc pages

make pdf        # single Manual.pdf file :pre

This will create a lammps/doc/html dir with the HTML doc pages so that

you can browse them locally on your system.  Type "make" from the the

lammps/doc dir to see other options.

:line

Install LAMMPS after a build :h3,link(install)

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 priveleges (e.g. sudo) if the place you

want to copy files to is protected.

[CMake variable]:

cmake CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake

make                        # perform make after CMake command

make install                # perform the installation :pre

Note that The CMAKE_INSTALL_PREFIX=path is not a -D variable like

other LAMMPS settings, but rather an option to the cmake command.  The

path is where to install the LAMMPS files.

TODO: is this sub-section correct?

[Traditional make]:

There is no "install" option in the src/Makefile for LAMMPS.  If you

wish to do this you will need to build, then manually copy the

desired LAMMPS files to the appopriate system directories.

"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

Build LAMMPS with CMake :h3

This page is a short summary of how to use CMake to build LAMMPS.

Specific details on CMake variables that enable LAMMPS build options

are given on the pages linked to from the "Build"_Build.html doc page.

Richard Berger (Temple U) has also written a more comprehensive guide

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

good place to start:

"Bulding LAMMPS using

CMake"_https://github.com/rbberger/lammps/tree/cmake_documentation/cmake

:line

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

create a Makefile.  Then use the standard make command to build

LAMMPS, which uses the created Makefile.

mkdir mydir; cd mydir                  # create a new dir for build          

cmake ~/lammps/cmake \[options ...\]   # command-line version

ccmake ~/lammps/cmake                  # curses version (terminal-style menu)

cmake-gui ~/lammps/cmake               # GUI version

make                                   # traditional make command

make install                           # optional, copy LAMMPS executable & library elsewhere :pre

The make command will compile and link LAMMPS, producing the

executable lmp and the library liblammps.a in mydir.

If your machine has multiple cores (most do), using a command like

"make -j" will be much faster.

:line

There are 3 variants of CMake: a command-line verison, a curses

version (teminal-style menu), and a GUI version.  You can use any of

them to build LAMMPS.  All the versions produce a Makefile as their

output.  See more details on each below.

You can specify a variety of options with any of the 3 versions, which

affect how the build is performed and what is included in the LAMMPS

executable.  Links to pages explaining all the options are listed on

the "Build"_Build.html doc page.

Perform the build in a new directory you create.  It can be a sub-dir

within lammps/cmake or anywhere you wish.  You can perform separate

builds, with different options, in as many directories as you like.

All the auxiliary files created by the build (executable, object

files, log files, etc) are stored in that directory or sub-directories

within it that CMake creates.

NOTE: To perform a CMake build, no packages can be installed in the

LAMMPS src dir.  Likewise no style*.h or a lmpinstalledpkgs.h file can

exist, which are auto-generated by "building LAMMPS via traditional

make"_Build_make.html.  CMake detects if this is not the case and

generates an error, telling you to type "make no-all purge" in the src

directory to un-install all packages.  The purge removes all the

auto-generated *.h files.

You must have CMake version 2.8 or later on your system to build

LAMMPS.  If you include the GPU package, version 3.2 or later is

required.  Installation instructions for CMake are below.

After the initial build, if you edit LAMMPS source files, or add your

own new files to the source directory, you can just re-type make from

your build directory and it will re-compile only the files that have

changed.  If you want to change CMake options, you can remove the

cache file CMakeCache.txt in the build directory and start over.  Or

you can run cmake again from the same build directory and alter

various options; see details below.

:line

[Command-line version of CMake]:

cmake \[options ...\] ~/lammps/cmake      # build from any dir

cmake \[options ...\] ..                  # build from lammps/cmake/newdir :pre

The cmake command takes one required argument, which is the LAMMPS

cmake directory which contains the CMakeLists.txt file.

The argument can be preceeded or followed by various CMake

command-line options.  Several useful ones are:

CAKE_INSTALL_PREFIX=path  # where to install LAMMPS executable/lib if desired

CMAKE_BUILD_TYPE=type     # type = Release or Debug

-G output                 # style of output CMake generates

-DVARIABLE=value          # setting for a LAMMPS feature to enable

-D VARIABLE=value         # ditto, but cannot come after CMakeLists.txt dir

All the LAMMPS-specific -D variables that a LAMMPS build supports are

described on the pages linked to from the "Build"_Build.html doc page.

All of these variable names are upper-case and their values are

lower-case, e.g. -D LAMMPS_SIZES=smallbig.  For boolean values, any of

these forms can be used: yes/no, on/off, 1/0.

By default CMake generates a Makefile to perform the LAMMPS build.

Alternate forms of build info can be generated via the -G switch,

e.g. Visual Studio on a Windows machine.  Type "cmake --help" to see

the "Generator" styles of output your system supports.

NOTE: When CMake runs, it prints configuration info to the screen.

You should scan this to verify all the features you requested were

enabled, including packages.  You can also see what compiler and

compile options will be used for the build.  Any errors will also be

flagged, e.g. mis-typed variable names or variable values.

CMake creates a CMakeCache.txt file when it runs.  This stores all the

settings, so that running CMake again from the same directory will

inherit those settings.

TODO: explain how to change settings on a subsequent cmake in the same

build dir.  In that case is "." the final arg of cmake?

[Curses version (terminal-style menu) of CMake]:

ccmake ~/lammps/cmake :pre

TODO: give brief explanation of how to find and toggle options, how to

perform the generate, how to use it multiple times.

[GUI version of CMake]:

cmake-gui ~/lammps/cmake :pre

TODO: give brief explanation of how to find and toggle options, how to

perform the generate, how to use it multiple times.

:line

[Installing CMake]

Check if your machine already has CMake installed:

which cmake             # do you have it?

which cmake3            # version 3 may have this name

cmake --version         # what specific version you have :pre

On clusters or supercomputers which use modules to manage software

packages, do this:

module list            # is a cmake module is already loaded

module avail           # is a cmake module available?

module load cmake3     # load cmake module with appropriate name :pre

If you do not have CMake or a new enough version, you can install it

as follows:

TODO: give install instructions for Linux, Mac, Windows

"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS

Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

Link LAMMPS as a library to another code :h3

LAMMPS can be used as a library by another application, including

Python scripts.  The files src/library.cpp and library.h define the

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

library"_Howto_library.html doc page for a description of the

interface and how to extend it for your needs.

The "Build basics"_Build_basics.html doc page explains how to build

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

these 2 files:

liblammps.so      # shared library

liblammps.a       # static library

:line

[Link with LAMMPS as a static library]:

The calling application can link to LAMMPS as a static library with a

link command like this:

g++ caller.o -L/home/sjplimp/lammps/src -llammps -o caller

The -L argument is the path to where the liblammps.a file is.  The

-llammps argument is shorthand for the file liblammps.a.

:line

[Link with LAMMPS as a shared library]:

If you wish to link to liblammps.so, the operating system finds shared

libraries to load at run-time using the environment variable

LD_LIBRARY_PATH.  To enable this you can do one of two things:

(1) Copy the liblammps.so file to a location the system can find it,

such as /usr/local/lib.  I.e. a directory already listed in your

LD_LIBRARY_PATH variable.  You can type

printenv LD_LIBRARY_PATH :pre

to see what directories are in that list.

(2) Add the LAMMPS src directory (or the directory you perform CMake

build in) to your LD_LIBRARY_PATH, so that the current version of the

shared library is always available to programs that use it.

For the csh or tcsh shells, you would add something like this to your

~/.cshrc file:

setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre

:line

[Calling the LAMMPS library]:

Either flavor of library (static or shared) allows one or more LAMMPS

objects to be instantiated from the calling program.

When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS

namespace; you can safely use any of its classes and methods from

within the calling code, as needed.

When used from a C or Fortran program, the library has a simple

C-style interface, provided in src/library.cpp and src/library.h.

See the "Python library"_Python_library.html doc page for a

description of the Python interface to LAMMPS, which wraps the C-style

interface.

See the sample codes in examples/COUPLE/simple for examples of C++ and

C and Fortran codes that invoke LAMMPS thru its library interface.

Other examples in the COUPLE directory use coupling ideas discussed on

the "Howto couple"_Howto_couple.html doc page.