<li class="toctree-l2"><a class="reference internal" href="#what-s-in-the-lammps-distribution">2.1. What’s in the LAMMPS distribution</a></li>
<li class="toctree-l2"><a class="reference internal" href="#making-lammps">2.2. Making LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="#making-lammps-with-optional-packages">2.3. Making LAMMPS with optional packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-via-the-make-py-script">2.4. Building LAMMPS via the Make.py script</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-as-a-library">2.5. Building LAMMPS as a library</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#additional-requirement-for-using-a-shared-library">2.5.3. <strong>Additional requirement for using a shared library:</strong></a></li>
<li class="toctree-l3"><a class="reference internal" href="#calling-the-lammps-library">2.5.4. <strong>Calling the LAMMPS library:</strong></a></li>
<span id="start-1"></span><h2>2.1. What’s in the LAMMPS distribution<a class="headerlink" href="#what-s-in-the-lammps-distribution" title="Permalink to this headline">¶</a></h2>
<p>When you download a LAMMPS tarball you will need to unzip and untar
the downloaded file with the following commands, after placing the
<p>This will create a LAMMPS directory containing two files and several
sub-directories:</p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="79%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>README</td>
<td>text file</td>
</tr>
<tr class="row-even"><td>LICENSE</td>
<td>the GNU General Public License (GPL)</td>
</tr>
<tr class="row-odd"><td>bench</td>
<td>benchmark problems</td>
</tr>
<tr class="row-even"><td>doc</td>
<td>documentation</td>
</tr>
<tr class="row-odd"><td>examples</td>
<td>simple test problems</td>
</tr>
<tr class="row-even"><td>potentials</td>
<td>embedded atom method (EAM) potential files</td>
</tr>
<tr class="row-odd"><td>src</td>
<td>source files</td>
</tr>
<tr class="row-even"><td>tools</td>
<td>pre- and post-processing tools</td>
</tr>
</tbody>
</table>
<p>Note that the <a class="reference external" href="download">download page</a> also has links to download
Windows exectubles and installers, as well as pre-built executables
for a few specific Linux distributions. It also has instructions for
how to download/install LAMMPS for Macs (via Homebrew), and to
download and update LAMMPS from SVN and Git repositories, which gives
you the same files that are in the download tarball.</p>
<p>The Windows and Linux executables for serial or parallel only include
certain packages and bug-fixes/upgrades listed on <a class="reference external" href="http://lammps.sandia.gov/bug.html">this page</a> up to a certain date, as
stated on the download page. If you want an executable with
non-included packages or that is more current, then you’ll need to
build LAMMPS yourself, as discussed in the next section.</p>
<p>Skip to the <a class="reference internal" href="#start-6"><span>Running LAMMPS</span></a> sections for info on how to
launch a LAMMPS Windows executable on a Windows box.</p>
<hr class="docutils" />
</div>
<div class="section" id="making-lammps">
<span id="start-2"></span><h2>2.2. Making LAMMPS<a class="headerlink" href="#making-lammps" title="Permalink to this headline">¶</a></h2>
<p>This section has the following sub-sections:</p>
<ul class="simple">
<li><a class="reference internal" href="#start-2-1"><span>Read this first</span></a></li>
<li><a class="reference internal" href="#start-2-2"><span>Steps to build a LAMMPS executable</span></a></li>
<li><a class="reference internal" href="#start-2-3"><span>Common errors that can occur when making LAMMPS</span></a></li>
This gives preference to a file you have created/edited and put in
src/MAKE/MINE.</p>
<p>Note that on a multi-processor or multi-core platform you can launch a
parallel make, by using the “-j” switch with the make command, which
will build LAMMPS more quickly.</p>
<p>If you get no errors and an executable like lmp_mpi or lmp_g++_serial
or lmp_mac is produced, then you’re done; it’s your lucky day.</p>
<p>Note that by default only a few of LAMMPS optional packages are
installed. To build LAMMPS with optional packages, see <a class="reference internal" href="#start-3"><span>this section</span></a> below.</p>
<p><strong>Step 1</strong></p>
<p>If Step 0 did not work, you will need to create a low-level Makefile
for your machine, like Makefile.foo. You should make a copy of an
existing Makefile.* in src/MAKE or one of its sub-directories as a
starting point. The only portions of the file you need to edit are
the first line, the “compiler/linker settings” section, and the
“LAMMPS-specific settings” section. When it works, put the edited
file in src/MAKE/MINE and it will not be altered by any future LAMMPS
updates.</p>
<p><strong>Step 2</strong></p>
<p>Change the first line of Makefile.foo to list the word “foo” after the
“#”, and whatever other options it will set. This is the line you
will see if you just type “make”.</p>
<p><strong>Step 3</strong></p>
<p>The “compiler/linker settings” section lists compiler and linker
settings for your C++ compiler, including optimization flags. You can
use g++, the open-source GNU compiler, which is available on all Unix
systems. You can also use mpicxx which will typically be available if
MPI is installed on your system, though you should check which actual
compiler it wraps. Vendor compilers often produce faster code. On
boxes with Intel CPUs, we suggest using the Intel icc compiler, which
can be downloaded from <a class="reference external" href="http://www.intel.com/software/products/noncom">Intel’s compiler site</a>.</p>
<p>If building a C++ code on your machine requires additional libraries,
then you should list them as part of the LIB variable. You should
not need to do this if you use mpicxx.</p>
<p>The DEPFLAGS setting is what triggers the C++ compiler to create a
dependency list for a source file. This speeds re-compilation when
source (<em>.cpp) or header (</em>.h) files are edited. Some compilers do
not support dependency file creation, or may use a different switch
than -D. GNU g++ and Intel icc works with -D. If your compiler can’t
create dependency files, then you’ll need to create a Makefile.foo
patterned after Makefile.storm, which uses different rules that do not
involve dependency files. Note that when you build LAMMPS for the
first time on a new platform, a long list of <a href="#id1"><span class="problematic" id="id2">*</span></a>.d files will be printed
out rapidly. This is not an error; it is the Makefile doing its
normal creation of dependencies.</p>
<p><strong>Step 4</strong></p>
<p>The “system-specific settings” section has several parts. Note that
if you change any -D setting in this section, you should do a full
re-compile, after typing “make clean” (which will describe different
clean options).</p>
<p>The LMP_INC variable is used to include options that turn on ifdefs
within the LAMMPS code. The options that are currently recogized are:</p>
<ul class="simple">
<li>-DLAMMPS_GZIP</li>
<li>-DLAMMPS_JPEG</li>
<li>-DLAMMPS_PNG</li>
<li>-DLAMMPS_FFMPEG</li>
<li>-DLAMMPS_MEMALIGN</li>
<li>-DLAMMPS_XDR</li>
<li>-DLAMMPS_SMALLBIG</li>
<li>-DLAMMPS_BIGBIG</li>
<li>-DLAMMPS_SMALLSMALL</li>
<li>-DLAMMPS_LONGLONG_TO_LONG</li>
<li>-DPACK_ARRAY</li>
<li>-DPACK_POINTER</li>
<li>-DPACK_MEMCPY</li>
</ul>
<p>The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It 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.</p>
<p>If you use -DLAMMPS_JPEG, the <a class="reference internal" href="dump_image.html"><em>dump image</em></a> command
will be able to write out JPEG image files. For JPEG files, you must
also link LAMMPS with a JPEG library, as described below. If you use
-DLAMMPS_PNG, the <a class="reference internal" href="dump.html"><em>dump image</em></a> command will be able to write
out PNG image files. For PNG files, you must also link LAMMPS with a
PNG library, as described below. If neither of those two defines are
used, LAMMPS will only be able to write out uncompressed PPM image
files.</p>
<p>If you use -DLAMMPS_FFMPEG, the <a class="reference internal" href="dump_image.html"><em>dump movie</em></a> command
will be available to support on-the-fly generation of rendered movies
the need to store intermediate image files. It requires that your
machines supports the “popen” function in the standard runtime library
and that an FFmpeg executable can be found by LAMMPS during the run.</p>
<p>Using -DLAMMPS_MEMALIGN=<bytes> enables the use of the
posix_memalign() call instead of malloc() when large chunks or memory
are allocated by LAMMPS. This can help to make more efficient use of
vector instructions of modern CPUS, since dynamically allocated memory
has to be aligned on larger than default byte boundaries (e.g. 16
bytes instead of 8 bytes on x86 type platforms) for optimal
performance.</p>
<p>If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the <a class="reference internal" href="dump.html"><em>dump</em></a> command for details.</p>
<p>Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, -D-
DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These
settings refer to use of 4-byte (small) vs 8-byte (big) integers
within LAMMPS, as specified in src/lmptype.h. The only reason to use
the BIGBIG setting is to enable simulation of huge molecular systems
(which store bond topology info) with more than 2 billion atoms, or to
track the image flags of moving atoms that wrap around a periodic box
more than 512 times. Normally, the only reason to use SMALLSMALL is
if your machine does not support 64-bit integers, though you can use
SMALLSMALL setting if you are running in serial or on a desktop
machine or small cluster where you will never run large systems or for
long time (more than 2 billion atoms, more than 2 billion timesteps).
See the <a class="reference internal" href="#start-2-4"><span>Additional build tips</span></a> section below for more
details on these settings.</p>
<p>Note that two packages, USER-ATC and USER-CUDA are not currently
compatible with -DLAMMPS_BIGBIG. Also the GPU package requires the
lib/gpu library to be compiled with the same setting, or the link will
fail.</p>
<p>The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or
MPI version does not recognize “long long” data types. In this case a
“long” data type is likely already 64-bits, in which case this setting
will convert to that data type.</p>
<p>Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
options can make for faster parallel FFTs (in the PPPM solver) on some
platforms. The -DPACK_ARRAY setting is the default. See the
<a class="reference internal" href="kspace_style.html"><em>kspace_style</em></a> command for info about PPPM. See
Step 6 below for info about building LAMMPS with an FFT library.</p>
<p><strong>Step 5</strong></p>
<p>The 3 MPI variables are used to specify an MPI library to build LAMMPS
with. Note that you do not need to set these if you use the MPI
compiler mpicxx for your CC and LINK setting in the section above.
The MPI wrapper knows where to find the needed files.</p>
<p>If you want LAMMPS to run in parallel, you must have an MPI library
installed on your platform. If MPI is installed on your system in the
usual place (under /usr/local), you also may not need to specify these
3 variables, assuming /usr/local is in your path. On some large
parallel machines which use “modules” for their compile/link
environements, you may simply need to include the correct module in
your build environment, before building LAMMPS. Or the parallel
machine may have a vendor-provided MPI which the compiler has no
trouble finding.</p>
<p>Failing this, these 3 variables can be used to specify where the mpi.h
file (MPI_INC) and the MPI library file (MPI_PATH) are found and the
name of the library file (MPI_LIB).</p>
<p>If you are installing MPI yourself, we recommend Argonne’s MPICH2
or OpenMPI. MPICH can be downloaded from the <a class="reference external" href="http://www.mcs.anl.gov/research/projects/mpich2/">Argonne MPI site</a>. OpenMPI can
be downloaded from the <a class="reference external" href="http://www.open-mpi.org">OpenMPI site</a>.
Other MPI packages should also work. If you are running on a big
parallel platform, your system people or the vendor should have
already installed a version of MPI, which is likely to be faster
than a self-installed MPICH or OpenMPI, so find out how to build
and link with it. If you use MPICH or OpenMPI, you will have to
configure and build it for your platform. The MPI configure script
should have compiler options to enable you to use the same compiler
you are using for the LAMMPS build, which can avoid problems that can
arise when linking LAMMPS to the MPI library.</p>
<p>If you just want to run LAMMPS on a single processor, you can use the
dummy MPI library provided in src/STUBS, since you don’t need a true
MPI library installed on your system. See src/MAKE/Makefile.serial
for how to specify the 3 MPI variables in this case. You will also
need to build the STUBS library for your platform before making LAMMPS
itself. Note that if you are building with src/MAKE/Makefile.serial,
e.g. by typing “make serial”, then the STUBS library is built for you.</p>
<p>To build the STUBS library from the src directory, type “make
mpi-stubs”, or from the src/STUBS dir, type “make”. This should
create a libmpi_stubs.a file suitable for linking to LAMMPS. If the
build fails, you will need to edit the STUBS/Makefile for your
platform.</p>
<p>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.</p>
<p><strong>Step 6</strong></p>
<p>The 3 FFT variables allow you to specify an FFT library which LAMMPS
uses (for performing 1d FFTs) when running the particle-particle
particle-mesh (PPPM) option for long-range Coulombics via the
ACML, and T3E. For backward compatability, using -DFFT_FFTW will use
the FFTW2 library. Using -DFFT_NONE will use the KISS library
described above.</p>
<p>You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables,
so the compiler and linker can find the needed FFT header and library
files. Note that on some large parallel machines which use “modules”
for their compile/link environements, you may simply need to include
the correct module in your build environment. Or the parallel machine
may have a vendor-provided FFT library which the compiler has no
trouble finding.</p>
<p>FFTW is a fast, portable library that should also work on any
platform. You can download it from
<a class="reference external" href="http://www.fftw.org">www.fftw.org</a>. Both the legacy version 2.1.X and
the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3.
Building FFTW for your box should be as simple as ./configure; make.
Note that on some platforms FFTW2 has been pre-installed, and uses
renamed files indicating the precision it was compiled with,
e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can
specify an additional define variable for FFT_INC called -DFFTW_SIZE,
which will select the correct include file. In this case, for FFT_LIB
you must also manually specify the correct library, namely -lsfftw or
-ldfftw.</p>
<p>The FFT_INC variable also allows for a -DFFT_SINGLE setting that will
use single-precision FFTs with PPPM, which can speed-up long-range
calulations, particularly in parallel or on GPUs. 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 the -DFFT_SINGLE setting trades off a little
accuracy for reduced memory use and parallel communication costs for
transposing 3d FFT data. Note that single precision FFTs have only
been tested with the FFTW3, FFTW2, MKL, and KISS FFT options.</p>
<p><strong>Step 7</strong></p>
<p>The 3 JPG variables allow you to specify a JPEG and/or PNG library
which LAMMPS uses when writing out JPEG or PNG files via the <a class="reference internal" href="dump_image.html"><em>dump image</em></a> command. These can be left blank if you do not
use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step
4, since in that case JPEG/PNG output will be disabled.</p>
<p>A standard JPEG library usually goes by the name libjpeg.a or
libjpeg.so and has an associated header file jpeglib.h. Whichever
JPEG library you have on your platform, you’ll need to set the
appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the
compiler and linker can find it.</p>
<p>A standard PNG library usually goes by the name libpng.a or libpng.so
and has an associated header file png.h. Whichever PNG library you
have on your platform, you’ll need to set the appropriate JPG_INC,
JPG_PATH, and JPG_LIB variables, so that the compiler and linker can
find it.</p>
<p>As before, if these header and library files are in the usual place on
your machine, you may not need to set these variables.</p>
<p><strong>Step 8</strong></p>
<p>Note that by default only a few of LAMMPS optional packages are
installed. To build LAMMPS with optional packages, see <a class="reference internal" href="#start-3"><span>this section</span></a> below, before proceeding to Step 9.</p>
<p><strong>Step 9</strong></p>
<p>That’s it. Once you have a correct Makefile.foo, and you have
pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need
to do from the src directory is type something like this:</p>
<p>You can make LAMMPS for multiple platforms from the same src
directory. Each target creates its own object sub-directory called
Obj_target where it stores the system-specific <a href="#id3"><span class="problematic" id="id4">*</span></a>.o files.</p>
<ol class="arabic simple" start="2">
<li>Cleaning up.</li>
</ol>
<p>Typing “make clean-all” or “make clean-machine” will delete <a href="#id5"><span class="problematic" id="id6">*</span></a>.o object
files created when LAMMPS is built, for either all builds or for a
particular machine.</p>
<p>(3) Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or
-DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL</p>
<p>As explained above, any of these 3 settings can be specified on the
LMP_INC line in your low-level src/MAKE/Makefile.foo.</p>
<p>The default is -DLAMMPS_SMALLBIG which allows for systems with up to
2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for
atomic systems which do not store bond topology info and thus do not
require atom IDs. If you use atom IDs for atomic systems (which is
the default) or if you use a molecular model, which stores bond
topology info and thus requires atom IDs, the limit is 2^31 atoms
(about 2 billion). This is because the IDs are stored in 32-bit
integers.</p>
<p>Likewise, with this setting, the 3 image flags for each atom (see the
<a class="reference internal" href="dump.html"><em>dump</em></a> doc page for a discussion) are stored in a 32-bit
integer, which means the atoms can only wrap around a periodic box (in
each dimension) at most 512 times. If atoms move through the periodic
box more than this many times, the image flags will “roll over”,
e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the <a class="reference internal" href="compute_msd.html"><em>compute msd</em></a> command, to be faulty.</p>
<p>To allow for larger atomic systems with atom IDs or larger molecular
systems or larger image flags, compile with -DLAMMPS_BIGBIG. This
stores atom IDs and image flags in 64-bit integers. This enables
atomic or molecular systems with atom IDS of up to 2^63 atoms (about
9e18). And image flags will not “roll over” until they reach 2^20 =
1048576.</p>
<p>If your system does not support 8-byte integers, you will need to
compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the
total number of atoms (for atomic or molecular systems) and timesteps
to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512.</p>
<p>Note that in src/lmptype.h there are definitions of all these data
types as well as the MPI data types associated with them. The MPI
types need to be consistent with the associated C data types, or else
LAMMPS will generate a run-time error. As far as we know, the
settings defined in src/lmptype.h are portable and work on every
current system.</p>
<p>In all cases, the size of problem that can be run on a per-processor
basis is limited by 4-byte integer storage to 2^31 atoms per processor
(about 2 billion). This should not normally be a limitation since such
a problem would have a huge per-processor memory footprint due to
neighbor lists and would run very slowly in terms of CPU secs/timestep.</p>
<hr class="docutils" />
<p id="start-2-5"><strong>*Building for a Mac:*</strong></p>
<p>OS X is BSD Unix, so it should just work. See the
src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files.</p>
<hr class="docutils" />
<p id="start-2-6"><strong>*Building for Windows:*</strong></p>
<p>The LAMMPS download page has an option to download both a serial and
parallel pre-built Windows executable. See the <a class="reference internal" href="#start-6"><span>Running LAMMPS</span></a> section for instructions on running these executables
on a Windows box.</p>
<p>The pre-built executables hosted on the <a class="reference external" href="http://lammps.sandia.gov/download.html">LAMMPS download page</a> are built with a subset
of the available packages; see the download page for the list. These
are single executable files. No examples or documentation in
included. You will need to download the full source code package to
obtain those.</p>
<p>As an alternative, you can download “daily builds” (and some older
<span id="start-3"></span><h2>2.3. Making LAMMPS with optional packages<a class="headerlink" href="#making-lammps-with-optional-packages" title="Permalink to this headline">¶</a></h2>
<p>This section has the following sub-sections:</p>
<p>to run your executable with the optional <a class="reference internal" href="#start-7"><span>-h command-line switch</span></a> for “help”, which will list the styles and commands
known to your executable.</p>
<p>There are two kinds of packages in LAMMPS, standard and user packages.
More information about the contents of standard and user packages is
given in <a class="reference internal" href="Section_packages.html"><em>Section_packages</em></a> of the manual. The
difference between standard and user packages is as follows:</p>
<p>Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LAMMPS.</p>
<p>User packages have been contributed by users, and always begin with
the user prefix. If they are a single command (single file), they are
typically in the user-misc package. Otherwise, they are a a set of
files grouped together which add a specific functionality to the code.</p>
<p>User packages don’t necessarily meet the requirements of the standard
packages. If you have problems using a feature provided in a user
package, you will likely need to contact the contributor directly to
get help. Information on how to submit additions you make to LAMMPS
as a user-contributed package is given in <a class="reference internal" href="Section_modify.html#mod-15"><span>this section</span></a> of the documentation.</p>
<p>Some packages (both standard and user) require additional libraries.
<p>Here is a brief summary of what Makefile.machine changes are needed.
Note that the Make.py tool, described in the next <a class="reference internal" href="#start-4"><span>Section 2.4</span></a> can automatically add the needed info to an existing
machine Makefile, using simple command-line arguments.</p>
<p>In src/MAKE/OPTIONS see the following Makefiles for examples of the
changes described below:</p>
<ul class="simple">
<li>Makefile.intel_cpu</li>
<li>Makefile.intel_phi</li>
<li>Makefile.kokkos_omp</li>
<li>Makefile.kokkos_cuda</li>
<li>Makefile.kokkos_phi</li>
<li>Makefile.omp</li>
</ul>
<p>For the USER-INTEL package, you have 2 choices when building. You can
build with CPU or Phi support. The latter uses Xeon Phi chips in
“offload” mode. Each of these modes requires additional settings in
your Makefile.machine for CCFLAGS and LINKFLAGS.</p>
<span id="start-4"></span><h2>2.4. Building LAMMPS via the Make.py script<a class="headerlink" href="#building-lammps-via-the-make-py-script" title="Permalink to this headline">¶</a></h2>
<p>The src directory includes a Make.py script, written in Python, which
can be used to automate various steps of the build process. It is
particularly useful for working with the accelerator packages, as well
as other packages which require auxiliary libraries to be built.</p>
<p>The goal of the Make.py tool is to allow any complex multi-step LAMMPS
build to be performed as a single Make.py command. And you can
archive the commands, so they can be re-invoked later via the -r
(redo) switch. If you find some LAMMPS build procedure that can’t be
done in a single Make.py command, let the developers know, and we’ll
see if we can augment the tool.</p>
<p>You can run Make.py from the src directory by typing either:</p>
<span id="start-5"></span><h2>2.5. Building LAMMPS as a library<a class="headerlink" href="#building-lammps-as-a-library" title="Permalink to this headline">¶</a></h2>
<p>LAMMPS can be built as either a static or shared library, which can
then be called from another application or a scripting language. See
<a class="reference internal" href="Section_howto.html#howto-10"><span>this section</span></a> for more info on coupling
LAMMPS to other codes. See <a class="reference internal" href="Section_python.html"><em>this section</em></a> for
more info on wrapping and running LAMMPS from Python.</p>
<div class="section" id="static-library">
<h3>2.5.1. <strong>Static library:</strong><a class="headerlink" href="#static-library" title="Permalink to this headline">¶</a></h3>
<p>To build LAMMPS as a static library (<a href="#id7"><span class="problematic" id="id8">*</span></a>.a file on Linux), type</p>
relocation R_X86_64_32 against `__pthread_key_create' can not be used
when making a shared object; recompile with -fPIC
../../lib/colvars/libcolvars.a: error adding symbols: Bad value
</pre></div>
</div>
<p>As an example, here is how to build and install the <a class="reference external" href="http://www-unix.mcs.anl.gov/mpi">MPICH library</a>, a popular open-source version of MPI, distributed by
Argonne National Labs, as a shared library in the default
<h3>2.5.3. <strong>Additional requirement for using a shared library:</strong><a class="headerlink" href="#additional-requirement-for-using-a-shared-library" title="Permalink to this headline">¶</a></h3>
<p>The operating system finds shared libraries to load at run-time using
the environment variable LD_LIBRARY_PATH. So you may wish to copy the
file src/liblammps.so or src/liblammps_g++.so (for example) to a place
the system can find it by default, such as /usr/local/lib, or you may
wish to add the LAMMPS src directory to LD_LIBRARY_PATH, so that the
current version of the shared library is always available to programs
that use it.</p>
<p>For the csh or tcsh shells, you would add something like this to your
<h3>2.5.4. <strong>Calling the LAMMPS library:</strong><a class="headerlink" href="#calling-the-lammps-library" title="Permalink to this headline">¶</a></h3>
<p>Either flavor of library (static or shared0 allows one or more LAMMPS
objects to be instantiated from the calling program.</p>
<p>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.</p>
<p>When used from a C or Fortran program or a scripting language like
Python, the library has a simple function-style interface, provided in
src/library.cpp and src/library.h.</p>
<p>See the sample codes in examples/COUPLE/simple for examples of C++ and
C and Fortran codes that invoke LAMMPS thru its library interface.
There are other examples as well in the COUPLE directory which are
discussed in <a class="reference internal" href="Section_howto.html#howto-10"><span>Section_howto 10</span></a> of the
manual. See <a class="reference internal" href="Section_python.html"><em>Section_python</em></a> of the manual for a
description of the Python wrapper provided with LAMMPS that operates
through the LAMMPS library interface.</p>
<p>The files src/library.cpp and library.h define the C-style API for
using LAMMPS as a library. See <a class="reference internal" href="Section_howto.html#howto-19"><span>Section_howto 19</span></a> of the manual for a description of the
interface and how to extend it for your needs.</p>
<hr class="docutils" />
</div>
</div>
<div class="section" id="running-lammps">
<span id="start-6"></span><h2>2.6. Running LAMMPS<a class="headerlink" href="#running-lammps" title="Permalink to this headline">¶</a></h2>
<p>By default, LAMMPS runs by reading commands from standard input. Thus
if you run the LAMMPS executable by itself, e.g.</p>
<li>You’ll need to use the mpiexec.exe and smpd.exe files from the MPICH2
package. Put them in same directory (or path) as the LAMMPS Windows
executable.</li>
<li>Get a command prompt by going to Start->Run... ,
then typing “cmd”.</li>
<li>Move to the directory where you have saved lmp_win_mpi.exe
(e.g. by typing: cd “Documents”).</li>
<li>Then type something like this: “mpiexec -localonly 4 lmp_win_mpi -in
in.lj”, replacing in.lj with the name of your LAMMPS input script.</li>
<li>Note that you may need to provide smpd with a passphrase (it doesn’t
matter what you type).</li>
<li>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. :l Alternatively, you can still
use this executable to run on a single processor by typing something
like: “lmp_win_mpi -in in.lj”.</li>
</ul>
<hr class="docutils" />
<p>The screen output from LAMMPS is described in the next section. As it
runs, LAMMPS also writes a log.lammps file with the same information.</p>
<p>Note that this sequence of commands copies the LAMMPS executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from (if you launch lmp_linux on its own and not
under mpirun). If that happens, LAMMPS will look for additional input
files and write its output files to the executable directory, rather
than your working directory, which is probably not what you want.</p>
<p>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 <a class="reference internal" href="Section_errors.html"><em>Section_errors</em></a> 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.</p>
<p>LAMMPS can run a 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.</p>
<p>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 setup a smaller problem.</p>
<hr class="docutils" />
</div>
<div class="section" id="command-line-options">
<span id="start-7"></span><h2>2.7. Command-line options<a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h2>
<p>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:</p>
<ul class="simple">
<li>-c or -cuda</li>
<li>-e or -echo</li>
<li>-h or -help</li>
<li>-i or -in</li>
<li>-k or -kokkos</li>
<li>-l or -log</li>
<li>-nc or -nocite</li>
<li>-pk or -package</li>
<li>-p or -partition</li>
<li>-pl or -plog</li>
<li>-ps or -pscreen</li>
<li>-r or -restart</li>
<li>-ro or -reorder</li>
<li>-sc or -screen</li>
<li>-sf or -suffix</li>
<li>-v or -var</li>
</ul>
<p>For example, lmp_ibm might be launched as follows:</p>
<p>Use variants of various styles if they exist. The specified style can
be <em>cuda</em>, <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em>. These refer to
optional packages that LAMMPS can be built with, as described above in
<a class="reference internal" href="#start-3"><span>Section 2.3</span></a>. The “cuda” style corresponds to the USER-CUDA
package, the “gpu” style 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.</p>
<p>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.</p>
<p>As an example, all of the packages provide a <a class="reference internal" href="pair_lj.html"><em>pair_style lj/cut</em></a> variant, with style names lj/cut/cuda,
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 (cuda,gpu,intel,kk,omp,opt) is automatically appended
<a class="reference internal" href="compute.html"><em>compute</em></a>, or <a class="reference internal" href="run_style.html"><em>run</em></a> style. If the variant
version does not exist, the standard version is created.</p>
<p>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 <a class="reference internal" href="package.html"><em>package gpu</em></a> command in your script.</p>
<p>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 <a class="reference internal" href="package.html"><em>package intel</em></a> command in your script. If the
USER-OMP package is also installed, the intel suffix will 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 <a class="reference internal" href="package.html"><em>package omp</em></a>
command in your script.</p>
<p>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 <a class="reference internal" href="package.html"><em>package kokkos</em></a> command in your script.</p>
<p>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 <a class="reference internal" href="package.html"><em>package omp</em></a> command in your script.</p>
<p>The <a class="reference internal" href="suffix.html"><em>suffix</em></a> 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.</p>
<div class="highlight-python"><div class="highlight"><pre>-var name value1 value2 ...
</pre></div>
</div>
<p>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 <a class="reference internal" href="variable.html"><em>index-style variable</em></a> 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 <a class="reference internal" href="variable.html"><em>variable</em></a> command for more info on
defining index and other kinds of variables and <a class="reference internal" href="Section_commands.html#cmd-2"><span>this section</span></a> for more info on using variables
in input scripts.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 they start with a “-”, e.g. a
negative numeric value. It is OK if the first value1 starts with a
“-”, since it is automatically skipped.</p>
</div>
<hr class="docutils" />
</div>
<div class="section" id="lammps-screen-output">
<span id="start-8"></span><h2>2.8. LAMMPS screen output<a class="headerlink" href="#lammps-screen-output" title="Permalink to this headline">¶</a></h2>
<p>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 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 then
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:</p>
<div class="highlight-python"><div class="highlight"><pre>Loop time of 49.002 on 2 procs for 2004 atoms
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>Pair time (%) = 35.0495 (71.5267)
Bond time (%) = 0.092046 (0.187841)
Kspce time (%) = 6.42073 (13.103)
Neigh time (%) = 2.73485 (5.5811)
Comm time (%) = 1.50291 (3.06703)
Outpt time (%) = 0.013799 (0.0281601)
Other time (%) = 2.13669 (4.36041)
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>Nlocal: 1002 ave, 1015 max, 989 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8720 ave, 8724 max, 8716 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354141 ave, 361422 max, 346860 min
Histogram: 1 0 0 0 0 0 0 0 0 1
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>Total # of neighbors = 708282
Ave neighs/atom = 353.434
Ave special neighs/atom = 2.34032
Number of reneighborings = 42
Dangerous reneighborings = 2
</pre></div>
</div>
<p>The first section gives the breakdown of the CPU run time (in seconds)
into major categories. The second section 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.</p>
<p>The last section gives aggregate statistics for pair-wise neighbors
and special neighbors that LAMMPS keeps track of (see the
<a class="reference internal" href="special_bonds.html"><em>special_bonds</em></a> command). The number of times
neighbor lists were rebuilt during the run is given as well as the
number of potentially “dangerous” rebuilds. If atom movement
triggered neighbor list rebuilding (see the
<a class="reference internal" href="neigh_modify.html"><em>neigh_modify</em></a> 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.</p>
<p>If an energy minimization was performed via the
<a class="reference internal" href="minimize.html"><em>minimize</em></a> command, additional information is printed,
<span id="start-9"></span><h2>2.9. Tips for users of previous LAMMPS versions<a class="headerlink" href="#tips-for-users-of-previous-lammps-versions" title="Permalink to this headline">¶</a></h2>
<p>The current C++ began with a complete rewrite of LAMMPS 2001, which
was written in F90. Features of earlier versions of LAMMPS are listed
in <a class="reference internal" href="Section_history.html"><em>Section_history</em></a>. The F90 and F77 versions
(2001 and 99) are also freely distributed as open-source codes; check
the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a> for distribution information if you prefer
those versions. The 99 and 2001 versions are no longer under active
development; they do not have all the features of C++ LAMMPS.</p>
<p>If you are a previous user of LAMMPS 2001, these are the most
significant changes you will notice in C++ LAMMPS:</p>
<p>(1) The names and arguments of many input script commands have
changed. All commands are now a single word (e.g. read_data instead
of read data).</p>
<p>(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS,
but you may need to specify the relevant commands in different ways.</p>
<p>(3) The format of the data file can be streamlined for some problems.
See the <a class="reference internal" href="read_data.html"><em>read_data</em></a> command for details. The data file
section “Nonbond Coeff” has been renamed to “Pair Coeff” in C++ LAMMPS.</p>
<p>(4) Binary restart files written by LAMMPS 2001 cannot be read by C++
LAMMPS with a <a class="reference internal" href="read_restart.html"><em>read_restart</em></a> command. This is
because they were output by F90 which writes in a different binary
format than C or C++ writes or reads. Use the <em>restart2data</em> tool
provided with LAMMPS 2001 to convert the 2001 restart file to a text
data file. Then edit the data file as necessary before using the C++
LAMMPS <a class="reference internal" href="read_data.html"><em>read_data</em></a> command to read it in.</p>
<p>(5) There are numerous small numerical changes in C++ LAMMPS that mean
you will not get identical answers when comparing to a 2001 run.
However, your initial thermodynamic energy and MD trajectory should be
close if you have setup the problem for both codes the same.</p>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.