Merge branch 'integration' into weighted-balancing

  <H1></H1><div class="section" id="lammps-documentation">

<h1>LAMMPS Documentation</h1>

<div class="section" id="aug-2016-version">

<h2>27 Aug 2016 version</h2>

<div class="section" id="sep-2016-version">

<h2>13 Sep 2016 version</h2>

</div>

<div class="section" id="version-info">

<h2>Version info:</h2>

<p>The LAMMPS &#8220;version&#8221; is the date when it was released, such as 1 May

2010. LAMMPS is updated continuously.  Whenever we fix a bug or add a

feature, we release it immediately, and post a notice on <a class="reference external" href="http://lammps.sandia.gov/bug.html">this page of the WWW site</a>.  Each dated copy of LAMMPS contains all the

feature, we release it immediately, and post a notice on <a class="reference external" href="http://lammps.sandia.gov/bug.html">this page of the WWW site</a>. Every 2-4 months one of the incremental releases

is subjected to more thorough testing and labeled as a <em>stable</em> version.</p>

<p>Each dated copy of LAMMPS contains all the

features and bug-fixes up to and including that version date. The

version date is printed to the screen and logfile every time you run

LAMMPS. It is also in the file src/version.h and in the LAMMPS

National Laboratories, a US Department of Energy facility, with

funding from the DOE.  It is an open-source code, distributed freely

under the terms of the GNU Public License (GPL).</p>

<p>The primary developers of LAMMPS are <a class="reference external" href="http://www.sandia.gov/~sjplimp">Steve Plimpton</a>, Aidan

Thompson, and Paul Crozier who can be contacted at

sjplimp,athomps,pscrozi at sandia.gov.  The <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a> at

<a class="reference external" href="http://lammps.sandia.gov">http://lammps.sandia.gov</a> has more information about the code and its

uses.</p>

<p>The current core group of LAMMPS developers is at Sandia National

Labs and Temple University:</p>

<ul class="simple">

<li><a class="reference external" href="http://www.sandia.gov/~sjplimp">Steve Plimpton</a>, sjplimp at sandia.gov</li>

<li>Aidan Thompson, athomps at sandia.gov</li>

<li>Stan Moore, stamoore at sandia.gov</li>

<li><a class="reference external" href="http://goo.gl/1wk0">Axel Kohlmeyer</a>, akohlmey at gmail.com</li>

</ul>

<p>Past core developers include Paul Crozier, Ray Shan and Mark Stevens,

all at Sandia. The <strong>LAMMPS home page</strong> at

<a class="reference external" href="http://lammps.sandia.gov">http://lammps.sandia.gov</a> has more information

about the code and its uses. Interaction with external LAMMPS developers,

bug reports and feature requests are mainly coordinated through the

<a class="reference external" href="https://github.com/lammps/lammps">LAMMPS project on GitHub.</a></p>

<hr class="docutils" />

<p>The LAMMPS documentation is organized into the following sections.  If

you find errors or omissions in this manual or have suggestions for

listed above:</p>

<table border="1" class="docutils">

<colgroup>

<col width="26%" />

<col width="74%" />

<col width="64%" />

<col width="36%" />

</colgroup>

<tbody valign="top">

<tr class="row-odd"><td>build the accelerator library</td>

<tr class="row-even"><td>install the accelerator package</td>

<td>make yes-opt, make yes-user-intel, etc</td>

</tr>

</tbody>

</table>

<div class="line-block">

<div class="line">install the accelerator package             | make yes-opt, make yes-user-intel, etc                                                                                           |</div>

</div>

<blockquote>

<div>only for USER-INTEL, KOKKOS, USER-OMP, OPT packages                                                          |</div></blockquote>

<table border="1" class="docutils">

<colgroup>

<col width="26%" />

<col width="74%" />

</colgroup>

<tbody valign="top">

<tr class="row-odd"><td>re-build LAMMPS</td>

<tr class="row-odd"><td>add compile/link flags to Makefile.machine in src/MAKE</td>

<td>only for USER-INTEL, KOKKOS, USER-OMP, OPT packages</td>

</tr>

<tr class="row-even"><td>re-build LAMMPS</td>

<td>make machine</td>

</tr>

</tbody>

</table>

<div class="line-block">

<div class="line">re-build LAMMPS                             | make machine                                                                                                                     |</div>

</div>

<blockquote>

<div>mpirun -np 32 lmp_machine -in in.script                                                          |</div></blockquote>

<blockquote>

<div>only for KOKKOS package                                   |</div></blockquote>

<blockquote>

<div><a class="reference internal" href="package.html"><span class="doc">package</span></a> command, &lt;br&gt;

only if defaults need to be changed |</div></blockquote>

<blockquote>

<div><a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command                                               |</div></blockquote>

<table border="1" class="docutils">

<colgroup>

</colgroup>

<tbody valign="top">

<tr class="row-odd"><td>prepare and test a regular LAMMPS simulation</td>

<td>lmp_machine -in in.script; mpirun -np 32 lmp_machine -in in.script</td>

</tr>

<tr class="row-even"><td>enable specific accelerator support via &#8216;-k on&#8217; <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>,</td>

<td>only needed for KOKKOS package</td>

</tr>

<tr class="row-odd"><td>set any needed options for the package via &#8220;-pk&#8221; <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a> or <a class="reference internal" href="package.html"><span class="doc">package</span></a> command,</td>

<td>only if defaults need to be changed</td>

