342 lines
13 KiB
Plaintext
342 lines
13 KiB
Plaintext
"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 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 :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
|