"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 building both with CMake and make.

"FFT library"_#fft for use with the "kspace_style pppm"_kspace_style.html command
"Size of LAMMPS data types"_#size
"Read or write compressed files"_#gzip
"Output of JPG and PNG files"_#graphics via the "dump image"_dump_image.html command
"Output of movie files"_#graphics via the "dump_movie"_dump_image.html command
"Memory allocation alignment"_#align
"Workaround for long long integers"_#longlong
"Error handling exceptions"_#exceptions when using LAMMPS as a library :all(b)

:line

FFT library :h4,link(fft)

When the KSPACE package is included in a LAMMPS build, the
"kspace_style pppm"_kspace_style.html command performs 3d FFTs which
require use of an FFT library to compute 1d FFTs.  The KISS FFT
library is included with LAMMPS but other libraries can be faster.
LAMMPS can use them if they are available on your system.

[CMake variables]:

-D FFT=value              # FFTW3 or MKL or KISS, 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

NOTE: The values for the FFT variable must be in upper-case.  This is
an exception to the rule that all CMake variables can be specified
with lower-case values.

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 FFTW3_LIBRARIES=path     # path to FFTW3 libraries
-D MKL_INCLUDE_DIRS=path    # ditto for Intel MKL library
-D MKL_LIBRARIES=path :pre

[Makefile.machine settings]:

FFT_INC = -DFFT_FFTW3         # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_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
                              # default is FFT_PACK_ARRAY if not specified

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 =       -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.  It is portable across all platforms.  Depending on the
size of the FFTs and the number of processors used, the other
libraries listed here can be faster.

However, note that long-range Coulombics are only a portion of the
per-timestep CPU cost, FFTs are only a portion of long-range
Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
communication can be costly).  A breakdown of these timings is printed
to the screen at the end of a run using the "kspace_style
pppm"_kspace_style.html command.  The "Run output"_Run_output.html
doc page gives more details.

FFTW is a fast, portable FFT library that should also work on any
platform and can be faster than the KISS FFT library.  You can
download it from "www.fftw.org"_http://www.fftw.org.  LAMMPS requires
version 3.X; the legacy version 2.1.X is no longer 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).

Performing 3d FFTs in parallel can be time consuming due to data
access and required communication.  This cost can be reduced by
performing single-precision FFTs instead of double precision.  Single
precision means the real and imaginary parts of a complex datum are
4-byte floats.  Double precision means they are 8-byte doubles.  Note
that Fourier transform and related PPPM operations are somewhat less
sensitive to floating point truncation errors and thus the resulting
error is less than the difference in precision. Using the -DFFT_SINGLE
setting trades off a little accuracy for reduced memory use and
parallel communication costs for transposing 3d FFT data.

When using -DFFT_SINGLE with FFTW3 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

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 :h4,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
                               # default is LAMMPS_SMALLBIG if not specified
[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 and the USER-INTEL package are currently
not compatible with the "bigbig" setting. Also, there are limitations
when using the library interface. Some functions with known issues
have been replaced by dummy calls printing a corresponding error rather
than crashing randomly or corrupting data.

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 :h4,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
outputs movie files in MPEG format.  Using these options requires the
following settings:

[CMake variables]:

-D WITH_JPEG=value      # yes or no
                          # default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value       # yes or no
                          # default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_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, executable 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 libz.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, libz.a (.so) files if make cannot find them
JPG_LIB = -ljpeg -lpng -lz       # 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 :h4,link(gzip)

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 WITH_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 :pre

[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_details.html#PKG-COMPRESS enables.

:line

Memory allocation alignment :h4,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.
On most current systems, the malloc() implementation returns
pointers that are aligned to 16-byte boundaries. Using SSE vector
instructions efficiently, however, requires memory blocks being
aligned on 64-byte boundaries.

[CMake variable]:

-D LAMMPS_MEMALIGN=value            # 0, 8, 16, 32, 64 (default) :pre

Use a LAMMPS_MEMALIGN value of 0 to disable using posix_memalign()
and revert to using the malloc() C-library function instead.  When
compiling LAMMPS for Windows systems, malloc() will always be used
and this setting ignored.

[Makefile.machine setting]:

LMP_INC = -DLAMMPS_MEMALIGN=value   # 8, 16, 32, 64 :pre

Do not set -DLAMMPS_MEMALIGN, if you want to have memory allocated
with the malloc() function call instead. -DLAMMPS_MEMALIGN [cannot]
be used on Windows, as it does use different function calls for
allocating aligned memory, that are not compatible with how LAMMPS
manages its dynamical memory.

:line

Workaround for long long integers :h4,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 :h4,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
