ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

changes to replace Section_start.txt

Browse Source
This commit is contained in:
Steven J. Plimpton
2018-08-09 10:19:10 -06:00
parent e88311235f
commit c97e6537c8
22 changed files with 3470 additions and 1823 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
doc/src/Build.txt Normal file
View File

@ -0,0 +1,50 @@
"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.

318
doc/src/Build_basics.txt Normal file
View File

@ -0,0 +1,318 @@
"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.

159
doc/src/Build_cmake.txt Normal file
View File

@ -0,0 +1,159 @@
"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

803
doc/src/Build_extras.txt Normal file
View File

@ -0,0 +1,803 @@
"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
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,
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.
This is the list of packages that may require additional steps.
"GPU"_#gpu,
"KIM"_#kim,
"KOKKOS"_#kokkos,
"LATTE"_#latte,
"MEAM"_#meam,
"MSCG"_#mscg,
"OPT"_#opt,
"POEMS"_#poems,
"PYTHON"_#python,
"REAX"_#reax,
"VORONOI"_#voronoi,
"USER-ATC"_#user-atc,
"USER-AWPMD"_#user-awpmd,
"USER-COLVARS"_#user-colvars,
"USER-H5MD"_#user-h5md,
"USER-INTEL"_#user-intel,
"USER-MOLFILE"_#user-molfile,
"USER-NETCDF"_#user-netcdf,
"USER-OMP"_#user-omp,
"USER-QMMM"_#user-qmmm,
"USER-QUIP"_#user-quip,
"USER-SMD"_#user-smd,
"USER-VTK"_#user-vtk :tb(c=6,ea=c)
:line
:line
COMPRESS package
To build with this package you must have the zlib compression library
available on your system.
[CMake build]:
If CMake cannot find the library, you can set these variables:
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libzlib.a (.so) file
[Traditional make]:
If make cannot find the library, you can edit the
lib/compress/Makefile.lammps file to specify the paths and library
name.
:line
GPU package :h3,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.
[CMake build]:
-D GPU_API=value # value = opencl (default) or cuda
-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)
-D GPU_ARCH=value # hardware choice for GPU_API=cuda
# 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
# on (default) or off
[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.
You can also build the library in one step from the lammps/src dir,
using a command like these, which simply invoke the lib/gpu/Install.py
script with the specified args:
make lib-gpu # print help message
make lib-gpu args="-b" # build GPU library with default Makefile.linux
make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
make lib-gpu args="-m mpi -p mixed -b" # build GPU library with mixed precision using settings in Makefile.mpi :pre
Note that this procedure starts with a Makefile.machine in lib/gpu, as
specified by the "-m" switch. For your convenience, machine makefiles
for "mpi" and "serial" are provided, which have the same settings as
the corresponding machine makefiles in the main LAMMPS source
folder. In addition you can alter 4 important settings in the
Makefile.machine you start from, via the -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)
CUDA_PRECISION = precision (double, mixed, single)
EXTRAMAKE = which Makefile.lammps.* file to copy to Makefile.lammps :ul
If the library build is successful, 3 files should be created:
lib/gpu/libgpu.a, lib/gpu/nvc_get_devices, and
lib/gpu/Makefile.lammps. The latter has settings that enable LAMMPS
to link with CUDA libraries. If the settings in Makefile.lammps for
your machine are not correct, the LAMMPS build will fail, and
lib/gpu/Makefile.lammps may need to be edited.
NOTE: If you re-build the GPU library in lib/gpu, you should always
un-install the GPU package, 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.
:line
KIM package :h3,link(kim)
To build with this package, the KIM library must be downloaded and
built on your system. It must include the KIM models that you want to
use with LAMMPS.
Note that in LAMMPS lingo, a KIM model driver is a pair style
(e.g. EAM or Tersoff). A KIM model is a pair style for a particular
element or alloy and set of parameters, e.g. EAM for Cu with a
specific EAM potential file. Also note that installing the KIM API
library with all its models, may take around 30 min to build. Of
course you only need to do that once.
See the list of KIM model drivers here:
https://openkim.org/kim-items/model-drivers/alphabetical
See the list of all KIM models here:
https://openkim.org/kim-items/models/by-model-drivers
See the list of example KIM models included by default here:
https://openkim.org/kim-api on the "What is in the KIM API source
package?" page.
[CMake build]:
TODO: how to do this
[Traditional make]:
You can do 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.
make lib-kim # print help message
make lib-kim args="-b " # (re-)install KIM API lib with only example models
make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
make lib-kim args="-b -a everything" # install KIM API lib with all models
make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
make lib-kim args="-p /usr/local/kim-api" # use an existing KIM API installation at the provided location
make lib-kim args="-p /usr/local/kim-api -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver :pre
:line
KOKKOS package :h3,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.
[CMake build]:
TODO: how to do this, how to select CPU vs KNL vs GPU, and other
traditional make settings
[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
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.
For multicore CPUs using OpenMP:
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = HSW # HSW = Haswell, SNB = SandyBridge, BDW = Broadwell, etc :pre
For Intel KNLs using OpenMP:
KOKKOS_DEVICES = OpenMP
KOKKOS_ARCH = KNL :pre
For NVIDIA GPUs using CUDA:
KOKKOS_DEVICES = Cuda
KOKKOS_ARCH = Pascal60,Power8 # P100 hosted by an IBM Power8, etc
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
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 :h3,link(latte)
To build with this package, you must download and build the LATTE
library.
[CMake build]:
TODO: how to do this
[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:
make lib-latte # print help message
make lib-latte args="-b" # download and build in lib/latte/LATTE-master
make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
:pre
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
also check that the Makefile.lammps file you create is appropriate for
the compiler you use on your system to build LATTE.
:line
MEAM package :h3,link(meam)
NOTE: You should test building the MEAM library with both the Intel
and GNU compilers to see if a simulation runs faster with one versus
the other on your system.
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
make lib-meam # print help message
make lib-meam args="-m mpi" # build with default Fortran compiler compatible with your MPI library
make lib-meam args="-m serial" # build with compiler compatible with "make serial" (GNU Fortran)
make lib-meam args="-m ifort" # build with Intel Fortran compiler using Makefile.ifort :pre
The build should produce two files: lib/meam/libmeam.a and
lib/meam/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with
Fortran (MEAM library). Typically the two compilers used for LAMMPS
and the MEAM library need to be consistent (e.g. both Intel or both
GNU compilers). If necessary, you can edit/create a new
lib/meam/Makefile.machine file for your system, which should define an
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine
file.
:line
MSCG package :h3,link(mscg)
Before building LAMMPS with this package, you must first download and
build the MS-CG library.
[CMake build]:
TODO: how to do this
[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:
make lib-mscg # print help message
make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make serial"
make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
# 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.
:line
OPT package :h3,link(opt)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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
:line
POEMS package :h3,link(poems)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
make lib-poems # print help message
make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-poems args="-m icc" # build with Intel icc compiler :pre
The build should produce two files: lib/poems/libpoems.a and
lib/poems/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to build LAMMPS with the
POEMS library (though typically the settings are just blank). If
necessary, you can edit/create a new lib/poems/Makefile.machine file
for your system, which should define an EXTRAMAKE variable to specify
a corresponding Makefile.lammps.machine file.
:line
PYTHON package :h3,link(python)
Building with the PYTHON package assumes 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
lib/python/README for more details.
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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.
:line
REAX package :h3,link(reax)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
make lib-reax # print help message
make lib-reax args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
make lib-reax args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
make lib-reax args="-m ifort" # build with Intel ifort compiler :pre
The build should produce two files: lib/reax/libreax.a and
lib/reax/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with
Fortran (REAX library). Typically the two compilers used for LAMMPS
and the REAX library need to be consistent (e.g. both Intel or both
GNU compilers). If necessary, you can edit/create a new
lib/reax/Makefile.machine file for your system, which should define an
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine
file.
:line
VORONOI package :h3,link(voronoi)
[CMake build]:
TODO: how to do this
[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;
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
args:
make lib-voronoi # print help message
make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6 :pre
Note that 2 symbolic (soft) links, "includelink" and "liblink", are
created in lib/voronoi to point to the Voro++ src dir. When LAMMPS
builds in src it will use these links. You should not need to edit
the lib/voronoi/Makefile.lammps file.
:line
:line
USER-ATC package :h3,link(user-atc)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
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")
make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-atc args="-m icc" # build with Intel icc compiler :pre
The build should produce two files: lib/atc/libatc.a and
lib/atc/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to build LAMMPS with the ATC
library. If necessary, you can edit/create a new
lib/atc/Makefile.machine file for your system, which should define an
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine
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:
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 :h3,link(user-awpmd)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
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")
make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-awpmd args="-m icc" # build with Intel icc compiler :pre
The build should produce two files: lib/awpmd/libawpmd.a and
lib/awpmd/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to build LAMMPS with the
AWPMD library. If necessary, you can edit/create a new
lib/awpmd/Makefile.machine file for your system, which should define
an EXTRAMAKE variable to specify a corresponding
Makefile.lammps.machine file.
Note that the Makefile.lammps file has settings for the BLAS and
LAPACK linear algebra libraries. As explained in lib/awpmd/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:
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-COLVARS package :h3,link(user-colvars)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
make lib-colvars # print help message
make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled :pre
The build should produce two files: lib/colvars/libcolvars.a and
lib/colvars/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to build LAMMPS with the
COLVARS library (though typically the settings are just blank). If
necessary, you can edit/create a new lib/colvars/Makefile.machine file
for your system, which should define an EXTRAMAKE variable to specify
a corresponding Makefile.lammps.machine file.
:line
USER-H5MD package :h3,link(user-h5md)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:
make lib-h5md # print help message
make lib-hm5d args="-m h5cc" # build with h5cc compiler :pre
The build should produce two files: lib/h5md/libch5md.a and
lib/h5md/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to build LAMMPS with the
system HDF5 library. If necessary, you can edit/create a new
lib/h5md/Makefile.machine file for your system, which should define an
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine
file.
:line
USER-INTEL package :h3,link(user-intel)
[CMake build]:
TODO: how to choose CPU vs KNL ??
[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.
For CPUs:
OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits
CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload \
-fno-alias -ansi-alias -restrict $(OPTFLAGS)
LINKFLAGS = -g -qopenmp $(OPTFLAGS)
LIB = -ltbbmalloc -ltbbmalloc_proxy :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)
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 :h3,link(user-molfile)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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.
:line
USER-NETCDF package :h3,link(user-netcdf)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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.
:line
USER-OMP package :h3,link(user-omp)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[Traditional make]:
CCFLAGS: add -fopenmp (and -restrict when using Intel compilers)
LINKFLAGS: add -fopenmp :ul
:line
USER-QMMM package :h3,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.
[CMake build]:
TODO: how to do this
[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:
make lib-qmmm # print help message
make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler :pre
The build should produce two files: lib/qmmm/libqmmm.a and
lib/qmmm/Makefile.lammps. The latter is copied from an existing
Makefile.lammps.* and has settings needed to build LAMMPS with the
QMMM library (though typically the settings are just blank). If
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:
:line
USER-QUIP package :h3,link(user-quip)
[CMake build]:
TODO: how to do this
[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. 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.
:line
USER-SMD package :h3,link(user-smd)
[CMake build]:
-D EIGEN3_INCLUDE_DIR
[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:
make lib-smd # print help message
make lib-smd args="-b" # download and build in default lib/smd/eigen-eigen-...
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:
:line
USER-VTK package :h3,link(user-vtk)
[CMake build]:
TODO: automatic, i.e. nothing to do?
[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:

85
doc/src/Build_link.txt Normal file
View File

@ -0,0 +1,85 @@
"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.

66
doc/src/Build_make.txt Normal file
View File

@ -0,0 +1,66 @@
"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 make :h3
Building LAMMPS with traditional make requires you have a
Makefile.machine file in the src/MAKE directory appropriate for your
system (see below). It can list various options for what to
include/exclude in a LAMMPS build. To include LAMMPS packages 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, so we suggest you try it first.
These commands perform a default LAMMPS build, producing the LAMMPS
executable lmp_serial or lmp_mpi in lammps/src:
cd lammps/src
make serial # build a serial LAMMPS executable
make mpi # build a parallel LAMMPS executable with MPI
make # see a variety of make options :pre
If your machine has multiple cores (most do), using a command like
"make -j mpi" will be much faster.
After the initial build, if you edit LAMMPS source files, or add new
files to the source directory, you can re-type make and it will only
re-compile the files that have changed.
:line
The lammps/src/MAKE directory contains all the Makefile.machine files
included in the LAMMPS distribution. Typing "make machine" uses
Makefile.machine. Thus the "make serial" or "make mpi" lines above
use Makefile.serial and Makefile.mpi. Others are in these dirs:
OPTIONS # Makefiles which enable specific options
MACHINES # Makefiles for specific machines
MINE # customized Makefiles you create :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.
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:
make mac # build serial LAMMPS on a Mac
make mac_mpi # build parallel LAMMPS on a Mac
make intel_cpu # build with the USER-INTEL package optimized for CPUs
make knl # build with the USER-INTEL package optimized for KNLs
make opt # build with the OPT package optimized for CPUs
make omp # build with the USER-OMP package optimized for OpenMP
make kokkos_omp # build with the KOKKOS package for OpenMP
make kokkos_cuda_mpi # build with the KOKKOS package for GPUs
make kokkos_phi # build with the KOKKOS package for KNLs :pre

182
doc/src/Build_package.txt Normal file
View File

@ -0,0 +1,182 @@
"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
Include packages in build :h3
In LAMMPS, a package is a group of files that enable a specific set of
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.
When building LAMMPS, you can choose to include or exclude each
package. In general there is no need to include a package if you
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
"-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
steps, as explained on the "Build extras"_Build_extras.html doc page.
These links take you to the extra instructions for those select
packages:
"GPU"_Build_extras.html#gpu,
"KIM"_Build_extras.html#kim,
"KOKKOS"_Build_extras.html#kokkos,
"LATTE"_Build_extras.html#latte,
"MEAM"_Build_extras.html#meam,
"MSCG"_Build_extras.html#mscg,
"OPT"_Build_extras.html#opt,
"POEMS"_Build_extras.html#poems,
"PYTHON"_Build_extras.html#python,
"REAX"_Build_extras.html#reax,
"VORONOI"_Build_extras.html#voronoi,
"USER-ATC"_Build_extras.html#user-atc,
"USER-AWPMD"_Build_extras.html#user-awpmd,
"USER-COLVARS"_Build_extras.html#user-colvars,
"USER-H5MD"_Build_extras.html#user-h5md,
"USER-INTEL"_Build_extras.html#user-intel,
"USER-MOLFILE"_Build_extras.html#user-molfile,
"USER-NETCDF"_Build_extras.html#user-netcdf,
"USER-OMP"_Build_extras.html#user-omp,
"USER-QMMM"_Build_extras.html#user-qmmm,
"USER-QUIP"_Build_extras.html#user-quip,
"USER-SMD"_Build_extras.html#user-smd,
"USER-VTK"_Build_extras.html#user-vtk :tb(c=6,ea=c)
[CMake variables]:
-D PKG_NAME=value # yes or no (default) :pre
Examples:
-D PKG_MANYBODY=yes
-D PKG_USER-INTEL=yes :pre
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.
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,
indicating how you can un-install all packages in the src dir.
[Traditional make]:
cd lammps/src
make ps # check which packages are currently installed
make yes-name # install a package with name
make no-name # un-install a package with name
make mpi # build LAMMPS with whatever packages are now installed :pre
Examples:
make no-rigid
make yes-user-intel :pre
All standard and user packages are included the same way.
NOTE: You must always re-build LAMMPS (via make) after installing or
un-installing a package, for the action to take effect.
NOTE: You cannot install or un-install packages and build LAMMPS in a
single make command with multiple targets, e.g. make yes-colloid mpi.
This is because the make procedure creates a list of source files that
will be out-of-date for the build if the package configuration changes
within the same command. You can include or exclude multiple packages
in a single make command, e.g. make yes-colloid no-manybody.
[CMake and make info]:
Any package can be included or excluded in a LAMMPS build, independent
of all other packages. However, some packages include files derived
from files in other packages. LAMMPS checks for this and does the
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
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.
These commands install/un-install sets of packages:
make yes-all | install all packages
make no-all | un-install all packages
make yes-standard or make yes-std | install standard packages
make no-standard or make no-std| un-install standard packages
make yes-user | install user packages
make no-user | un-install user packages
make yes-lib | install packages that require extra libraries
make no-lib | un-install packages that require extra libraries
make yes-ext | install packages that require external libraries
make no-ext | un-install packages that require external libraries :tb(s=|,a=l)
which install/un-install various sets of packages. Typing "make
package" will list all the these commands.
NOTE: Installing or un-installing a package works by simply copying
files back and forth between the main src directory and
sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC),
so that the files are included or excluded when LAMMPS is built.
The following make commands help manage files that exist in both the
src directory and in package sub-directories. You do not normally
need to use these commands unless you are editing LAMMPS files or are
"installing a patch"_Install_patch.html downloaded from the LAMMPS web
site.
Type "make package-status" or "make ps" to show which packages are
currently installed. For those that are installed, it will list any
files that are different in the src directory and package
sub-directory.
Type "make package-installed" or "make pi" to show which packages are
currently installed, without listing the status of packages that are
not installed.
Type "make package-update" or "make pu" to overwrite src files with
files from the package sub-directories if the package is installed.
It should be used after a "patch has been applied"_Install_patch.html,
since patches only update the files in the package sub-directory, but
not the src files.
Type "make package-overwrite" to overwrite files in the package
sub-directories with src files.
Type "make package-diff" to list all differences between pairs of
files in both the src dir and a package dir.

327
doc/src/Build_settings.txt Normal file
View File

@ -0,0 +1,327 @@
"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
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.
"FFT library"_#fft for use with "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
"Memory allocation alignment"_#align
"Workaround for long long integers"_#longlong
"Error handling exceptions"_#exceptions when using LAMMPS as a library :all(b)
:line
:line
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 are typically
faster if they are available on your system. See details on other FFT
libraries below.
[CMake variables]:
-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
Usually these settings are all that is needed. If CMake cannot find
the FFT library, you can set these variables:
-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
-D FFTW2_LIBRARIES=path # path to FFTW3 libraries
-D FFTW2_INCLUDE_DIRS=path # ditto for FFTW2
-D FFTW3_LIBRARIES=path
-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
-D MKL_LIBRARIES=path :pre
[Makefile.machine settings]:
FFT_INC = -DFFT_FFTW3 # FFTW3, FFTW2, FFTW (same as FFTW3), MKL, or KISS
# default is KISS if not specified
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
FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision
FFT_LIB = -lfftw # FFTW2 double precision, or -ldfftw
FFT_LIB = -lsfftw # FFTW2 single precision
FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler
FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compier :pre
As with CMake, you do not need to set paths in FFT_INC or FFT_PATH, if
make can find the FFT header and library files. You must specify
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.
FFTW is fast, portable library that should also work on any platform
and typically be faster than KISS FFT. You can download it from
"www.fftw.org"_http://www.fftw.org. Both the 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 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).
3d FFTs can be computationally expensive. Their 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
insensitive to floating point truncation errors and thus do not always
need to be performed in double precision. Using this 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.
For FFTW3, do the following, which should produce the additional
library libfftw3f.a
make clean
./configure --enable-single; make; make install :pre
For FFTW2, do the following, which should produce the additional
library libsfftw.a
make clean
./configure --enable-float --enable-type-prefix; make; make install :pre
Performing 3d FFTs requires communication to transpose the 3d FFT
grid. The data packing/unpacking for this can be done in one of 3
modes (ARRAY, POINTER, MEMCPY) as set by the FFT_PACK syntax above.
Depending on the machine, the size of the FFT grid, the number of
processors used, one option may be slightly faster. The default is
ARRAY mode.
:line
Size of LAMMPS data types :h3,link(size)
LAMMPS has a few integer data types which can be defined as 4-byte or
8-byte integers. The default setting of "smallbig" is almost always
adequate.
[CMake variable]:
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall :pre
[Makefile.machine setting]:
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :pre
[CMake and make info]:
The default "smallbig" setting allows for simulations with:
total atom count = 2^63 atoms (about 9e18)
total timesteps = 2^63 (about 9e18)
atom IDs = 2^31 (about 2 billion)
image flags = roll over at 512 :ul
The "bigbig" setting increases the latter two limits. It allows for:
total atom count = 2^63 atoms (about 9e18)
total timesteps = 2^63 (about 9e18)
atom IDs = 2^63 (about 9e18)
image flags = roll over at about 1 million (2^20) :ul
The "smallsmall" setting is only needed if your machine does not
support 8-byte integers. It allows for:
total atom count = 2^31 atoms (about 2 billion)
total timesteps = 2^31 (about 2 billion)
atom IDs = 2^31 (about 2 billion)
image flags = roll over at 512 (2^9) :ul
Atom IDs are not required for atomic systems which do not store bond
topology information, though IDs are enabled by default. The
"atom_modify id no"_atom_modify.html command will turn them off. Atom
IDs are required for molecular systems with bond topology (bonds,
angles, dihedrals, etc). Thus if you model a molecular system with
more than 2 billion atoms, you need the "bigbig" setting.
Image flags store 3 values per atom which count the number of times an
atom has moved through the periodic box in each dimension. See the
"dump"_dump.html doc page for a discussion. If an atom moves through
the periodic box more than this limit, the value will "roll over",
e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the "compute
msd"_compute_msd.html command, to be faulty.
Note that the USER-ATC package is not currently compatible with the
"bigbig" setting.
Also note that the GPU package requires its lib/gpu library to be
compiled with the same size setting, or the link will fail. A CMake
build does this automatically. When building with make, the setting
in whichever lib/gpu/Makefile is used must be the same as above.
:line
Output of JPG, PNG, and movie files :h3,link(graphics)
The "dump image"_dump_image.html command has options to output JPEG or
PNG image files. Likewise the "dump movie"_dump_image.html command
ouputs movie files in MPEG format. Using these options requires the
following settings:
[CMake variables]:
-D LAMMPS_JPEG=value # yes or no
# default = yes if CMake finds JPEG files, else no
-D LAMMPS_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB files, else no
-D LAMMPS_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no :pre
Usually these settings are all that is needed. If CMake cannot find
the graphics header, library, executuable files, you can set these
variables:
-D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file
-D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file
-D PNG_INCLUDE_DIR=path # path to png.h header file
-D PNG_LIBRARIES=path # path to libpng.a (.so) file
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libzlib.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable :pre
[Makefile.machine settings]:
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG :pre
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libzlib.a (.so) files if make cannot find them
JPG_LIB = -ljpeg -lpng -lzlib # library names :pre
As with CMake, you do not need to set JPG_INC or JPG_PATH, if make can
find the graphics header and library files. You must specify JPG_LIB
with a list of graphics libraries to include in the link. You must
insure ffmpeg is in a directory where LAMMPS can find it at runtime,
i.e. a dir in your PATH environment variable.
[CMake and make info]:
Using ffmpeg to output movie files requires that your machine
supports the "popen" function in the standard runtime library.
NOTE: On some clusters with high-speed networks, using the fork()
library calls (required by popen()) can interfere with the fast
communication library and lead to simulations using ffmpeg to hang or
crash.
:line
Read or write compressed files :h3,link(compress)
If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including
"read_data"_read_data.html, "rerun"_rerun.html, and "dump"_dump.html.
[CMake variables]:
-D LAMMPS_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
[Makefile.machine setting]:
LMP_INC = -DLAMMPS_GZIP :pre
[CMake and make info]:
This option requires that your machine supports the "popen()" function
in the standard runtime library and that a gzip executable can be
found by LAMMPS during a run.
NOTE: On some clusters with high-speed networks, using the fork()
library calls (required by popen()) can interfere with the fast
communication library and lead to simulations using compressed output
or input to hang or crash. For selected operations, compressed file
I/O is also available using a compression library instead, which is
what the "COMPRESS package"_Packages.html enables.
:line
Memory allocation alignment :h3,link(align)
This setting enables the use of the posix_memalign() call instead of
malloc() when LAMMPS allocates large chunks or memory. This can make
vector instructions on CPUs more efficient, if dynamically allocated
memory is aligned on larger-than-default byte boundaries.
[CMake variable]:
-D LAMMPS_MEMALIGN=value # 8, 16, 32, 64 (default) :pre
[Makefile.machine setting]:
LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64 :pre
TODO: I think the make default (no LAMMPS_MEMALIGN) is to not
use posix_memalign(), just malloc(). Does a CMake build have
an equivalent option? I.e. none.
:line
Workaround for long long integers :h3,link(longlong)
If your system or MPI version does not recognize "long long" data
types, the following setting will be needed. It converts "long long"
to a "long" data type, which should be the desired 8-byte integer on
those systems:
[CMake variable]:
-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) :pre
[Makefile.machine setting]:
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG :pre
:line
Exception handling when using LAMMPS as a library :h3,link(exceptions)
This setting is useful when external codes drive LAMMPS as a library.
With this option enabled LAMMPS errors do not kill the caller.
Instead, the call stack is unwound and control returns to the caller,
e.g. to Python.
[CMake variable]:
-D LAMMPS_EXCEPTIONS=value # yes or no (default) :pre
[Makefile.machine setting]:
LMP_INC = -DLAMMPS_EXCEPTIONS :pre

64
doc/src/Install.txt Normal file
View File

@ -0,0 +1,64 @@
"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Build.html
:c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
Install LAMMPS :h2
You can download LAMMPS as an executable or as source code.
With source code, you also have to "build LAMMPS"_Build.html. But you
have more flexibility as to what features to include or exclude in the
build. If you plan to "modify or extend LAMMPS"_Modify.html, then you
need the source code.
<!-- RST
.. toctree::
Install_linux
Install_mac
Install_windows
Install_tarball
Install_git
Install_svn
Install_patch
END_RST -->
<!-- HTML_ONLY -->
"Download an executable for Linux"_Install_linux.html
"Download an executable for Mac"_Install_mac.html
"Download an executable for Windows"_Install_windows.html :all(b)
"Download source as a tarball"_Install_tarball.html
"Donwload source via Git"_Install_git.html
"Donwload source via SVN"_Install_svn.html
"Install patch files"_Install_patch.html :all(b)
<!-- END_HTML_ONLY -->
These are the files and sub-directories in the LAMMPS distribution:
README: text file
LICENSE: GNU General Public License (GPL)
bench: benchmark problems
cmake: CMake build files
doc: documentation
examples: simple test problems
lib: additional provided or external libraries
potentials: interatomic potential files
python: Python wrapper on LAMMPS
src: source files
tools: pre- and post-processing tools :tb(s=:,a=l)
You will have all of these if you download source. You will only have
some of them if you download executables, as explained on the pages
listed above.

120
doc/src/Install_git.txt Normal file
View File

@ -0,0 +1,120 @@
"Higher level section"_Install.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
Download source via Git :h3
All LAMMPS development is coordinated through the "LAMMPS GitHub
site". If you clone the LAMMPS repository onto your local machine, it
has several advantages:
You can stay current with changes to LAMMPS with a single git
command. :ulb,l
You can create your own development branches to add code to LAMMPS. :l
You can submit your new features back to GitHub for inclusion in
LAMMPS. :l,ule
You must have "Git"_git installed on your system to communicate with
the public Git server for LAMMPS.
IMPORTANT NOTE: As of Oct 2016, the official home of public LAMMPS
development is on GitHub. The previously advertised LAMMPS git
repositories on git.lammps.org and bitbucket.org are now deprecated,
may not be up-to-date, and may go away at any time.
:link(git,http://git-scm.com)
You can follow LAMMPS development on 3 different Git branches:
[stable] : this branch is updated with every stable release
[unstable] : this branch is updated with every patch release
[master] : this branch continuously follows ongoing development :ul
To access the Git repositories on your box, use the clone command to
create a local copy of the LAMMPS repository with a command like:
git clone -b unstable https://github.com/lammps/lammps.git mylammps :pre
where "mylammps" is the name of the directory you wish to create on
your machine and "unstable" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branchname>".)
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with two exceptions:
1) No LAMMPS packages are initially installed in the src dir (a few
packages are installed by default in the tarball src dir). You can
install whichever packages you wish before building LAMMPS; type "make
package" from the src dir to see the options, and the
"Packages"_Packages.html doc page for a discussion of packages.
2) The HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing "make fetch" in the doc directory.
Or they can be generated from the content provided in doc/src by
typing "make html" from the the doc directory.
After initial cloning, as bug fixes and new features are added to
LAMMPS, as listed on "this page"_bug.html, you can stay up-to-date by
typing the following Git commands from within the "mylammps"
directory:
git checkout unstable # not needed if you always stay in this branch
git checkout stable # use one of the 3 checkout commands
git checkout master
git pull :pre
Doing a "pull" will not change any files you have added to the LAMMPS
directory structure. It will also not change any existing LAMMPS
files you have edited, unless those files have changed in the
repository. In that case, Git will attempt to merge the new
repository file with your version of the file and tell you if there
are any conflicts. See the Git documentation for details.
If you want to access a particular previous release version of LAMMPS,
you can instead "checkout" any version with a published tag. See the
output of "git tag -l" for the list of tags. The Git command to do
this is as follows.
git checkout tagID :pre
Stable versions and what tagID to use for a particular stable version
are discussed on "this page"_bug.html. Note that this command will
print some warnings, because in order to get back to the latest
revision and to be able to update with "git pull" again, you first
will need to first type "git checkout unstable" (or check out any
other desired branch).
Once you have updated your local files with a "git pull" (or "git
checkout"), you still need to re-build LAMMPS if any source files have
changed. To do this, you should cd to the src directory and type:
make purge # remove any deprecated src files
make package-update # sync package files with src files
make foo # re-build for your machine (mpi, serial, etc) :pre
just as described on the "Install patch"_Install_patch.html doc page,
after a patch has been installed.
IMPORTANT NOTE: If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The version in
the src dir is merely a copy and will be wiped out if you type "make
package-update".
IMPORTANT NOTE: The GitHub servers support both the "git://" and
"https://" access protocols for anonymous read-only access. If you
have a correspondingly configured GitHub account, you may also use SSH
with "git@github.com:/lammps/lammps.git".
The LAMMPS GitHub project is managed by Christoph Junghans (LANL,
junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at
gmail.com) and Richard Berger (Temple U, richard.berger at
temple.edu).

120
doc/src/Install_linux.txt Normal file
View File

@ -0,0 +1,120 @@
"Higher level section"_Install.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
Download an executable for Linux :h3
Binaries are available for many different versions of Linux:
"Pre-built binary RPMs for Fedora/RedHat/CentOS/openSUSE"_#rpm
"Pre-built Ubuntu Linux executables"_#unbuntu
"Pre-built Gentoo Linux executable"_#gentoo :all(b)
:line
:line
Pre-built binary RPMs for Fedora/RedHat/CentOS/openSUSE :h4,link(rpm)
Pre-built LAMMPS executables for various Linux distributions
can be downloaded as binary RPM files from this site:
"http://rpm.lammps.org"_http://rpm.lammps.org
There are multiple package variants supporting serial, parallel and
Python wrapper versions. The LAMMPS binaries contain all optional
packages included in the source distribution except: GPU, KIM, REAX,
and USER-INTEL.
Installation instructions for the various versions are here:
"http://rpm.lammps.org/install.html"_http://rpm.lammps.org/install.html
The instructions show how to enable the repository in the respective
system's package management system. Installing and updating are then
straightforward and automatic.
Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting
up this RPM capability.
:line
Pre-built Ubuntu Linux executables :h4,link(ubuntu)
A pre-built LAMMPS executable suitable for running on the latest
Ubuntu Linux versions, can be downloaded as a Debian package. This
allows you to install LAMMPS with a single command, and stay
up-to-date with the current version of LAMMPS by simply updating your
operating system.
To install the appropriate personal-package archive (PPA), do the
following once:
sudo add-apt-repository ppa:gladky-anton/lammps
sudo apt-get update :pre
To install LAMMPS do the following once:
sudo apt-get install lammps-daily :pre
This downloads an executable named "lammps-daily" to your box, which
can then be used in the usual way to run input scripts:
lammps-daily < in.lj :pre
To update LAMMPS to the most current version, do the following:
sudo apt-get update :pre
which will also update other packages on your system.
To get a copy of the current documentation and examples:
sudo apt-get install lammps-daily-doc :pre
which will download the doc files in
/usr/share/doc/lammps-daily-doc/doc and example problems in
/usr/share/doc/lammps-doc/examples.
Note that you may still wish to download the tarball to get potential
files and auxiliary tools.
To un-install LAMMPS, do the following:
sudo apt-get remove lammps-daily :pre
Note that the lammps-daily executable is built with the following
sequence of make commands, as if you had done the same with the
unpacked tarball files in the src directory:
make yes-all; make no-lib; make openmpi
Thus it builds with FFTW3 and OpenMPI.
Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this
Ubuntu package capability.
:line
Pre-built Gentoo Linux executable :h4,link(gentoo)
LAMMPS is part of Gentoo's main package tree and can be installed by
typing:
% emerge --ask lammps :pre
Note that in Gentoo the LAMMPS source is downloaded and the package is
built on the your machine.
Certain LAMMPS packages can be enable via USE flags, type
% equery uses lammps :pre
for details.
Thanks to Nicolas Bock and Christoph Junghans (LANL) for setting up
this Gentoo capability.

55
doc/src/Install_mac.txt Normal file
View File

@ -0,0 +1,55 @@
"Higher level section"_Install.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
Download an executable for Mac :h3
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
"Homebrew"_homebrew. Only four of the LAMMPS packages are unavailable
at this time because of additional needs not yet met: KIM, GPU,
USER-INTEL, USER-ATC.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:
% brew tap homebrew/science
% brew install lammps # serial version
% brew install lammps --with-mpi # mpi support :pre
This will install the executable "lammps", a python module named
"lammps", and additional resources with all the standard packages. To
get the location of the additional resources type this:
% brew info lammps :pre
This command also tells you additional installation options available.
The user-packages are available as options, just install them like
this example for the USER-OMP package:
% brew install lammps --enable-user-omp :pre
It is usually best to install LAMMPS with the most up to date source
files, which can be done with the "--HEAD" option:
% brew install lammps --HEAD :pre
To re-install the LAMMPS HEAD, run this command occasionally (make sure
to use the desired options).
% brew install --force lammps --HEAD $\{options\} :pre
Once LAMMPS is installed, you can test the installation with the
Lennard-Jones benchmark file:
% brew test lammps -v :pre
If you have problems with the installation you can post issues to
"this link"_https://github.com/Homebrew/homebrew-science/issues.
Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting
up the Homebrew capability.

67
doc/src/Install_patch.txt Normal file
View File

@ -0,0 +1,67 @@
"Higher level section"_Install.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
Applying patches :h3
It is easy to stay current with the most recent LAMMPS patch releases
if you use Git or SVN to track LAMMPS development. Instructions for
how to stay current are on the "Install git"_Install_git.html and
"Install svn"_Install_svn.html doc pages.
If you prefer to download a tarball, as described on the "Install
git"_Install_tarball.html doc page, you can stay current by
downloading "patch files" when new patch releases are made. A link to
a patch file is posted on the "bug and feature page"_bug of the
website, along with a list of changed files and details about what is
in the new patch release. This page explains how to apply the patch
file to your local LAMMPS directory.
NOTE: You should not apply patch files to a local Git or SVN repo of
LAMMPS, only to an unpacked tarball. Use Git and SVN commands to
update repo versions of LAMMPS.
Here are the steps to apply a patch file. Note that if your version
of LAMMPS is several patch releases behind, you need to apply all the
intervening patch files in succession to bring your version of LAMMPS
up to date.
Download the patch file. You may have to shift-click in your browser
to download the file instead of display it. Patch files have names
like patch.12Dec16. :ulb,l
Put the patch file in your top-level LAMMPS directory, where the
LICENSE and README files are. :l
Apply the patch by typing the following command from your top-level
LAMMPS directory, where the redirected file is the name of the patch
file. :l
patch -bp1 < patch.12Dec16 :pre
A list of updated files print out to the screen. The -b switch
creates backup files of your originals (e.g. src/force.cpp.orig), so
you can manually undo the patch if something goes wrong. :l
Type the following from the src directory, to enforce consistency
between the src and package directories. This is OK to do even if you
don't use one or more packages. If you are applying several patches
successively, you only need to type this once at the end. The purge
command removes deprecated src files if any were removed by the patch
from package sub-directories. :l
make purge
make package-update :pre
Re-build LAMMPS via the "make" command. :l,ule
IMPORTANT NOTE: If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-dir of src, then re-install the package. The version in the src
dir is merely a copy and will be wiped out if you type "make
package-update".

95
doc/src/Install_svn.txt Normal file
View File

@ -0,0 +1,95 @@
"Higher level section"_Install.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
Download source via SVN :h3
IMPORTANT NOTE: As of Oct 2016, SVN support is now implemented via a
git-to-subversion interface service on GitHub and no longer through a
mirror of the internal SVN repository at Sandia.
You must have the "Subversion (SVN) client software"_svn installed on
your system to communicate with the Git server in this mode.
:link(svn,http://subversion.apache.org)
You can follow LAMMPS development on 3 different SVN branches:
[stable] : this branch is updated with every stable release
[unstable] : this branch is updated with every patch release
[master] : this branch continuously follows ongoing development :ul
The corresponding command lines to do an initial checkout are as
follows. (Note that unlike Git, you must perform a separate checkout
into a unique directory for each of the 3 branches.)
svn checkout https://github.com/lammps/lammps.git/branches/unstable mylammps
svn checkout https://github.com/lammps/lammps.git/branches/stable mylammps
svn checkout https://github.com/lammps/lammps.git/trunk mylammps :pre
where "mylammps" is the name of the directory you wish to create on
your machine.
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with two exceptions:
1) No LAMMPS packages are initially installed in the src dir (a few
packages are installed by default in the tarball src dir). You can
install whichever packages you wish before building LAMMPS; type "make
package" from the src dir to see the options, and the
"Packages"_Packages.html doc page for a discussion of packages.
2) The HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing "make fetch" in the doc directory.
Or they can be generated from the content provided in doc/src by
typing "make html" from the the doc directory.
After initial checkout, as bug fixes and new features are added to
LAMMPS, as listed on "this page"_bug.html, you can stay up-to-date by
typing the following SVN commands from within the "mylammps"
directory:
svn update :pre
You can also check if there are any updates by typing:
svn -qu status :pre
Doing an "update" will not change any files you have added to the
LAMMPS directory structure. It will also not change any existing
LAMMPS files you have edited, unless those files have changed in the
repository. In that case, SVN will attempt to merge the new
repository file with your version of the file and tell you if there
are any conflicts. See the SVN documentation for details.
Please refer to the "subversion client support help pages on
GitHub"_https://help.github.com/articles/support-for-subversion-clients
if you want to use advanced features like accessing particular
previous release versions via tags.
Once you have updated your local files with an "svn update" (or "svn
co"), you still need to re-build LAMMPS if any source files have
changed. To do this, you should cd to the src directory and type:
make purge # remove any deprecated src files
make package-update # sync package files with src files
make foo # re-build for your machine (mpi, serial, etc) :pre
just as described on the "Install patch"_Install_patch.html doc page,
after a patch has been installed.
IMPORTANT NOTE: If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The version in
the src dir is merely a copy and will be wiped out if you type "make
package-update".
The LAMMPS GitHub project is managed by Christoph Junghans (LANL,
junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at
gmail.com) and Richard Berger (Temple U, richard.berger at
temple.edu).

64
doc/src/Install_tarball.txt Normal file
View File

@ -0,0 +1,64 @@
"Higher level section"_Install.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
Download source as a tarball :h3
You can download a current LAMMPS tarball from the "download page"_download
of the "LAMMPS website"_lws.
:link(download,http://lammps.sandia.gov/download.html)
:link(bug,http://lammps.sandia.gov/bug.html)
:link(older,http://lammps.sandia.gov/tars)
You have two choices of tarballs, either the most recent stable
release or the most current patch release. Stable releases occur a
few times per year, and undergo more testing before release. Patch
releases occur a couple times per month. The new contents in all
releases are listed on the "bug and feature page"_bug of the website.
Older versions of LAMMPS can also be downloaded from "this
page"_older.
Once you have a tarball, unzip and untar it with the following
command:
tar -xzvf lammps*.tar.gz :pre
This will create a LAMMPS directory with the version date
in its name, e.g. lammps-23Jun18.
:line
You can also download a zip file via the "Clone or download" button on
the "LAMMPS GitHub site"_git. The file name will be lammps-master.zip
which can be unzipped with the following command, to create
a lammps-master dir:
unzip lammps*.zip :pre
This version is the most up-to-date LAMMPS development version. It
will have the date of the most recent patch release (see the file
src/version.h). But it will also include any new bug-fixes or
features added since the last patch release. They will be included in
the next patch release tarball.
:link(git,https://github.com/lammps/lammps)
:line
If you download a current LAMMPS tarball, one way to stay current as
new patch tarballs are released, is to download a patch file which you
can apply to your local directory to update it for each new patch
release. (Or of course you could just download the newest tarball
periodically.)
The patch files are posted on the "bug and feature page"_bug of the
website, along with a list of changed files and details about what is
in the new patch release. Instructions for applying a patch file are
on the "Install patch"_Install_patch.html doc page.

52
doc/src/Install_windows.txt Normal file
View File

@ -0,0 +1,52 @@
"Higher level section"_Install.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
Download an executable for Windows :h3
Pre-compiled Windows installers which install LAMMPS executables on a
Windows system can be downloaded from this site:
"http://rpm.lammps.org/windows.html"_http://rpm.lammps.org/windows.html
Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for
current and older versions of LAMMPS are available. 32-bit and 64-bit
installers are available, and each installer contains both a serial
and parallel executable. The installer site also explains how to
install the Windows MPI package (MPICH2 from Argonne National Labs),
needed to run in parallel.
The LAMMPS binaries contain all optional packages included in the
source distribution except: KIM, REAX, KOKKOS, USER-INTEL,
and USER-QMMM. The serial version also does not include the MPIIO and
USER-LB packages. GPU support is provided for OpenCL.
The installer site also has instructions on how to run LAMMPS under
Windows, once it is installed, in both serial and parallel.
When you download the installer package, you run it on your Windows
machine. It will then prompt you with a dialog, where you can choose
the installation directory, unpack and copy several executables,
potential files, documentation pdfs, selected example files, etc. It
will then update a few system settings (e.g. PATH, LAMMPS_POTENTIALS)
and add an entry into the Start Menu (with references to the
documentation, LAMMPS homepage and more). From that menu, there is
also a link to an uninstaller that removes the files and undoes the
environment manipulations.
Note that to update to a newer version of LAMMPS, you should typically
uninstall the version you currently have, download a new installer,
and go thru the install procedure described above. I.e. the same
procedure for installing/updating most Windows programs. You can
install multiple versions of LAMMPS (in different directories), but
only the executable for the last-installed package will be found
automatically, so this should only be done for debugging purposes.
Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting
up this Windows capability.

37
doc/src/Run.txt Normal file
View File

@ -0,0 +1,37 @@
"Previous Section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS
Documentation"_ld - "LAMMPS Commands"_lc - "Next
Section"_Commands.html :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Commands_all.html)
:line
Run LAMMPS :h2
These pages explain how to run LAMMPS once you have "installed an
executable"_Install.html or "downloaded the source code"_Install.html
and "built an executable"_Build.html. The "Commands"_Commands.html
doc page describes how input scripts are structured and the commands
they can contain.
<!-- RST
.. toctree::
Run_basics
Run_options
Run_output
Run_windows
END_RST -->
<!-- HTML_ONLY -->
"Basics of running LAMMPS"_Run_basics.html
"Command-line options"_Run_options.html
"Screen and logfile output"_Run_output.html
"Running LAMMPS on Windows"_Run_windows.html :all(b)
<!-- END_HTML_ONLY -->

87
doc/src/Run_basics.txt Normal file
View File

@ -0,0 +1,87 @@
"Higher level section"_Run.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
Basics of running LAMMPS :h3
LAMMPS is run from the command line, reading commands from standard
input, which are typically listed in an input script:
lmp_serial < in.file
lmp_serial -in in.file
~/lammps/src/lmp_serial < in.file
mpirun -np 4 lmp_mpi -in in.file
mpirun -np 8 ~/lammps/src/lmp_mpi -in in.file
mpirun -np 6 /usr/local/bin/lmp_mpi -in in.file :pre
You normally run from the directory your input script is in. That is
also where output files are produced, unless you specify otherwise in
your input script. As in some of the examples above, the LAMMPS
executable can be elsewhere.
NOTE: The redirection operator "<" can often be used with mpirun, but
some systems require the -in form.
As LAMMPS runs it prints info to the screen and a logfile named
log.lammps. More info about output is given on the "Run
output"_Run_output.html doc page.
If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See the "Errors"_Errors.html doc page for a
discussion of the various kinds of errors LAMMPS can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
:line
LAMMPS can run the same problem on any number of processors, including
a single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories. See the "Errors
common"_Errors_common.html doc page for discussion of this.
LAMMPS can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or define a smaller problem.
If you run LAMMPS in parallel via mpirun, you should be aware of the
"processors"_processors.html command which controls how MPI tasks are
mapped to the simulation box, as well as mpirun options that control
how MPI tasks are assigned to physical cores of the node(s) of the
machine you are running on. These settings can improve performance,
though the defaults are often adequate.
For example, it is often important to bind MPI tasks (processes) to
physical cores (processor affinity), so that the operating system does
not migrate them during a simulation. If this is not the default
behavior on your machine, the mpirun option "--bind-to core" (OpenMPI)
or "-bind-to core" (MPICH) can be used.
If the LAMMPS command(s) you are using support multi-threading, you
can set the number of threads per MPI task via the environment
variable OMP_NUM_THREADS, before you launch LAMMPS:
export OMP_NUM_THREADS=2 # bash
setenv OMP_NUM_THREADS 2 # csh or tcsh :pre
This can also be done via the "package"_package.html command or via
the "-pk command-line switch"_Run_options.html which invokes the
package command. See the "package"_package.html command or
"Speed"_Speed.html doc pages for more details about which accerlarator
packages and which commands support multi-threading.
:line
You can experiment with running LAMMPS using any of the input scripts
provided in the examples or bench directory. Input scripts are named
in.* and sample outputs are named log.*.P where P is the number of
processors it was run on.
Some of the examples or benchmarks require LAMMPS to be built with
optional packages.

470
doc/src/Run_options.txt Normal file
View File

@ -0,0 +1,470 @@
"Higher level section"_Run.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
Command-line options :h3
At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. Either the full word or a one-or-two
letter abbreviation can be used:
"-e or -echo"_#echo
"-h or -help"_#help
"-i or -in"_#in
"-k or -kokkos"_#kokkos
"-l or -log"_#log
"-nc or -nocite"_#nocite
"-pk or -package"_#package
"-p or -partition"_#partition
"-pl or -plog"_#plot
"-ps or -pscreen"_#pscreen
"-r or -restart"_#restart
"-ro or -reorder"_#reorder
"-sc or -screen"_#screen
"-sf or -suffix"_#suffix
"-v or -var"_#var :ul
For example, the lmp_mpi executable might be launched as follows:
mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy
mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy :pre
:line
:line
[-echo style] :link(echo)
Set the style of command echoing. The style can be {none} or {screen}
or {log} or {both}. Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile. This
can be useful to figure out which line of your script is causing an
input error. The default value is {log}. The echo style can also be
set by using the "echo"_echo.html command in the input script itself.
:line
[-help] :link(help)
Print a brief help summary and a list of options compiled into this
executable for each LAMMPS style (atom_style, fix, compute,
pair_style, bond_style, etc). This can tell you if the command you
want to use was included via the appropriate package at compile time.
LAMMPS will print the info and immediately exit if this switch is
used.
:line
[-in file] :link(file)
Specify a file to use as an input script. This is an optional switch
when running LAMMPS in one-partition mode. If it is not specified,
LAMMPS reads its script from standard input, typically from a script
via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should
also work in parallel, but if it does not (in the unlikely case that
an MPI implementation does not support it), then use the -in flag.
Note that this is a required switch when running LAMMPS in
multi-partition mode, since multiple processors cannot all read from
stdin.
:line
[-kokkos on/off keyword/value ...] :link(kokkos)
Explicitly enable or disable KOKKOS support, as provided by the KOKKOS
package. Even if LAMMPS is built with this package, as described
above in "Section 2.3"_#start_3, this switch must be set to enable
running with the KOKKOS-enabled styles the package provides. If the
switch is not set (the default), LAMMPS will operate as if the KOKKOS
package were not installed; i.e. you can run standard LAMMPS or with
the GPU or USER-OMP packages, for testing or benchmarking purposes.
Additional optional keyword/value pairs can be specified which
determine how Kokkos will use the underlying hardware on your
platform. These settings apply to each MPI task you launch via the
"mpirun" or "mpiexec" command. You may choose to run one or more MPI
tasks per physical node. Note that if you are running on a desktop
machine, you typically have one physical node. On a cluster or
supercomputer there may be dozens or 1000s of physical nodes.
Either the full word or an abbreviation can be used for the keywords.
Note that the keywords do not use a leading minus sign. I.e. the
keyword is "t", not "-t". Also note that each of the keywords has a
default setting. Examples of when to use these options and what
settings to use on different platforms is given on the "Speed
kokkos"_Speed_kokkos.html doc page.
d or device
g or gpus
t or threads
n or numa :ul
device Nd :pre
This option is only relevant if you built LAMMPS with CUDA=yes, you
have more than one GPU per node, and if you are running with only one
MPI task per node. The Nd setting is the ID of the GPU on the node to
run on. By default Nd = 0. If you have multiple GPUs per node, they
have consecutive IDs numbered as 0,1,2,etc. This setting allows you
to launch multiple independent jobs on the node, each with a single
MPI task per node, and assign each job to run on a different GPU.
gpus Ng Ns :pre
This option is only relevant if you built LAMMPS with CUDA=yes, you
have more than one GPU per node, and you are running with multiple MPI
tasks per node (up to one per GPU). The Ng setting is how many GPUs
you will use. The Ns setting is optional. If set, it is the ID of a
GPU to skip when assigning MPI tasks to GPUs. This may be useful if
your desktop system reserves one GPU to drive the screen and the rest
are intended for computational work like running LAMMPS. By default
Ng = 1 and Ns is not set.
Depending on which flavor of MPI you are running, LAMMPS will look for
one of these 3 environment variables
SLURM_LOCALID (various MPI variants compiled with SLURM support)
MV2_COMM_WORLD_LOCAL_RANK (Mvapich)
OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre
which are initialized by the "srun", "mpirun" or "mpiexec" commands.
The environment variable setting for each MPI rank is used to assign a
unique GPU ID to the MPI task.
threads Nt :pre
This option assigns Nt number of threads to each MPI task for
performing work when Kokkos is executing in OpenMP or pthreads mode.
The default is Nt = 1, which essentially runs in MPI-only mode. If
there are Np MPI tasks per physical node, you generally want Np*Nt =
the number of physical cores per node, to use your available hardware
optimally. This also sets the number of threads used by the host when
LAMMPS is compiled with CUDA=yes.
numa Nm :pre
This option is only relevant when using pthreads with hwloc support.
In this case Nm defines the number of NUMA regions (typically sockets)
on a node which will be utilized by a single MPI rank. By default Nm
= 1. If this option is used the total number of worker-threads per
MPI rank is threads*numa. Currently it is always almost better to
assign at least one MPI rank per NUMA region, and leave numa set to
its default value of 1. This is because letting a single process span
multiple NUMA regions induces a significant amount of cross NUMA data
traffic which is slow.
:line
[-log file] :link(log)
Specify a log file for LAMMPS to write status information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
file log.lammps. If this switch is used, LAMMPS writes to the
specified file. In multi-partition mode, if the switch is not used, a
log.lammps file is created with hi-level status information. Each
partition also writes to a log.lammps.N file where N is the partition
ID. If the switch is specified in multi-partition mode, the hi-level
logfile is named "file" and each partition also logs information to a
file.N. For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created. Using a
"log"_log.html command in the input script will override this setting.
Option -plog will override the name of the partition log files file.N.
:line
[-nocite] :link(nocite)
Disable writing the log.cite file which is normally written to list
references for specific cite-able features used during a LAMMPS run.
See the "citation page"_http://lammps.sandia.gov/cite.html for more
details.
:line
[-package style args ....] :link(package)
Invoke the "package"_package.html command with style and args. The
syntax is the same as if the command appeared at the top of the input
script. For example "-package gpu 2" or "-pk gpu 2" is the same as
"package gpu 2"_package.html in the input script. The possible styles
and args are documented on the "package"_package.html doc page. This
switch can be used multiple times, e.g. to set options for the
USER-INTEL and USER-OMP packages which can be used together.
Along with the "-suffix" command-line switch, this is a convenient
mechanism for invoking accelerator packages and their options without
having to edit an input script.
:line
[-partition 8x2 4 5 ...] :link(partition)
Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P
processors and this switch is not used, LAMMPS runs in one partition,
i.e. all P processors run a single simulation. If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation. The arguments to the switch
specify the number of processors in each partition. Arguments of the
form MxN mean M partitions, each with N processors. Arguments of the
form N mean a single partition with N processors. The sum of
processors in all partitions must equal P. Thus the command
"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
processors.
Running with multiple partitions can be useful for running
"multi-replica simulations"_Howto_replica.html, where each replica
runs on on one or a few processors. Note that with MPI installed on a
machine (e.g. your desktop), you can run on more (virtual) processors
than you have physical processors.
To run multiple independent simulations from one input script, using
multiple partitions, see the "Howto multiple"_Howto_multiple.html doc
page. World- and universe-style "variables"_variable.html are useful
in this context.
:line
[-plog file] :link(plog)
Specify the base name for the partition log files, so partition N
writes log information to file.N. If file is none, then no partition
log files are created. This overrides the filename specified in the
-log command-line option. This option is useful when working with
large numbers of partitions, allowing the partition log files to be
suppressed (-plog none) or placed in a sub-directory (-plog
replica_files/log.lammps) If this option is not used the log file for
partition N is log.lammps.N or whatever is specified by the -log
command-line option.
:line
[-pscreen file] :link(pscreen)
Specify the base name for the partition screen file, so partition N
writes screen information to file.N. If file is none, then no
partition screen files are created. This overrides the filename
specified in the -screen command-line option. This option is useful
when working with large numbers of partitions, allowing the partition
screen files to be suppressed (-pscreen none) or placed in a
sub-directory (-pscreen replica_files/screen). If this option is not
used the screen file for partition N is screen.N or whatever is
specified by the -screen command-line option.
:line
[-restart restartfile {remap} datafile keyword value ...] :link(restart)
Convert the restart file into a data file and immediately exit. This
is the same operation as if the following 2-line input script were
run:
read_restart restartfile {remap}
write_data datafile keyword value ... :pre
Note that the specified restartfile and datafile can have wild-card
characters ("*",%") as described by the
"read_restart"_read_restart.html and "write_data"_write_data.html
commands. But a filename such as file.* will need to be enclosed in
quotes to avoid shell expansion of the "*" character.
Note that following restartfile, the optional flag {remap} can be
used. This has the same effect as adding it to the
"read_restart"_read_restart.html command, as explained on its doc
page. This is only useful if the reading of the restart file triggers
an error that atoms have been lost. In that case, use of the remap
flag should allow the data file to still be produced.
Also note that following datafile, the same optional keyword/value
pairs can be listed as used by the "write_data"_write_data.html
command.
:line
[-reorder] :link(reorder)
This option has 2 forms:
-reorder nth N
-reorder custom filename :pre
Reorder the processors in the MPI communicator used to instantiate
LAMMPS, in one of several ways. The original MPI communicator ranks
all P processors from 0 to P-1. The mapping of these ranks to
physical processors is done by MPI before LAMMPS begins. It may be
useful in some cases to alter the rank order. E.g. to insure that
cores within each node are ranked in a desired order. Or when using
the "run_style verlet/split"_run_style.html command with 2 partitions
to insure that a specific Kspace processor (in the 2nd partition) is
matched up with a specific set of processors in the 1st partition.
See the "Speed tips"_Speed_tips.html doc page for more details.
If the keyword {nth} is used with a setting {N}, then it means every
Nth processor will be moved to the end of the ranking. This is useful
when using the "run_style verlet/split"_run_style.html command with 2
partitions via the -partition command-line switch. The first set of
processors will be in the first partition, the 2nd set in the 2nd
partition. The -reorder command-line switch can alter this so that
the 1st N procs in the 1st partition and one proc in the 2nd partition
will be ordered consecutively, e.g. as the cores on one physical node.
This can boost performance. For example, if you use "-reorder nth 4"
and "-partition 9 3" and you are running on 12 processors, the
processors will be reordered from
0 1 2 3 4 5 6 7 8 9 10 11 :pre
to
0 1 2 4 5 6 8 9 10 3 7 11 :pre
so that the processors in each partition will be
0 1 2 4 5 6 8 9 10
3 7 11 :pre
See the "processors" command for how to insure processors from each
partition could then be grouped optimally for quad-core nodes.
If the keyword is {custom}, then a file that specifies a permutation
of the processor ranks is also specified. The format of the reorder
file is as follows. Any number of initial blank or comment lines
(starting with a "#" character) can be present. These should be
followed by P lines of the form:
I J :pre
where P is the number of processors LAMMPS was launched with. Note
that if running in multi-partition mode (see the -partition switch
above) P is the total number of processors in all partitions. The I
and J values describe a permutation of the P processors. Every I and
J should be values from 0 to P-1 inclusive. In the set of P I values,
every proc ID should appear exactly once. Ditto for the set of P J
values. A single I,J pairing means that the physical processor with
rank I in the original MPI communicator will have rank J in the
reordered communicator.
Note that rank ordering can also be specified by many MPI
implementations, either by environment variables that specify how to
order physical processors, or by config files that specify what
physical processors to assign to each MPI rank. The -reorder switch
simply gives you a portable way to do this without relying on MPI
itself. See the "processors out"_processors.html command for how
to output info on the final assignment of physical processors to
the LAMMPS simulation domain.
:line
[-screen file] :link(screen)
Specify a file for LAMMPS to write its screen information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
screen. If this switch is used, LAMMPS writes to the specified file
instead and you will see no screen output. In multi-partition mode,
if the switch is not used, hi-level status information is written to
the screen. Each partition also writes to a screen.N file where N is
the partition ID. If the switch is specified in multi-partition mode,
the hi-level screen dump is named "file" and each partition also
writes screen information to a file.N. For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed. Option -pscreen will override the name of the
partition screen files file.N.
:line
[-suffix style args] :link(suffix)
Use variants of various styles if they exist. The specified style can
be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These
refer to optional packages that LAMMPS can be built with, as described
above in "Section 2.3"_#start_3. The "gpu" style corresponds to the
GPU package, the "intel" style to the USER-INTEL package, the "kk"
style to the KOKKOS package, the "opt" style to the OPT package, and
the "omp" style to the USER-OMP package. The hybrid style is the only
style that accepts arguments. It allows for two packages to be
specified. The first package specified is the default and will be used
if it is available. If no style is available for the first package,
the style for the second package will be used if available. For
example, "-suffix hybrid intel omp" will use styles from the
USER-INTEL package if they are installed and available, but styles for
the USER-OMP package otherwise.
Along with the "-package" command-line switch, this is a convenient
mechanism for invoking accelerator packages and their options without
having to edit an input script.
As an example, all of the packages provide a "pair_style
lj/cut"_pair_lj.html variant, with style names lj/cut/gpu,
lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style
can be specified explicitly in your input script, e.g. pair_style
lj/cut/gpu. If the -suffix switch is used the specified suffix
(gpu,intel,kk,omp,opt) is automatically appended whenever your input
script command creates a new "atom"_atom_style.html,
"pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or
"run"_run_style.html style. If the variant version does not exist,
the standard version is created.
For the GPU package, using this command-line switch also invokes the
default GPU settings, as if the command "package gpu 1" were used at
the top of your input script. These settings can be changed by using
the "-package gpu" command-line switch or the "package
gpu"_package.html command in your script.
For the USER-INTEL package, using this command-line switch also
invokes the default USER-INTEL settings, as if the command "package
intel 1" were used at the top of your input script. These settings
can be changed by using the "-package intel" command-line switch or
the "package intel"_package.html command in your script. If the
USER-OMP package is also installed, the hybrid style with "intel omp"
arguments can be used to make the omp suffix a second choice, if a
requested style is not available in the USER-INTEL package. It will
also invoke the default USER-OMP settings, as if the command "package
omp 0" were used at the top of your input script. These settings can
be changed by using the "-package omp" command-line switch or the
"package omp"_package.html command in your script.
For the KOKKOS package, using this command-line switch also invokes
the default KOKKOS settings, as if the command "package kokkos" were
used at the top of your input script. These settings can be changed
by using the "-package kokkos" command-line switch or the "package
kokkos"_package.html command in your script.
For the OMP package, using this command-line switch also invokes the
default OMP settings, as if the command "package omp 0" were used at
the top of your input script. These settings can be changed by using
the "-package omp" command-line switch or the "package
omp"_package.html command in your script.
The "suffix"_suffix.html command can also be used within an input
script to set a suffix, or to turn off or back on any suffix setting
made via the command line.
:line
[-var name value1 value2 ...] :link(var)
Specify a variable that will be defined for substitution purposes when
the input script is read. This switch can be used multiple times to
define multiple variables. "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as $\{abc\}). An "index-style
variable"_variable.html will be created and populated with the
subsequent values, e.g. a set of filenames. Using this command-line
option is equivalent to putting the line "variable name index value1
value2 ..." at the beginning of the input script. Defining an index
variable as a command-line argument overrides any setting for the same
index variable in the input script, since index variables cannot be
re-defined.
See the "variable"_variable.html command for more info on defining
index and other kinds of variables and the "Commands
parse"_Commands_parse.html page for more info on using variables in
input scripts.
NOTE: Currently, the command-line parser looks for arguments that
start with "-" to indicate new switches. Thus you cannot specify
multiple variable values if any of them start with a "-", e.g. a
negative numeric value. It is OK if the first value1 starts with a
"-", since it is automatically skipped.

176
doc/src/Run_output.txt Normal file
View File

@ -0,0 +1,176 @@
"Higher level section"_Run.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
Screen and logfile output :h3
As LAMMPS reads an input script, it prints information to both the
screen and a log file about significant actions it takes to setup a
simulation. When the simulation is ready to begin, LAMMPS performs
various initializations, and prints info about the run it is about to
perform, including the amount of memory (in MBytes per processor) that
the simulation requires. It also prints details of the initial
thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few
timesteps. When the run concludes, LAMMPS prints the final
thermodynamic state and a total run time for the simulation. It also
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:
Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms :pre
Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s
97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre
MPI task timings breakdown:
Section | min time | avg time | max time |%varavg| %total
---------------------------------------------------------------
Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60
Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21
Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97
Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12
Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74
Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02
Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08
Other | | 0.007178 | | | 0.26 :pre
Nlocal: 501 ave 508 max 490 min
Histogram: 1 0 0 0 0 0 1 1 0 1
Nghost: 6586.25 ave 6628 max 6548 min
Histogram: 1 0 1 0 0 0 1 0 0 1
Neighs: 177007 ave 180562 max 170212 min
Histogram: 1 0 0 0 0 0 0 1 1 1 :pre
Total # of neighbors = 708028
Ave neighs/atom = 353.307
Ave special neighs/atom = 2.34032
Neighbor list builds = 26
Dangerous builds = 0 :pre
:line
The first section provides a global loop timing summary. The {loop
time} is the total wall-clock time for the simulation to run. The
{Performance} line is provided for convenience to help predict how
long it will take to run a desired physical simulation. The {CPU use}
line provides the CPU utilization per MPI task; it should be close to
100% times the number of OpenMP threads (or 1 of not using OpenMP).
Lower numbers correspond to delays due to file I/O or insufficient
thread utilization.
:line
The {MPI task} section gives the breakdown of the CPU run time (in
seconds) into major categories:
{Pair} = non-bonded force computations
{Bond} = bonded interactions: bonds, angles, dihedrals, impropers
{Kspace} = long-range interactions: Ewald, PPPM, MSM
{Neigh} = neighbor list construction
{Comm} = inter-processor communication of atoms and their properties
{Output} = output of thermodynamic info and dump files
{Modify} = fixes and computes invoked by fixes
{Other} = all the remaining time :ul
For each category, there is a breakdown of the least, average and most
amount of wall time any processor spent on this category of
computation. The "%varavg" is the percentage by which the max or min
varies from the average. This is an indication of load imbalance. A
percentage close to 0 is perfect load balance. A large percentage is
imbalance. The final "%total" column is the percentage of the total
loop time is spent in this category.
When using the "timer full"_timer.html setting, an additional column
is added that also prints the CPU utilization in percent. In addition,
when using {timer full} and the "package omp"_package.html command are
active, a similar timing summary of time spent in threaded regions to
monitor thread utilization and load balance is provided. A new {Thread
timings} section is also added, which lists the time spent in reducing
the per-thread data elements to the storage for non-threaded
computation. These thread timings are measured for the first MPI rank
only and and thus, because the breakdown for MPI tasks can change from
MPI rank to MPI rank, this breakdown can be very different for
individual ranks. Here is an example output for this section:
Thread timings breakdown (MPI rank 0):
Total threaded time 0.6846 / 90.6%
Section | min time | avg time | max time |%varavg| %total
---------------------------------------------------------------
Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18
Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68
Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89
Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70
Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre
:line
The third section above lists the number of owned atoms (Nlocal),
ghost atoms (Nghost), and pair-wise neighbors stored per processor.
The max and min values give the spread of these values across
processors with a 10-bin histogram showing the distribution. The total
number of histogram counts is equal to the number of processors.
:line
The last section gives aggregate statistics (across all processors)
for pair-wise neighbors and special neighbors that LAMMPS keeps track
of (see the "special_bonds"_special_bonds.html command). The number
of times neighbor lists were rebuilt is tallied, as is the number of
potentially {dangerous} rebuilds. If atom movement triggered neighbor
list rebuilding (see the "neigh_modify"_neigh_modify.html command),
then dangerous reneighborings are those that were triggered on the
first timestep atom movement was checked for. If this count is
non-zero you may wish to reduce the delay factor to insure no force
interactions are missed by atoms moving beyond the neighbor skin
distance before a rebuild takes place.
:line
If an energy minimization was performed via the
"minimize"_minimize.html command, additional information is printed,
e.g.
Minimization stats:
Stopping criterion = linesearch alpha is zero
Energy initial, next-to-last, final =
-6372.3765206 -8328.46998942 -8328.46998942
Force two-norm initial, final = 1059.36 5.36874
Force max component initial, final = 58.6026 1.46872
Final line search alpha, max atom move = 2.7842e-10 4.0892e-10
Iterations, force evaluations = 701 1516 :pre
The first line prints the criterion that determined minimization was
converged. The next line lists the initial and final energy, as well
as the energy on the next-to-last iteration. The next 2 lines give a
measure of the gradient of the energy (force on all atoms). The
2-norm is the "length" of this 3N-component force vector; the largest
component (x, y, or z) of force (infinity-norm) is also given. Then
information is provided about the line search and statistics on how
many iterations and force-evaluations the minimizer required.
Multiple force evaluations are typically done at each iteration to
perform a 1d line minimization in the search direction. See the
"minimize"_minimize.html doc page for more details.
:line
If a "kspace_style"_kspace_style.html long-range Coulombics solver
that performs FFTs was used during the run (PPPM, Ewald), then
additional information is printed, e.g.
FFT time (% of Kspce) = 0.200313 (8.34477)
FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre
The first line is the time spent doing 3d FFTs (several per timestep)
and the fraction it represents of the total KSpace time (listed
above). Each 3d FFT requires computation (3 sets of 1d FFTs) and
communication (transposes). The total flops performed is 5Nlog_2(N),
where N is the number of points in the 3d grid. The FFTs are timed
with and without the communication and a Gflop rate is computed. The
3d rate is with communication; the 1d rate is without (just the 1d
FFTs). Thus you can estimate what fraction of your FFT time was spent
in communication, roughly 75% in the example above.

73
doc/src/Run_windows.txt Normal file
View File

@ -0,0 +1,73 @@
"Higher level section"_Run.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
Running LAMMPS on Windows :h3
To run a serial (non-MPI) executable, follow these steps:
Get a command prompt by going to Start->Run... ,
then typing "cmd". :ulb,l
Move to the directory where you have your input script,
(e.g. by typing: cd "Documents"). :l
At the command prompt, type "lmp_serial -in in.file", where
in.file is the name of your LAMMPS input script. :l,ule
Note that the serial executable includes support for multi-threading
parallelization from the styles in the USER-OMP packages. To run with
4 threads, you can type this:
lmp_serial -in in.lj -pk omp 4 -sf omp :pre
:line
For the MPI executable, which allows you to run LAMMPS under Windows
in parallel, follow these steps.
Download and install a compatible MPI library binary package:
for 32-bit Windows: "mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi
for 64-bit Windows: "mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi :ul
The LAMMPS Windows installer packages will automatically adjust your
path for the default location of this MPI package. After the
installation of the MPICH2 software, it needs to be integrated into
the system. For this you need to start a Command Prompt in
{Administrator Mode} (right click on the icon and select it). Change
into the MPICH2 installation directory, then into the subdirectory
[bin] and execute [smpd.exe -install]. Exit the command window.
Get a new, regular command prompt by going to Start->Run... ,
then typing "cmd". :ulb,l
Move to the directory where you have your input file
(e.g. by typing: cd "Documents"). :l,ule
Then type something like this:
mpiexec -localonly 4 lmp_mpi -in in.file
mpiexec -np 4 lmp_mpi -in in.file :pre
where in.file is the name of your LAMMPS input script. For the latter
case, you may be prompted to enter your password.
In this mode, output may not immediately show up on the screen, so if
your input script takes a long time to execute, you may need to be
patient before the output shows up.
The parallel executable can also run on a single processor by typing
something like this:
lmp_mpi -in in.lj :pre
Note that the parallel executable also includes OpenMP
multi-threading, which can be combined with MPI using something like:
mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre

1823
doc/src/Section_start.txt
View File

File diff suppressed because it is too large Load Diff