</tr>

<tr class="row-even"><td>use accelerated styles in your input via &#8220;-sf&#8221; <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a> or <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command</td>

<td>lmp_machine -in in.script -sf gpu</td>

</tr>

</tbody>

</table>

<p>Note that the first 4 steps can be done as a single command, using the

<li>The GPU package accelerates only pair force, neighbor list, and PPPM

calculations.</li>

<li>The GPU package requires neighbor lists to be built on the CPU when using

exclusion lists or a triclinic simulation box.</li>

exclusion lists, hybrid pair styles, or a triclinic simulation box.</li>

</ul>

</div>

</div>

evaluated as an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a>.  This is a way

to use numeric formulas in an input script without having to assign

them to variable names.  For example, these 3 input script lines:</p>

<div class="highlight-default"><div class="highlight"><pre><span></span>variable X equal (xlo+xhi)/2+sqrt(v_area)

<pre class="literal-block">

variable X equal (xlo+xhi)/2+sqrt(v_area)

region 1 block $X 2 INF INF EDGE EDGE

variable X delete

</pre></div>

</div>

</pre>

<p>can be replaced by</p>

<div class="highlight-default"><div class="highlight"><pre><span></span>region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

</pre></div>

</div>

<pre class="literal-block">

region 1 block $((xlo+xhi)/2+sqrt(v_area)) 2 INF INF EDGE EDGE

</pre>

<p>so that you do not have to define (or discard) a temporary variable X.</p>

<p>Note that neither the curly-bracket or immediate form of variables can

contain nested $ characters for other variables to substitute for.

<dt><em>Bad TIP4P bond type for PPPMDisp/TIP4P</em></dt>

<dd>Specified bond type is not valid.</dd>

<dt><em>Bad fix ID in fix append/atoms command</em></dt>

<dd>The value of the fix_id for keyword spatial must start with the suffix

<a href="#id6"><span class="problematic" id="id7">f_</span></a>.</dd>

<dd>The value of the fix_id for keyword spatial must start with &#8216;f_&#8217;.</dd>

<dt><em>Bad grid of processors</em></dt>

<dd>The 3d grid of processors defined by the processors command does not

match the number of processors LAMMPS is being run on.</dd>

have fully consistent image flags, since some bonds will cross

periodic boundaries and connect two atoms with the same image

flag.</dd>

<dt><em>KIM Model does not provide `energy&#8217;; Potential energy will be zero</em></dt>

<dt><em>KIM Model does not provide &#8216;energy&#8217;; Potential energy will be zero</em></dt>

<dd>Self-explanatory.</dd>

<dt><em>KIM Model does not provide `forces&#8217;; Forces will be zero</em></dt>

<dt><em>KIM Model does not provide &#8216;forces&#8217;; Forces will be zero</em></dt>

<dd>Self-explanatory.</dd>

<dt><em>KIM Model does not provide `particleEnergy&#8217;; energy per atom will be zero</em></dt>

<dt><em>KIM Model does not provide &#8216;particleEnergy&#8217;; energy per atom will be zero</em></dt>

<dd>Self-explanatory.</dd>

<dt><em>KIM Model does not provide `particleVirial&#8217;; virial per atom will be zero</em></dt>

<dt><em>KIM Model does not provide &#8216;particleVirial&#8217;; virial per atom will be zero</em></dt>

<dd>Self-explanatory.</dd>

<dt><em>Kspace_modify slab param &lt; 2.0 may cause unphysical behavior</em></dt>

<dd>The kspace_modify slab parameter should be larger to insure periodic

</tbody>

</table>

<p>Here is how you can run and visualize one of the sample problems:</p>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">indent</span>

<span class="n">cp</span> <span class="o">../../</span><span class="n">src</span><span class="o">/</span><span class="n">lmp_linux</span> <span class="o">.</span>           <span class="c1"># copy LAMMPS executable to this dir</span>

<span class="n">lmp_linux</span> <span class="o">-</span><span class="ow">in</span> <span class="ow">in</span><span class="o">.</span><span class="n">indent</span>            <span class="c1"># run the problem</span>

</pre></div>

</div>

<pre class="literal-block">

cd indent

cp ../../src/lmp_linux .           # copy LAMMPS executable to this dir

lmp_linux -in in.indent            # run the problem

</pre>

<p>Running the simulation produces the files <em>dump.indent</em> and

<em>log.lammps</em>.  You can visualize the dump file of snapshots with a

variety of 3rd-party tools highlighted on the

<a class="reference internal" href="dump_image.html"><span class="doc">dump image</span></a> doc page for more details.  E.g. this

Imagemagick command would create a GIF file suitable for viewing in a

browser.</p>

<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">%</span> <span class="n">convert</span> <span class="o">-</span><span class="n">loop</span> <span class="mi">1</span> <span class="o">*.</span><span class="n">jpg</span> <span class="n">foo</span><span class="o">.</span><span class="n">gif</span>

</pre></div>

</div>

<pre class="literal-block">

% convert -loop 1 *.jpg foo.gif

</pre>

</div>

<hr class="docutils" />

<div class="section" id="uppercase-directories">

<h2>7.2. Uppercase directories</h2>

<table border="1" class="docutils">

<colgroup>

<col width="10%" />

<col width="90%" />

<col width="11%" />

<col width="89%" />

</colgroup>

<tbody valign="top">

<tr class="row-odd"><td>ASPHERE</td>