jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

more updates to Build doc page

This commit is contained in:
Steven J. Plimpton 2018-08-10 15:04:33 -06:00
parent b33452040a
commit 907b061e0b
7 changed files with 510 additions and 491 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
doc/src/Build_basics.txt
View File

@ -37,16 +37,16 @@ without MPI. It can also be built with support for OpenMP threading
-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.
The executable created by CMake (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
make mybox :pre # uses Makefile.mybox to produce lmp_mybox :pre
Serial build (see src/MAKE/Makefile.serial):
@ -81,15 +81,15 @@ 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.
If you are installing MPI yourself, we recommend MPICH2 from Argonne
National Laboratory 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
@ -100,22 +100,22 @@ be compiled for using OpenMP threading.
However, there are a few commands in LAMMPS that have native OpenMP
support. These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and
USER-DPD packages. In addition some commands support OpenMP threading
not directly, but through the libraries they are interfacing to:
e.g. LATTE and USER-COLVARS. 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.
USER-DPD packages. In addition some packages support OpenMP threading
indirectly through the libraries they interface to: e.g. LATTE and
USER-COLVARS. 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.
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 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 the conventional makefiles, the CCFLAGS and LINKFLAGS variables
need to include the compiler flag, that enables OpenMP. For GNU
compilers, this flag is -fopenmp, for (recent) Intel compilers,
it is -qopenmp. Please refer to the documentation of your compiler,
if you are using a different compiler to compile 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.
:line
@ -142,7 +142,7 @@ simply loading the appropriate module before building LAMMPS.
-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
By default CMake will use a compiler it finds and it will add
optimization flags appropriate to that compiler and any "accelerator
packages"_Speed_packages.html you have included in the build.
@ -161,11 +161,11 @@ 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
as to which 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.
also in the Cmake output. You should check to insure you are using
the compiler and optimization flags are the ones you want.
[Makefile.machine settings]:
@ -208,20 +208,16 @@ 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
library. The LAMMPS 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.
from Python via its library interface.
[CMake variables]:
@ -232,7 +228,7 @@ from Python.
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.
shared library named liblammps.so.
[Traditional make]:
@ -241,8 +237,9 @@ 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.
The two library builds also create generic soft links, named
liblammps.a and liblammps.so, which point to the liblammps_machine
files.
[CMake and make info]:
@ -250,16 +247,16 @@ 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.
the lib/packages directroy, 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
Argonne National Lab, as a shared library in the default
/usr/local/lib location:
:link(mpich,http://www-unix.mcs.anl.gov/mpi)
@ -280,9 +277,10 @@ Build the LAMMPS documentation :h3,link(doc)
-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.
This will create the HTML doc pages within the CMake build directory.
The reason to do this is if you want to "install" LAMMPS on a system
after the CMake build via "make install", and include the doc pages in
the install.
[Traditional make]:
@ -291,7 +289,7 @@ 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
you can browse them locally on your system. Type "make" from the
lammps/doc dir to see other options.
:line
@ -301,8 +299,8 @@ 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.
that you may need super-user priveleges (e.g. sudo) if the directory
you want to copy files to is protected.
[CMake variable]:
@ -313,5 +311,5 @@ make install # perform the installation into prefix :pre
[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.
wish to do this you will need to first build LAMMPS, then manually
copy the desired LAMMPS files to the appropriate system directories.

125
doc/src/Build_cmake.txt
View File

@ -10,7 +10,7 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
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
Details on CMake variables that enable specific 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
@ -19,15 +19,17 @@ good place to start:
"Bulding LAMMPS using
CMake"_https://github.com/lammps/lammps/blob/master/cmake/README.md
:line
Building LAMMPS with CMake is a two-step process. First you use CMake
to create a build environment in a new folder. On Linux systems, this
will be based on makefiles for use with make. Then you use the make
command to build LAMMPS, which uses the created Makefile(s). Example:
to create a build environment in a new directory. On Linux systems,
this will be based on makefiles for use with make. Then you use the
make command to build LAMMPS, which uses the created
Makefile(s). Example:
cd lammps # change to the folder with the LAMMPS sources
mkdir build; cd build # create a new dir for build
cd lammps # change to the LAMMPS distribution directory
mkdir build; cd build # create a new directory (folder) for build
cmake ../cmake \[options ...\] # configuration with (command-line) cmake
make # compilation :pre
@ -38,12 +40,12 @@ executable called "lmp" and a library called "liblammps.a" in the
"build" folder.
If your machine has multiple CPU cores (most do these days), using a
command like "make -jN" (with N being the number of available local CPU
cores) can be much faster. If you plan to do development on LAMMPS or
may need to recompile LAMMPS repeatedly, the installation of the ccache
(= Compiler Cache) software may speed up compilation even more.
command like "make -jN" (with N being the number of available local
CPU cores) can be much faster. If you plan to do development on
LAMMPS or need to recompile LAMMPS repeatedly, installation of the
ccache (= Compiler Cache) software may speed up compilation even more.
After compilation, you optionally, can copy the LAMMPS executable and
After compilation, you can optionally copy the LAMMPS executable and
library into your system folders (by default under /usr/local) with:
make install # optional, copy LAMMPS executable & library elsewhere :pre
@ -61,26 +63,26 @@ 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.
You must perform the CMake build system generation and compilation in
a new directory you create. It can be anywhere on your local machine;
in the following, we will assume, that you are building in the folder
"lammps/build". You can perform separate builds independently at the
same time and with different options, for as long as you put each of
them into a separate directory. There can be as many build 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.
You must perform the CMake build system generation and compilation in
a new directory you create. It can be anywhere on your local machine.
In these Build pages we assume that you are building in a directory
called "lammps/build". You can perform separate builds independently
with different options, so long as you perform each of them in a
separate directory you create. All the auxiliary files created by one
build process (executable, object files, log files, etc) are stored in
this directory or sub-directories within it that CMake creates.
NOTE: To perform a CMake build, no packages may be installed or a build
attempted in the LAMMPS src folder using the "conventional build
procedure"_Build_make.html. CMake detects if this is the case and
NOTE: To perform a CMake build, no packages can be installed or a
build been previously attempted in the LAMMPS src directory by using
"make" commands to "perform a conventional LAMMPS
build"_Build_make.html. CMake detects if this is 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.
directory to un-install all packages. The purge removes all the *.h
files auto-generated by make.
You must have CMake version 2.8 or later on your system to build LAMMPS.
If you include the GPU or KOKKOS packages, CMake version 3.2 or later is
required. Installation instructions for CMake are below.
You must have CMake version 2.8 or later on your system to build
LAMMPS. If you include the GPU or KOKKOS packages, CMake 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
@ -104,10 +106,10 @@ The argument can be preceeded or followed by various CMake
command-line options. Several useful ones are:
-D CMAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired
-D 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
-D 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 :pre
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.
@ -115,17 +117,18 @@ 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.
On Unix/Linux CMake generates a Makefile by default 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, Xcode on MacOS or
KDevelop on Linux. Type "cmake --help" to see the "Generator" styles
of output your system supports.
On Unix/Linux machines, CMake generates a Makefile by default 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,
Xcode on MacOS, or KDevelop on Linux. 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 review this to verify all the features you requested were
enabled, including packages. You can also see what compilers and
compile options will be used for the build. Any errors will also be
flagged, e.g. mis-typed variable names or variable values.
compile options will be used for the build. Any errors in CMake
variable syntax 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 when running CMake again you can use the current
@ -135,33 +138,39 @@ settings will be inherited unless the CMakeCache.txt file is removed.
If you later want to change a setting you can rerun cmake in the build
directory with different setting. Please note that some automatically
detected variables will not change their value. In these cases it is
usually better to start with a fresh build directory.
detected variables will not change their value when you rerun cmake.
In these cases it is usually better to first remove all the
files/directories in the build directory, or start with a fresh build
directory.
:line
[Curses version (terminal-style menu) of CMake]:
ccmake ../cmake :pre
You initiate the configuration and build environment generation steps
separately. For the first you have to type [c], for the second you have
to type [g]. You may need to type [c] multiple times, and may be
required to edit some of the entries of CMake configuration variables in
between. Please see the "ccmake
separately. For the first you have to type [c], for the second you
have to type [g]. You may need to type [c] multiple times, and may be
required to edit some of the entries of CMake configuration variables
in between. Please see the "ccmake
manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for
more information.
:line
[GUI version of CMake]:
cmake-gui ../cmake :pre
You initiate the configuration and build environment generation steps
separately. For the first you have to click on the [Configure] button,
for the second you have to click on the [Generate] button. You may need
to click on [Configure] multiple times, and may be required to edit some
of the entries of CMake configuration variables in between. Please see
the "cmake-gui
manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html for
more information.
for the second you have to click on the [Generate] button. You may
need to click on [Configure] multiple times, and may be required to
edit some of the entries of CMake configuration variables in between.
Please see the "cmake-gui
manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html
for more information.
:line
@ -176,13 +185,13 @@ cmake --version # what specific version you have :pre
On clusters or supercomputers which use environment modules to manage
software packages, do this:
module list # is a cmake module is already loaded
module list # is a cmake module already loaded?
module avail # is a cmake module available?
module load cmake3 # load cmake module with appropriate name :pre
Most Linux distributions offer precompiled cmake packages through their
package management system. If you do not have CMake or a new enough
version, you can download the latest version at
"https://cmake.org/download/"_https://cmake.org/download/. Instructions
on how to install it on various platforms can be found
"here"_https://cmake.org/install/.
Most Linux distributions offer precompiled cmake packages through
their package management system. If you do not have CMake or a new
enough version, you can download the latest version at
"https://cmake.org/download/"_https://cmake.org/download/.
Instructions on how to install it on various platforms can be found
"on this page"_https://cmake.org/install/.

562
doc/src/Build_extras.txt
View File

@ -10,14 +10,18 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
Packages with extra build options :h3
When building with some packages, additional steps may be required,
beyond just "-D PKG_NAME=yes" for CMake or "make yes-name" for make,
in addition to:
-D PKG_NAME=yes # CMake
make yes-name # make :pre
as described on the "Build_package"_Build_package.html doc page.
For a CMake build there may be additional variables that can be 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 be downloaded and built, and you may need to tell LAMMPS where it
is found on your system.
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.
@ -48,7 +52,7 @@ This is the list of packages that may require additional steps.
:line
:line
COMPRESS package
COMPRESS package :h4,link(compress)
To build with this package you must have the zlib compression library
available on your system.
@ -70,9 +74,8 @@ name.
GPU package :h4,link(gpu)
To build with this package, you need to choose options for precision
and which GPU hardware to build for. To build with make you also need
to build the library in lib/gpu first.
To build with this package, you must choose options for precision and
which GPU hardware to build for.
[CMake build]:
@ -80,9 +83,9 @@ to build the library in lib/gpu first.
-D GPU_PREC=value # precision setting
# value = single or mixed (default) or double
-D OCL_TUNE=value # hardware choice for GPU_API=opencl
# generic (default) or intel (Intel CPU) or phi (Intel Xeon Phi) or fermi (NVIDIA) or kepler (NVIDIA) or cypress (NVIDIA)
# generic (default) or intel (Intel CPU) or phi (Intel Xeon Phi) or fermi, kepler, cypress (NVIDIA)
-D GPU_ARCH=value # hardware choice for GPU_API=cuda
# value = sm20 (Fermi) or sm30 or sm (Kepler) or sm50 (Maxwell) or sm60 (Pascal) or sm70 (Volta)
# value = sm20 (Fermi) or sm30 (Kepler) or sm50 (Maxwell) or sm60 (Pascal) or sm70 (Volta)
# default is Cuda-compiler dependent, but typically Fermi
-D CUDPP_OPT=value # optimization setting for GPU_API=cudea
# enables CUDA Performance Primitives Optimizations
@ -90,12 +93,13 @@ to build the library in lib/gpu first.
[Traditional make]:
You must first 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.
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
@ -111,8 +115,8 @@ 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 -h, -a, -p, -e switches, and
also save a copy of the new Makefile, if desired:
Makefile.machine you start from via the -h, -a, -p, -e switches, and
also save a copy of the new Makefile if desired:
CUDA_HOME = where NVIDIA CUDA software is installed on your system
CUDA_ARCH = what GPU hardware you have (see help message for details)
@ -127,10 +131,10 @@ 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, then re-install it and re-build LAMMPS.
This is because the compilation of files in the GPU package use the
library settings from the lib/gpu/Makefile.machine used to build the
GPU library.
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.
:line
@ -159,14 +163,13 @@ package?" page.
[CMake build]:
-D PKG_KIM=on # enable KIM package
-D DOWNLOAD_KIM=value # download OpenKIM API v1 for build, value = off (default) or on
-D KIM_LIBRARY=path # (only needed if at custom location) path to KIM shared library
-D KIM_INCLUDE_DIR=path # (only needed if at custom location) path to KIM include directory :pre
-D KIM_LIBRARY=path # path to KIM shared library (only needed if a custom location)
-D KIM_INCLUDE_DIR=path # path to KIM include directory (only needed if a custom location) :pre
[Traditional make]:
You can do download and build the KIM library manually if you prefer;
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
step from the lammps/src dir, using a command like these, which simply
invoke the lib/kim/Install.py script with the specified args.
@ -183,35 +186,34 @@ make lib-kim args="-p /usr/local/kim-api -a EAM_Dynamo_Ackland_W__MO_14162719659
KOKKOS package :h4,link(kokkos)
To build with this package, you have to choose a Kokkos setting for
either CPU (multi-threading via OpenMP) or KNL (OpenMP) or GPU (Cuda)
support.
To build with this package, you must choose which hardware you want to
build for, either CPUs (multi-threading via OpenMP) or KNLs (OpenMP)
or GPUs (Cuda).
[CMake build]:
TODO: how to do this, how to select CPU vs KNL vs GPU, and other
traditional make settings
TODO: how to do this, how to select CPU vs KNL vs GPU, and specify
the particular flavor of hardware: e.g. HSW vs BWL
[Traditional make]:
how to choose these 3 things: mode archgpu=N archcpu=SNB
mode = omp or cuda or phi (def = KOKKOS_DEVICES setting in Makefile )
archgpu = number like 35 (Kepler) or 21 (Fermi) (def = none)
sets KOKKOS_ARCH for GPU to appropriate value
archcpu = SNB or HSW or BGQ or Power7 or Power8 (def = none)
for CPU = SandyBridge, Haswell, BGQ, Power7, Power8
sets KOKKOS_ARCH for GPU to appropriate value :pre
For the KOKKOS package, you have 3 choices when building. You can
build with either CPU or KNL or GPU support. Each choice requires
additional settings in your Makefile.machine for the 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:
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = HSW # HSW = Haswell, SNB = SandyBridge, BDW = Broadwell, etc :pre
KOKKOS_ARCH = HSW :pre
Possible values are:
HSW for Intel Haswell
SNB for Intel SandyBridge
BDW for Intel Broadwell
BGQ for IBM BlueGene Q
Power7 for IBM
Power8 for IBM :ul
For Intel KNLs using OpenMP:
@ -227,21 +229,13 @@ KOKKOS_ARCH = Kepler37,Power8 # K80 hosted by an IBM Power8, etc :pre
For GPUs, you also need these 2 lines in your Makefile.machine before
the CC line is defined, in this case for use with OpenMPI mpicxx. The
2 lines define a nvcc wrapper compiler, which will use nvcc for
compiling CUDA files or use a C++ compiler for non-Kokkos, non-CUDA
compiling CUDA files and use a C++ compiler for non-Kokkos, non-CUDA
files.
KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd)
export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper
CC = mpicxx :pre
Once you have an appropriate Makefile.machine, you can
install/un-install the package and build LAMMPS in the usual manner.
Note that you cannot build one executable to run on multiple hardware
targets (CPU or KNL or GPU). You need to build LAMMPS once for each
hardware target, to produce a separate executable. Also note that we
do not recommend building with other acceleration packages installed
(GPU, OPT, USER-INTEL, USER-OMP) when also building with KOKKOS.
:line
LATTE package :h4,link(latte)
@ -251,16 +245,16 @@ library.
[CMake build]:
-D PKG_LATTE=on # enable LATTE package
-D DOWNLOAD_LATTE=value # download LATTE for build, value = off (default) or on
-D LATTE_LIBRARY=path # (only needed if at custom location) path to LATTE shared library :pre
-D LATTE_LIBRARY=path # path to LATTE shared library (only needed if a custom location) :pre
[Traditional make]:
You can do this 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 args:
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
args:
make lib-latte # print help message
make lib-latte args="-b" # download and build in lib/latte/LATTE-master
@ -271,7 +265,7 @@ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
Note that 3 symbolic (soft) links, "includelink" and "liblink" and
"filelink.o", are created in lib/latte to point into the LATTE home
dir. When LAMMPS builds in src it will use these links. You should
dir. When LAMMPS itself is built it will use these links. You should
also check that the Makefile.lammps file you create is appropriate for
the compiler you use on your system to build LATTE.
@ -281,23 +275,23 @@ MEAM package :h4,link(meam)
NOTE: the use of the MEAM package is discouraged, as it has been
superseded by the USER-MEAMC package, which is a direct translation of
the Fortran code in the MEAM library to C++. The code in USER-MEAMC is
functionally completely equivalent, fully supports use in "pair_style
hybrid"_pair_hybrid.html, and has optimizations (e.g. no translations of
data structures or neighbor lists are required) that make it
significantly faster than the MEAM package.
the Fortran code in the MEAM library to C++. The code in USER-MEAMC
should be functionally equivalent to the MEAM package, fully supports
use of "pair_style hybrid"_pair_hybrid.html (the MEAM packaged doesn
not), and has optimizations that make it significantly faster than the
MEAM package.
[CMake build]:
-D PKG_MEAM=on # enable MEAM package :pre
No additional settings are needed besides "-D PKG_MEAM=yes".
[Traditional make]:
Before building LAMMPS with this package, you must first build the
MEAM library in lib/meam. You can do this manually if you prefer;
follow the instructions in lib/meam/README. You can also do it in one
step from the lammps/src dir, using a command like these, which simply
invoke the lib/meam/Install.py script with the specified args:
Before building LAMMPS, you must build the MEAM library in lib/meam.
You can build the MEAM library manually if you prefer; follow the
instructions in lib/meam/README. You can also do it in one step from
the lammps/src dir, using a command like these, which simply invoke
the lib/meam/Install.py script with the specified args:
make lib-meam # print help message
make lib-meam args="-m mpi" # build with default Fortran compiler compatible with your MPI library
@ -318,28 +312,24 @@ file.
MSCG package :h4,link(mscg)
Before building LAMMPS with this package, you must first download and
build the MS-CG library.
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.
[CMake build]:
-D PKG_MSCG=on # enable MSCG package
-D DOWNLOAD_MSCG=value # download MSCG for build, value = off (default) or on
-D MSCG_LIBRARY=path # (only needed if at custom location) path to MSCG shared library
-D MSCG_INCLUDE_DIR=path # (only needed if at custom location) path to MSCG include directory :pre
-D MSCG_LIBRARY=path # path to MSCG shared library (only needed if a custom location)
-D MSCG_INCLUDE_DIR=path # path to MSCG include directory (only needed if a custom location) :pre
[Traditional make]:
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.
Assuming these libraries are in place, you can do the download and
build of MS-CG 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:
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:
make lib-mscg # print help message
make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
@ -348,9 +338,10 @@ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-releas
# with the settings compatible with "make mpi"
make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release :pre
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.
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.
:line
@ -358,16 +349,14 @@ OPT package :h4,link(opt)
[CMake build]:
-D PKG_OPT=on # enable OPT package :pre
No additional settings are needed besides "-D PKG_OPT=yes".
[Traditional make]:
NOTE: The compile flag "-restrict" must be used to build LAMMPS with
the OPT package when using Intel compilers. It should be added to
the CCFLAGS line of your Makefile.machine. See Makefile.opt in
src/MAKE/OPTIONS for an example.
CCFLAGS: add -restrict for Intel compilers :ul
The compile flag "-restrict" must be used to build LAMMPS with the OPT
package when using Intel compilers. It should be added to the CCFLAGS
line of your Makefile.machine. See src/MAKE/OPTIONS/Makefile.opt for
an example.
:line
@ -375,15 +364,15 @@ POEMS package :h4,link(poems)
[CMake build]:
-D PKG_POEMS=on # enable POEMS package :pre
No additional settings are needed besides "-D PKG_OPT=yes".
[Traditional make]:
Before building LAMMPS with this package, you must first 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 dir, using a command like these, which
simply invoke the lib/poems/Install.py script with the specified args:
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
dir, using a command like these, which simply invoke the
lib/poems/Install.py script with the specified args:
make lib-poems # print help message
make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
@ -402,47 +391,52 @@ a corresponding Makefile.lammps.machine file.
PYTHON package :h4,link(python)
Building with the PYTHON package assumes you have a Python shared
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 the
version, 2.6 or later. Python 3 is not yet supported. See
lib/python/README for more details.
[CMake build]:
-D PKG_PYTHON=on # enable PYTHON package
-D PYTHON_EXECUTABLE=path # path to Python executable which should be used :pre
-D PYTHON_EXECUTABLE=path # path to Python executable to use :pre
If you want to use a different Python version other than your system default, you can
either create a virtualenv, activate it and then run cmake or use the PYTHON_EXECUTABLE
variable to specify which Python interpreter should be used. Please note that you will
also need to have the development headers installed, e.g. python2-devel.
Without this setting, CMake will you your system default Python. 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.
[Traditional make]:
The build uses the lib/python/Makefile.lammps file in the compile/link
process. You should only need to create a new Makefile.lammps.* file
(and copy it to Makefile.lammps) if the LAMMPS build fails.
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.
:line
REAX package :h4,link(reax)
NOTE: the use of the REAX package is discouraged, as it is no longer
maintained. Please use the USER-REAX package instead, and possibly the
KOKKOS enabled variant of that, which has a more robust memory
management.
NOTE: the use of the REAX package and its "pair_style
reax"_pair_reax.html command is discouraged, as it is no longer
maintained. Please use the USER-REAXC package and its "pair_style
reax/c"_pair_reaxc.html command instead, and possibly its KOKKOS
enabled variant (pair_style reax/c/kk), which has a more robust memory
management. See the "pair_style reax/c"_pair_reaxc.html doc page for
details.
[CMake build]:
-D PKG_REAX=on # enable REAX package :pre
No additional settings are needed besides "-D PKG_REAX=yes".
[Traditional make]:
Before building LAMMPS with this package, you must first build the
REAX library in lib/reax. You can do this manually if you prefer;
follow the instructions in lib/reax/README. You can also do it in one
step from the lammps/src dir, using a command like these, which simply
invoke the lib/reax/Install.py script with the specified args:
Before building LAMMPS, you must build the REAX library in lib/reax.
You can do this manually if you prefer; follow the instructions in
lib/reax/README. You can also do it in one step from the lammps/src
dir, using a command like these, which simply invoke the
lib/reax/Install.py script with the specified args:
make lib-reax # print help message
make lib-reax args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
@ -463,17 +457,20 @@ file.
VORONOI package :h4,link(voronoi)
To build with this package, you must download and build the "Voro++
library"_voro_home.
:link(voro_home,http://math.lbl.gov/voro++)
[CMake build]:
-D PKG_VORONOI=on # enable VORONOI package
-D DOWNLOAD_VORO=value # download VORO for build, value = off (default) or on
-D DOWNLOAD_VORO=value # download Voro++ for build, value = off (default) or on
-D VORO_LIBRARY=path # (only needed if at custom location) path to VORO shared library
-D VORO_INCLUDE_DIR=path # (only needed if at custom location) path to VORO include directory :pre
[Traditional make]:
Before building LAMMPS with this package, you must first download and
build the Voro++ library. You can do this manually if you prefer;
You can download and build the Voro++ library manually if you prefer;
follow the instructions in lib/voronoi/README. You can also do it in
one step from the lammps/src dir, using a command like these, which
simply invoke the lib/voronoi/Install.py script with the specified
@ -494,18 +491,20 @@ the lib/voronoi/Makefile.lammps file.
USER-ATC package :h4,link(user-atc)
The USER-ATC package requires the MANYBODY package also be installed.
[CMake build]:
-D PKG_USER-ATC=on # enable USER-ATC package
-D PKG_MANYBODY=on # requires MANYBODY package :pre
No additional settings are needed besides "-D PKG_REAX=yes" and "-D
PKG_MANYBODY=yes".
[Traditional make]:
Before building LAMMPS with this package, you must first build the ATC
library in lib/atc. You can do this manually if you prefer; follow
the instructions in lib/atc/README. You can also do it in one step
from the lammps/src dir, using a command like these, which simply
invoke the lib/atc/Install.py script with the specified args:
Before building LAMMPS, you must build the ATC library in lib/atc.
You can do this manually if you prefer; follow the instructions in
lib/atc/README. You can also do it in one step from the lammps/src
dir, using a command like these, which simply invoke the
lib/atc/Install.py script with the specified args:
make lib-atc # print help message
make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
@ -523,30 +522,29 @@ file.
Note that the Makefile.lammps file has settings for the BLAS and
LAPACK linear algebra libraries. As explained in lib/atc/README these
can either exist on your system, or you can use the files provided in
lib/linalg. In the latter case you also need to build the library
in lib/linalg with a command like these:
lib/linalg. In the latter case you also need to build the library in
lib/linalg with a command like these:
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
make lib-linalg args="-m gfortran" # build with GNU Fortran compiler :pre
:line
USER-AWPMD package :h4,link(user-awpmd)
[CMake build]:
-D PKG_USER-AWPMD=on # enable USER-AWPMD package :pre
No additional settings are needed besides "-D PKG_USER-AQPMD=yes".
[Traditional make]:
Before building LAMMPS with this package, you must first build the
AWPMD library in lib/awpmd. You can do this manually if you prefer;
follow the instructions in lib/awpmd/README. You can also do it in
one step from the lammps/src dir, using a command like these, which
simply invoke the lib/awpmd/Install.py script with the specified args:
Before building LAMMPS, you must build the AWPMD library in lib/awpmd.
You can do this manually if you prefer; follow the instructions in
lib/awpmd/README. You can also do it in one step from the lammps/src
dir, using a command like these, which simply invoke the
lib/awpmd/Install.py script with the specified args:
make lib-awpmd # print help message
make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
@ -578,16 +576,15 @@ USER-COLVARS package :h4,link(user-colvars)
[CMake build]:
-D PKG_USER-COLVARS=on # enable USER-COLVARS package :pre
No additional settings are needed besides "-D PKG_USER-COLVARS=yes".
[Traditional make]:
Before building LAMMPS with this package, you must first build the
COLVARS library in lib/colvars. You can do this manually if you
prefer; follow the instructions in lib/colvars/README. You can also
do it in one step from the lammps/src dir, using a command like these,
which simply invoke the lib/colvars/Install.py script with the
specified args:
Before building LAMMPS, you must build the COLVARS library in
lib/colvars. You can do this manually if you prefer; follow the
instructions in lib/colvars/README. You can also do it in one step
from the lammps/src dir, using a command like these, which simply
invoke the lib/colvars/Install.py script with the specified args:
make lib-colvars # print help message
make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
@ -606,25 +603,27 @@ a corresponding Makefile.lammps.machine file.
USER-H5MD package :h4,link(user-h5md)
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.
[CMake build]:
-D PKG_USER-H5MD=on # enable USER-H5MD package :pre
No additional settings are needed besides "-D PKG_USER-H5MD=yes".
This will autodetect the H5MD library if it is installed on your system at standard locations.
Several advanced H5MD options exist if you need to specify where it was installed. Run with
ccmake to see these options.
This should autodetect 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.
[Traditional make]:
Note that to follow these steps to compile and link to the CH5MD
library, you need the standard HDF5 software package installed on your
system, which should include the h5cc compiler and the HDF5 library.
Before building LAMMPS with this package, you must first build the
CH5MD library in lib/h5md. You can do this manually if you prefer;
follow the instructions in lib/h5md/README. You can also do it in one
step from the lammps/src dir, using a command like these, which simply
invoke the lib/h5md/Install.py script with the specified args:
Before building LAMMPS, you must build the CH5MD library in lib/h5md.
You can do this manually if you prefer; follow the instructions in
lib/h5md/README. You can also do it in one step from the lammps/src
dir, using a command like these, which simply invoke the
lib/h5md/Install.py script with the specified args:
make lib-h5md # print help message
make lib-hm5d args="-m h5cc" # build with h5cc compiler :pre
@ -641,84 +640,79 @@ file.
USER-INTEL package :h4,link(user-intel)
To build with this package, you must choose which hardware you want to
build for, either Intel CPUs or Intel KNLs. 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 "Speed
intel"_Speed_intel.html doc page.
[CMake build]:
TODO: how to choose CPU vs KNL ??
TODO: How do you choose CPU vs KKL, so that CMake knows
which flags to add to CCFLAGS ??
[Traditional make]:
For the USER-INTEL package, you have 2 choices when building. You can
build with either CPU or KNL support. Each choice requires additional
settings in your Makefile.machine for CCFLAGS and LINKFLAGS and
optimized malloc libraries. See the
src/MAKE/OPTIONS/Makefile.intel_cpu and src/MAKE/OPTIONS/Makefile.knl
files for examples.
Choose which hardware to compile for in Makefile.machine via the
following settings. See src/MAKE/OPTIONS/Makefile.intel_cpu* and
Makefile.knl files for examples.
For CPUs:
OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload \
-fno-alias -ansi-alias -restrict $(OPTFLAGS)
-fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc -ltbbmalloc_proxy :pre
LIB = -ltbbmalloc :pre
For KNLs:
OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload \
-fno-alias -ansi-alias -restrict $(OPTFLAGS)
-fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc :pre
Once you have an appropriate Makefile.machine, you can
install/un-install the package and build LAMMPS in the usual manner.
Note that you cannot build one executable to run on multiple hardware
targets (Intel CPUs or KNL). You need to build LAMMPS once for each
hardware target, to produce a separate executable.
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 "Speed intel"_Speed_intel.html doc page.
:line
USER-MOLFILE package :h4,link(user-molfile)
[CMake build]:
-D PKG_USER-MOLFILE=on # enable USER-MOLFILE package :pre
No additional settings are needed besides "-D PKG_USER-MOLFILE=yes".
[Traditional make]:
Note that the lib/molfile/Makefile.lammps file has a setting for a
dynamic loading library libdl.a that should is typically present on
all systems, which is required for LAMMPS to link with this package.
If the setting is not valid for your system, you will need to edit the
Makefile.lammps file. See lib/molfile/README and
lib/molfile/Makefile.lammps for details.
The lib/molfile/Makefile.lammps file has a setting for a dynamic
loading library libdl.a that is typically present on all systems. It
is required for LAMMPS to link with this package. If the setting is
not valid for your system, you will need to edit the Makefile.lammps
file. See lib/molfile/README and lib/molfile/Makefile.lammps for
details.
:line
USER-NETCDF package :h4,link(user-netcdf)
To build with this package you must have the NetCDF library installed
on your system.
[CMake build]:
-D PKG_USER-NETCDF=on # enable USER-NETCDF package :pre
No additional settings are needed besides "-D PKG_USER-NETCDF=yes".
This will autodetect the NETCDF library if it is installed on your
system at standard locations. Several advanced NETCDF options exist,
for example if you need to specify where it was installed. Best use
the ccmake (console) or cmake-gui (graphical) tools to see these
options and set them interactively from their user interfaces.
This should autodetect 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.
[Traditional make]:
Note that to follow these steps, you need the standard NetCDF software
package installed on your system. The lib/netcdf/Makefile.lammps file
has settings for NetCDF include and library files that LAMMPS needs to
compile and linkk with this package. If the settings are not valid
for your system, you will need to edit the Makefile.lammps file. See
lib/netcdf/README for details.
The lib/netcdf/Makefile.lammps file has settings for NetCDF include
and library files which LAMMPS needs to build with this package. If
the settings are not valid for your system, you will need to edit the
Makefile.lammps file. See lib/netcdf/README for details.
:line
@ -726,47 +720,53 @@ USER-OMP package :h4,link(user-omp)
[CMake build]:
-D PKG_USER-OMP=on # enable USER-OMP package
-D BUILD_OMP=on # enable OpenMP support :pre
No additional settings are needed besides "-D PKG_USER-OMP=yes".
TODO: Is "-D BUILD_OMP=yes" also needed? Or is it enabled
if PKG_USER-OMP is set?
[Traditional make]:
CCFLAGS: add -fopenmp (or -qopenmp -restrict when using Intel compilers on Linux)
LINKFLAGS: add -fopenmp (or -qopenmp when using Intel compilers on Linux) :ul
These compile and link flags must be added to your Makefile.machine file.
See src/MAKE/OPTIONS/Makefile.omp for an example.
For other platforms and compilers, please consult the documentation for the
corresponding compiler.
CCFLAGS: -fopenmp
CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux
LINKFLAGS: -fopenmp
LINKFLAGS: -qopenmp # for Intel compilers on Linux :pre
For other platforms and compilers, consult the OpenMP documentation
for the compiler.
:line
USER-QMMM package :h4,link(user-qmmm)
The LAMMPS executable these steps produce is not yet functional for a
QM/MM simulation. You must also build Quantum ESPRESSO and create a
new executable which links LAMMPS and Quantum ESPRESSO together.
These are steps 3 and 4 described in the lib/qmmm/README file.
Unfortunately, the Quantum ESPRESSO developers keep breaking the
interface that the QM/MM code in LAMMPS is using, so that currently
(Summer 2018) using this feature requires either correcting the
library interface feature in recent Quantum ESPRESSO releases, or
using an outdated version of QE. The last version of Quantum ESPRESSO
known to work with this QM/MM interface in LAMMPS was version 5.4.1
from 2016.
NOTE: The LAMMPS executable these steps produce is not yet functional
for a QM/MM simulation. You must also build Quantum ESPRESSO and
create a new executable (pwqmmm.x) which links LAMMPS and Quantum
ESPRESSO together. These are steps 3 and 4 described in the
lib/qmmm/README file. Unfortunately, the Quantum ESPRESSO developers
keep breaking the interface that the QM/MM code in LAMMPS is using, so
that currently (summer 2018) using this feature requires either
correcting the library interface feature in recent Quantum ESPRESSO
releases, or using an outdated version of QE. The last version of
Quantum ESPRESSO known to work with this QM/MM interface in LAMMPS was
version 5.4.1 from 2016.
[CMake build]:
The CMake build system currently does not support building the
full, QM/MM capable hybrid executable of LAMMPS and QE called
pwqmmm.x. Please use the traditional make procedure.
The CMake build system currently does not support building the full
QM/MM-capable hybrid executable of LAMMPS and QE called pwqmmm.x. You
must use the traditional make build for this package.
[Traditional make]:
Before building LAMMPS with this package, you must first build the
QMMM library in lib/qmmm. You can do this manually if you prefer;
follow the first two steps explained in lib/qmmm/README. You can
also do it in one step from the lammps/src dir, using a command like
these, which simply invoke the lib/qmmm/Install.py script with the
specified args:
Before building LAMMPS, you must build the QMMM library in lib/qmmm.
You can do this manually if you prefer; follow the first two steps
explained in lib/qmmm/README. You can also do it in one step from the
lammps/src dir, using a command like these, which simply invoke the
lib/qmmm/Install.py script with the specified args:
make lib-qmmm # print help message
make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
@ -781,89 +781,95 @@ necessary, you can edit/create a new lib/qmmm/Makefile.machine file
for your system, which should define an EXTRAMAKE variable to specify
a corresponding Makefile.lammps.machine file.
You can then install/un-install the package and build LAMMPS in the
usual manner. After completing the LAMMPS build and compiling Quantum
ESPRESSO with external library support, you can 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.
You can then install QMMM package and build LAMMPS in the usual
manner. After completing the LAMMPS build and compiling Quantum
ESPRESSO with external library support, 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.
:line
USER-QUIP package :h4,link(user-quip)
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.
[CMake build]:
-D PKG_USER-QUIP=on # enable USER-QUIP package
-D QUIP_LIBRARIES=/path/to/libquip.a # set the location of the quip library :pre
-D QUIP_LIBRARIES=path # path to libquip.a (only needed if a custom location)
This will include the USER-QUIP package and tell the build system where
to find the quip library. You have to first follow the steps to compile
and install the QUIP library in the same was as for the traditional
make build process (see below).
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 QUIP_LIBRARIES if CMake cannot find the QUIP library.
[Traditional make]:
Note that to follow these steps to compile and link to the QUIP
library, you must first download and build QUIP on your systems. 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. Note that it requires setting two
environment variables, QUIP_ROOT and QUIP_ARCH, which will be accessed
by the lib/quip/Makefile.lammps file which is used when you compile and
link LAMMPS with this package. You should only need to edit this file
if the LAMMPS build can not use its settings to successfully build on
your system.
The download/build procedure for the QUIP library, described in
lib/quip/README file requires setting two environment variables,
QUIP_ROOT and QUIP_ARCH. These are accessed by the
lib/quip/Makefile.lammps file which is used when you compile and link
LAMMPS with this package. You should only need to edit
Makefile.lammps if the LAMMPS build can not use its settings to
successfully build on your system.
:line
USER-SMD package :h4,link(user-smd)
To build with this package, you must download the Eigen library.
Eigen is a template library, so you do not need to build it.
[CMake build]:
-D PKG_USER-SMD=on # enable USER-SMD package
-D EIGEN3_INCLUDE_DIR=path # path to include directory of Eigen library :pre
-D EIGEN3_INCLUDE_DIR=path # path to Eigen library :pre
TODO: there is no download option for the Eigen lib?
CMake will not download the Eigen library. But once you have done
that, a CMake build of LAMMPS with "-D PKG_USER-SMD=yes" should work.
Set EIGEN3_INCLUDE_DIR if CMake cannot find the Eigen library.
[Traditional make]:
Before building LAMMPS with this package, you must first download the
Eigen library. Eigen is a template library, so you do not need to
build it, just download it. You can do this manually if you prefer;
follow the instructions in lib/smd/README. You can also do it in one
step from the lammps/src dir, using a command like these, which simply
invoke the lib/smd/Install.py script with the specified args:
You can download the Eigen library manually if you prefer; follow the
instructions in lib/smd/README. You can also do it in one step from
the lammps/src dir, using a command like these, which simply invoke
the lib/smd/Install.py script with the specified args:
make lib-smd # print help message
make lib-smd args="-b" # download and build in default lib/smd/eigen-eigen-...
make lib-smd args="-b" # download to lib/smd/eigen3
make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3 :pre
Note that a symbolic (soft) link named "includelink" is created in
lib/smd to point to the Eigen dir. When LAMMPS builds it will use
this link. You should not need to edit the lib/smd/Makefile.lammps file.
You can then install/un-install the package and build LAMMPS in the
usual manner:
this link. You should not need to edit the lib/smd/Makefile.lammps
file.
:line
USER-VTK package :h4,link(user-vtk)
To build with this package you must have the VTK library installed on
your system.
[CMake build]:
-D PKG_USER-VTK=on # enable USER-VTK package :pre
No additional settings are needed besides "-D PKG_USER-VTK=yes".
This will autodetect 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. Run with
ccmake to see these options.
This should autodetect 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.
[Traditional make]:
The lib/vtk/Makefile.lammps file has settings for accessing VTK files
and its library, which are required for LAMMPS to build and link with
this package. If the settings are not valid for your system, check if
one of the other lib/vtk/Makefile.lammps.* files is compatible and
copy it to Makefile.lammps. If none of the provided files work, you
will need to edit the Makefile.lammps file.
You can then install/un-install the package and build LAMMPS in the
usual manner:
and its library, which LAMMPS needs to build with this package. If
the settings are not valid for your system, check if one of the other
lib/vtk/Makefile.lammps.* files is compatible and copy it to
Makefile.lammps. If none of the provided files work, you will need to
edit the Makefile.lammps file. See lib/vtk/README for details.

63
doc/src/Build_make.txt
View File

@ -9,17 +9,18 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
Build LAMMPS with make :h3
Building LAMMPS with traditional makefiles requires, that you have a
Makefile."machine" file in the src/MAKE, src/MAKE/MACHINES,
src/MAKE/OPTIONS, or src/MAKE/MINE directory, which is appropriate
for your system (see below). It can list various options for
customizing your LAMMPS build with a number of global compilation
options and features. To include LAMMPS packages (i.e. optional
commands and styles) you must install them first, as discussed on
the "Build package"_Build_package.html doc page. If the packages
use provided or external libraries, you must build those libraries
before building LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html
can automate all of this for many types of machines, especially
Building LAMMPS with traditional makefiles requires that you have a
Makefile."machine" file appropriate for your system in the src/MAKE,
src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see
below). It can include various options for customizing your LAMMPS
build with a number of global compilation options and features.
To include LAMMPS packages (i.e. optional commands and styles) you
must install them first, as discussed on the "Build
package"_Build_package.html doc page. If the packages require
provided or external libraries, you must build those libraries before
building LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html can
automate all of this for many types of machines, especially
workstations, desktops and laptops, so we suggest you try it first.
These commands perform a default LAMMPS build, producing the LAMMPS
@ -31,19 +32,23 @@ make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options :pre
This initial compilation can take a long time, since LAMMPS is a large
project with many features. If your machine has multiple CPU cores (most
do these days), using a command like "make -jN mpi" (with N being to the
number of available local CPU cores) can be much faster. If you plan to
do development on LAMMPS or may need to recompile LAMMPS repeatedly, the
project with many features. If your machine has multiple CPU cores
(most do these days), using a command like "make -jN mpi" (with N =
the number of available CPU cores) can be much faster. If you plan to
do development on LAMMPS or need to recompile LAMMPS repeatedly, the
installation of the ccache (= Compiler Cache) software may speed up
compilation even more.
After the initial build, whenever you edit LAMMPS source files, or
add or remove new files to the source directory (e.g. by installing or
uninstalling packages), you must recompile and relink the LAMMPS executable
with the same command line, but the makefiles will make certain, that
only files that need to be recompiled will be compiled (because they
were changed or depend on files, that were changed).
After the initial build, whenever you edit LAMMPS source files, or add
or remove new files to the source directory (e.g. by installing or
uninstalling packages), you must recompile and relink the LAMMPS
executable with the same "make" command. This makefiles dependencies
should insure that only the subset of files that need to be are
recompiled.
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
@ -57,17 +62,17 @@ MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create (you may need to create this folder) :pre
Typing "make" lists all the available Makefile.machine files. A file
with the same name can appear in multiple dirs (not a good idea). The
order the dirs are searched is as follows: src/MAKE/MINE, src/MAKE,
src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference to a
customized file you put in src/MAKE/MINE.
with the same name can appear in multiple folders (not a good idea).
The order the dirs are searched is as follows: src/MAKE/MINE,
src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference
to a customized file you put in src/MAKE/MINE.
Makefiles you may wish to try include these (some require a package
first be installed). Many of these include specific compiler flags
for optimized performance. Please note, however, that most of these
customized machine Makefile are contributed and since both, compilers
and also OS configs, as well as LAMMPS itself keep changing all the
time, some of these settings and recommendations may be outdated:
for optimized performance. Please note, however, that some of these
customized machine Makefile are contributed by users. Since both
compilers, OS configs, and LAMMPS itself keep changing, their settings
may become outdated:
make mac # build serial LAMMPS on a Mac
make mac_mpi # build parallel LAMMPS on a Mac

43
doc/src/Build_package.txt
View File

@ -14,8 +14,9 @@ features. For example, force fields for molecular systems or
rigid-body constraints are in packages. In the src directory, each
package is a sub-directory with the package name in capital letters.
A complete list of packages with brief overviews of each are on the
"Packages details"_Packages_details.html doc page.
An overview of packages is given on the "Packages"_Packages.html doc
page. Brief overviews of each package are on the "Packages
details"_Packages_details.html doc page.
When building LAMMPS, you can choose to include or exclude each
package. In general there is no need to include a package if you
@ -23,13 +24,10 @@ never plan to use its features.
If you get a run-time error that a LAMMPS command or style is
"Unknown", it is often because the command is contained in a package,
and your build did not include the package. Running LAMMPS with the
and your build did not include that package. Running LAMMPS with the
"-h command-line switch"_Run_options.html will print all the included
packages and commands for that executable.
The mechanism for including packages is different for CMake versus a
traditional make.
For the majority of packages, if you follow the single step below to
include it, you can then build LAMMPS exactly the same as you would
without any packages installed. A few packages may require additional
@ -62,6 +60,9 @@ packages:
"USER-SMD"_Build_extras.html#user-smd,
"USER-VTK"_Build_extras.html#user-vtk :tb(c=6,ea=c)
The mechanism for including packages is simple but different for CMake
versus make.
[CMake variables]:
-D PKG_NAME=value # yes or no (default) :pre
@ -75,6 +76,9 @@ All standard and user packages are included the same way. Note that
USER packages have a hyphen between USER and the rest of the package
name, not an underscore.
See the shortcut section below for how to install many packages at
once with CMake.
NOTE: If you toggle back and forth between building with CMake vs
make, no packages in the src directory can be installed when you
invoke cmake. CMake will give an error if that is not the case,
@ -95,6 +99,9 @@ make yes-user-intel :pre
All standard and user packages are included the same way.
See the shortcut section below for how to install many packages at
once with make.
NOTE: You must always re-build LAMMPS (via make) after installing or
un-installing a package, for the action to take effect.
@ -114,14 +121,6 @@ right thing. Individual files are only included if their dependencies
are already included. Likewise, if a package is excluded, other files
dependent on that package are also excluded.
NOTE: The one exception is that for a build via make (ok via CMake),
we do not recommend building with the KOKKOS package installed along
with any of the other acceleration packages (GPU, OPT, USER-INTEL,
USER-OMP) also installed. This is because of how Kokkos sometimes
builds using a wrapper compiler which can make it difficult to invoke
all the compile/link flags correctly for both Kokkos and non-Kokkos
files.
When you download a LAMMPS tarball, three packages are pre-installed
in the src directory: KSPACE, MANYBODY, MOLECULE. This is because
they are so commonly used. When you download LAMMPS source files from
@ -129,9 +128,19 @@ the Git or SVN repositories, no packages are pre-installed.
:line
The following make commands are useful for managing package source
files and their installation when building LAMMPS via traditional
make. Just type "make" in lammps/src to see a one-line summary.
[CMake shortcuts for installing many packages]:
TODO: brief discussion of the cmake command line options with presets
that Axel or Richard enabled to install sets of packages at once?
Are these just for cmake, or also ccmake and cmake-gui?
:line
[Make shortcuts for installing many packages]:
The following commands are useful for managing package source files
and their installation when building LAMMPS via traditional make.
Just type "make" in lammps/src to see a one-line summary.
These commands install/un-install sets of packages:

74
doc/src/Build_settings.txt
View File

@ -10,13 +10,13 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
Optional build settings :h3
LAMMPS can be built with several optional settings. Each sub-section
explain how to do this for either a CMake build or traditional make.
explain how to do this for building both with CMake and make.
"FFT library"_#fft for use with "kspace_style pppm"_kspace_style.html command
"FFT library"_#fft for use with the "kspace_style pppm"_kspace_style.html command
"Size of LAMMPS data types"_#size
"Read or write compressed files"_#compress
"Output of JPG and PNG files"_#graphics via "dump image"_dump_image.html command
"Output of movie files"_#graphics via "dump_movie"_dump_image.html command
"Output of JPG and PNG files"_#graphics via the "dump image"_dump_image.html command
"Output of movie files"_#graphics via the "dump_movie"_dump_image.html command
"Memory allocation alignment"_#align
"Workaround for long long integers"_#longlong
"Error handling exceptions"_#exceptions when using LAMMPS as a library :all(b)
@ -29,21 +29,12 @@ FFT library :h3,link(fft)
When the KSPACE package is included in a LAMMPS build, the
"kspace_style pppm"_kspace_style.html command performs 3d FFTs which
require use of an FFT library to compute 1d FFTs. The KISS FFT
library is included with LAMMPS but other libraries can be faster
(typically up to 20%), and LAMMPS can use them, if they are
available on your system. Since the use of FFTs is usually only part
of the total computation done by LAMMPS, however, the total
performance difference for typical cases is in the range of 2-5%.
Thus it is safe to use KISS FFT and look into using other FFT
libraries when optimizing for maximum performance. See details
on enabling the use of other FFT libraries below.
library is included with LAMMPS but other libraries can be faster.
LAMMPS can use them if they are available on your system.
NOTE: FFTW2 has not been updated since 1999 and has been declared
obsolete by its developers.
[CMake variables]:
-D FFT=value # KISSFFT or FFTW3 or FFTW2 or MKL, default is FFTW3 if found, else KISSFFT
-D FFT=value # kiss or fftw3 or fftw2 or mkl, default is fftw3 if found, else kiss
-D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy :pre
@ -64,8 +55,6 @@ FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW2, -DFFT_FFTW (same as -D
FFT_INC = -DFFT_SINGLE # do not specify for double precision
FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY :pre
TODO: change code to use FFT_PACK_OPTION
FFT_INC = -I/usr/local/include
FFT_PATH = -L/usr/local/lib
FFT_LIB = -lfftw3 # FFTW3 double precision
@ -82,38 +71,45 @@ FFT_LIB with the appropriate FFT libraries to include in the link.
[CMake and make info]:
The "KISS FFT library"_http://kissfft.sf.net is included in the LAMMPS
distribution, so not FFT_LIB setting is required. It is portable
across all platforms.
distribution. It is portable across all platforms. Depending on the
size of the FFTs and the number of processors used, the other
libraries listed here can be faster.
However, note that long-range Coulombics are only a portion of the
per-timestep CPU cost, FFTs are only a portion of long-range
Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
communication can be costly). A breakdown of these timings is printed
to the screen at the end of a run using the "kspace_style
pppm"_kspace_style.html command. The "Run output"_doc page gives more
details.
FFTW is a fast, portable FFT library that should also work on any
platform and can be faster than KISS FFT. You can download it from
"www.fftw.org"_http://www.fftw.org. Both the (obsolete) legacy version
2.1.X and the newer 3.X versions are supported. Building FFTW for your
box should be as simple as ./configure; make; make install. The install
command typically requires root privileges (e.g. invoke it via sudo),
unless you specify a local directory with the "--prefix" option of
configure. Type "./configure --help" to see various options.
The total impact on the performance of LAMMPS by KISS FFT versus
other FFT libraries is for many case rather small (since FFTs are only
a small to moderate part of the total computation). Thus if FFTW is
not detected on your system, it is usually safe to continue with
KISS FFT and look into installing FFTW only when optimizing LAMMPS
for maximum performance.
2.1.X and the newer 3.X versions are supported.
NOTE: FFTW2 has not been updated since 1999 and has been declared
obsolete by its developers.
Building FFTW for your box should be as simple as ./configure; make;
make install. The install command typically requires root privileges
(e.g. invoke it via sudo), unless you specify a local directory with
the "--prefix" option of configure. Type "./configure --help" to see
various options.
The Intel MKL math library is part of the Intel compiler suite. It
can be used with the Intel or GNU compiler (see FFT_LIB setting above).
Performing 3d FFTs in parallel can be time consuming due to data
access and required communication. This cost can be reduced
by performing single-precision FFTs instead of double precision.
Single precision means the real and imaginary parts of a complex datum
are 4-byte floats. Double precesion means they are 8-byte doubles.
Note that Fourier transform and related PPPM operations are somewhat
less sensitive to floating point truncation errors and thus the resulting
access and required communication. This cost can be reduced by
performing single-precision FFTs instead of double precision. Single
precision means the real and imaginary parts of a complex datum are
4-byte floats. Double precesion means they are 8-byte doubles. Note
that Fourier transform and related PPPM operations are somewhat less
sensitive to floating point truncation errors and thus the resulting
error is less than the difference in precision. Using the -DFFT_SINGLE
setting trades off a little accuracy for reduced memory use and parallel
communication costs for transposing 3d FFT data.
setting trades off a little accuracy for reduced memory use and
parallel communication costs for transposing 3d FFT data.
When using -DFFT_SINGLE with FFTW3 or FFTW2, you may need to build the
FFTW library a second time with support for single-precision.

22
doc/src/Speed_tips.txt
View File

@ -9,7 +9,7 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
General tips :h3
NOTE: this section 5.2 is still a work in progress
NOTE: this page is still a work in progress
Here is a list of general ideas for improving simulation performance.
Most of them are only applicable to certain models and certain
@ -20,13 +20,8 @@ problem size, number of processors used, and your machine. There is
no substitute for identifying performance bottlenecks, and trying out
various options.
make individual pages for these, or one for PPPM
one for timestepping, etc
one for balancing
or proc layout
rRESPA
2-FFT PPPM
Two-FFT PPPM
Staggered PPPM
single vs double PPPM
partial charge PPPM
@ -34,12 +29,13 @@ verlet/split run style
processor command for proc layout and numa layout
load-balancing: balance and fix balance :ul
2-FFT PPPM, also called {analytic differentiation} or {ad} PPPM, uses
2 FFTs instead of the 4 FFTs used by the default {ik differentiation}
PPPM. However, 2-FFT PPPM also requires a slightly larger mesh size to
achieve the same accuracy as 4-FFT PPPM. For problems where the FFT
cost is the performance bottleneck (typically large problems running
on many processors), 2-FFT PPPM may be faster than 4-FFT PPPM.
Two-FFT PPPM, also called {analytic differentiation} or {ad} PPPM,
uses 2 FFTs instead of the 4 FFTs used by the default {ik
differentiation} PPPM. However, 2-FFT PPPM also requires a slightly
larger mesh size to achieve the same accuracy as 4-FFT PPPM. For
problems where the FFT cost is the performance bottleneck (typically
large problems running on many processors), 2-FFT PPPM may be faster
than 4-FFT PPPM.
Staggered PPPM performs calculations using two different meshes, one
shifted slightly with respect to the other. This can reduce force