<p>The LAMMPS “version” 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>. 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
directory name created when you unpack a tarball, and at the top of
the first page of the manual (this page).</p>
<ul class="simple">
<li>If you browse the HTML doc pages on the LAMMPS WWW site, they always
describe the most current version of LAMMPS.</li>
<li>If you browse the HTML doc pages included in your tarball, they
describe the version you have.</li>
<li>The <a class="reference external" href="Manual.pdf">PDF file</a> on the WWW site or in the tarball is updated
about once per month. This is because it is large, and we don’t want
it to be part of every patch.</li>
<li>There is also a <a class="reference external" href="Developer.pdf">Developer.pdf</a> file in the doc
directory, which describes the internal structure and algorithms of
LAMMPS.</li>
</ul>
<p>LAMMPS stands for Large-scale Atomic/Molecular Massively Parallel
Simulator.</p>
<p>LAMMPS is a classical molecular dynamics simulation code designed to
run efficiently on parallel computers. It was developed at Sandia
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 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>
The lammps.org domain, currently hosting <a class="reference external" href="https://ci.lammps.org/job/lammps/">public continuous integration testing</a> and <a class="reference external" href="http://rpm.lammps.org">precompiled Linux RPM and Windows installer packages</a> is located
at Temple University and managed by Richard Berger,
richard.berger at temple.edu.</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
useful information to add, please send an email to the developers so
we can improve the LAMMPS documentation.</p>
<p>Once you are familiar with LAMMPS, you may want to bookmark <a class="reference internal" href="Section_commands.html#comm"><span class="std std-ref">this page</span></a> at Section_commands.html#comm since
it gives quick access to documentation for all LAMMPS commands.</p>
<p><a class="reference external" href="Manual.pdf">PDF file</a> of the entire manual, generated by
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#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="Section_start.html#making-lammps">2.2. Making LAMMPS</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#making-lammps-with-optional-packages">2.3. Making LAMMPS with optional packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#building-lammps-via-the-make-py-tool">2.4. Building LAMMPS via the Make.py tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_start.html#building-lammps-as-a-library">2.5. Building LAMMPS as a library</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#general-strategies">5.2. General strategies</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#packages-with-optimized-styles">5.3. Packages with optimized styles</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#tip3p-water-model">6.7. TIP3P water model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#tip4p-water-model">6.8. TIP4P water model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#spc-water-model">6.9. SPC water model</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#coupling-lammps-to-other-codes">6.10. Coupling LAMMPS to other codes</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#calculating-a-diffusion-coefficient">6.22. Calculating a diffusion coefficient</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#using-chunks-to-calculate-system-properties">6.23. Using chunks to calculate system properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_howto.html#setting-parameters-for-the-kspace-style-pppm-disp-command">6.24. Setting parameters for the <code class="docutils literal"><span class="pre">kspace_style</span> <span class="pre">pppm/disp</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_modify.html#submitting-new-features-for-inclusion-in-lammps">10.15. Submitting new features for inclusion in LAMMPS</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#overview-of-running-lammps-from-python">11.1. Overview of running LAMMPS from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#overview-of-using-python-from-a-lammps-script">11.2. Overview of using Python from a LAMMPS script</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#building-lammps-as-a-shared-library">11.3. Building LAMMPS as a shared library</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#installing-the-python-wrapper-into-python">11.4. Installing the Python wrapper into Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#extending-python-with-mpi-to-run-in-parallel">11.5. Extending Python with MPI to run in parallel</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#testing-the-python-lammps-interface">11.6. Testing the Python-LAMMPS interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#using-lammps-from-python">11.7. Using LAMMPS from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="Section_python.html#example-python-scripts-that-use-lammps">11.8. Example Python scripts that use LAMMPS</a></li>
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>.
<a class="reference internal" href="if.html"><span class="doc">if</span></a>, and <a class="reference internal" href="python.html"><span class="doc">python</span></a> commands for examples.</p>
<p>A “#” or “$” character that is between quotes will not be treated as a
comment indicator in (2) or substituted for as a variable in (3).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the argument is itself a command that requires a quoted
argument (e.g. using a <a class="reference internal" href="print.html"><span class="doc">print</span></a> command as part of an
<a class="reference internal" href="if.html"><span class="doc">if</span></a> or <a class="reference internal" href="run.html"><span class="doc">run every</span></a> command), then single, double, or
triple quotes can be nested in the usual manner. See the doc pages
for those commands for examples. Only one of level of nesting is
allowed, but that should be sufficient for most use cases.</p>
<p>Output options are set by the <a class="reference internal" href="thermo.html"><span class="doc">thermo</span></a>, <a class="reference internal" href="dump.html"><span class="doc">dump</span></a>,
and <a class="reference internal" href="restart.html"><span class="doc">restart</span></a> commands.</p>
<ol class="arabic simple" start="4">
<li>Run a simulation</li>
</ol>
<p>A molecular dynamics simulation is run using the <a class="reference internal" href="run.html"><span class="doc">run</span></a>
command. Energy minimization (molecular statics) is performed using
the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command. A parallel tempering
(replica-exchange) simulation can be run using the
<p>This section lists all LAMMPS commands alphabetically, with a separate
listing below of styles within certain commands. The <a class="reference internal" href="#cmd-4"><span class="std std-ref">previous section</span></a> lists the same commands, grouped by category. Note
that some style options for some commands are part of specific LAMMPS
packages, which means they cannot be used unless the package was
included when LAMMPS was built. Not all packages are included in a
default LAMMPS build. These dependencies are listed as Restrictions
<p>See the <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command for one-line descriptions of
each style or click on the style itself for a full description. Some
of the styles have accelerated versions, which can be used if LAMMPS
is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k =
<p>These are additional compute styles in USER packages, which can be
used if <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">LAMMPS is built with the appropriate package</span></a>.</p>
<p>See the <a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> command for an overview of pair
potentials. Click on the style itself for a full description. Many
of the styles have accelerated versions, which can be used if LAMMPS
is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k =
<p>These are additional pair styles in USER packages, which can be used
if <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">LAMMPS is built with the appropriate package</span></a>.</p>
<p>See the <a class="reference internal" href="bond_style.html"><span class="doc">bond_style</span></a> command for an overview of bond
potentials. Click on the style itself for a full description. Some
of the styles have accelerated versions, which can be used if LAMMPS
is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k =
<p>These are additional bond styles in USER packages, which can be used
if <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">LAMMPS is built with the appropriate package</span></a>.</p>
<p>See the <a class="reference internal" href="angle_style.html"><span class="doc">angle_style</span></a> command for an overview of
angle potentials. Click on the style itself for a full description.
Some of the styles have accelerated versions, which can be used if
LAMMPS is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
<p>These are additional angle styles in USER packages, which can be used
if <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">LAMMPS is built with the appropriate package</span></a>.</p>
<p>See the <a class="reference internal" href="dihedral_style.html"><span class="doc">dihedral_style</span></a> command for an overview
of dihedral potentials. Click on the style itself for a full
description. Some of the styles have accelerated versions, which can
be used if LAMMPS is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
<p>These are additional dihedral styles in USER packages, which can be
used if <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">LAMMPS is built with the appropriate package</span></a>.</p>
<p>See the <a class="reference internal" href="improper_style.html"><span class="doc">improper_style</span></a> command for an overview
of improper potentials. Click on the style itself for a full
description. Some of the styles have accelerated versions, which can
be used if LAMMPS is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
<p>These are additional improper styles in USER packages, which can be
used if <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">LAMMPS is built with the appropriate package</span></a>.</p>
<p>See the <a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style</span></a> command for an overview of
Kspace solvers. Click on the style itself for a full description.
Some of the styles have accelerated versions, which can be used if
LAMMPS is built with the <a class="reference internal" href="Section_accelerate.html"><span class="doc">appropriate accelerated package</span></a>. This is indicated by additional
letters in parenthesis: g = GPU, i = USER-INTEL, k = KOKKOS, o =
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>.
<span id="err-1"></span><h2>12.1. Common problems</h2>
<p>If two LAMMPS runs do not produce the same answer on different
machines or different numbers of processors, this is typically not a
bug. 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 within a few 100s or few 1000s of timesteps.
However, the statistical properties of the two runs (e.g. average
energy or temperature) should still be the same.</p>
<p>If the <a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> command is used to set initial atom
velocities, a particular atom can be assigned a different velocity
when the problem is run on a different number of processors or on
different machines. If this happens, the phase space trajectories of
the two simulations will rapidly diverge. See the discussion of the
<em>loop</em> option in the <a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> command for details and
options that avoid this issue.</p>
<p>Similarly, the <a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> command generates a
lattice of atoms. For the same physical system, the ordering and
numbering of atoms by atom ID may be different depending on the number
of processors.</p>
<p>Some commands use random number generators which may be setup to
produce different random number streams on each processor and hence
will produce different effects when run on different numbers of
processors. A commonly-used example is the <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> command for thermostatting.</p>
<p>A LAMMPS simulation typically has two stages, setup and run. Most
LAMMPS errors are detected at setup time; others like a bond
stretching too far may not occur until the middle of a run.</p>
<p>LAMMPS tries to flag errors and print informative error messages so
you can fix the problem. Of course, LAMMPS cannot figure out your
physics or numerical mistakes, like choosing too big a timestep,
specifying erroneous force field coefficients, or putting 2 atoms on
top of each other! If you run into errors that LAMMPS doesn’t catch
that you think it should flag, please send an email to the
<p>If you get an error message about an invalid command in your input
script, you can determine what command is causing the problem by
looking in the log.lammps file or using the <a class="reference internal" href="echo.html"><span class="doc">echo command</span></a>
to see it on the screen. If you get an error like “Invalid ...
style”, with ... being fix, compute, pair, etc, it means that you
mistyped the style name or that the command is part of an optional
package which was not compiled into your executable. The list of
available styles in your executable can be listed by using <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">the -h command-line argument</span></a>. The installation
and compilation of optional packages is explained in the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">installation instructions</span></a>.</p>
<p>For a given command, LAMMPS expects certain arguments in a specified
order. If you mess this up, LAMMPS will often flag the error, but it
may also simply read a bogus argument and assign a value that is
valid, but not what you wanted. E.g. trying to read the string “abc”
as an integer value of 0. Careful reading of the associated doc page
for the command should allow you to fix these problems. Note that
some commands allow for variables to be specified in place of numeric
constants so that the value can be evaluated and change over the
course of a run. This is typically done with the syntax <em>v_name</em> for
a parameter, where name is the name of the variable. This is only
allowed if the command documentation says it is.</p>
<p>Generally, LAMMPS will print a message to the screen and logfile and
exit gracefully when it encounters a fatal error. Sometimes it will
print a WARNING to the screen and logfile and continue on; you can
decide if the WARNING is important or not. A WARNING message that is
generated in the middle of a run is only printed to the screen, not to
the logfile, to avoid cluttering up thermodynamic output. If LAMMPS
crashes or hangs without spitting out an error message first then it
could be a bug (see <a class="reference internal" href="#err-2"><span class="std std-ref">this section</span></a>) or one of the following
cases:</p>
<p>LAMMPS runs in the available memory a processor allows to be
allocated. Most reasonable MD runs are compute limited, not memory
limited, so this shouldn’t be a bottleneck on most platforms. Almost
all large memory allocations in the code are done via C-style malloc’s
which will generate an error message if you run out of memory.
Smaller chunks of memory are allocated via C++ “new” statements. If
you are unlucky you could run out of memory just when one of these
small requests is made, in which case the code will crash or hang (in
parallel), since LAMMPS doesn’t trap on those errors.</p>
<p>Illegal arithmetic can cause LAMMPS to run slow or crash. This is
typically due to invalid physics and numerics that your simulation is
computing. If you see wild thermodynamic values or NaN values in your
LAMMPS output, something is wrong with your simulation. If you
suspect this is happening, it is a good idea to print out
thermodynamic info frequently (e.g. every timestep) via the
<a class="reference internal" href="thermo.html"><span class="doc">thermo</span></a> so you can monitor what is happening.
Visualizing the atom movement is also a good idea to insure your model
is behaving as you expect.</p>
<p>In parallel, one way LAMMPS can hang is due to how different MPI
implementations handle buffering of messages. If the code hangs
without an error message, it may be that you need to specify an MPI
setting or two (usually via an environment variable) to enable
buffering or boost the sizes of messages that can be buffered.</p>
<p>If you are confident that you have found a bug in LAMMPS, follow these
steps.</p>
<p>Check the <a class="reference external" href="http://lammps.sandia.gov/bug.html">New features and bug fixes</a> section of the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW site</a> to see if the bug has already been reported or fixed or the
<a class="reference external" href="http://lammps.sandia.gov/unbug.html">Unfixed bug</a> to see if a fix is
pending.</p>
<p>Check the <a class="reference external" href="http://lammps.sandia.gov/mail.html">mailing list</a>
to see if it has been discussed before.</p>
<p>If not, send an email to the mailing list describing the problem with
any ideas you have as to what is causing it or where in the code the
problem might be. The developers will ask for more info if needed,
such as an input script or data files.</p>
<p>The most useful thing you can do to help us fix the bug is to isolate
the problem. Run it on the smallest number of atoms and fewest number
of processors and with the simplest input script that reproduces the
bug and try to identify what command or combination of commands is
causing the problem.</p>
<p>As a last resort, you can send an email directly to the
<p>means that line #78 in the file src/velocity.cpp generated the error.
Looking in the source code may help you figure out what went wrong.</p>
<p>Note that error messages from <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">user-contributed packages</span></a> are not listed here. If such an
error occurs and is not self-explanatory, you’ll need to look in the
source code or contact the author of the package.</p>
</div>
<div class="section" id="error">
<span id="id2"></span><h2>12.4. Errors:</h2>
<dl class="docutils">
<dt><em>1-3 bond count is inconsistent</em></dt>
<dd>An inconsistency was detected when computing the number of 1-3
neighbors for each atom. This likely means something is wrong with
the bond topologies you have defined.</dd>
<dt><em>1-4 bond count is inconsistent</em></dt>
<dd>An inconsistency was detected when computing the number of 1-4
neighbors for each atom. This likely means something is wrong with
the bond topologies you have defined.</dd>
<dt><em>Accelerator sharing is not currently supported on system</em></dt>
<dd>Multiple MPI processes cannot share the accelerator on your
system. For NVIDIA GPUs, see the nvidia-smi command to change this
setting.</dd>
<dt><em>All angle coeffs are not set</em></dt>
<dd>All angle coefficients must be set in the data file or by the
angle_coeff command before running a simulation.</dd>
<dt><em>All atom IDs = 0 but atom_modify id = yes</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>All atoms of a swapped type must have same charge.</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>All atoms of a swapped type must have the same charge.</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>All bond coeffs are not set</em></dt>
<dd>All bond coefficients must be set in the data file or by the
bond_coeff command before running a simulation.</dd>
<dt><em>All dihedral coeffs are not set</em></dt>
<dd>All dihedral coefficients must be set in the data file or by the
dihedral_coeff command before running a simulation.</dd>
<dt><em>All improper coeffs are not set</em></dt>
<dd>All improper coefficients must be set in the data file or by the
improper_coeff command before running a simulation.</dd>
<dt><em>All masses are not set</em></dt>
<dd>For atom styles that define masses for each atom type, all masses must
be set in the data file or by the mass command before running a
simulation. They must also be set before using the velocity
command.</dd>
<dt><em>All mol IDs should be set for fix gcmc group atoms</em></dt>
<dd>The molecule flag is on, yet not all molecule ids in the fix group
have been set to non-zero positive values by the user. This is an
error since all atoms in the fix gcmc group are eligible for deletion,
rotation, and translation and therefore must have valid molecule ids.</dd>
<dt><em>All pair coeffs are not set</em></dt>
<dd>All pair coefficients must be set in the data file or by the
pair_coeff command before running a simulation.</dd>
<dt><em>All read_dump x,y,z fields must be specified for scaled, triclinic coords</em></dt>
<dd>For triclinic boxes and scaled coordinates you must specify all 3 of
the x,y,z fields, else LAMMPS cannot reconstruct the unscaled
coordinates.</dd>
<dt><em>All universe/uloop variables must have same # of values</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>All variables in next command must be same style</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Angle atom missing in delete_bonds</em></dt>
<dd>The delete_bonds command cannot find one or more atoms in a particular
angle on a particular processor. The pairwise cutoff is too short or
the atoms are too far apart to make a valid angle.</dd>
<dt><em>Angle atom missing in set command</em></dt>
<dd>The set command cannot find one or more atoms in a particular angle on
a particular processor. The pairwise cutoff is too short or the atoms
are too far apart to make a valid angle.</dd>
<dt><em>Angle atoms %d %d %d missing on proc %d at step %ld</em></dt>
<dd>One or more of 3 atoms needed to compute a particular angle are
missing on this processor. Typically this is because the pairwise
cutoff is set too short or the angle has blown apart and an atom is
too far away.</dd>
<dt><em>Angle atoms missing on proc %d at step %ld</em></dt>
<dd>One or more of 3 atoms needed to compute a particular angle are
missing on this processor. Typically this is because the pairwise
cutoff is set too short or the angle has blown apart and an atom is
too far away.</dd>
<dt><em>Angle coeff for hybrid has invalid style</em></dt>
<dd>Angle style hybrid uses another angle style as one of its
coefficients. The angle style used in the angle_coeff command or read
from a restart file is not recognized.</dd>
<dt><em>Angle coeffs are not set</em></dt>
<dd>No angle coefficients have been assigned in the data file or via the
angle_coeff command.</dd>
<dt><em>Angle extent > half of periodic box length</em></dt>
<dd>This error was detected by the neigh_modify check yes setting. It is
an error because the angle atoms are so far apart it is ambiguous how
it should be defined.</dd>
<dt><em>Angle potential must be defined for SHAKE</em></dt>
<dd>When shaking angles, an angle_style potential must be used.</dd>
<dt><em>Angle style hybrid cannot have hybrid as an argument</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Angle style hybrid cannot have none as an argument</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Angle style hybrid cannot use same angle style twice</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Angle table must range from 0 to 180 degrees</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Angle table parameters did not set N</em></dt>
<dd>List of angle table parameters must include N setting.</dd>
<dt><em>Angle_coeff command before angle_style is defined</em></dt>
<dd>Coefficients cannot be set in the data file or via the angle_coeff
command until an angle_style has been assigned.</dd>
<dt><em>Angle_coeff command before simulation box is defined</em></dt>
<dd>The angle_coeff command cannot be used before a read_data,
read_restart, or create_box command.</dd>
<dt><em>Angle_coeff command when no angles allowed</em></dt>
<dd>The chosen atom style does not allow for angles to be defined.</dd>
<dt><em>Angle_style command when no angles allowed</em></dt>
<dd>The chosen atom style does not allow for angles to be defined.</dd>
<dt><em>Angles assigned incorrectly</em></dt>
<dd>Angles read in from the data file were not assigned correctly to
atoms. This means there is something invalid about the topology
definitions.</dd>
<dt><em>Angles defined but no angle types</em></dt>
<dd>The data file header lists angles but no angle types.</dd>
<dt><em>Append boundary must be shrink/minimum</em></dt>
<dd>The boundary style of the face where atoms are added
must be of type m (shrink/minimum).</dd>
<dt><em>Arccos of invalid value in variable formula</em></dt>
<dd>Argument of arccos() must be between -1 and 1.</dd>
<dt><em>Arcsin of invalid value in variable formula</em></dt>
<dd>Argument of arcsin() must be between -1 and 1.</dd>
<dt><em>Assigning body parameters to non-body atom</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Assigning ellipsoid parameters to non-ellipsoid atom</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Assigning line parameters to non-line atom</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Assigning quat to non-body atom</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Assigning tri parameters to non-tri atom</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>At least one atom of each swapped type must be present to define charges.</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom IDs must be consecutive for velocity create loop all</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom IDs must be used for molecular systems</em></dt>
<dd>Atom IDs are used to identify and find partner atoms in bonds.</dd>
<dt><em>Atom count changed in fix neb</em></dt>
<dd>This is not allowed in a NEB calculation.</dd>
<dt><em>Atom count is inconsistent, cannot write data file</em></dt>
<dd>The sum of atoms across processors does not equal the global number
of atoms. Probably some atoms have been lost.</dd>
<dt><em>Atom count is inconsistent, cannot write restart file</em></dt>
<dd>Sum of atoms across processors does not equal initial total count.
This is probably because you have lost some atoms.</dd>
<dt><em>Atom in too many rigid bodies - boost MAXBODY</em></dt>
<dd>Fix poems has a parameter MAXBODY (in fix_poems.cpp) which determines
the maximum number of rigid bodies a single atom can belong to (i.e. a
multibody joint). The bodies you have defined exceed this limit.</dd>
<dt><em>Atom sort did not operate correctly</em></dt>
<dd>This is an internal LAMMPS error. Please report it to the
developers.</dd>
<dt><em>Atom sorting has bin size = 0.0</em></dt>
<dd>The neighbor cutoff is being used as the bin size, but it is zero.
Thus you must explicitly list a bin size in the atom_modify sort
command or turn off sorting.</dd>
<dt><em>Atom style hybrid cannot have hybrid as an argument</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom style hybrid cannot use same atom style twice</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom style template molecule must have atom types</em></dt>
<dd>The defined molecule(s) does not specify atom types.</dd>
<dt><em>Atom style was redefined after using fix property/atom</em></dt>
<dd>This is not allowed.</dd>
<dt><em>Atom type must be zero in fix gcmc mol command</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom vector in equal-style variable formula</em></dt>
<dd>Atom vectors generate one value per atom which is not allowed
in an equal-style variable.</dd>
<dt><em>Atom-style variable in equal-style variable formula</em></dt>
<dd>Atom-style variables generate one value per atom which is not allowed
in an equal-style variable.</dd>
<dt><em>Atom_modify id command after simulation box is defined</em></dt>
<dd>The atom_modify id command cannot be used after a read_data,
read_restart, or create_box command.</dd>
<dt><em>Atom_modify map command after simulation box is defined</em></dt>
<dd>The atom_modify map command cannot be used after a read_data,
read_restart, or create_box command.</dd>
<dt><em>Atom_modify sort and first options cannot be used together</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom_style command after simulation box is defined</em></dt>
<dd>The atom_style command cannot be used after a read_data,
read_restart, or create_box command.</dd>
<dt><em>Atom_style line can only be used in 2d simulations</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atom_style tri can only be used in 3d simulations</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atomfile variable could not read values</em></dt>
<dd>Check the file assigned to the variable.</dd>
<dt><em>Atomfile variable in equal-style variable formula</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Atomfile-style variable in equal-style variable formula</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Attempt to pop empty stack in fix box/relax</em></dt>
<dd>Internal LAMMPS error. Please report it to the developers.</dd>
<dt><em>Attempt to push beyond stack limit in fix box/relax</em></dt>
<dd>Internal LAMMPS error. Please report it to the developers.</dd>
<dt><em>Attempting to rescale a 0.0 temperature</em></dt>
<dd>Cannot rescale a temperature that is already 0.0.</dd>
<dt><em>Bad FENE bond</em></dt>
<dd>Two atoms in a FENE bond have become so far apart that the bond cannot
be computed.</dd>
<dt><em>Bad TIP4P angle type for PPPM/TIP4P</em></dt>
<dd>Specified angle type is not valid.</dd>
<dt><em>Bad TIP4P angle type for PPPMDisp/TIP4P</em></dt>
<dd>Specified angle type is not valid.</dd>
<dt><em>Bad TIP4P bond type for PPPM/TIP4P</em></dt>
<dd>Specified bond type is not valid.</dd>
<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 ‘f_’.</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>
<dd>This is not allowed if the kspace_modify overlap setting is no.</dd>
<dt><em>PPPM order < minimum allowed order</em></dt>
<dd>The default minimum order is 2. This can be reset by the
kspace_modify minorder command.</dd>
<dt><em>PPPM order cannot be < 2 or > than %d</em></dt>
<dd>This is a limitation of the PPPM implementation in LAMMPS.</dd>
<dt><em>PPPMDisp Coulomb grid is too large</em></dt>
<dd>The global PPPM grid is larger than OFFSET in one or more dimensions.
OFFSET is currently set to 4096. You likely need to decrease the
requested accuracy.</dd>
<dt><em>PPPMDisp Dispersion grid is too large</em></dt>
<dd>The global PPPM grid is larger than OFFSET in one or more dimensions.
OFFSET is currently set to 4096. You likely need to decrease the
requested accuracy.</dd>
<dt><em>PPPMDisp can only currently be used with comm_style brick</em></dt>
<dd>This is a current restriction in LAMMPS.</dd>
<dt><em>PPPMDisp coulomb order cannot be greater than %d</em></dt>
<dd>This is a limitation of the PPPM implementation in LAMMPS.</dd>
<dt><em>PPPMDisp used but no parameters set, for further information please see the pppm/disp documentation</em></dt>
<dd>An efficient and accurate usage of the pppm/disp requires settings via the kspace_modify command. Please see the pppm/disp documentation for further instructions.</dd>
<dt><em>PRD command before simulation box is defined</em></dt>
<dd>The prd command cannot be used before a read_data,
read_restart, or create_box command.</dd>
<dt><em>PRD nsteps must be multiple of t_event</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>PRD t_corr must be multiple of t_event</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Package command after simulation box is defined</em></dt>
<dd>The package command cannot be used afer a read_data, read_restart, or
create_box command.</dd>
<dt><em>Package cuda command without USER-CUDA package enabled</em></dt>
<dd>The USER-CUDA package must be installed via “make yes-user-cuda”
before LAMMPS is built, and the “-c on” must be used to enable the
package.</dd>
<dt><em>Package gpu command without GPU package installed</em></dt>
<dd>The GPU package must be installed via “make yes-gpu” before LAMMPS is
built.</dd>
<dt><em>Package intel command without USER-INTEL package installed</em></dt>
<dd>The USER-INTEL package must be installed via “make yes-user-intel”
before LAMMPS is built.</dd>
<dt><em>Package kokkos command without KOKKOS package enabled</em></dt>
<dd>The KOKKOS package must be installed via “make yes-kokkos” before
LAMMPS is built, and the “-k on” must be used to enable the package.</dd>
<dt><em>Package omp command without USER-OMP package installed</em></dt>
<dd>The USER-OMP package must be installed via “make yes-user-omp” before
LAMMPS is built.</dd>
<dt><em>Pair body requires atom style body</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Pair body requires body style nparticle</em></dt>
<dd>This pair style is specific to the nparticle body style.</dd>
<dt><em>Pair brownian requires atom style sphere</em></dt>
<dd>You specified an inner cutoff for a Coulombic table that is longer
than the global cutoff. Probably not what you wanted.</dd>
<dt><em>Temperature for MSST is not for group all</em></dt>
<dd>User-assigned temperature to MSST fix does not compute temperature for
all atoms. Since MSST computes a global pressure, the kinetic energy
contribution from the temperature is assumed to also be for all atoms.
Thus the pressure used by MSST could be inaccurate.</dd>
<dt><em>Temperature for NPT is not for group all</em></dt>
<dd>User-assigned temperature to NPT fix does not compute temperature for
all atoms. Since NPT computes a global pressure, the kinetic energy
contribution from the temperature is assumed to also be for all atoms.
Thus the pressure used by NPT could be inaccurate.</dd>
<dt><em>Temperature for fix modify is not for group all</em></dt>
<dd>The temperature compute is being used with a pressure calculation
which does operate on group all, so this may be inconsistent.</dd>
<dt><em>Temperature for thermo pressure is not for group all</em></dt>
<dd>User-assigned temperature to thermo via the thermo_modify command does
not compute temperature for all atoms. Since thermo computes a global
pressure, the kinetic energy contribution from the temperature is
assumed to also be for all atoms. Thus the pressure printed by thermo
could be inaccurate.</dd>
<dt><em>The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands – fix ave/spatial will be removed in the summer of 2015</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>The minimizer does not re-orient dipoles when using fix efield</em></dt>
<dd>This means that only the atom coordinates will be minimized,
not the orientation of the dipoles.</dd>
<dt><em>Too many common neighbors in CNA %d times</em></dt>
<dd>More than the maximum # of neighbors was found multiple times. This
was unexpected.</dd>
<dt><em>Too many inner timesteps in fix ttm</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Too many neighbors in CNA for %d atoms</em></dt>
<dd>More than the maximum # of neighbors was found multiple times. This
was unexpected.</dd>
<dt><em>Triclinic box skew is large</em></dt>
<dd>The displacement in a skewed direction is normally required to be less
than half the box length in that dimension. E.g. the xy tilt must be
between -half and +half of the x box length. You have relaxed the
constraint using the box tilt command, but the warning means that a
LAMMPS simulation may be inefficient as a result.</dd>
<dt><em>Use special bonds = 0,1,1 with bond style fene</em></dt>
<dd>Most FENE models need this setting for the special_bonds command.</dd>
<dt><em>Use special bonds = 0,1,1 with bond style fene/expand</em></dt>
<dd>Most FENE models need this setting for the special_bonds command.</dd>
<dt><em>Using a manybody potential with bonds/angles/dihedrals and special_bond exclusions</em></dt>
<dd>This is likely not what you want to do. The exclusion settings will
eliminate neighbors in the neighbor list, which the manybody potential
needs to calculated its terms correctly.</dd>
<dt><em>Using compute temp/deform with inconsistent fix deform remap option</em></dt>
<dd>Fix nvt/sllod assumes deforming atoms have a velocity profile provided
by “remap v” or “remap none” as a fix deform option.</dd>
<dt><em>Using compute temp/deform with no fix deform defined</em></dt>
<dd>This is probably an error, since it makes little sense to use
compute temp/deform in this case.</dd>
<dt><em>Using fix srd with box deformation but no SRD thermostat</em></dt>
<dd>The deformation will heat the SRD particles so this can
be dangerous.</dd>
<dt><em>Using kspace solver on system with no charge</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Using largest cut-off for lj/long/dipole/long long long</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Using largest cutoff for buck/long/coul/long</em></dt>
<dd>Self-exlanatory.</dd>
<dt><em>Using largest cutoff for lj/long/coul/long</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Using largest cutoff for pair_style lj/long/tip4p/long</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Using package gpu without any pair style defined</em></dt>
<dd>Self-explanatory.</dd>
<dt><em>Using pair potential shift with pair_modify compute no</em></dt>
<dd>The shift effects will thus not be computed.</dd>
<dt><em>Using pair tail corrections with nonperiodic system</em></dt>
<dd>This is probably a bogus thing to do, since tail corrections are
computed by integrating the density of a periodic system out to
infinity.</dd>
<dt><em>Using pair tail corrections with pair_modify compute no</em></dt>
<dd>The tail corrections will thus not be computed.</dd>
<dt><em>pair style reax is now deprecated and will soon be retired. Users should switch to pair_style reax/c</em></dt>
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>.
<p>As of summer 2016 we are using the <a class="reference external" href="https://github.com/lammps/lammps/issues">LAMMPS project issue tracker on GitHub</a> for keeping
track of suggested, planned or pending new features. This includes
discussions of how to best implement them, or why they would be
useful. Especially if a planned or proposed feature is non-trivial
to add, e.g. because it requires changes to some of the core
classes of LAMMPS, people planning to contribute a new feature to
LAMMS are encouraged to submit an issue about their planned
implementation this way in order to receive feedback from the
LAMMPS core developers. They will provide suggestions about
the validity of the proposed approach and possible improvements,
pitfalls or alternatives.</p>
<p>Please see some of the closed issues for examples of how to
suggest code enhancements, submit proposed changes, or report
elated issues and how they are resoved.</p>
<p>As an alternative to using GitHub, you may e-mail the
<a class="reference external" href="http://lammps.sandia.gov/authors.html">core developers</a> or send
an e-mail to the <a class="reference external" href="http://lammps.sandia.gov/mail.html">LAMMPS Mail list</a>
if you want to have your suggestion added to the list.</p>
<hr class="docutils" />
</div>
<div class="section" id="past-versions">
<span id="hist-2"></span><h2>13.2. Past versions</h2>
<p>LAMMPS development began in the mid 1990s under a cooperative research
& development agreement (CRADA) between two DOE labs (Sandia and LLNL)
and 3 companies (Cray, Bristol Myers Squibb, and Dupont). The goal was
to develop a large-scale parallel classical MD code; the coding effort
was led by Steve Plimpton at Sandia.</p>
<p>After the CRADA ended, a final F77 version, LAMMPS 99, was
released. As development of LAMMPS continued at Sandia, its memory
management was converted to F90; a final F90 version was released as
LAMMPS 2001.</p>
<p>The current LAMMPS is a rewrite in C++ and was first publicly released
as an open source code in 2004. It includes many new features beyond
those in LAMMPS 99 or 2001. It also includes features from older
parallel MD codes written at Sandia, namely ParaDyn, Warp, and
GranFlow (see below).</p>
<p>In late 2006 we began merging new capabilities into LAMMPS that were
developed by Aidan Thompson at Sandia for his MD code GRASP, which has
a parallel framework similar to LAMMPS. Most notably, these have
included many-body potentials - Stillinger-Weber, Tersoff, ReaxFF -
and the associated charge-equilibration routines needed for ReaxFF.</p>
<p>The <a class="reference external" href="http://lammps.sandia.gov/history.html">History link</a> on the
LAMMPS WWW page gives a timeline of features added to the
C++ open-source version of LAMMPS over the last several years.</p>
<p>These older codes are available for download from the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW site</a>, except for Warp & GranFlow which were primarily used
internally. A brief listing of their features is given here.</p>
<p>LAMMPS 2001</p>
<ul class="simple">
<li>F90 + MPI</li>
<li>dynamic memory</li>
<li>spatial-decomposition parallelism</li>
<li>NVE, NVT, NPT, NPH, rRESPA integrators</li>
<li>LJ and Coulombic pairwise force fields</li>
<li>all-atom, united-atom, bead-spring polymer force fields</li>
<li>CHARMM-compatible force fields</li>
<li>class 2 force fields</li>
<li>3d/2d Ewald & PPPM</li>
<li>various force and temperature constraints</li>
<li>SHAKE</li>
<li>Hessian-free truncated-Newton minimizer</li>
<li>user-defined diagnostics</li>
</ul>
<p>LAMMPS 99</p>
<ul class="simple">
<li>F77 + MPI</li>
<li>static memory allocation</li>
<li>spatial-decomposition parallelism</li>
<li>most of the LAMMPS 2001 features with a few exceptions</li>
<li>no 2d Ewald & PPPM</li>
<li>molecular force fields are missing a few CHARMM terms</li>
<li>no SHAKE</li>
</ul>
<p>Warp</p>
<ul class="simple">
<li>F90 + MPI</li>
<li>spatial-decomposition parallelism</li>
<li>embedded atom method (EAM) metal potentials + LJ</li>
<li>lattice and grain-boundary atom creation</li>
<li>NVE, NVT integrators</li>
<li>boundary conditions for applying shear stresses</li>
<li>temperature controls for actively sheared systems</li>
<li>per-atom energy and centro-symmetry computation and output</li>
</ul>
<p>ParaDyn</p>
<ul class="simple">
<li>F77 + MPI</li>
<li>atom- and force-decomposition parallelism</li>
<li>embedded atom method (EAM) metal potentials</li>
<li>lattice atom creation</li>
<li>NVE, NVT, NPT integrators</li>
<li>all serial DYNAMO features for controls and constraints</li>
</ul>
<p>GranFlow</p>
<ul class="simple">
<li>F90 + MPI</li>
<li>spatial-decomposition parallelism</li>
<li>frictional granular potentials</li>
<li>NVE integrator</li>
<li>boundary conditions for granular flow and packing and walls</li>
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>.
<li>energy minimization via conjugate gradient or steepest descent relaxation</li>
<li>rRESPA hierarchical timestepping</li>
<li>rerun command for post-processing of dump files</li>
</ul>
</div>
<div class="section" id="diagnostics">
<h3>1.2.7. Diagnostics</h3>
<ul class="simple">
<li>see the various flavors of the <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> and <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> commands</li>
<li>Various pre- and post-processing serial tools are packaged
with LAMMPS; see these <a class="reference internal" href="Section_tools.html"><span class="doc">doc pages</span></a>.</li>
<li>Our group has also written and released a separate toolkit called
<a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a> which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
written in <a class="reference external" href="http://www.python.org">Python</a> and is available for download from <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">the Pizza.py WWW site</a>.</li>
</ul>
</div>
<div class="section" id="specialized-features">
<h3>1.2.11. Specialized features</h3>
<p>These are LAMMPS capabilities which you may not think of as typical
<li>perform sophisticated analyses of your MD simulation</li>
<li>visualize your MD simulation</li>
<li>plot your output data</li>
</ul>
<p>A few tools for pre- and post-processing tasks are provided as part of
the LAMMPS package; they are described in <a class="reference internal" href="Section_tools.html"><span class="doc">this section</span></a>. However, many people use other codes or
write their own tools for these tasks.</p>
<p>As noted above, our group has also written and released a separate
toolkit called <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a> which addresses some of the listed
bullets. It provides tools for doing setup, analysis, plotting, and
visualization for LAMMPS simulations. Pizza.py is written in
<a class="reference external" href="http://www.python.org">Python</a> and is available for download from <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">the Pizza.py WWW site</a>.</p>
<p>LAMMPS requires as input a list of initial atom coordinates and types,
molecular topology information, and force-field coefficients assigned
to all atoms and bonds. LAMMPS will not build molecular systems and
assign force-field parameters for you.</p>
<p>For atomic systems LAMMPS provides a <a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a>
command which places atoms on solid-state lattices (fcc, bcc,
user-defined, etc). Assigning small numbers of force field
coefficients can be done via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair coeff</span></a>, <a class="reference internal" href="bond_coeff.html"><span class="doc">bond coeff</span></a>, <a class="reference internal" href="angle_coeff.html"><span class="doc">angle coeff</span></a>, etc commands.
For molecular systems or more complicated simulation geometries, users
typically use another code as a builder and convert its output to
LAMMPS input format, or write their own code to generate atom
coordinate and molecular topology for LAMMPS to read in.</p>
<p>For complicated molecular systems (e.g. a protein), a multitude of
topology information and hundreds of force-field coefficients must
typically be specified. We suggest you use a program like
<a class="reference external" href="http://www.scripps.edu/brooks">CHARMM</a> or <a class="reference external" href="http://amber.scripps.edu">AMBER</a> or other molecular builders to setup
such problems and dump its information to a file. You can then
reformat the file as LAMMPS input. Some of the tools in <a class="reference internal" href="Section_tools.html"><span class="doc">this section</span></a> can assist in this process.</p>
<p>Similarly, LAMMPS creates output files in a simple format. Most users
post-process these files with their own analysis tools or re-format
them for input into other programs, including visualization packages.
If you are convinced you need to compute something on-the-fly as
LAMMPS runs, see <a class="reference internal" href="Section_modify.html"><span class="doc">Section 10</span></a> for a discussion
of how you can use the <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> and <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> and
<a class="reference internal" href="fix.html"><span class="doc">fix</span></a> commands to print out data of your choosing. Keep in
mind that complicated computations can slow down the molecular
dynamics timestepping, particularly if the computations are not
parallel, so it is often better to leave such analysis to
post-processing codes.</p>
<p>A very simple (yet fast) visualizer is provided with the LAMMPS
package - see the <a class="reference internal" href="Section_tools.html#xmovie"><span class="std std-ref">xmovie</span></a> tool in <a class="reference internal" href="Section_tools.html"><span class="doc">this section</span></a>. It creates xyz projection views of
atomic coordinates and animates them. We find it very useful for
debugging purposes. For high-quality visualization we recommend the
<span id="intro-4"></span><h2>1.4. Open source distribution</h2>
<p>LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the <a class="reference external" href="http://www.gnu.org/copyleft/gpl.html">GNU Public License</a> (GPL). This
is often referred to as open-source distribution - see
<a class="reference external" href="http://www.gnu.org">www.gnu.org</a> or <a class="reference external" href="http://www.opensource.org">www.opensource.org</a> for more
details. The legal text of the GPL is in the LICENSE file that is
included in the LAMMPS distribution.</p>
<p>Here is a summary of what the GPL means for LAMMPS users:</p>
<p>(1) Anyone is free to use, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.</p>
<p>(2) If you distribute a modified version of LAMMPS, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
LAMMPS.</p>
<p>(3) If you release any code that includes LAMMPS source code, then it
must also be open-sourced, meaning you distribute it under the terms
of the GPL.</p>
<p>(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should
remain part of the code.</p>
<p>In the spirit of an open-source code, these are various ways you can
contribute to making LAMMPS better. You can send email to the
<a class="reference external" href="http://lammps.sandia.gov/authors.html">developers</a> on any of these
items.</p>
<ul class="simple">
<li>Point prospective users to the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a>. Mention it in
talks or link to it from your WWW site.</li>
<li>If you find an error or omission in this manual or on the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a>, or have a suggestion for something to clarify or include,
<li>If you find a bug, <a class="reference internal" href="Section_errors.html#err-2"><span class="std std-ref">Section 12.2</span></a>
describes how to report it.</li>
<li>If you publish a paper using LAMMPS results, send the citation (and
any cool pictures or movies if you like) to add to the Publications,
Pictures, and Movies pages of the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a>, with links
and attributions back to you.</li>
<li>Create a new Makefile.machine that can be added to the src/MAKE
directory.</li>
<li>The tools sub-directory of the LAMMPS distribution has various
stand-alone codes for pre- and post-processing of LAMMPS data. More
details are given in <a class="reference internal" href="Section_tools.html"><span class="doc">Section 9</span></a>. If you write
a new tool that users will find useful, it can be added to the LAMMPS
distribution.</li>
<li>LAMMPS is designed to be easy to extend with new code for features
like potentials, boundary conditions, diagnostic computations, etc.
<a class="reference internal" href="Section_modify.html"><span class="doc">This section</span></a> gives details. If you add a
feature of general interest, it can be added to the LAMMPS
distribution.</li>
<li>The Benchmark page of the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a> lists LAMMPS
performance on various platforms. The files needed to run the
benchmarks are part of the LAMMPS distribution. If your machine is
sufficiently different from those listed, your timing data can be
added to the page.</li>
<li>You can send feedback for the User Comments page of the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a>. It might be added to the page. No promises.</li>
<li>Cash. Small denominations, unmarked bills preferred. Paper sack OK.
Leave on desk. VISA also accepted. Chocolate chip cookies
<span id="intro-5"></span><h2>1.5. Acknowledgments and citations</h2>
<p>LAMMPS development has been funded by the <a class="reference external" href="http://www.doe.gov">US Department of Energy</a> (DOE), through its CRADA, LDRD, ASCI, and Genomes-to-Life
programs and its <a class="reference external" href="http://www.sc.doe.gov/ascr/home.html">OASCR</a> and <a class="reference external" href="http://www.er.doe.gov/production/ober/ober_top.html">OBER</a> offices.</p>
<p>Specifically, work on the latest version was funded in part by the US
Department of Energy’s Genomics:GTL program
(<a class="reference external" href="http://www.doegenomestolife.org">www.doegenomestolife.org</a>) under the <a class="reference external" href="http://www.genomes2life.org">project</a>, “Carbon
Sequestration in Synechococcus Sp.: From Molecular Machines to
Hierarchical Modeling”.</p>
<p>The following paper describe the basic parallel algorithms used in
LAMMPS. If you use LAMMPS results in your published work, please cite
this paper and include a pointer to the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW Site</a>
<p>Other papers describing specific algorithms used in LAMMPS are listed
under the <a class="reference external" href="http://lammps.sandia.gov/cite.html">Citing LAMMPS link</a> of
the LAMMPS WWW page.</p>
<p>The <a class="reference external" href="http://lammps.sandia.gov/papers.html">Publications link</a> on the
LAMMPS WWW page lists papers that have cited LAMMPS. If your paper is
not listed there for some reason, feel free to send us the info. If
the simulations in your paper produced cool pictures or animations,
we’ll be pleased to add them to the
<a class="reference external" href="http://lammps.sandia.gov/pictures.html">Pictures</a> or
<a class="reference external" href="http://lammps.sandia.gov/movies.html">Movies</a> pages of the LAMMPS WWW
site.</p>
<p>The core group of LAMMPS developers is at Sandia National Labs:</p>
<ul class="simple">
<li>Steve Plimpton, sjplimp at sandia.gov</li>
<li>Aidan Thompson, athomps at sandia.gov</li>
<li>Paul Crozier, pscrozi at sandia.gov</li>
</ul>
<p>The following folks are responsible for significant contributions to
the code, or other aspects of the LAMMPS development effort. Many of
the packages they have written are somewhat unique to LAMMPS and the
code would not be as general-purpose as it is without their expertise
and efforts.</p>
<ul class="simple">
<li>Axel Kohlmeyer (Temple U), akohlmey at gmail.com, SVN and Git repositories, indefatigable mail list responder, USER-CG-CMM and USER-OMP packages</li>
<li>Roy Pollock (LLNL), Ewald and PPPM solvers</li>
<li>Mike Brown (ORNL), brownw at ornl.gov, GPU package</li>
<li>Greg Wagner (Sandia), gjwagne at sandia.gov, MEAM package for MEAM potential</li>
<li>Mike Parks (Sandia), mlparks at sandia.gov, PERI package for Peridynamics</li>
<li>Rudra Mukherjee (JPL), Rudranarayan.M.Mukherjee at jpl.nasa.gov, POEMS package for articulated rigid body motion</li>
<li>Reese Jones (Sandia) and collaborators, rjones at sandia.gov, USER-ATC package for atom/continuum coupling</li>
<li>Ilya Valuev (JIHT), valuev at physik.hu-berlin.de, USER-AWPMD package for wave-packet MD</li>
<li>Christian Trott (U Tech Ilmenau), christian.trott at tu-ilmenau.de, USER-CUDA package</li>
<li>Andres Jaramillo-Botero (Caltech), ajaramil at wag.caltech.edu, USER-EFF package for electron force field</li>
<li>Christoph Kloss (JKU), Christoph.Kloss at jku.at, USER-LIGGGHTS package for granular models and granular/fluid coupling</li>
<li>Metin Aktulga (LBL), hmaktulga at lbl.gov, USER-REAXC package for C version of ReaxFF</li>
<li>Georg Gunzenmuller (EMI), georg.ganzenmueller at emi.fhg.de, USER-SPH package</li>
</ul>
<p>As discussed in <a class="reference internal" href="Section_history.html"><span class="doc">Section 13</span></a>, LAMMPS
originated as a cooperative project between DOE labs and industrial
partners. Folks involved in the design and testing of the original
version of LAMMPS were the following:</p>
<ul class="simple">
<li>John Carpenter (Mayo Clinic, formerly at Cray Research)</li>
<li>Terry Stouch (Lexicon Pharmaceuticals, formerly at Bristol Myers Squibb)</li>
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>.
<li class="toctree-l2"><a class="reference internal" href="#submitting-new-features-for-inclusion-in-lammps">10.15. Submitting new features for inclusion in LAMMPS</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<div class="line">10.6 <a class="reference internal" href="#mod-6"><span class="std std-ref">Fix styles</span></a> which include integrators, temperature and pressure control, force constraints, boundary conditions, diagnostic output, etc</div>
<div class="line">10.15 <a class="reference internal" href="#mod-15"><span class="std std-ref">Submitting new features for inclusion in LAMMPS</span></a></div>
<div class="line"><br /></div>
</div>
<p>LAMMPS is designed in a modular fashion so as to be easy to modify and
extend with new functionality. In fact, about 75% of its source code
is files added in this fashion.</p>
<p>In this section, changes and additions users can make are listed along
with minimal instructions. If you add a new feature to LAMMPS and
think it will be of interest to general users, we encourage you to
submit it to the developers for inclusion in the released version of
LAMMPS. Information about how to do this is provided
<td>retreive extra info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>pack_exchange</td>
<td>store all an atom’s info to migrate to another processor (required)</td>
</tr>
<tr class="row-even"><td>unpack_exchange</td>
<td>retrieve an atom’s info from the buffer (required)</td>
</tr>
<tr class="row-odd"><td>size_restart</td>
<td>number of restart quantities associated with proc’s atoms (required)</td>
</tr>
<tr class="row-even"><td>pack_restart</td>
<td>pack atom quantities into a buffer (required)</td>
</tr>
<tr class="row-odd"><td>unpack_restart</td>
<td>unpack atom quantities from a buffer (required)</td>
</tr>
<tr class="row-even"><td>create_atom</td>
<td>create an individual atom of this style (required)</td>
</tr>
<tr class="row-odd"><td>data_atom</td>
<td>parse an atom line from the data file (required)</td>
</tr>
<tr class="row-even"><td>data_atom_hybrid</td>
<td>parse additional atom info unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>data_vel</td>
<td>parse one line of velocity information from data file (optional)</td>
</tr>
<tr class="row-even"><td>data_vel_hybrid</td>
<td>parse additional velocity data unique to this atom style (optional)</td>
</tr>
<tr class="row-odd"><td>memory_usage</td>
<td>tally memory allocated by atom arrays (required)</td>
</tr>
</tbody>
</table>
<p>The constructor of the derived class sets values for several variables
that you must set when defining a new atom style, which are documented
in atom_vec.h. New atom arrays are defined in atom.cpp. Search for
the word “customize” and you will find locations you will need to
modify.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is possible to add some attributes, such as a molecule ID, to
atom styles that do not have them via the <a class="reference internal" href="fix_property_atom.html"><span class="doc">fix property/atom</span></a> command. This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms. See the <a class="reference internal" href="fix_property_atom.html"><span class="doc">fix property/atom</span></a> doc page for examples of cases
where this is useful and details on how to initialize, access, and
<a class="reference internal" href="compute.html"><span class="doc">computes</span></a> can be added to LAMMPS, as discussed below.
The code for these classes can use the per-atom properties defined by
fix property/atom. The Atom class has a find_custom() method that is
useful in this context:</p>
<pre class="literal-block">
int index = atom->find_custom(char *name, int &flag);
</pre>
<p>The “name” of a custom attribute, as specified in the <a class="reference internal" href="fix_property_atom.html"><span class="doc">fix property/atom</span></a> command, is checked to verify
that it exists and its index is returned. The method also sets flag =
0/1 depending on whether it is an integer or floating-point attribute.
The vector of values associated with the attribute can then be
accessed using the returned index as</p>
<pre class="literal-block">
int *ivector = atom->ivector[index];
double *dvector = atom->dvector[index];
</pre>
<p>Ivector or dvector are vectors of length Nlocal = # of owned atoms,
which store the attributes of individual atoms.</p>
<p>There is one class that computes and prints thermodynamic information
to the screen and log file; see the file thermo.cpp.</p>
<p>There are two styles defined in thermo.cpp: “one” and “multi”. There
is also a flexible “custom” style which allows the user to explicitly
list keywords for quantities to print when thermodynamic info is
output. See the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command for a list
of defined quantities.</p>
<p>The thermo styles (one, multi, etc) are simply lists of keywords.
Adding a new style thus only requires defining a new list of keywords.
Search for the word “customize” with references to “thermo style” in
thermo.cpp to see the two locations where code will need to be added.</p>
<p>New keywords can also be added to thermo.cpp to compute new quantities
for output. Search for the word “customize” with references to
“keyword” in thermo.cpp to see the several locations where code will
need to be added.</p>
<p>Note that the <a class="reference internal" href="thermo.html"><span class="doc">thermo_style custom</span></a> command already allows
for thermo output of quantities calculated by <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a>,
<a class="reference internal" href="compute.html"><span class="doc">computes</span></a>, and <a class="reference internal" href="variable.html"><span class="doc">variables</span></a>. Thus, it may
be simpler to compute what you wish via one of those constructs, than
by adding a new keyword to the thermo command.</p>
<p>There is one class that computes and stores <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>
information in LAMMPS; see the file variable.cpp. The value
associated with a variable can be periodically printed to the screen
via the <a class="reference internal" href="print.html"><span class="doc">print</span></a>, <a class="reference internal" href="fix_print.html"><span class="doc">fix print</span></a>, or
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> commands. Variables of style
“equal” can compute complex equations that involve the following types
of arguments:</p>
<pre class="literal-block">
thermo keywords = ke, vol, atoms, ...
other variables = v_a, v_myvar, ...
math functions = div(x,y), mult(x,y), add(x,y), ...
<span id="mod-15"></span><h2>10.15. Submitting new features for inclusion in LAMMPS</h2>
<p>We encourage users to submit new features or modifications for
LAMMPS to <a class="reference external" href="http://lammps.sandia.gov/authors.html">the core developers</a>
so they can be added to the LAMMPS distribution. The preferred way to
manage and coordinate this is as of Fall 2016 via the LAMMPS project on
<a class="reference external" href="https://github.com/lammps/lammps">GitHub</a>. An alternative is to contact
the LAMMPS developers or the indicated developer of a package or feature
directly and send in your contribution via e-mail.</p>
<p>For any larger modifications or programming project, you are encouraged
to contact the LAMMPS developers ahead of time, in order to discuss
implementation strategies and coding guidelines, that will make it
easier to integrate your contribution and result in less work for
everybody involved. You are also encouraged to search through the list
of <a class="reference external" href="https://github.com/lammps/lammps/issues">open issues on GitHub</a> and
submit a new issue for a planned feature, so you would not duplicate
the work of others (and possibly get scooped by them) or have your work
duplicated by others.</p>
<p>How quickly your contribution will be integrated
depends largely on how much effort it will cause to integrate and test
it, how much it requires changes to the core codebase, and of how much
interest it is to the larger LAMMPS community. Please see below for a
checklist of typical requirements. Once you have prepared everything,
see <a class="reference internal" href="tutorial_github.html"><span class="doc">this tutorial</span></a> for instructions on how to
submit your changes or new files through a GitHub pull request. If you
prefer to submit patches or full files, you should first make certain,
that your code works correctly with the latest patch-level version of
LAMMPS and contains all bugfixes from it. Then create a gzipped tar
file of all changed or added files or a corresponding patch file using
‘diff -u’ or ‘diff -c’ and compress it with gzip. Please only use
gzip compression, as this works well on all platforms.</p>
<p>If the new features/files are broadly useful we may add them as core
files to LAMMPS or as part of a <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">standard package</span></a>. Else we will add them as a
user-contributed file or package. Examples of user packages are in
src sub-directories that start with USER. The USER-MISC package is
simply a collection of (mostly) unrelated single files, which is the
simplest way to have your contribution quickly added to the LAMMPS
distribution. You can see a list of the both standard and user
packages by typing “make package” in the LAMMPS src directory.</p>
<p>Note that by providing us files to release, you are agreeing to make
them open-source, i.e. we can release them under the terms of the GPL,
used as a license for the rest of LAMMPS. See <a class="reference internal" href="Section_intro.html#intro-4"><span class="std std-ref">Section 1.4</span></a> for details.</p>
<p>With user packages and files, all we are really providing (aside from
the fame and fortune that accompanies having your name in the source
code and on the <a class="reference external" href="http://lammps.sandia.gov/authors.html">Authors page</a>
of the <a class="reference external" href="http://lammps.sandia.gov">LAMMPS WWW site</a>), is a means for you to distribute your
work to the LAMMPS user community, and a mechanism for others to
easily try out your new feature. This may help you find bugs or make
contact with new collaborators. Note that you’re also implicitly
agreeing to support your code which means answer questions, fix bugs,
and maintain it if LAMMPS changes in some way that breaks it (an
unusual event).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you prefer to actively develop and support your add-on
feature yourself, then you may wish to make it available for download
from your own website, as a user package that LAMMPS users can add to
their copy of LAMMPS. See the <a class="reference external" href="http://lammps.sandia.gov/offsite.html">Offsite LAMMPS packages and tools</a> page of the LAMMPS web
site for examples of groups that do this. We are happy to advertise
your package and web site from that page. Simply email the
<a class="reference external" href="http://lammps.sandia.gov/authors.html">developers</a> with info about
your package and we will post it there.</p>
</div>
<p>The previous sections of this doc page describe how to add new “style”
files of various kinds to LAMMPS. Packages are simply collections of
one or more new class files which are invoked as a new style within a
LAMMPS input script. If designed correctly, these additions typically
do not require changes to the main core of LAMMPS; they are simply
add-on files. If you think your new feature requires non-trivial
changes in core LAMMPS files, you’ll need to <a class="reference external" href="http://lammps.sandia.gov/authors.html">communicate with the developers</a>, since we may or may
not want to make those changes. An example of a trivial change is
making a parent-class method “virtual” when you derive a new child
class from it.</p>
<p>Here is a checklist of steps you need to follow to submit a single file
or user package for our consideration. Following these steps will save
both you and us time. See existing files in packages in the src dir for
examples. If you are uncertain, please ask.</p>
<ul class="simple">
<li>All source files you provide must compile with the most current
version of LAMMPS with multiple configurations. In particular you
need to test compiling LAMMPS from scratch with -DLAMMPS_BIGBIG
set in addition to the default -DLAMMPS_SMALLBIG setting. Your code
will need to work correctly in serial and in parallel using MPI.</li>
<li>For consistency with the rest of LAMMPS and especially, if you want
your contribution(s) to be added to main LAMMPS code or one of its
standard packages, it needs to be written in a style compatible with
other LAMMPS source files. This means: 2-character indentation per
level, <strong>no tabs</strong>, no lines over 80 characters. I/O is done via
the C-style stdio library, class header files should not import any
system headers outside <stdio.h>, STL containers should be avoided
in headers, and forward declarations used where possible or needed.
All added code should be placed into the LAMMPS_NS namespace or a
sub-namespace; global or static variables should be avoided, as they
conflict with the modular nature of LAMMPS and the C++ class structure.
Header files must <strong>not</strong> import namespaces with <em>using</em>.
This all is so the developers can more easily understand, integrate,
and maintain your contribution and reduce conflicts with other parts
of LAMMPS. This basically means that the code accesses data
structures, performs its operations, and is formatted similar to other
LAMMPS source files, including the use of the error class for error
and warning messages.</li>
<li>If you want your contribution to be added as a user-contributed
feature, and it’s a single file (actually a *.cpp and *.h file) it can
rapidly be added to the USER-MISC directory. Send us the one-line
entry to add to the USER-MISC/README file in that dir, along with the
2 source files. You can do this multiple times if you wish to
contribute several individual features.</li>
<li>If you want your contribution to be added as a user-contribution and
it is several related featues, it is probably best to make it a user
package directory with a name like USER-FOO. In addition to your new
files, the directory should contain a README text file. The README
should contain your name and contact information and a brief
description of what your new package does. If your files depend on
other LAMMPS style files also being installed (e.g. because your file
is a derived class from the other LAMMPS class), then an Install.sh
file is also needed to check for those dependencies. See other README
and Install.sh files in other USER directories as examples. Send us a
tarball of this USER-FOO directory.</li>
<li>Your new source files need to have the LAMMPS copyright, GPL notice,
and your name and email address at the top, like other
user-contributed LAMMPS source files. They need to create a class
that is inside the LAMMPS namespace. If the file is for one of the
USER packages, including USER-MISC, then we are not as picky about the
coding style (see above). I.e. the files do not need to be in the
same stylistic format and syntax as other LAMMPS files, though that
would be nice for developers as well as users who try to read your
code.</li>
<li>You <strong>must</strong> also create a <strong>documentation</strong> file for each new command or
style you are adding to LAMMPS. For simplicity and convenience, the
documentation of groups of closely related commands or styles may be
combined into a single file. This will be one file for a single-file
feature. For a package, it might be several files. These are simple
text files with a specific markup language, that are then auto-converted
to HTML and PDF. The tools for this conversion are included in the
source distribution, and the translation can be as simple as doing
“make html pdf” in the doc folder.
Thus the documentation source files must be in the same format and
style as other *.txt files in the lammps/doc/src directory for similar
commands and styles; use one or more of them as a starting point.
A description of the markup can also be found in
lammps/doc/utils/txt2html/README.html
As appropriate, the text files can include links to equations
(see doc/Eqs/*.tex for examples, we auto-create the associated JPG
files), or figures (see doc/JPG for examples), or even additional PDF
files with further details (see doc/PDF for examples). The doc page
should also include literature citations as appropriate; see the
bottom of doc/fix_nh.txt for examples and the earlier part of the same
file for how to format the cite itself. The “Restrictions” section of
the doc page should indicate that your command is only available if
LAMMPS is built with the appropriate USER-MISC or USER-FOO package.
See other user package doc files for examples of how to do this. The
prerequiste for building the HTML format files are Python 3.x and
virtualenv, the requirement for generating the PDF format manual
is the <a class="reference external" href="http://www.htmldoc.org/">htmldoc</a> software. Please run at least
“make html” and carefully inspect and proofread the resuling HTML format
doc page before submitting your code.</li>
<li>For a new package (or even a single command) you should include one or
more example scripts demonstrating its use. These should run in no
more than a couple minutes, even on a single processor, and not require
large data files as input. See directories under examples/USER for
examples of input scripts other users provided for their packages.
These example inputs are also required for validating memory accesses
and testing for memory leaks with valgrind</li>
<li>If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the *.cpp
source file. See src/USER-EFF/atom_vec_electron.cpp for an example.
A LaTeX citation is stored in a variable at the top of the file and a
single line of code that references the variable is added to the
constructor of the class. Whenever a user invokes your feature from
their input script, this will cause LAMMPS to output the citation to a
log.cite file and prompt the user to examine the file. Note that you
should only use this for a paper you or your group authored.
E.g. adding a cite in the code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended
usage. That kind of citation should just be in the doc page you
provide.</li>
</ul>
<p>Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your documentation and README files, and the
easier you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try out your new feature.</p>
<p id="foo"><strong>(Foo)</strong> Foo, Morefoo, and Maxfoo, J of Classic Potentials, 75, 345 (1997).</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>.
<p>Contents: Compute and pair styles that implement the adiabatic
core/shell model for polarizability. The compute temp/cs command
measures the temperature of a system with core/shell particles. The
pair styles augment Born, Buckingham, and Lennard-Jones styles with
core/shell capabilities. See <a class="reference internal" href="Section_howto.html#howto-26"><span class="std std-ref">Section howto 6.26</span></a> for an overview of how to use the
<p>Contents: Dozens of atom, pair, bond, angle, dihedral, improper styles
which run with the Kokkos library to provide optimization for
multicore CPUs (via OpenMP), NVIDIA GPUs, or the Intel Xeon Phi (in
native mode). All of them have a “kk” in their style name. <a class="reference internal" href="accelerate_kokkos.html"><span class="doc">Section accelerate kokkos</span></a> gives details of what
hardware and software is required on your system, and how to build and
use this package. See the GPU, OPT, USER-INTEL, USER-OMP packages,
which also provide optimizations for the same range of hardware.</p>
<p>Building with the KOKKOS package requires choosing which of 3 hardware
options you are optimizing for: CPU acceleration via OpenMP, GPU
acceleration, or Intel Xeon Phi. (You can build multiple times to
create LAMMPS executables for different hardware.) It also requires a
C++11 compatible compiler. For GPUs, the NVIDIA “nvcc” compiler is
used, and an appopriate KOKKOS_ARCH setting should be made in your
Makefile.machine for your GPU hardware and NVIDIA software.</p>
<p>The simplest way to do this is to use Makefile.kokkos_cuda or
Makefile.kokkos_omp or Makefile.kokkos_phi in src/MAKE/OPTIONS, via
“make kokkos_cuda” or “make kokkos_omp” or “make kokkos_phi”. (Check
the KOKKOS_ARCH setting in Makefile.kokkos_cuda), Or, as illustrated
below, you can use the Make.py script with its “-kokkos” option to
choose which hardware to build for. Type “python src/Make.py -h
-kokkos” to see the details. If these methods do not work on your
system, you will need to read the <a class="reference internal" href="accelerate_kokkos.html"><span class="doc">Section accelerate kokkos</span></a> doc page for details of what
Makefile.machine settings are needed.</p>
<p>To install via make or Make.py for each of 3 hardware options:</p>
<pre class="literal-block">
make yes-kokkos
make kokkos_omp # for CPUs with OpenMP
make kokkos_cuda # for GPUs, check the KOKKOS_ARCH setting in Makefile.kokkos_cuda
make kokkos_phi # for Xeon Phis
</pre>
<p>Make.py -p kokkos -kokkos omp -a machine # for CPUs with OpenMP
Make.py -p kokkos -kokkos cuda arch=35 -a machine # for GPUs of style arch
Make.py -p kokkos -kokkos phi -a machine # for Xeon Phis</p>
<p>Contents: A variety of long-range Coulombic solvers, and pair styles
which compute the corresponding short-range portion of the pairwise
Coulombic interactions. These include Ewald, particle-particle
particle-mesh (PPPM), and multilevel summation method (MSM) solvers.</p>
<p>Building with the KSPACE package requires a 1d FFT library be present
on your system for use by the PPPM solvers. This can be the KISS FFT
library provided with LAMMPS, or 3rd party libraries like FFTW or a
vendor-supplied FFT library. See step 6 of <a class="reference internal" href="Section_start.html#start-2-2"><span class="std std-ref">Section start 2.2.2</span></a> of the manual for details of how
to select different FFT options in your machine Makefile. The Make.py
tool has an “-fft” option which can insert these settings into your
machine Makefile automatically. Type “python src/Make.py -h -fft” to
<p>Contents: A handful of pair styles with an “opt” in their style name
which are optimized for improved CPU performance on single or multiple
cores. These include EAM, LJ, CHARMM, and Morse potentials. <a class="reference internal" href="accelerate_opt.html"><span class="doc">Section accelerate opt</span></a> gives details of how to build and
use this package. See the KOKKOS, USER-INTEL, and USER-OMP packages,
which also have styles optimized for CPU performance.</p>
<p>Some C++ compilers, like the Intel compiler, require the compile flag
“-restrict” to build LAMMPS with the OPT package. It should be added
to the CCFLAGS line of your Makefile.machine. Or use Makefile.opt in
src/MAKE/OPTIONS, via “make opt”. For compilers that use the flag,
the Make.py command adds it automatically to the Makefile.auto file it
<p>Contents: A <a class="reference internal" href="python.html"><span class="doc">python</span></a> command which allow you to execute
Python code from a LAMMPS input script. The code can be in a separate
file or embedded in the input script itself. See <a class="reference external" href="Section_python.html"">Section python 11.2</a> for an overview of using Python from
LAMMPS and for other ways to use LAMMPS and Python together.</p>
<p>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 supported. The build uses the
contents of the lib/python/Makefile.lammps file to find all the Python
files required in the build/link process. See the lib/python/README
file if the settings in that file do not work on your system. Note
that the Make.py script has a “-python” option to allow an alternate
lib/python/Makefile.lammps file to be specified and LAMMPS to be built
in one step. Type “python src/Make.py -h -python” to see the details.</p>
<p>Contents: A collection of multi-replica methods that are used by
invoking multiple instances (replicas) of LAMMPS
simulations. Communication between individual replicas is performed in
different ways by the different methods. See <a class="reference internal" href="Section_howto.html#howto-5"><span class="std std-ref">Section howto 6.5</span></a> for an overview of how to run
multi-replica simulations in LAMMPS. Multi-replica methods included
in the package are nudged elastic band (NEB), parallel replica
dynamics (PRD), temperature accelerated dynamics (TAD), parallel
tempering, and a verlet/split algorithm for performing long-range
Coulombics on one set of processors, and the remainded of the force
Sampling and Restraints. This package implements a <a class="reference internal" href="fix_colvars.html"><span class="doc">fix colvars</span></a> command which wraps a COLVARS library which
can perform those kinds of simulations. See src/USER-COLVARS/README
<p>Contents: This package contains methods for simulating polarizable
systems using thermalized Drude oscillators. It has computes, fixes,
and pair styles for this purpose. See <a class="reference internal" href="Section_howto.html#howto-27"><span class="std std-ref">Section howto 6.27</span></a> for an overview of how to use the
package. See src/USER-DRUDE/README for additional details. There are
auxiliary tools for using this package in tools/drude.</p>
<p>Contents: FEP stands for free energy perturbation. This package
provides methods for performing FEP simulations by using a <a class="reference internal" href="fix_adapt_fep.html"><span class="doc">fix adapt/fep</span></a> command with soft-core pair potentials,
which have a “soft” in their style name. See src/USER-FEP/README for
more details. There are auxiliary tools for using this package in
<p>Contents: Dozens of pair, bond, angle, dihedral, and improper styles
that are optimized for Intel CPUs and the Intel Xeon Phi (in offload
mode). All of them have an “intel” in their style name. <a class="reference internal" href="accelerate_intel.html"><span class="doc">Section accelerate intel</span></a> gives details of what hardware
and compilers are required on your system, and how to build and use
this package. Also see src/USER-INTEL/README for more details. See
the KOKKOS, OPT, and USER-OMP packages, which also have CPU and
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>.
<li class="toctree-l4"><a class="reference internal" href="#building-lammps-for-multiple-platforms">2.2.3.1. Building LAMMPS for multiple platforms.</a></li>
<li class="toctree-l3"><a class="reference internal" href="#packages-that-require-extra-libraries">2.3.3. Packages that require extra libraries</a></li>
<li class="toctree-l3"><a class="reference internal" href="#packages-that-require-makefile-machine-settings">2.3.4. Packages that require Makefile.machine settings</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-via-the-make-py-tool">2.4. Building LAMMPS via the Make.py tool</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. Calling the LAMMPS library</a></li>
<span id="start-1"></span><h2>2.1. What’s in the LAMMPS distribution</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
tarball in an appropriate directory.</p>
<pre class="literal-block">
tar -xzvf lammps*.tar.gz
</pre>
<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="http://lammps.sandia.gov/download.html">download page</a> also has links to download
pre-build Windows installers, as well as pre-built packages for
several widely used 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 access to the up-to-date sources that are used by the LAMMPS
core developers.</p>
<p>The Windows and Linux packages for serial or parallel include
only selected 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 class="std std-ref">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</h2>
<p>This section has the following sub-sections:</p>
<ul class="simple">
<li><a class="reference internal" href="#start-2-1"><span class="std std-ref">Read this first</span></a></li>
<li><a class="reference internal" href="#start-2-2"><span class="std std-ref">Steps to build a LAMMPS executable</span></a></li>
<li><a class="reference internal" href="#start-2-3"><span class="std std-ref">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 <strong>lmp_mpi</strong> or <strong>lmp_serial</strong>
or <strong>lmp_mac</strong> 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 class="std std-ref">this section</span></a> below.</p>
</div>
<div class="section" id="step-1">
<h4>2.2.2.2. Step 1</h4>
<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>
</div>
<div class="section" id="step-2">
<h4>2.2.2.3. Step 2</h4>
<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>
</div>
<div class="section" id="step-3">
<h4>2.2.2.4. Step 3</h4>
<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 (*.cpp) or header (*.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 *.d files will be printed
out rapidly. This is not an error; it is the Makefile doing its
normal creation of dependencies.</p>
</div>
<div class="section" id="step-4">
<h4>2.2.2.5. Step 4</h4>
<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>-DLAMMPS_EXCEPTIONS</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>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 are
provided in the COMPRESS package. From more details about compiling
LAMMPS with packages, please see below.</p>
</div>
<p>If you use -DLAMMPS_JPEG, the <a class="reference internal" href="dump_image.html"><span class="doc">dump image</span></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"><span class="doc">dump image</span></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"><span class="doc">dump movie</span></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>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Similar to the note above, this option can conflict with
high-speed networks, because it uses popen().</p>
</div>
<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"><span class="doc">dump</span></a> command for details.</p>
<p>Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG,
-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 class="std std-ref">Additional build tips</span></a> section below for more
details on these settings.</p>
<p>Note that the USER-ATC package is 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>The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative
versions of error handling inside of LAMMPS. This is useful when
external codes drive LAMMPS as a library. Using this option, LAMMPS
errors do not kill the caller. Instead, the call stack is unwound and
control returns to the caller. The library interface provides the
lammps_has_error() and lammps_get_last_error_message() functions to
detect and find out more about a LAMMPS error.</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"><span class="doc">kspace_style</span></a> command for info about PPPM. See
Step 6 below for info about building LAMMPS with an FFT library.</p>
</div>
<div class="section" id="step-5">
<h4>2.2.2.6. Step 5</h4>
<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>
</div>
<div class="section" id="step-6">
<h4>2.2.2.7. Step 6</h4>
<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>
</div>
<div class="section" id="step-7">
<h4>2.2.2.8. Step 7</h4>
<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"><span class="doc">dump image</span></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>
</div>
<div class="section" id="step-8">
<h4>2.2.2.9. Step 8</h4>
<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 class="std std-ref">this section</span></a> below, before proceeding to Step 9.</p>
</div>
<div class="section" id="step-9">
<h4>2.2.2.10. Step 9</h4>
<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>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"><span class="doc">dump</span></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"><span class="doc">compute msd</span></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" />
</div>
</div>
<div class="section" id="building-for-a-mac">
<span id="start-2-5"></span><h3>2.2.4. Building for a Mac</h3>
<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" />
</div>
<div class="section" id="building-for-windows">
<span id="start-2-6"></span><h3>2.2.5. Building for Windows</h3>
<p>If you want to build a Windows version of LAMMPS, you can build it
yourself, but it may require some effort. LAMMPS expects a Unix-like
build environment for the default build procedure. This can be done
using either Cygwin or MinGW; the latter also exists as a ready-to-use
Linux-to-Windows cross-compiler in several Linux distributions. In
these cases, you can do the installation after installing several
unix-style commands like make, grep, sed and bash with some shell
utilities.</p>
<p>For Cygwin and the MinGW cross-compilers, suitable makefiles are
provided in src/MAKE/MACHINES. When using other compilers, like
Visual C++ or Intel compilers for Windows, you may have to implement
your own build system. Since none of the current LAMMPS core developers
has significant experience building executables on Windows, we are
happy to distribute contributed instructions and modifications, but
we cannot provide support for those.</p>
<p>With the so-called “Anniversary Update” to Windows 10, there is a
Ubuntu subsystem available for Windows, that can be installed and
then it can be used to compile/install LAMMPS as if you are running
on a Ubuntu Linux system.</p>
<p>As an alternative, you can download “daily builds” (and some older
<p>The source code for LAMMPS is structured as a set of core files which
are always included, plus optional packages. Packages are groups of
files that enable a specific set of features. For example, force
fields for molecular systems or granular systems are in packages.</p>
<p><a class="reference internal" href="Section_packages.html"><span class="doc">Section packages</span></a> in the manual has details
about all the packages, including specific instructions for building
LAMMPS with each package, which are covered in a more general manner
below.</p>
<p>You can see the list of all packages by typing “make package” from
within the src directory of the LAMMPS distribution. This also lists
various make commands that can be used to manipulate packages.</p>
<p>If you use a command in a LAMMPS input script that is part of a
package, you must have built LAMMPS with that package, else you will
get an error that the style is invalid or the command is unknown.
Every command’s doc page specfies if it is part of a package. You can
also type</p>
<pre class="literal-block">
lmp_machine -h
</pre>
<p>to run your executable with the optional <a class="reference internal" href="#start-7"><span class="std std-ref">-h command-line switch</span></a> for “help”, which will simply list the styles and
commands known to your executable, and immediately exit.</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"><span class="doc">Section 4</span></a> of the manual. The
difference between standard and user packages is as follows:</p>
<p>Standard packages, such as molecule or kspace, 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, such as user-atc or user-omp, 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 may need to contact the contributor directly to get help.
Information on how to submit additions you make to LAMMPS as single
files or either a standard or user-contributed package are given in
<a class="reference internal" href="Section_modify.html#mod-15"><span class="std std-ref">this section</span></a> of the documentation.</p>
<span id="start-3-3"></span><h3>2.3.3. Packages that require extra libraries</h3>
<p>A few of the standard and user packages require additional auxiliary
libraries. Many of them are provided with LAMMPS, in which case they
must be compiled first, before LAMMPS is built, if you wish to include
that package. If you get a LAMMPS build error about a missing
library, this is likely the reason. See the
<a class="reference internal" href="Section_packages.html"><span class="doc">Section 4</span></a> doc page for a list of
packages that have these kinds of auxiliary libraries.</p>
<p>The lib directory in the distribution has sub-directories with package
names that correspond to the needed auxiliary libs, e.g. lib/gpu.
Each sub-directory has a README file that gives more details. Code
for most of the auxiliary libraries is included in that directory.
Examples are the USER-ATC and MEAM packages.</p>
<p>A few of the lib sub-directories do not include code, but do include
instructions (and sometimes scripts) that automate the process of
downloading the auxiliary library and installing it so LAMMPS can link
to it. Examples are the KIM, VORONOI, USER-MOLFILE, and USER-SMD
packages.</p>
<p>The lib/python directory (for the PYTHON package) contains only a
choice of Makefile.lammps.* files. This is because no auxiliary code
or libraries are needed, only the Python library and other system libs
that should already available on your system. However, the
Makefile.lammps file is needed to tell LAMMPS which libs to use and
where to find them.</p>
<p>For libraries with provided code, the sub-directory README file
(e.g. lib/atc/README) has instructions on how to build that library.
This information is also summarized in <a class="reference internal" href="Section_packages.html"><span class="doc">Section packages</span></a>. Typically this is done by typing
<span id="start-3-4"></span><h3>2.3.4. Packages that require Makefile.machine settings</h3>
<p>A few packages require specific settings in Makefile.machine, to
either build or use the package effectively. These are the
USER-INTEL, KOKKOS, USER-OMP, and OPT packages, used for accelerating
code performance on CPUs or other hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section acclerate</span></a>.</p>
<p>A summary of what Makefile.machine changes are needed for each of
these packages is given in <a class="reference internal" href="Section_packages.html"><span class="doc">Section packages</span></a>.
The details are given on the doc pages that describe each of these
<p>You can also look at the following machine Makefiles in
src/MAKE/OPTIONS, which include the changes. Note that the USER-INTEL
and KOKKOS packages allow for settings that build LAMMPS for different
hardware. The USER-INTEL package builds for CPU and the Xeon Phi, the
KOKKOS package builds for OpenMP, GPUs (Cuda), and the Xeon Phi.</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>
<li>Makefile.opt</li>
</ul>
<p>Also note that the Make.py tool, described in the next <a class="reference internal" href="#start-4"><span class="std std-ref">Section 2.4</span></a> can automatically add the needed info to an existing
machine Makefile, using simple command-line arguments.</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>
<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
<p>Either flavor of library (static or shared) 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 class="std std-ref">Section 6.10</span></a> of the
manual. See <a class="reference internal" href="Section_python.html"><span class="doc">Section 11</span></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 class="std std-ref">Section 6.19</span></a> of the manual for a description of the
interface and how to extend it for your needs.</p>
<p>Explicitly enable or disable KOKKOS support, as provided by the KOKKOS
package. Even if LAMMPS is built with this package, as described
above in <a class="reference internal" href="#start-3"><span class="std std-ref">Section 2.3</span></a>, 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.</p>
<p>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.</p>
<p>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. Example of when to use these options and what
settings to use on different platforms is given in <a class="reference internal" href="Section_accelerate.html#acc-3"><span class="std std-ref">Section 5.8</span></a>.</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>, <em>opt</em>, or <em>hybrid</em>. These
refer to optional packages that LAMMPS can be built with, as described
above in <a class="reference internal" href="#start-3"><span class="std std-ref">Section 2.3</span></a>. 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.</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"><span class="doc">pair_style lj/cut</span></a> 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 <a class="reference internal" href="atom_style.html"><span class="doc">atom</span></a>,
<a class="reference internal" href="run_style.html"><span class="doc">run</span></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"><span class="doc">package gpu</span></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"><span class="doc">package intel</span></a> 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
<a class="reference internal" href="package.html"><span class="doc">package omp</span></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"><span class="doc">package kokkos</span></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"><span class="doc">package omp</span></a> command in your script.</p>
<p>The <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command can also be used within an input
script to set a suffix, or to turn off or back on any suffix setting
<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"><span class="doc">index-style variable</span></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"><span class="doc">variable</span></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 class="std std-ref">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>
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>.
<p>LAMMPS is designed to be a computational kernel for performing
molecular dynamics computations. Additional pre- and post-processing
steps are often necessary to setup and analyze a simulation. A few
additional tools are provided with the LAMMPS distribution and are
described in this section.</p>
<p>Our group has also written and released a separate toolkit called
<a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a> which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
written in <a class="reference external" href="http://www.python.org">Python</a> and is available for download from <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">the Pizza.py WWW site</a>.</p>
<p>Note that many users write their own setup or analysis tools or use
other existing codes and convert their output to a LAMMPS input format
or vice versa. The tools listed here are included in the LAMMPS
distribution as examples of auxiliary tools. Some of them are not
actively supported by Sandia, as they were contributed by LAMMPS
users. If you have problems using them, we can direct you to the
authors.</p>
<p>The source code for each of these codes is in the tools sub-directory
of the LAMMPS distribution. There is a Makefile (which you may need
to edit for your platform) which will build several of the tools which
reside in that directory. Some of them are larger packages in their
Zr. The files can then be used with the <a class="reference internal" href="pair_eam.html"><span class="doc">pair_style eam/alloy</span></a> command.</p>
<p>The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
and is based on his paper:</p>
<p>X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
144113 (2004).</p>
<hr class="docutils" />
</div>
<div class="section" id="eam-generate-tool">
<span id="eamgn"></span><h2>9.9. eam generate tool</h2>
<p>The tools/eam_generate directory contains several one-file C programs
that convert an analytic formula into a tabulated <a class="reference internal" href="pair_eam.html"><span class="doc">embedded atom method (EAM)</span></a> setfl potential file. The potentials they
produce are in the potentials directory, and can be used with the
<p>The source files and potentials were provided by Gerolf Ziegenhain
(gerolf at ziegenhain.com).</p>
<hr class="docutils" />
</div>
<div class="section" id="eff-tool">
<span id="eff"></span><h2>9.10. eff tool</h2>
<p>The tools/eff directory contains various scripts for generating
structures and post-processing output for simulations using the
electron force field (eFF).</p>
<p>These tools were provided by Andres Jaramillo-Botero at CalTech
(ajaramil at wag.caltech.edu).</p>
<hr class="docutils" />
</div>
<div class="section" id="emacs-tool">
<span id="emacs"></span><h2>9.11. emacs tool</h2>
<p>The tools/emacs directory contains a Lips add-on file for Emacs that
enables a lammps-mode for editing of input scripts when using Emacs,
with various highlighting options setup.</p>
<p>These tools were provided by Aidan Thompson at Sandia
(athomps at sandia.gov).</p>
<hr class="docutils" />
</div>
<div class="section" id="fep-tool">
<span id="fep"></span><h2>9.12. fep tool</h2>
<p>The tools/fep directory contains Python scripts useful for
post-processing results from performing free-energy perturbation
simulations using the USER-FEP package.</p>
<p>The scripts were contributed by Agilio Padua (Universite Blaise
Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.</p>
<p>See README file in the tools/fep directory.</p>
<hr class="docutils" />
</div>
<div class="section" id="i-pi-tool">
<span id="ipi"></span><h2>9.13. i-pi tool</h2>
<p>The tools/i-pi directory contains a version of the i-PI package, with
all the LAMMPS-unrelated files removed. It is provided so that it can
be used with the <a class="reference internal" href="fix_ipi.html"><span class="doc">fix ipi</span></a> command to perform
path-integral molecular dynamics (PIMD).</p>
<p>The i-PI package was created and is maintained by Michele Ceriotti,
michele.ceriotti at gmail.com, to interface to a variety of molecular
dynamics codes.</p>
<p>See the tools/i-pi/manual.pdf file for an overview of i-PI, and the
<a class="reference internal" href="fix_ipi.html"><span class="doc">fix ipi</span></a> doc page for further details on running PIMD
calculations with LAMMPS.</p>
<hr class="docutils" />
</div>
<div class="section" id="ipp-tool">
<span id="ipp"></span><h2>9.14. ipp tool</h2>
<p>The tools/ipp directory contains a Perl script ipp which can be used
to facilitate the creation of a complicated file (say, a lammps input
script or tools/createatoms input file) using a template file.</p>
<p>ipp was created and is maintained by Reese Jones (Sandia), rjones at
sandia.gov.</p>
<p>See two examples in the tools/ipp directory. One of them is for the
tools/createatoms tool’s input file.</p>
<hr class="docutils" />
</div>
<div class="section" id="kate-tool">
<span id="kate"></span><h2>9.15. kate tool</h2>
<p>The file in the tools/kate directory is an add-on to the Kate editor
in the KDE suite that allow syntax highlighting of LAMMPS input
scripts. See the README.txt file for details.</p>
<p>The file was provided by Alessandro Luigi Sellerio
(alessandro.sellerio at ieni.cnr.it).</p>
<hr class="docutils" />
</div>
<div class="section" id="lmp2arc-tool">
<span id="arc"></span><h2>9.16. lmp2arc tool</h2>
<p>The lmp2arc sub-directory contains a tool for converting LAMMPS output
files to the format for Accelrys’ Insight MD code (formerly
MSI/Biosym and its Discover MD code). See the README file for more
information.</p>
<p>This tool was written by John Carpenter (Cray), Michael Peachey
(Cray), and Steve Lustig (Dupont). John is now at the Mayo Clinic
(jec at mayo.edu), but still fields questions about the tool.</p>
<p>This tool was updated for the current LAMMPS C++ version by Jeff
Greathouse at Sandia (jagreat at sandia.gov).</p>
<hr class="docutils" />
</div>
<div class="section" id="lmp2cfg-tool">
<span id="cfg"></span><h2>9.17. lmp2cfg tool</h2>
<p>The lmp2cfg sub-directory contains a tool for converting LAMMPS output
files into a series of *.cfg files which can be read into the
<a class="reference external" href="http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</a> visualizer. See
the README file for more information.</p>
<p>This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).</p>
<hr class="docutils" />
</div>
<div class="section" id="lmp2vmd-tool">
<span id="vmd"></span><h2>9.18. lmp2vmd tool</h2>
<p>The lmp2vmd sub-directory contains a README.txt file that describes
details of scripts and plugin support within the <a class="reference external" href="http://www.ks.uiuc.edu/Research/vmd">VMD package</a> for visualizing LAMMPS
dump files.</p>
<p>The VMD plugins and other supporting scripts were written by Axel
Kohlmeyer (akohlmey at cmm.chem.upenn.edu) at U Penn.</p>
<p>The pymol_asphere sub-directory contains a tool for converting a
LAMMPS dump file that contains orientation info for ellipsoidal
particles into an input file for the <a class="reference external" href="http://www.pymol.org">PyMol visualization package</a> or its <a class="reference external" href="http://sourceforge.net/scm/?type=svn&group_id=4546">open source variant</a>.</p>
<p>Specifically, the tool triangulates the ellipsoids so they can be
viewed as true ellipsoidal particles within PyMol. See the README and
examples directory within pymol_asphere for more information.</p>
<p>This tool was written by Mike Brown at Sandia.</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>.
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
<p>Note that if the “-sf gpu” switch is used, it also issues a default
<a class="reference internal" href="package.html"><span class="doc">package gpu 1</span></a> command, which sets the number of
GPUs/node to 1.</p>
<p>Using the “-pk” switch explicitly allows for setting of the number of
GPUs/node to use and additional options. Its syntax is the same as
same as the “package gpu” command. See the <a class="reference internal" href="package.html"><span class="doc">package</span></a>
command doc page for details, including the default values used for
all its options if it is not specified.</p>
<p>Note that the default for the <a class="reference internal" href="package.html"><span class="doc">package gpu</span></a> command is to
set the Newton flag to “off” pairwise interactions. It does not
affect the setting for bonded interactions (LAMMPS default is “on”).
The “off” setting for pairwise interaction is currently required for
GPU package pair styles.</p>
<p><strong>Or run with the GPU package by editing an input script:</strong></p>
<p>The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and use of multiple MPI tasks/GPU is the same.</p>
<p>Use the <a class="reference internal" href="suffix.html"><span class="doc">suffix gpu</span></a> command, or you can explicitly add an
“gpu” suffix to individual styles in your input script, e.g.</p>
<pre class="literal-block">
pair_style lj/cut/gpu 2.5
</pre>
<p>You must also use the <a class="reference internal" href="package.html"><span class="doc">package gpu</span></a> command to enable the
GPU package, unless the “-sf gpu” or “-pk gpu” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switches</span></a> were used. It specifies the
number of GPUs/node to use, as well as other options.</p>
<p><strong>Speed-ups to expect:</strong></p>
<p>The performance of a GPU versus a multi-core CPU is a function of your
hardware, which pair style is used, the number of atoms/GPU, and the
precision used on the GPU (double, single, mixed).</p>
<p>See the <a class="reference external" href="http://lammps.sandia.gov/bench.html">Benchmark page</a> of the
LAMMPS web site for performance of the GPU package on various
hardware, including the Titan HPC platform at ORNL.</p>
<p>You should also experiment with how many MPI tasks per GPU to use to
give the best performance for your problem and machine. This is also
a function of the problem size and the pair style being using.
Likewise, you should experiment with the precision setting for the GPU
library to see if single or mixed precision will give accurate
results, since they will typically be faster.</p>
<p><strong>Guidelines for best performance:</strong></p>
<ul class="simple">
<li>Using multiple MPI tasks per GPU will often give the best performance,
as allowed my most multi-core CPU/GPU configurations.</li>
<li>If the number of particles per MPI task is small (e.g. 100s of
particles), it can be more efficient to run with fewer MPI tasks per
GPU, even if you do not use all the cores on the compute node.</li>
<li>The <a class="reference internal" href="package.html"><span class="doc">package gpu</span></a> command has several options for tuning
performance. Neighbor lists can be built on the GPU or CPU. Force
calculations can be dynamically balanced across the CPU cores and
GPUs. GPU-specific settings can be made which can be optimized
for different hardware. See the <a class="reference internal" href="package.html"><span class="doc">packakge</span></a> command
doc page for details.</li>
<li>As described by the <a class="reference internal" href="package.html"><span class="doc">package gpu</span></a> command, GPU
accelerated pair styles can perform computations asynchronously with
CPU computations. The “Pair” time reported by LAMMPS will be the
maximum of the time required to complete the CPU pair style
computations and the time required to complete the GPU pair style
computations. Any time spent for GPU-enabled pair styles for
computations that run simultaneously with <a class="reference internal" href="bond_style.html"><span class="doc">bond</span></a>,
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>.
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
respectively. Or the effect of the “-pk” or “-sf” switches can be
duplicated by adding the <a class="reference internal" href="package.html"><span class="doc">package kokkos</span></a> or <a class="reference internal" href="suffix.html"><span class="doc">suffix kk</span></a> commands respectively to your input script.</p>
<p>Or you can follow these steps:</p>
<p>CPU-only (run all-MPI or with OpenMP threading):</p>
<pre class="literal-block">
cd lammps/src
make yes-kokkos
make g++ KOKKOS_DEVICES=OpenMP
</pre>
<p>Intel Xeon Phi:</p>
<pre class="literal-block">
cd lammps/src
make yes-kokkos
make g++ KOKKOS_DEVICES=OpenMP KOKKOS_ARCH=KNC
</pre>
<p>CPUs and GPUs:</p>
<pre class="literal-block">
cd lammps/src
make yes-kokkos
make cuda KOKKOS_DEVICES=Cuda
</pre>
<p>These examples set the KOKKOS-specific OMP, MIC, CUDA variables on the
make command line which requires a GNU-compatible make command. Try
“gmake” if your system’s standard make complains.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you build using make line variables and re-build LAMMPS twice
with different KOKKOS options and the *same* target, e.g. g++ in the
first two examples above, then you *must* perform a “make clean-all”
or “make clean-machine” before each build. This is to force all the
KOKKOS-dependent files to be re-compiled with the new options.</p>
</div>
<p>You can also hardwire these make variables in the specified machine
makefile, e.g. src/MAKE/Makefile.g++ in the first two examples above,
with a line like:</p>
<pre class="literal-block">
KOKKOS_ARCH = KNC
</pre>
<p>Note that if you build LAMMPS multiple times in this manner, using
different KOKKOS options (defined in different machine makefiles), you
do not have to worry about doing a “clean” in between. This is
because the targets will be different.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The 3rd example above for a GPU, uses a different machine
makefile, in this case src/MAKE/Makefile.cuda, which is included in
the LAMMPS distribution. To build the KOKKOS package for a GPU, this
makefile must use the NVIDA “nvcc” compiler. And it must have a
KOKKOS_ARCH setting that is appropriate for your NVIDIA hardware and
installed software. Typical values for KOKKOS_ARCH are given below,
as well as other settings that must be included in the machine
makefile, if you create your own.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Currently, there are no precision options with the KOKKOS
package. All compilation and computation is performed in double
precision.</p>
</div>
<p>There are other allowed options when building with the KOKKOS package.
As above, they can be set either as variables on the make command line
or in Makefile.machine. This is the full list of options, including
those discussed above, Each takes a value shown below. The
<p>KOKKOS_DEVICE sets the parallelization method used for Kokkos code
(within LAMMPS). KOKKOS_DEVICES=OpenMP means that OpenMP will be
used. KOKKOS_DEVICES=Pthreads means that pthreads will be used.
KOKKOS_DEVICES=Cuda means an NVIDIA GPU running CUDA will be used.</p>
<p>If KOKKOS_DEVICES=Cuda, then the lo-level Makefile in the src/MAKE
directory must use “nvcc” as its compiler, via its CC setting. For
best performance its CCFLAGS setting should use -O3 and have a
KOKKOS_ARCH setting that matches the compute capability of your NVIDIA
hardware and software installation, e.g. KOKKOS_ARCH=Kepler30. Note
the minimal required compute capability is 2.0, but this will give
signicantly reduced performance compared to Kepler generation GPUs
with compute capability 3.x. For the LINK setting, “nvcc” should not
be used; instead use g++ or another compiler suitable for linking C++
applications. Often you will want to use your MPI compiler wrapper
for this setting (i.e. mpicxx). Finally, the lo-level Makefile must
also have a “Compilation rule” for creating *.o files from *.cu files.
See src/Makefile.cuda for an example of a lo-level Makefile with all
of these settings.</p>
<p>KOKKOS_USE_TPLS=hwloc binds threads to hardware cores, so they do not
migrate during a simulation. KOKKOS_USE_TPLS=hwloc should always be
used if running with KOKKOS_DEVICES=Pthreads for pthreads. It is not
necessary for KOKKOS_DEVICES=OpenMP for OpenMP, because OpenMP
provides alternative methods via environment variables for binding
threads to hardware cores. More info on binding threads to cores is
given in <a class="reference internal" href="Section_accelerate.html#acc-3"><span class="std std-ref">this section</span></a>.</p>
<p>KOKKOS_ARCH=KNC enables compiler switches needed when compling for an
Intel Phi processor.</p>
<p>KOKKOS_USE_TPLS=librt enables use of a more accurate timer mechanism
on most Unix platforms. This library is not available on all
platforms.</p>
<p>KOKKOS_DEBUG is only useful when developing a Kokkos-enabled style
within LAMMPS. KOKKOS_DEBUG=yes enables printing of run-time
debugging information that can be useful. It also enables runtime
bounds checking on Kokkos data structures.</p>
<p>KOKKOS_CUDA_OPTIONS are additional options for CUDA.</p>
<p>For more information on Kokkos see the Kokkos programmers’ guide here:
/lib/kokkos/doc/Kokkos_PG.pdf.</p>
<p><strong>Run with the KOKKOS package from the command line:</strong></p>
<p>The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.</p>
<p>When using KOKKOS built with host=OMP, you need to choose how many
OpenMP threads per MPI task will be used (via the “-k” command-line
switch discussed below). Note that the product of MPI tasks * OpenMP
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.</p>
<p>When using the KOKKOS package built with device=CUDA, you must use
exactly one MPI task per physical GPU.</p>
<p>When using the KOKKOS package built with host=MIC for Intel Xeon Phi
coprocessor support you need to insure there are one or more MPI tasks
per coprocessor, and choose the number of coprocessor threads to use
per MPI task (via the “-k” command-line switch discussed below). The
product of MPI tasks * coprocessor threads/task should not exceed the
maximum number of threads the coproprocessor is designed to run,
otherwise performance will suffer. This value is 240 for current
generation Xeon Phi(TM) chips, which is 60 physical cores * 4
threads/core. Note that with the KOKKOS package you do not need to
specify how many Phi coprocessors there are per node; each
coprocessors is simply treated as running some number of MPI tasks.</p>
<p>You must use the “-k on” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a> to enable the KOKKOS package. It
takes additional arguments for hardware settings appropriate to your
system. Those arguments are <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">documented here</span></a>. The two most commonly used
which will automatically append “kk” to styles that support it. Use
the “-pk kokkos” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a> if
you wish to change any of the default <a class="reference internal" href="package.html"><span class="doc">package kokkos</span></a>
optionns set by the “-k on” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>.</p>
<p>Note that the default for the <a class="reference internal" href="package.html"><span class="doc">package kokkos</span></a> command is
to use “full” neighbor lists and set the Newton flag to “off” for both
pairwise and bonded interactions. This typically gives fastest
performance. If the <a class="reference internal" href="newton.html"><span class="doc">newton</span></a> command is used in the input
script, it can override the Newton flag defaults.</p>
<p>However, when running in MPI-only mode with 1 thread per MPI task, it
will typically be faster to use “half” neighbor lists and set the
Newton flag to “on”, just as is the case for non-accelerated pair
styles. You can do this with the “-pk” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>.</p>
<p><strong>Or run with the KOKKOS package by editing an input script:</strong></p>
<p>The discussion above for the mpirun/mpiexec command and setting
appropriate thread and GPU values for host=OMP or host=MIC or
device=CUDA are the same.</p>
<p>You must still use the “-k on” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a> to enable the KOKKOS package, and
specify its additional arguments for hardware options appopriate to
your system, as documented above.</p>
<p>Use the <a class="reference internal" href="suffix.html"><span class="doc">suffix kk</span></a> command, or you can explicitly add a
“kk” suffix to individual styles in your input script, e.g.</p>
<pre class="literal-block">
pair_style lj/cut/kk 2.5
</pre>
<p>You only need to use the <a class="reference internal" href="package.html"><span class="doc">package kokkos</span></a> command if you
wish to change any of its option defaults, as set by the “-k on”
<p>The performance of KOKKOS running in different modes is a function of
your hardware, which KOKKOS-enable styles are used, and the problem
size.</p>
<p>Generally speaking, the following rules of thumb apply:</p>
<ul class="simple">
<li>When running on CPUs only, with a single thread per MPI task,
performance of a KOKKOS style is somewhere between the standard
(un-accelerated) styles (MPI-only mode), and those provided by the
USER-OMP package. However the difference between all 3 is small (less
than 20%).</li>
<li>When running on CPUs only, with multiple threads per MPI task,
performance of a KOKKOS style is a bit slower than the USER-OMP
package.</li>
<li>When running large number of atoms per GPU, KOKKOS is typically faster
than the GPU package.</li>
<li>When running on Intel Xeon Phi, KOKKOS is not as fast as
the USER-INTEL package, which is optimized for that hardware.</li>
</ul>
<p>See the <a class="reference external" href="http://lammps.sandia.gov/bench.html">Benchmark page</a> of the
LAMMPS web site for performance of the KOKKOS package on different
hardware.</p>
<p><strong>Guidelines for best performance:</strong></p>
<p>Here are guidline for using the KOKKOS package on the different
hardware configurations listed above.</p>
<p>Many of the guidelines use the <a class="reference internal" href="package.html"><span class="doc">package kokkos</span></a> command
See its doc page for details and default settings. Experimenting with
its options can provide a speed-up for specific calculations.</p>
<p><strong>Running on a multi-core CPU:</strong></p>
<p>If N is the number of physical cores/node, then the number of MPI
tasks/node * number of threads/task should not exceed N, and should
typically equal N. Note that the default threads/task is 1, as set by
the “t” keyword of the “-k” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>. If you do not change this, no
additional parallelism (beyond MPI) will be invoked on the host
CPU(s).</p>
<p>You can compare the performance running in different modes:</p>
<ul class="simple">
<li>run with 1 MPI task/node and N threads/task</li>
<li>run with N MPI tasks/node and 1 thread/task</li>
<li>run with settings in between these extremes</li>
</ul>
<p>Examples of mpirun commands in these modes are shown above.</p>
<p>When using KOKKOS to perform multi-threading, it is important for
performance to bind both MPI tasks to physical cores, and threads to
physical cores, so they do not migrate during a simulation.</p>
<p>If you are not certain MPI tasks are being bound (check the defaults
for your MPI installation), binding can be forced with these flags:</p>
<p>For binding threads with the KOKKOS OMP option, use thread affinity
environment variables to force binding. With OpenMP 3.1 (gcc 4.7 or
later, intel 12 or later) setting the environment variable
OMP_PROC_BIND=true should be sufficient. For binding threads with the
KOKKOS pthreads option, compile LAMMPS the KOKKOS HWLOC=yes option, as
discussed in <a class="reference internal" href="Section_start.html#start-3-4"><span class="std std-ref">Section 2.3.4</span></a> of the
manual.</p>
<p><strong>Running on GPUs:</strong></p>
<p>Insure the -arch setting in the machine makefile you are using,
e.g. src/MAKE/Makefile.cuda, is correct for your GPU hardware/software
(see <a class="reference internal" href="Section_start.html#start-3-4"><span class="std std-ref">this section</span></a> of the manual for
details).</p>
<p>The -np setting of the mpirun command should set the number of MPI
tasks/node to be equal to the # of physical GPUs on the node.</p>
<p>Use the “-k” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a> to
specify the number of GPUs per node, and the number of threads per MPI
task. As above for multi-core CPUs (and no GPU), if N is the number
of physical cores/node, then the number of MPI tasks/node * number of
threads/task should not exceed N. With one GPU (and one MPI task) it
may be faster to use less than all the available cores, by setting
threads/task to a smaller value. This is because using all the cores
on a dual-socket node will incur extra cost to copy memory from the
2nd socket to the GPU.</p>
<p>Examples of mpirun commands that follow these rules are shown above.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When using a GPU, you will achieve the best performance if your
input script does not use any fix or compute styles which are not yet
Kokkos-enabled. This allows data to stay on the GPU for multiple
timesteps, without being copied back to the host CPU. Invoking a
non-Kokkos fix or compute, or performing I/O for
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo</span></a> or <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> output will cause data
to be copied back to the CPU.</p>
</div>
<p>You cannot yet assign multiple MPI tasks to the same GPU with the
KOKKOS package. We plan to support this in the future, similar to the
GPU package in LAMMPS.</p>
<p>You cannot yet use both the host (multi-threaded) and device (GPU)
together to compute pairwise interactions with the KOKKOS package. We
hope to support this in the future, similar to the GPU package in
LAMMPS.</p>
<p><strong>Running on an Intel Phi:</strong></p>
<p>Kokkos only uses Intel Phi processors in their “native” mode, i.e.
not hosted by a CPU.</p>
<p>As illustrated above, build LAMMPS with OMP=yes (the default) and
MIC=yes. The latter insures code is correctly compiled for the Intel
Phi. The OMP setting means OpenMP will be used for parallelization on
the Phi, which is currently the best option within Kokkos. In the
future, other options may be added.</p>
<p>Current-generation Intel Phi chips have either 61 or 57 cores. One
core should be excluded for running the OS, leaving 60 or 56 cores.
Each core is hyperthreaded, so there are effectively N = 240 (4*60) or
N = 224 (4*56) cores to run on.</p>
<p>The -np setting of the mpirun command sets the number of MPI
tasks/node. The “-k on t Nt” command-line switch sets the number of
threads/task as Nt. The product of these 2 values should be N, i.e.
240 or 224. Also, the number of threads/task should be a multiple of
4 so that logical threads from more than one MPI task do not run on
the same physical core.</p>
<p>Examples of mpirun commands that follow these rules are shown above.</p>
<div class="section" id="restrictions">
<h2>5.3.3.1. Restrictions</h2>
<p>As noted above, if using GPUs, the number of MPI tasks per compute
node should equal to the number of GPUs per compute node. In the
future Kokkos will support assigning multiple MPI tasks to a single
GPU.</p>
<p>Currently Kokkos does not support AMD GPUs due to limits in the
available backend programming models. Specifically, Kokkos requires
extensive C++ support from the Kernel language. This is expected to
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>.
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
<p>Your compiler must support the OpenMP interface. You should have one
or more multi-core CPUs so that multiple threads can be launched by
each MPI task running on a CPU.</p>
<p><strong>Building LAMMPS with the USER-OMP package:</strong></p>
<p>The lines above illustrate how to include/build with the USER-OMP
package in two steps, using the “make” command. Or how to do it with
one command via the src/Make.py script, described in <a class="reference internal" href="Section_start.html#start-4"><span class="std std-ref">Section 2.4</span></a> of the manual. Type “Make.py -h” for
help.</p>
<p>Note that the CCFLAGS and LINKFLAGS settings in Makefile.machine must
include “-fopenmp”. Likewise, if you use an Intel compiler, the
CCFLAGS setting must include “-restrict”. The Make.py command will
add these automatically.</p>
<p><strong>Run with the USER-OMP package from the command line:</strong></p>
<p>The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.</p>
<p>You need to choose how many OpenMP threads per MPI task will be used
by the USER-OMP package. Note that the product of MPI tasks *
threads/task should not exceed the physical number of cores (on a
node), otherwise performance will suffer.</p>
<p>As in the lines above, use the “-sf omp” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>, which will automatically append
“omp” to styles that support it. The “-sf omp” switch also issues a
default <a class="reference internal" href="package.html"><span class="doc">package omp 0</span></a> command, which will set the
number of threads per MPI task via the OMP_NUM_THREADS environment
variable.</p>
<p>You can also use the “-pk omp Nt” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>, to explicitly set Nt = # of OpenMP
threads per MPI task to use, as well as additional options. Its
syntax is the same as the <a class="reference internal" href="package.html"><span class="doc">package omp</span></a> command whose doc
page gives details, including the default values used if it is not
specified. It also gives more details on how to set the number of
threads via the OMP_NUM_THREADS environment variable.</p>
<p><strong>Or run with the USER-OMP package by editing an input script:</strong></p>
<p>The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and threads/MPI task is the same.</p>
<p>Use the <a class="reference internal" href="suffix.html"><span class="doc">suffix omp</span></a> command, or you can explicitly add an
“omp” suffix to individual styles in your input script, e.g.</p>
<pre class="literal-block">
pair_style lj/cut/omp 2.5
</pre>
<p>You must also use the <a class="reference internal" href="package.html"><span class="doc">package omp</span></a> command to enable the
USER-OMP package. When you do this you also specify how many threads
per MPI task to use. The command doc page explains other options and
how to set the number of threads via the OMP_NUM_THREADS environment
variable.</p>
<p><strong>Speed-ups to expect:</strong></p>
<p>Depending on which styles are accelerated, you should look for a
reduction in the “Pair time”, “Bond time”, “KSpace time”, and “Loop
time” values printed at the end of a run.</p>
<p>You may see a small performance advantage (5 to 20%) when running a
USER-OMP style (in serial or parallel) with a single thread per MPI
task, versus running standard LAMMPS with its standard un-accelerated
styles (in serial or all-MPI parallelization with 1 task/core). This
is because many of the USER-OMP styles contain similar optimizations
to those used in the OPT package, described in <a class="reference internal" href="accelerate_opt.html"><span class="doc">Section accelerate 5.3.6</span></a>.</p>
<p>With multiple threads/task, the optimal choice of number of MPI
tasks/node and OpenMP threads/task can vary a lot and should always be
tested via benchmark runs for a specific simulation running on a
specific machine, paying attention to guidelines discussed in the next
sub-section.</p>
<p>A description of the multi-threading strategy used in the USER-OMP
package and some performance examples are <a class="reference external" href="http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1">presented here</a></p>
<p><strong>Guidelines for best performance:</strong></p>
<p>For many problems on current generation CPUs, running the USER-OMP
package with a single thread/task is faster than running with multiple
threads/task. This is because the MPI parallelization in LAMMPS is
often more efficient than multi-threading as implemented in the
USER-OMP package. The parallel efficiency (in a threaded sense) also
varies for different USER-OMP styles.</p>
<p>Using multiple threads/task can be more effective under the following
circumstances:</p>
<ul class="simple">
<li>Individual compute nodes have a significant number of CPU cores but
the CPU itself has limited memory bandwidth, e.g. for Intel Xeon 53xx
(Clovertown) and 54xx (Harpertown) quad-core processors. Running one
MPI task per CPU core will result in significant performance
degradation, so that running with 4 or even only 2 MPI tasks per node
is faster. Running in hybrid MPI+OpenMP mode will reduce the
inter-node communication bandwidth contention in the same way, but
offers an additional speedup by utilizing the otherwise idle CPU
cores.</li>
<li>The interconnect used for MPI communication does not provide
sufficient bandwidth for a large number of MPI tasks per node. For
example, this applies to running over gigabit ethernet or on Cray XT4
or XT5 series supercomputers. As in the aforementioned case, this
effect worsens when using an increasing number of nodes.</li>
<li>The system has a spatially inhomogeneous particle density which does
not map well to the <a class="reference internal" href="processors.html"><span class="doc">domain decomposition scheme</span></a> or
<a class="reference internal" href="balance.html"><span class="doc">load-balancing</span></a> options that LAMMPS provides. This is
because multi-threading achives parallelism over the number of
particles, not via their distribution in space.</li>
<li>A machine is being used in “capability mode”, i.e. near the point
where MPI parallelism is maxed out. For example, this can happen when
using the <a class="reference internal" href="kspace_style.html"><span class="doc">PPPM solver</span></a> for long-range
electrostatics on large numbers of nodes. The scaling of the KSpace
calculation (see the <a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style</span></a> command) becomes
the performance-limiting factor. Using multi-threading allows less
MPI tasks to be invoked and can speed-up the long-range solver, while
increasing overall performance by parallelizing the pairwise and
bonded calculations via OpenMP. Likewise additional speedup can be
sometimes be achived by increasing the length of the Coulombic cutoff
and thus reducing the work done by the long-range solver. Using the
<a class="reference internal" href="run_style.html"><span class="doc">run_style verlet/split</span></a> command, which is compatible
with the USER-OMP package, is an alternative way to reduce the number
of MPI tasks assigned to the KSpace calculation.</li>
</ul>
<p>Additional performance tips are as follows:</p>
<ul class="simple">
<li>The best parallel efficiency from <em>omp</em> styles is typically achieved
when there is at least one MPI task per physical CPU chip, i.e. socket
or die.</li>
<li>It is usually most efficient to restrict threading to a single
socket, i.e. use one or more MPI task per socket.</li>
<li>NOTE: By default, several current MPI implementations use a processor
affinity setting that restricts each MPI task to a single CPU core.
Using multi-threading in this mode will force all threads to share the
one core and thus is likely to be counterproductive. Instead, binding
MPI tasks to a (multi-core) socket, should solve this issue.</li>
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>.
<li class="toctree-l2"><a class="reference internal" href="Section_accelerate.html#comparison-of-various-accelerator-packages">5.4. Comparison of various accelerator packages</a></li>
<p><strong>Building LAMMPS with the OPT package:</strong></p>
<p>The lines above illustrate how to build LAMMPS with the OPT package in
two steps, using the “make” command. Or how to do it with one command
via the src/Make.py script, described in <a class="reference internal" href="Section_start.html#start-4"><span class="std std-ref">Section 2.4</span></a> of the manual. Type “Make.py -h” for
help.</p>
<p>Note that if you use an Intel compiler to build with the OPT package,
the CCFLAGS setting in your Makefile.machine must include “-restrict”.
The Make.py command will add this automatically.</p>
<p><strong>Run with the OPT package from the command line:</strong></p>
<p>As in the lines above, use the “-sf opt” <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">command-line switch</span></a>, which will automatically append
“opt” to styles that support it.</p>
<p><strong>Or run with the OPT package by editing an input script:</strong></p>
<p>Use the <a class="reference internal" href="suffix.html"><span class="doc">suffix opt</span></a> command, or you can explicitly add an
“opt” suffix to individual styles in your input script, e.g.</p>
<pre class="literal-block">
pair_style lj/cut/opt 2.5
</pre>
<p><strong>Speed-ups to expect:</strong></p>
<p>You should see a reduction in the “Pair time” value printed at the end
of a run. On most machines for reasonable problem sizes, it will be a
5 to 20% savings.</p>
<p><strong>Guidelines for best performance:</strong></p>
<p>Just try out an OPT pair style to see how it performs.</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>.
<li>style = <em>linear</em> or <em>spline</em> = method of interpolation</li>
<li>N = use N values in table</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
angle_style table linear 1000
angle_coeff 3 file.table ENTRY1
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Style <em>table</em> creates interpolation tables of length <em>N</em> from angle
potential and derivative values listed in a file(s) as a function of
angle The files are read by the <a class="reference internal" href="angle_coeff.html"><span class="doc">angle_coeff</span></a>
command.</p>
<p>The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and derivative values at each of
<em>N</em> angles. During a simulation, these tables are used to interpolate
energy and force values on individual atoms as needed. The
interpolation is done in one of 2 styles: <em>linear</em> or <em>spline</em>.</p>
<p>For the <em>linear</em> style, the angle is used to find 2 surrounding table
values from which an energy or its derivative is computed by linear
interpolation.</p>
<p>For the <em>spline</em> style, a cubic spline coefficients are computed and
stored at each of the <em>N</em> values in the table. The angle is used to
find the appropriate set of coefficients which are used to evaluate a
cubic polynomial which computes the energy or derivative.</p>
<p>The following coefficients must be defined for each angle type via the
<a class="reference internal" href="angle_coeff.html"><span class="doc">angle_coeff</span></a> command as in the example above.</p>
<ul class="simple">
<li>filename</li>
<li>keyword</li>
</ul>
<p>The filename specifies a file containing tabulated energy and
derivative values. The keyword specifies a section of the file. The
format of this file is described below.</p>
<hr class="docutils" />
<p>The format of a tabulated file is as follows (without the
parenthesized comments):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Angle potential for harmonic (one or more comment or blank lines)</span>
<p>A section begins with a non-blank line whose 1st character is not a
“#”; blank lines or lines starting with “#” can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
<a class="reference internal" href="angle_coeff.html"><span class="doc">angle_coeff</span></a> command. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.</p>
<p>The parameter “N” is required and its value is the number of table
entries that follow. Note that this may be different than the <em>N</em>
specified in the <a class="reference internal" href="angle_style.html"><span class="doc">angle_style table</span></a> command. Let
Ntable = <em>N</em> in the angle_style command, and Nfile = “N” in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and derivative
values at Ntable different points. The resulting tables of length
Ntable are then used as described above, when computing energy and
force for individual angles and their atoms. This means that if you
want the interpolation tables of length Ntable to match exactly what
is in the tabulated file (with effectively no preliminary
interpolation), you should set Ntable = Nfile.</p>
<p>The “FP” parameter is optional. If used, it is followed by two values
fplo and fphi, which are the 2nd derivatives at the innermost and
outermost angle settings. These values are needed by the spline
construction routines. If not specified by the “FP” parameter, they
are estimated (less accurately) by the first two and last two
derivative values in the table.</p>
<p>The “EQ” parameter is also optional. If used, it is followed by a the
equilibrium angle value, which is used, for example, by the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> command. If not used, the equilibrium angle is
set to 180.0.</p>
<p>Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
the angle value (in degrees), the 3rd value is the energy (in energy
units), and the 4th is -dE/d(theta) (also in energy units). The 3rd
term is the energy of the 3-atom configuration for the specified
angle. The last term is the derivative of the energy with respect to
the angle (in degrees, not radians). Thus the units of the last term
are still energy, not force. The angle values must increase from one
line to the next. The angle values must also begin with 0.0 and end
with 180.0, i.e. span the full range of possible angles.</p>
<p>Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This angle style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info on packages.</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>.
<li><p class="first">style = <em>angle</em> or <em>atomic</em> or <em>body</em> or <em>bond</em> or <em>charge</em> or <em>dipole</em> or <em>dpd</em> or <em>electron</em> or <em>ellipsoid</em> or <em>full</em> or <em>line</em> or <em>meso</em> or <em>molecular</em> or <em>peri</em> or <em>smd</em> or <em>sphere</em> or <em>tri</em> or <em>template</em> or <em>hybrid</em></p>
<pre class="literal-block">
args = none for any style except the following
<em>body</em> args = bstyle bstyle-args
bstyle = style of body particles
bstyle-args = additional arguments specific to the bstyle
see the <a class="reference internal" href="body.html"><span class="doc">body</span></a> doc page for details
<em>template</em> args = template-ID
template-ID = ID of molecule template specified in a separate <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command
<em>hybrid</em> args = list of one or more sub-styles, each with their args
</pre>
</li>
<li><p class="first">accelerated styles (with same args) = <em>angle/kk</em> or <em>atomic/kk</em> or <em>bond/kk</em> or <em>charge/kk</em> or <em>full/kk</em> or <em>molecular/kk</em></p>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
atom_style atomic
atom_style bond
atom_style full
atom_style body nparticle 2 10
atom_style hybrid charge bond
atom_style hybrid charge body nparticle 2 5
atom_style template myMols
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define what style of atoms to use in a simulation. This determines
what attributes are associated with the atoms. This command must be
used before a simulation is setup via a <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a>,
<p class="last">It is possible to add some attributes, such as a molecule ID, to
atom styles that do not have them via the <a class="reference internal" href="fix_property_atom.html"><span class="doc">fix property/atom</span></a> command. This command also
allows new custom attributes consisting of extra integer or
floating-point values to be added to atoms. See the <a class="reference internal" href="fix_property_atom.html"><span class="doc">fix property/atom</span></a> doc page for examples of cases
where this is useful and details on how to initialize, access, and
output the custom values.</p>
</div>
<p>All of the above styles define point particles, except the <em>sphere</em>,
<em>ellipsoid</em>, <em>electron</em>, <em>peri</em>, <em>wavepacket</em>, <em>line</em>, <em>tri</em>, and
<em>body</em> styles, which define finite-size particles. See <a class="reference internal" href="Section_howto.html#howto-14"><span class="std std-ref">Section 6.14</span></a> for an overview of using finite-size
particle models with LAMMPS.</p>
<p>All of the point-particle styles assign mass to particles on a
per-type basis, using the <a class="reference internal" href="mass.html"><span class="doc">mass</span></a> command, The finite-size
particle styles assign mass to individual particles on a per-particle
basis.</p>
<p>For the <em>sphere</em> style, the particles are spheres and each stores a
per-particle diameter and mass. If the diameter > 0.0, the particle
is a finite-size sphere. If the diameter = 0.0, it is a point
particle.</p>
<p>For the <em>ellipsoid</em> style, the particles are ellipsoids and each
stores a flag which indicates whether it is a finite-size ellipsoid or
a point particle. If it is an ellipsoid, it also stores a shape
vector with the 3 diamters of the ellipsoid and a quaternion 4-vector
with its orientation.</p>
<p>For the <em>dipole</em> style, a point dipole is defined for each point
particle. Note that if you wish the particles to be finite-size
spheres as in a Stockmayer potential for a dipolar fluid, so that the
particles can rotate due to dipole-dipole interactions, then you need
to use atom_style hybrid sphere dipole, which will assign both a
diameter and dipole moment to each particle.</p>
<p>For the <em>electron</em> style, the particles representing electrons are 3d
Gaussians with a specified position and bandwidth or uncertainty in
position, which is represented by the eradius = electron size.</p>
<p>For the <em>peri</em> style, the particles are spherical and each stores a
per-particle mass and volume.</p>
<p>The <em>dpd</em> style is for dissipative particle dynamics (DPD) particles.
Note that it is part of the USER-DPD package, and is not for use with
the <a class="reference internal" href="pair_dpd.html"><span class="doc">pair_style dpd or dpd/stat</span></a> commands, which can
simply use atom_style atomic. Atom_style dpd extends DPD particle
properties with internal temperature (dpdTheta), internal conductive
energy (uCond), internal mechanical energy (uMech), and internal
chemical energy (uChem).</p>
<p>The <em>meso</em> style is for smoothed particle hydrodynamics (SPH)
particles which store a density (rho), energy (e), and heat capacity
(cv).</p>
<p>The <em>smd</em> style is for a general formulation of Smooth Particle
Hydrodynamics. Both fluids and solids can be modeled. Particles
store the mass and volume of an integration point, a kernel diameter
used for calculating the field variables (e.g. stress and deformation)
and a contact radius for calculating repulsive forces which prevent
individual physical bodies from penetretating each other.</p>
<p>The <em>wavepacket</em> style is similar to <em>electron</em>, but the electrons may
consist of several Gaussian wave packets, summed up with coefficients
cs= (cs_re,cs_im). Each of the wave packets is treated as a separate
particle in LAMMPS, wave packets belonging to the same electron must
have identical <em>etag</em> values.</p>
<p>For the <em>line</em> style, the particles are idealized line segments and
each stores a per-particle mass and length and orientation (i.e. the
end points of the line segment).</p>
<p>For the <em>tri</em> style, the particles are planar triangles and each
stores a per-particle mass and size and orientation (i.e. the corner
points of the triangle).</p>
<p>The <em>template</em> style allows molecular topolgy (bonds,angles,etc) to be
defined via a molecule template using the <a class="reference external" href="molecule.txt">molecule</a>
command. The template stores one or more molecules with a single copy
of the topology info (bonds,angles,etc) of each. Individual atoms
only store a template index and template atom to identify which
molecule and which atom-within-the-molecule they represent. Using the
<em>template</em> style instead of the <em>bond</em>, <em>angle</em>, <em>molecular</em> styles
can save memory for systems comprised of a large number of small
molecules, all of a single type (or small number of types). See the
paper by Grime and Voth, in <a class="reference internal" href="#grime"><span class="std std-ref">(Grime)</span></a>, for examples of how this
can be advantageous for large-scale coarse-grained systems.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When using the <em>template</em> style with a <a class="reference internal" href="molecule.html"><span class="doc">molecule template</span></a> that contains multiple molecules, you should
insure the atom types, bond types, angle_types, etc in all the
molecules are consistent. E.g. if one molecule represents H2O and
another CO2, then you probably do not want each molecule file to
define 2 atom types and a single bond type, because they will conflict
with each other when a mixture system of H2O and CO2 molecules is
defined, e.g. by the <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command. Rather the
H2O molecule should define atom types 1 and 2, and bond type 1. And
the CO2 molecule should define atom types 3 and 4 (or atom types 3 and
2 if a single oxygen type is desired), and bond type 2.</p>
</div>
<p>For the <em>body</em> style, the particles are arbitrary bodies with internal
attributes defined by the “style” of the bodies, which is specified by
the <em>bstyle</em> argument. Body particles can represent complex entities,
such as surface meshes of discrete points, collections of
sub-particles, deformable objects, etc.</p>
<p>The <a class="reference internal" href="body.html"><span class="doc">body</span></a> doc page descibes the body styles LAMMPS
currently supports, and provides more details as to the kind of body
particles they represent. For all styles, each body particle stores
moments of inertia and a quaternion 4-vector, so that its orientation
and position can be time integrated due to forces and torques.</p>
<p>Note that there may be additional arguments required along with the
<em>bstyle</em> specification, in the atom_style body command. These
arguments are described in the <a class="reference internal" href="body.html"><span class="doc">body</span></a> doc page.</p>
<hr class="docutils" />
<p>Typically, simulations require only a single (non-hybrid) atom style.
If some atoms in the simulation do not have all the properties defined
by a particular style, use the simplest style that defines all the
needed properties by any atom. For example, if some atoms in a
simulation are charged, but others are not, use the <em>charge</em> style.
If some atoms have bonds, but others do not, use the <em>bond</em> style.</p>
<p>The only scenario where the <em>hybrid</em> style is needed is if there is no
single style which defines all needed properties of all atoms. For
example, as mentioned above, if you want dipolar particles which will
rotate due to torque, you need to use “atom_style hybrid sphere
dipole”. When a hybrid style is used, atoms store and communicate the
union of all quantities implied by the individual styles.</p>
<p>When using the <em>hybrid</em> style, you cannot combine the <em>template</em> style
with another molecular style that stores bond,angle,etc info on a
per-atom basis.</p>
<p>LAMMPS can be extended with new atom styles as well as new body
styles; see <a class="reference internal" href="Section_modify.html"><span class="doc">this section</span></a>.</p>
<hr class="docutils" />
<p>Styles with a <em>kk</em> suffix are functionally the same as the
corresponding style without the suffix. They have been optimized to
run faster, depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>Note that other acceleration packages in LAMMPS, specifically the GPU,
USER-INTEL, USER-OMP, and OPT packages do not use accelerated atom
styles.</p>
<p>The accelerated styles are part of the KOKKOS package. They are only
enabled if LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command cannot be used after the simulation box is defined by a
<p>Many of the styles listed above are only enabled if LAMMPS was built
with a specific package, as listed below. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The <em>angle</em>, <em>bond</em>, <em>full</em>, <em>molecular</em>, and <em>template</em> styles are
part of the MOLECULE package.</p>
<p>The <em>line</em> and <em>tri</em> styles are part of the ASPHERE package.</p>
<p>The <em>body</em> style is part of the BODY package.</p>
<p>The <em>dipole</em> style is part of the DIPOLE package.</p>
<p>The <em>peri</em> style is part of the PERI package for Peridynamics.</p>
<p>The <em>electron</em> style is part of the USER-EFF package for <a class="reference internal" href="pair_eff.html"><span class="doc">electronic force fields</span></a>.</p>
<p>The <em>dpd</em> style is part of the USER-DPD package for dissipative
particle dynamics (DPD).</p>
<p>The <em>meso</em> style is part of the USER-SPH package for smoothed particle
hydrodyanmics (SPH). See <a class="reference external" href="USER/sph/SPH_LAMMPS_userguide.pdf">this PDF guide</a> to using SPH in LAMMPS.</p>
<p>The <em>wavepacket</em> style is part of the USER-AWPMD package for the
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>.
<p>This doc page is not about a LAMMPS input script command, but about
body particles, which are generalized finite-size particles.
Individual body particles can represent complex entities, such as
surface meshes of discrete points, collections of sub-particles,
deformable objects, etc. Note that other kinds of finite-size
spherical and aspherical particles are also supported by LAMMPS, such
as spheres, ellipsoids, line segments, and triangles, but they are
simpler entities that body particles. See <a class="reference internal" href="Section_howto.html#howto-14"><span class="std std-ref">Section 6.14</span></a> for a general overview of all
these particle types.</p>
<p>Body particles are used via the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a>
command. It takes a body style as an argument. The current body
styles supported by LAMMPS are as follows. The name in the first
column is used as the <em>bstyle</em> argument for the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a> command.</p>
<p>The body style determines what attributes are stored for each body and
thus how they can be used to compute pairwise body/body or
bond/non-body (point particle) interactions. More details of each
style are described below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The rounded/polygon style listed in the table above and
described below has not yet been relesed in LAMMPS. It will be soon.</p>
</div>
<p>We hope to add more styles in the future. See <a class="reference internal" href="Section_modify.html#mod-12"><span class="std std-ref">Section 10.12</span></a> for details on how to add a new body
style to the code.</p>
<hr class="docutils" />
<p><strong>When to use body particles:</strong></p>
<p>You should not use body particles to model a rigid body made of
simpler particles (e.g. point, sphere, ellipsoid, line segment,
triangular particles), if the interaction between pairs of rigid
bodies is just the summation of pairwise interactions between the
simpler particles. LAMMPS already supports this kind of model via the
<a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command. Any of the numerous pair styles
that compute interactions between simpler particles can be used. The
<a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command time integrates the motion of the
rigid bodies. All of the standard LAMMPS commands for thermostatting,
adding constraints, performing output, etc will operate as expected on
the simple particles.</p>
<p>By contrast, when body particles are used, LAMMPS treats an entire
body as a single particle for purposes of computing pairwise
interactions, building neighbor lists, migrating particles between
processors, outputting particles to a dump file, etc. This means that
interactions between pairs of bodies or between a body and non-body
(point) particle need to be encoded in an appropriate pair style. If
such a pair style were to mimic the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> model,
it would need to loop over the entire collection of interactions
between pairs of simple particles within the two bodies, each time a
single body/body interaction was computed.</p>
<p>Thus it only makes sense to use body particles and develop such a pair
style, when particle/particle interactions are more complex than what
the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command can already calculate. For
example, if particles have one or more of the following attributes:</p>
<ul class="simple">
<li>represented by a surface mesh</li>
<li>represented by a collection of geometric entities (e.g. planes + spheres)</li>
<li>deformable</li>
<li>internal stress that induces fragmentation</li>
</ul>
<p>then the interaction between pairs of particles is likely to be more
complex than the summation of simple sub-particle interactions. An
example is contact or frictional forces between particles with planar
sufaces that inter-penetrate.</p>
<p>These are additional LAMMPS commands that can be used with body
<p>These values are the current position of the vertex within the
simulation domain, not a displacement from the center-of-mass (COM) of
the body particle itself. These values are calculated using the
current COM and orientation of the body particle.</p>
<p>For images created by the <a class="reference internal" href="dump_image.html"><span class="doc">dump image</span></a> command, if the
<em>body</em> keyword is set, then each body particle is drawn as a convex
polygon consisting of N line segments. Note that the line segments
are drawn between the N vertices, which does not correspond exactly to
the physical extent of the body (because the <a class="reference external" href="pair_body_rounded_polygon.cpp">pair_style rounded/polygon</a> defines finite-size
spheres at those point and the line segments between the spheres are
tangent to the spheres). The drawn diameter of each line segment is
determined by the <em>bflag1</em> parameter for the <em>body</em> keyword. The
<em>bflag2</em> argument is ignored.</p>
<hr class="docutils" />
<p id="fraige"><strong>(Fraige)</strong> F. Y. Fraige, P. A. Langston, A. J. Matchett, J. Dodds,
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>.
<li>style = <em>linear</em> or <em>spline</em> = method of interpolation</li>
<li>N = use N values in table</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
bond_style table linear 1000
bond_coeff 1 file.table ENTRY1
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Style <em>table</em> creates interpolation tables of length <em>N</em> from bond
potential and force values listed in a file(s) as a function of bond
length. The files are read by the <a class="reference internal" href="bond_coeff.html"><span class="doc">bond_coeff</span></a>
command.</p>
<p>The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and force values at each of <em>N</em>
distances. During a simulation, these tables are used to interpolate
energy and force values as needed. The interpolation is done in one
of 2 styles: <em>linear</em> or <em>spline</em>.</p>
<p>For the <em>linear</em> style, the bond length is used to find 2 surrounding
table values from which an energy or force is computed by linear
interpolation.</p>
<p>For the <em>spline</em> style, a cubic spline coefficients are computed and
stored at each of the <em>N</em> values in the table. The bond length is
used to find the appropriate set of coefficients which are used to
evaluate a cubic polynomial which computes the energy or force.</p>
<p>The following coefficients must be defined for each bond type via the
<a class="reference internal" href="bond_coeff.html"><span class="doc">bond_coeff</span></a> command as in the example above.</p>
<ul class="simple">
<li>filename</li>
<li>keyword</li>
</ul>
<p>The filename specifies a file containing tabulated energy and force
values. The keyword specifies a section of the file. The format of
this file is described below.</p>
<hr class="docutils" />
<p>The format of a tabulated file is as follows (without the
parenthesized comments):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Bond potential for harmonic (one or more comment or blank lines)</span>
<p>A section begins with a non-blank line whose 1st character is not a
“#”; blank lines or lines starting with “#” can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
<a class="reference internal" href="bond_coeff.html"><span class="doc">bond_coeff</span></a> command. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.</p>
<p>The parameter “N” is required and its value is the number of table
entries that follow. Note that this may be different than the <em>N</em>
specified in the <a class="reference internal" href="bond_style.html"><span class="doc">bond_style table</span></a> command. Let
Ntable = <em>N</em> in the bond_style command, and Nfile = “N” in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and force
values at Ntable different points. The resulting tables of length
Ntable are then used as described above, when computing energy and
force for individual bond lengths. This means that if you want the
interpolation tables of length Ntable to match exactly what is in the
tabulated file (with effectively no preliminary interpolation), you
should set Ntable = Nfile.</p>
<p>The “FP” parameter is optional. If used, it is followed by two values
fplo and fphi, which are the derivatives of the force at the innermost
and outermost bond lengths. These values are needed by the spline
construction routines. If not specified by the “FP” parameter, they
are estimated (less accurately) by the first two and last two force
values in the table.</p>
<p>The “EQ” parameter is also optional. If used, it is followed by a the
equilibrium bond length, which is used, for example, by the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> command. If not used, the equilibrium bond
length is to the distance in the table with the lowest potential energy.</p>
<p>Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
the bond length r (in distance units), the 3rd value is the energy (in
energy units), and the 4th is the force (in force units). The bond
lengths must range from a LO value to a HI value, and increase from
one line to the next. If the actual bond length is ever smaller than
the LO value or larger than the HI value, then the bond energy and
force is evaluated as if the bond were the LO or HI length.</p>
<p>Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This bond style can only be used if LAMMPS was built with the
MOLECULE package (which it is by default). See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info on packages.</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>.
<p>The style <em>p</em> means the box is periodic, so that particles interact
across the boundary, and they can exit one end of the box and re-enter
the other end. A periodic dimension can change in size due to
constant pressure boundary conditions or box deformation (see the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> and <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> commands). The <em>p</em>
style must be applied to both faces of a dimension.</p>
<p>The styles <em>f</em>, <em>s</em>, and <em>m</em> mean the box is non-periodic, so that
particles do not interact across the boundary and do not move from one
side of the box to the other.</p>
<p>For style <em>f</em>, the position of the face is fixed. If an atom moves
outside the face it will be deleted on the next timestep that
reneighboring occurs. This will typically generate an error unless
you have set the <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify lost</span></a> option to
allow for lost atoms.</p>
<p>For style <em>s</em>, the position of the face is set so as to encompass the
atoms in that dimension (shrink-wrapping), no matter how far they
move. Note that when the difference between the current box dimensions
and the shrink-wrap box dimensions is large, this can lead to lost
atoms at the beginning of a run when running in parallel. This is due
to the large change in the (global) box dimensions also causing
significant changes in the individual sub-domain sizes. If these
changes are farther than the communication cutoff, atoms will be lost.
This is best addressed by setting initial box dimensions to match the
shrink-wrapped dimensions more closely, by using <em>m</em> style boundaries
(see below).</p>
<p>For style <em>m</em>, shrink-wrapping occurs, but is bounded by the value
specified in the data or restart file or set by the
<a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command. For example, if the upper z
face has a value of 50.0 in the data file, the face will always be
positioned at 50.0 or above, even if the maximum z-extent of all the
atoms becomes less than 50.0. This can be useful if you start a
simulation with an empty box or if you wish to leave room on one side
of the box, e.g. for atoms to evaporate from a surface.</p>
<p>For triclinic (non-orthogonal) simulation boxes, if the 2nd dimension
of a tilt factor (e.g. y for xy) is periodic, then the periodicity is
enforced with the tilt factor offset. If the 1st dimension is
shrink-wrapped, then the shrink wrapping is applied to the tilted box
face, to encompass the atoms. E.g. for a positive xy tilt, the xlo
and xhi faces of the box are planes tilting in the +y direction as y
increases. These tilted planes are shrink-wrapped around the atoms to
determine the x extent of the box.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">Section 6.12</span></a> of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command cannot be used after the simulation box is defined by a
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> or <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command or
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command. See the
<a class="reference internal" href="change_box.html"><span class="doc">change_box</span></a> command for how to change the simulation
box boundaries after it has been defined.</p>
<p>For 2d simulations, the z dimension must be periodic.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands</h2>
<p>See the <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify</span></a> command for a discussion
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>.
<li><p class="first">group-ID = ID of group of atoms to (optionally) displace</p>
</li>
<li><p class="first">one or more parameter/arg pairs may be appended</p>
<pre class="literal-block">
parameter = <em>x</em> or <em>y</em> or <em>z</em> or <em>xy</em> or <em>xz</em> or <em>yz</em> or <em>boundary</em> or <em>ortho</em> or <em>triclinic</em> or <em>set</em> or <em>remap</em>
<p>The size and shape of the initial simulation box are specified by the
<a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> or <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> or
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command used to setup the simulation.
The size and shape may be altered by subsequent runs, e.g. by use of
the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> or <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> commands.
The <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a>, <a class="reference internal" href="read_data.html"><span class="doc">read data</span></a>, and
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> commands also determine whether the
simulation box is orthogonal or triclinic and their doc pages explain
the meaning of the xy,xz,yz tilt factors.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">Section 6.12</span></a> of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.</p>
<p>The keywords used in this command are applied sequentially to the
simulation box and the atoms in it, in the order specified.</p>
<p>Before the sequence of keywords are invoked, the current box
size/shape is stored, in case a <em>remap</em> keyword is used to map the
atom coordinates from a previously stored box size/shape to the
current one.</p>
<p>After all the keywords have been processed, any shrink-wrap boundary
conditions are invoked (see the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command)
which may change simulation box boundaries, and atoms are migrated to
new owning processors.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This means that you cannot use the change_box command to enlarge
a shrink-wrapped box, e.g. to make room to insert more atoms via the
<a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> command, because the simulation box
will be re-shrink-wrapped before the change_box command completes.
Instead you could do something like this, assuming the simulation box
is non-periodic and atoms extend from 0 to 20 in all dimensions:</p>
</div>
<pre class="literal-block">
change_box all x final -10 20
create_atoms 1 single -5 5 5 # this will fail to insert an atom
</pre>
<pre class="literal-block">
change_box all x final -10 20 boundary f s s
create_atoms 1 single -5 5 5
change_box boundary s s s # this will work
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unlike the earlier “displace_box” version of this command, atom
remapping is NOT performed by default. This command allows remapping
to be done in a more general way, exactly when you specify it (zero or
more times) in the sequence of transformations. Thus if you do not
use the <em>remap</em> keyword, atom coordinates will not be changed even if
the box size/shape changes. If a uniformly strained state is desired,
the <em>remap</em> keyword should be specified.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is possible to lose atoms with this command. E.g. by
changing the box without remapping the atoms, and having atoms end up
outside of non-periodic boundaries. It is also possible to alter
bonds between atoms straddling a boundary in bad ways. E.g. by
converting a boundary from periodic to non-periodic. It is also
possible when remapping atoms to put them (nearly) on top of each
other. E.g. by converting a boundary from non-periodic to periodic.
All of these will typically lead to bad dynamics and/or generate error
messages.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The simulation box size/shape can be changed by arbitrarily
large amounts by this command. This is not a problem, except that the
mapping of processors to the simulation box is not changed from its
initial 3d configuration; see the <a class="reference internal" href="processors.html"><span class="doc">processors</span></a>
command. Thus, if the box size/shape changes dramatically, the
mapping of processors to the simulation box may not end up as optimal
as the initial mapping attempted to be.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because the keywords used in this command are applied one at a
time to the simulation box and the atoms in it, care must be taken
with triclinic cells to avoid exceeding the limits on skew after each
transformation in the sequence. If skew is exceeded before the final
transformation this can be avoided by changing the order of the
sequence, or breaking the transformation into two or more smaller
transformations. For more information on the allowed limits for box
skew see the discussion on triclinic boxes on <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">this page</span></a>.</p>
</div>
<hr class="docutils" />
<p>For the <em>x</em>, <em>y</em>, and <em>z</em> parameters, this is the meaning of their
styles and values.</p>
<p>For style <em>final</em>, the final lo and hi box boundaries of a dimension
are specified. The values can be in lattice or box distance units.
See the discussion of the units keyword below.</p>
<p>For style <em>delta</em>, plus or minus changes in the lo/hi box boundaries
of a dimension are specified. The values can be in lattice or box
distance units. See the discussion of the units keyword below.</p>
<p>For style <em>scale</em>, a multiplicative factor to apply to the box length
of a dimension is specified. For example, if the initial box length
is 10, and the factor is 1.1, then the final box length will be 11. A
factor less than 1.0 means compression.</p>
<p>The <em>volume</em> style changes the specified dimension in such a way that
the overall box volume remains constant with respect to the operation
performed by the preceding keyword. The <em>volume</em> style can only be
used following a keyword that changed the volume, which is any of the
<em>x</em>, <em>y</em>, <em>z</em> keywords. If the preceding keyword “key” had a <em>volume</em>
style, then both it and the current keyword apply to the keyword
preceding “key”. I.e. this sequence of keywords is allowed:</p>
<pre class="literal-block">
change_box all x scale 1.1 y volume z volume
</pre>
<p>The <em>volume</em> style changes the associated dimension so that the
overall box volume is unchanged relative to its value before the
preceding keyword was invoked.</p>
<p>If the following command is used, then the z box length will shrink by
the same 1.1 factor the x box length was increased by:</p>
<pre class="literal-block">
change_box all x scale 1.1 z volume
</pre>
<p>If the following command is used, then the y,z box lengths will each
shrink by sqrt(1.1) to keep the volume constant. In this case, the
y,z box lengths shrink so as to keep their relative aspect ratio
constant:</p>
<pre class="literal-block">
change_box all"x scale 1.1 y volume z volume
</pre>
<p>If the following command is used, then the final box will be a factor
of 10% larger in x and y, and a factor of 21% smaller in z, so as to
keep the volume constant:</p>
<pre class="literal-block">
change_box all x scale 1.1 z volume y scale 1.1 z volume
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For solids or liquids, when one dimension of the box is
expanded, it may be physically undesirable to hold the other 2 box
lengths constant since that implies a density change. For solids,
adjusting the other dimensions via the <em>volume</em> style may make
physical sense (just as for a liquid), but may not be correct for
materials and potentials whose Poisson ratio is not 0.5.</p>
</div>
<p>For the <em>scale</em> and <em>volume</em> styles, the box length is expanded or
compressed around its mid point.</p>
<hr class="docutils" />
<p>For the <em>xy</em>, <em>xz</em>, and <em>yz</em> parameters, this is the meaning of their
styles and values. Note that changing the tilt factors of a triclinic
box does not change its volume.</p>
<p>For style <em>final</em>, the final tilt factor is specified. The value
can be in lattice or box distance units. See the discussion of the
units keyword below.</p>
<p>For style <em>delta</em>, a plus or minus change in the tilt factor is
specified. The value can be in lattice or box distance units. See
the discussion of the units keyword below.</p>
<p>All of these styles change the xy, xz, yz tilt factors. In LAMMPS,
tilt factors (xy,xz,yz) for triclinic boxes are required to be no more
than half the distance of the parallel box length. For example, if
xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt
factor must be between -5 and 5. Similarly, both xz and yz must be
between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a
limitation, since if the maximum tilt factor is 5 (as in this
example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
... are all equivalent. Any tilt factor specified by this command
must be within these limits.</p>
<hr class="docutils" />
<p>The <em>boundary</em> keyword takes arguments that have exactly the same
meaning as they do for the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command. In each
dimension, a single letter assigns the same style to both the lower
and upper face of the box. Two letters assigns the first style to the
lower face and the second style to the upper face.</p>
<p>The style <em>p</em> means the box is periodic; the other styles mean
non-periodic. For style <em>f</em>, the position of the face is fixed. For
style <em>s</em>, the position of the face is set so as to encompass the
atoms in that dimension (shrink-wrapping), no matter how far they
move. For style <em>m</em>, shrink-wrapping occurs, but is bounded by the
current box edge in that dimension, so that the box will become no
smaller. See the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command for more
explanation of these style options.</p>
<p>Note that the “boundary” command itself can only be used before the
simulation box is defined via a <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> or
command. This command allows the boundary conditions to be changed
later in your input script. Also note that the
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> will change boundary conditions to
match what is stored in the restart file. So if you wish to change
them, you should use the change_box command after the read_restart
command.</p>
<hr class="docutils" />
<p>The <em>ortho</em> and <em>triclinic</em> keywords convert the simulation box to be
orthogonal or triclinic (non-orthongonal). See <a class="reference internal" href="Section_howto.html#howto-13"><span class="std std-ref">this section</span></a> for a discussion of how non-orthongal
boxes are represented in LAMMPS.</p>
<p>The simulation box is defined as either orthogonal or triclinic when
it is created via the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a>,
<p>These keywords allow you to toggle the existing simulation box from
orthogonal to triclinic and vice versa. For example, an initial
equilibration simulation can be run in an orthogonal box, the box can
be toggled to triclinic, and then a <a class="reference internal" href="Section_howto.html#howto-13"><span class="std std-ref">non-equilibrium MD (NEMD) simulation</span></a> can be run with deformation
via the <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> command.</p>
<p>If the simulation box is currently triclinic and has non-zero tilt in
xy, yz, or xz, then it cannot be converted to an orthogonal box.</p>
<hr class="docutils" />
<p>The <em>set</em> keyword saves the current box size/shape. This can be
useful if you wish to use the <em>remap</em> keyword more than once or if you
wish it to be applied to an intermediate box size/shape in a sequence
of keyword operations. Note that the box size/shape is saved before
any of the keywords are processed, i.e. the box size/shape at the time
the create_box command is encountered in the input script.</p>
<p>The <em>remap</em> keyword remaps atom coordinates from the last saved box
size/shape to the current box state. For example, if you stretch the
box in the x dimension or tilt it in the xy plane via the <em>x</em> and <em>xy</em>
keywords, then the <em>remap</em> commmand will dilate or tilt the atoms to
conform to the new box size/shape, as if the atoms moved with the box
as it deformed.</p>
<p>Note that this operation is performed without regard to periodic
boundaries. Also, any shrink-wrapping of non-periodic boundaries (see
the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command) occurs after all keywords,
including this one, have been processed.</p>
<p>Only atoms in the specified group are remapped.</p>
<hr class="docutils" />
<p>The <em>units</em> keyword determines the meaning of the distance units used
to define various arguments. A <em>box</em> value selects standard distance
units as defined by the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for
units = real or metal. A <em>lattice</em> value means the distance units are
in lattice spacings. The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have
been previously used to define the lattice spacing.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>If you use the <em>ortho</em> or <em>triclinic</em> keywords, then at the point in
the input script when this command is issued, no <a class="reference internal" href="dump.html"><span class="doc">dumps</span></a> can
be active, nor can a <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> be active. This is
because these commands test whether the simulation box is orthogonal
when they are first issued. Note that these commands can be used in
your script before a change_box command is issued, so long as an
<a class="reference internal" href="undump.html"><span class="doc">undump</span></a> or <a class="reference internal" href="unfix.html"><span class="doc">unfix</span></a> command is also used to
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>.
<p>Defines a computation that calculates the local lattice structure
according to the formulation given in <a class="reference internal" href="#ackland"><span class="std std-ref">(Ackland)</span></a>.</p>
<p>In contrast to the <a class="reference internal" href="compute_centro_atom.html"><span class="doc">centro-symmetry parameter</span></a> this method is stable against
temperature boost, because it is based not on the distance between
particles but the angles. Therefore statistical fluctuations are
averaged out a little more. A comparison with the Common Neighbor
Analysis metric is made in the paper.</p>
<p>The result is a number which is mapped to the following different
lattice structures:</p>
<ul class="simple">
<li>0 = UNKNOWN</li>
<li>1 = BCC</li>
<li>2 = FCC</li>
<li>3 = HCP</li>
<li>4 = ICO</li>
</ul>
<p>The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of
which computes this quantity.-</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The per-atom vector values will be unitless since they are the
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>.
<p>Define a computation that calculates the angular momemtum of multiple
chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the 3 components of the angular momentum
vector for each chunk, due to the velocity/momentum of the individual
atoms in the chunk around the center-of-mass of the chunk. The
calculation includes all effects due to atoms passing thru periodic
boundaries.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The coordinates of an atom contribute to the chunk’s angular
momentum in “unwrapped” form, by using the image flags associated with
each atom. See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command for a discussion
of “unwrapped” coordinates. See the Atoms section of the
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<p>The simplest way to output the results of the compute angmom/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
3 for the 3 xyz components of the angular momentum for each chunk.
These values can be accessed by any command that uses global array
values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
<p>Defines a computation that calculates the hexagonal close-packed “c”
lattice vector for each atom in the group. It does this by
calculating the normal unit vector to the basal plane for each atom.
The results enable efficient identification and characterization of
twins and grains in hexagonal close-packed structures.</p>
<p>The output of the compute is thus the 3 components of a unit vector
associdate with each atom. The components are set to 0.0 for
atoms not in the group.</p>
<p>Details of the calculation are given in <a class="reference internal" href="#barrett"><span class="std std-ref">(Barrett)</span></a>.</p>
<p>The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently or to have multiple compute/dump commands, each of
which computes this quantity.</p>
<p>An example input script that uses this compute is provided
in examples/USER/misc/basal.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom array with 3 columns, which can be
accessed by indices 1-3 by any command that uses per-atom values from
a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The per-atom vector values are unitless since the 3 columns represent
components of a unit vector.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The output of this compute will be meaningless unless the atoms are on
(or near) hcp lattice sites, since the calculation assumes a
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>.
<p>Define a computation that calculates properties of individual body
sub-particles. The number of datums generated, aggregated across all
processors, equals the number of body sub-particles plus the number of
non-body particles in the system, modified by the group parameter as
explained below. See <a class="reference internal" href="Section_howto.html#howto-14"><span class="std std-ref">Section 6.14</span></a>
of the manual and the <a class="reference internal" href="body.html"><span class="doc">body</span></a> doc page for more details on
using body particles.</p>
<p>The local data stored by this command is generated by looping over all
the atoms. An atom will only be included if it is in the group. If
the atom is a body particle, then its N sub-particles will be looped
over, and it will contribute N datums to the count of datums. If it
is not a body particle, it will contribute 1 datum.</p>
<p>For both body particles and non-body particles, the <em>id</em> keyword
will store the ID of the particle.</p>
<p>For both body particles and non-body particles, the <em>type</em> keyword
will store the type of the particle.</p>
<p>The <em>integer</em> keywords mean different things for body and non-body
particles. If the atom is not a body particle, only its <em>x</em>, <em>y</em>, <em>z</em>
coordinates can be referenced, using the <em>integer</em> keywords 1,2,3.
Note that this means that if you want to access more fields than this
for body particles, then you cannot include non-body particles in the
group.</p>
<p>For a body particle, the <em>integer</em> keywords refer to fields calculated
by the body style for each sub-particle. The body style, as specified
by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a>, determines how many fields
exist and what they are. See the <a class="reference internal" href="body.html"><span class="doc">body</span></a> doc page for
details of the different styles.</p>
<p>Here is an example of how to output body information using the <a class="reference internal" href="dump.html"><span class="doc">dump local</span></a> command with this compute. If fields 1,2,3 for the
body sub-particles are x,y,z coordinates, then the dump file will be
formatted similar to the output of a <a class="reference internal" href="dump.html"><span class="doc">dump atom or custom</span></a>
command.</p>
<pre class="literal-block">
compute 1 all body/local type 1 2 3
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_1[4]
</pre>
<p><strong>Output info:</strong></p>
<p>This compute calculates a local vector or local array depending on the
number of keywords. The length of the vector or number of rows in the
array is the number of datums as described above. If a single keyword
is specified, a local vector is produced. If two or more keywords are
specified, a local array is produced where the number of columns = the
number of keywords. The vector or array can be accessed by any
command that uses local values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options.</p>
<p>The <a class="reference internal" href="units.html"><span class="doc">units</span></a> for output values depend on the body style.</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>.
<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</p>
</li>
<li><p class="first">chunk/atom = style name of this compute command</p>
<pre class="literal-block">
style = <em>bin/1d</em> or <em>bin/2d</em> or <em>bin/3d</em> or <em>bin/sphere</em> or <em>type</em> or <em>molecule</em> or <em>compute/fix/variable</em>
<em>bin/1d</em> args = dim origin delta
dim = <em>x</em> or <em>y</em> or <em>z</em>
origin = <em>lower</em> or <em>center</em> or <em>upper</em> or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
<em>bin/2d</em> args = dim origin delta dim origin delta
dim = <em>x</em> or <em>y</em> or <em>z</em>
origin = <em>lower</em> or <em>center</em> or <em>upper</em> or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
<em>bin/3d</em> args = dim origin delta dim origin delta dim origin delta
dim = <em>x</em> or <em>y</em> or <em>z</em>
origin = <em>lower</em> or <em>center</em> or <em>upper</em> or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
dim = <em>x</em> or <em>y</em> or <em>z</em> = axis of cylinder axis
origin = <em>lower</em> or <em>center</em> or <em>upper</em> or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
crmin,crmax = bin from cylinder radius rmin to rmax (distance units)
ncbin = # of concentric circle bins between rmin and rmax
<em>type</em> args = none
<em>molecule</em> args = none
<em>compute/fix/variable</em> = c_ID, c_ID[I], f_ID, f_ID[I], v_name with no args
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
</pre>
</li>
<li><p class="first">zero or more keyword/values pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>region</em> or <em>nchunk</em> or <em>static</em> or <em>compress</em> or <em>bound</em> or <em>discard</em> or <em>pbc</em> or <em>units</em></p>
<pre class="literal-block">
<em>region</em> value = region-ID
region-ID = ID of region atoms must be in to be part of a chunk
<em>nchunk</em> value = <em>once</em> or <em>every</em>
once = only compute the number of chunks once
every = re-compute the number of chunks whenever invoked
<em>limit</em> values = 0 or Nc max or Nc exact
0 = no limit on the number of chunks
Nc max = limit number of chunks to be <= Nc
Nc exact = set number of chunks to exactly Nc
<em>ids</em> value = <em>once</em> or <em>nfreq</em> or <em>every</em>
once = assign chunk IDs to atoms only once, they persist thereafter
nfreq = assign chunk IDs to atoms only once every Nfreq steps (if invoked by <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> which sets Nfreq)
every = assign chunk IDs to atoms whenever invoked
<em>compress</em> value = <em>yes</em> or <em>no</em>
yes = compress chunk IDs to eliminate IDs with no atoms
no = do not compress chunk IDs even if some IDs have no atoms
<em>discard</em> value = <em>yes</em> or <em>no</em> or <em>mixed</em>
yes = discard atoms with out-of-range chunk IDs by assigning a chunk ID = 0
no = keep atoms with out-of-range chunk IDs by assigning a valid chunk ID
mixed = keep or discard such atoms according to spatial binning rule
<em>bound</em> values = x/y/z lo hi
x/y/z = <em>x</em> or <em>y</em> or <em>z</em> to bound sptial bins in this dimension
lo = <em>lower</em> or coordinate value (distance units)
hi = <em>upper</em> or coordinate value (distance units)
<em>pbc</em> value = <em>no</em> or <em>yes</em>
yes = use periodic distance for bin/sphere and bin/cylinder styles
<em>units</em> value = <em>box</em> or <em>lattice</em> or <em>reduced</em>
<p>Define a computation that calculates an integer chunk ID from 1 to
Nchunk for each atom in the group. Values of chunk IDs are determined
by the <em>style</em> of chunk, which can be based on atom type or molecule
ID or spatial binning or a per-atom property or value calculated by
another <a class="reference internal" href="compute.html"><span class="doc">compute</span></a>, <a class="reference internal" href="fix.html"><span class="doc">fix</span></a>, or <a class="reference internal" href="variable.html"><span class="doc">atom-style variable</span></a>. Per-atom chunk IDs can be used by other
computes with “chunk” in their style name, such as <a class="reference internal" href="compute_com_chunk.html"><span class="doc">compute com/chunk</span></a> or <a class="reference internal" href="compute_msd_chunk.html"><span class="doc">compute msd/chunk</span></a>. Or they can be used by the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command to sum and time average a
variety of per-atom properties over the atoms in each chunk. Or they
can simply be accessed by any command that uses per-atom values from a
compute as input, as discussed in <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a>.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for an overview of
how this compute can be used with a variety of other commands to
tabulate properties of a simulation. The howto section gives several
examples of input script commands that can be used to calculate
interesting properties.</p>
<p>Conceptually it is important to realize that this compute does two
simple things. First, it sets the value of <em>Nchunk</em> = the number of
chunks, which can be a constant value or change over time. Second, it
assigns each atom to a chunk via a chunk ID. Chunk IDs range from 1
to <em>Nchunk</em> inclusive; some chunks may have no atoms assigned to them.
Atoms that do not belong to any chunk are assigned a value of 0. Note
that the two operations are not always performed together. For
example, spatial bins can be setup once (which sets <em>Nchunk</em>), and
atoms assigned to those bins many times thereafter (setting their
chunk IDs).</p>
<p>All other commands in LAMMPS that use chunk IDs assume there are
<em>Nchunk</em> number of chunks, and that every atom is assigned to one of
those chunks, or not assigned to any chunk.</p>
<p>There are many options for specifying for how and when <em>Nchunk</em> is
calculated, and how and when chunk IDs are assigned to atoms. The
details depend on the chunk <em>style</em> and its <em>args</em>, as well as
optional keyword settings. They can also depend on whether a <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command is using this compute, since
that command requires <em>Nchunk</em> to remain static across windows of
timesteps it specifies, while it accumulates per-chunk averages.</p>
<p>The details are described below.</p>
<p>The different chunk styles operate as follows. For each style, how it
calculates <em>Nchunk</em> and assigns chunk IDs to atoms is explained. Note
that using the optional keywords can change both of those actions, as
described further below where the keywords are discussed.</p>
<hr class="docutils" />
<p>The <em>binning</em> styles perform a spatial binning of atoms, and assign an
atom the chunk ID corresponding to the bin number it is in. <em>Nchunk</em>
is set to the number of bins, which can change if the simulation box
size changes.</p>
<p>The <em>bin/1d</em>, <em>bin/2d</em>, and <em>bin/3d</em> styles define bins as 1d layers
(slabs), 2d pencils, or 3d boxes. The <em>dim</em>, <em>origin</em>, and <em>delta</em>
settings are specified 1, 2, or 3 times. For 2d or 3d bins, there is
no restriction on specifying dim = x before dim = y or z, or dim = y
before dim = z. Bins in a particular <em>dim</em> have a bin size in that
dimension given by <em>delta</em>. In each dimension, bins are defined
relative to a specified <em>origin</em>, which may be the lower/upper edge of
the simulation box (in that dimension), or its center point, or a
specified coordinate value. Starting at the origin, sufficient bins
are created in both directions to completely span the simulation box
or the bounds specified by the optional <em>bounds</em> keyword.</p>
<p>For orthogonal simulation boxes, the bins are layers, pencils, or
boxes aligned with the xyz coordinate axes. For triclinic
(non-orthogonal) simulation boxes, the bin faces are parallel to the
tilted faces of the simulation box. See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">this section</span></a> of the manual for a discussion of
the geometry of triclinic boxes in LAMMPS. As described there, a
tilted simulation box has edge vectors a,b,c. In that nomenclature,
bins in the x dimension have faces with normals in the “b” cross “c”
direction. Bins in y have faces normal to the “a” cross “c”
direction. And bins in z have faces normal to the “a” cross “b”
direction. Note that in order to define the size and position of
these bins in an unambiguous fashion, the <em>units</em> option must be set
to <em>reduced</em> when using a triclinic simulation box, as noted below.</p>
<p>The meaning of <em>origin</em> and <em>delta</em> for triclinic boxes is as follows.
Consider a triclinic box with bins that are 1d layers or slabs in the
x dimension. No matter how the box is tilted, an <em>origin</em> of 0.0
means start layers at the lower “b” cross “c” plane of the simulation
box and an <em>origin</em> of 1.0 means to start layers at the upper “b”
cross “c” face of the box. A <em>delta</em> value of 0.1 in <em>reduced</em> units
means there will be 10 layers from 0.0 to 1.0, regardless of the
current size or shape of the simulation box.</p>
<p>The <em>bin/sphere</em> style defines a set of spherical shell bins around
the origin (<em>xorig</em>,<em>yorig</em>,<em>zorig</em>), using <em>nsbin</em> bins with radii
equally spaced between <em>srmin</em> and <em>srmax</em>. This is effectively a 1d
vector of bins. For example, if <em>srmin</em> = 1.0 and <em>srmax</em> = 10.0 and
<em>nsbin</em> = 9, then the first bin spans 1.0 < r < 2.0, and the last bin
spans 9.0 < r 10.0. The geometry of the bins is the same whether the
simulation box is orthogonal or triclinic; i.e. the spherical shells
are not tilted or scaled differently in different dimensions to
transform them into ellipsoidal shells.</p>
<p>The <em>bin/cylinder</em> style defines bins for a cylinder oriented along
the axis <em>dim</em> with the axis coordinates in the other two radial
dimensions at (<em>c1</em>,<em>c2</em>). For dim = x, c1/c2 = y/z; for dim = y,
c1/c2 = x/z; for dim = z, c1/c2 = x/y. This is effectively a 2d array
of bins. The first dimension is along the cylinder axis, the second
dimension is radially outward from the cylinder axis. The bin size
and positions along the cylinder axis are specified by the <em>origin</em>
and <em>delta</em> values, the same as for the <em>bin/1d</em>, <em>bin/2d</em>, and
<em>bin/3d</em> styles. There are <em>ncbin</em> concentric circle bins in the
radial direction from the cylinder axis with radii equally spaced
between <em>crmin</em> and <em>crmax</em>. For example, if <em>crmin</em> = 1.0 and
<em>crmax</em> = 10.0 and <em>ncbin</em> = 9, then the first bin spans 1.0 < r <
2.0, and the last bin spans 9.0 < r 10.0. The geometry of the bins in
the radial dimensions is the same whether the simulation box is
orthogonal or triclinic; i.e. the concetric circles are not tilted or
scaled differently in the two different dimensions to transform them
into ellipses.</p>
<p>The created bins (and hence the chunk IDs) are numbered consecutively
from 1 to the number of bins = <em>Nchunk</em>. For <em>bin2d</em> and <em>bin3d</em>, the
numbering varies most rapidly in the first dimension (which could be
x, y, or z), next rapidly in the 2nd dimension, and most slowly in the
3rd dimension. For <em>bin/sphere</em>, the bin with smallest radii is chunk
1 and the bni with largest radii is chunk Nchunk = <em>ncbin</em>. For
<em>bin/cylinder</em>, the numbering varies most rapidly in the dimension
along the cylinder axis and most slowly in the radial direction.</p>
<p>Each time this compute is invoked, each atom is mapped to a bin based
on its current position. Note that between reneighboring timesteps,
atoms can move outside the current simulation box. If the box is
periodic (in that dimension) the atom is remapping into the periodic
box for purposes of binning. If the box in not periodic, the atom may
have moved outside the bounds of all bins. If an atom is not inside
any bin, the <em>discard</em> keyword is used to determine how a chunk ID is
assigned to the atom.</p>
<hr class="docutils" />
<p>The <em>type</em> style uses the atom type as the chunk ID. <em>Nchunk</em> is set
to the number of atom types defined for the simulation, e.g. via the
<p>The <em>molecule</em> style uses the molecule ID of each atom as its chunk
ID. <em>Nchunk</em> is set to the largest chunk ID. Note that this excludes
molecule IDs for atoms which are not in the specified group or
optional region.</p>
<p>There is no requirement that all atoms in a particular molecule are
assigned the same chunk ID (zero or non-zero), though you probably
want that to be the case, if you wish to compute a per-molecule
property. LAMMPS will issue a warning if that is not the case, but
only the first time that <em>Nchunk</em> is calculated.</p>
<p>Note that atoms with a molecule ID = 0, which may be non-molecular
solvent atoms, have an out-of-range chunk ID. These atoms are
discarded (not assigned to any chunk) or assigned to <em>Nchunk</em>,
depending on the value of the <em>discard</em> keyword.</p>
<hr class="docutils" />
<p>The <em>compute/fix/variable</em> styles set the chunk ID of each atom based
on a quantity calculated and stored by a compute, fix, or variable.
In each case, it must be a per-atom quantity. In each case the
referenced floating point values are converted to an integer chunk ID
as follows. The floating point value is truncated (rounded down) to
an integer value. If the integer value is <= 0, then a chunk ID of 0
is assigned to the atom. If the integer value is > 0, it becomes the
chunk ID to the atom. <em>Nchunk</em> is set to the largest chunk ID. Note
that this excludes atoms which are not in the specified group or
optional region.</p>
<p>If the style begins with “c_”, a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If the style begins with “f_”, a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with the
timestep on which this compute accesses the fix, else an error
results. Users can also write code for their own fix styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If a value begins with “v_”, a variable name for an <em>atom</em> or
<em>atomfile</em> style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> must follow which has been
previously defined in the input script. Variables of style <em>atom</em> can
reference thermodynamic keywords and various per-atom attributes, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of generating per-atom quantities to
treat as a chunk ID.</p>
<p>Normally, <em>Nchunk</em> = the number of chunks, is re-calculated every time
this fix is invoked, though the value may or may not change. As
explained below, the <em>nchunk</em> keyword can be set to <em>once</em> which means
<em>Nchunk</em> will never change.</p>
<p>If a <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command uses this compute, it
can also turn off the re-calculation of <em>Nchunk</em> for one or more
windows of timesteps. The extent of the windows, during which Nchunk
is held constant, are determined by the <em>Nevery</em>, <em>Nrepeat</em>, <em>Nfreq</em>
values and the <em>ave</em> keyword setting that are used by the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command.</p>
<p>Specifically, if <em>ave</em> = <em>one</em>, then for each span of <em>Nfreq</em>
timesteps, <em>Nchunk</em> is held constant between the first timestep when
averaging is done (within the Nfreq-length window), and the last
timestep when averaging is done (multiple of Nfreq). If <em>ave</em> =
<em>running</em> or <em>window</em>, then <em>Nchunk</em> is held constant forever,
starting on the first timestep when the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command invokes this compute.</p>
<p>Note that multiple <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> commands can use
the same compute chunk/atom compute. However, the time windows they
induce for holding <em>Nchunk</em> constant must be identical, else an error
will be generated.</p>
<p>The various optional keywords operate as follows. Note that some of
them function differently or are ignored by different chunk styles.
Some of them also have different default values, depending on
the chunk style, as listed below.</p>
<p>The <em>region</em> keyword applies to all chunk styles. If used, an atom
must be in both the specified group and the specified geometric
<a class="reference internal" href="region.html"><span class="doc">region</span></a> to be assigned to a chunk.</p>
<hr class="docutils" />
<p>The <em>nchunk</em> keyword applies to all chunk styles. It specifies how
often <em>Nchunk</em> is recalculated, which in turn can affect the chunk IDs
assigned to individual atoms.</p>
<p>If <em>nchunk</em> is set to <em>once</em>, then <em>Nchunk</em> is only calculated once,
the first time this compute is invoked. If <em>nchunk</em> is set to
<em>every</em>, then <em>Nchunk</em> is re-calculated every time the compute is
invoked. Note that, as described above, the use of this compute
by the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command can override
the <em>every</em> setting.</p>
<p>The default values for <em>nchunk</em> are listed below and depend on the
chunk style and other system and keyword settings. They attempt to
represent typical use cases for the various chunk styles. The
<em>nchunk</em> value can always be set explicitly if desired.</p>
<hr class="docutils" />
<p>The <em>limit</em> keyword can be used to limit the calculated value of
<em>Nchunk</em> = the number of chunks. The limit is applied each time
<em>Nchunk</em> is calculated, which also limits the chunk IDs assigned to
any atom. The <em>limit</em> keyword is used by all chunk styles except the
<em>binning</em> styles, which ignore it. This is because the number of bins
can be tailored using the <em>bound</em> keyword (described below) which
effectively limits the size of <em>Nchunk</em>.</p>
<p>If <em>limit</em> is set to <em>Nc</em> = 0, then no limit is imposed on <em>Nchunk</em>,
though the <em>compress</em> keyword can still be used to reduce <em>Nchunk</em>, as
described below.</p>
<p>If <em>Nc</em> > 0, then the effect of the <em>limit</em> keyword depends on whether
the <em>compress</em> keyword is also used with a setting of <em>yes</em>, and
whether the <em>compress</em> keyword is specified before the <em>limit</em> keyword
or after.</p>
<p>In all cases, <em>Nchunk</em> is first calculated in the usual way for each
chunk style, as described above.</p>
<p>First, here is what occurs if <em>compress yes</em> is not set. If <em>limit</em>
is set to <em>Nc max</em>, then <em>Nchunk</em> is reset to the smaller of <em>Nchunk</em>
and <em>Nc</em>. If <em>limit</em> is set to <em>Nc exact</em>, then <em>Nchunk</em> is reset to
<em>Nc</em>, whether the original <em>Nchunk</em> was larger or smaller than <em>Nc</em>.
If <em>Nchunk</em> shrank due to the <em>limit</em> setting, then atom chunk IDs >
<em>Nchunk</em> will be reset to 0 or <em>Nchunk</em>, depending on the setting of
the <em>discard</em> keyword. If <em>Nchunk</em> grew, there will simply be some
chunks with no atoms assigned to them.</p>
<p>If <em>compress yes</em> is set, and the <em>compress</em> keyword comes before the
<em>limit</em> keyword, the compression operation is performed first, as
described below, which resets <em>Nchunk</em>. The <em>limit</em> keyword is then
applied to the new <em>Nchunk</em> value, exactly as described in the
preceeding paragraph. Note that in this case, all atoms will end up
with chunk IDs <= <em>Nc</em>, but their original values (e.g. molecule ID or
compute/fix/variable value) may have been > <em>Nc</em>, because of the
compression operation.</p>
<p>If <em>compress yes</em> is set, and the <em>compress</em> keyword comes after the
<em>limit</em> keyword, then the <em>limit</em> value of <em>Nc</em> is applied first to
the uncompressed value of <em>Nchunk</em>, but only if <em>Nc</em> < <em>Nchunk</em>
(whether <em>Nc max</em> or <em>Nc exact</em> is used). This effectively means all
atoms with chunk IDs > <em>Nc</em> have their chunk IDs reset to 0 or <em>Nc</em>,
depending on the setting of the <em>discard</em> keyword. The compression
operation is then performed, which may shrink <em>Nchunk</em> further. If
the new <em>Nchunk</em> < <em>Nc</em> and <em>limit</em> = <em>Nc exact</em> is specified, then
<em>Nchunk</em> is reset to <em>Nc</em>, which results in extra chunks with no atoms
assigned to them. Note that in this case, all atoms will end up with
chunk IDs <= <em>Nc</em>, and their original values (e.g. molecule ID or
compute/fix/variable value) will also have been <= <em>Nc</em>.</p>
<hr class="docutils" />
<p>The <em>ids</em> keyword applies to all chunk styles. If the setting is
<em>once</em> then the chunk IDs assigned to atoms the first time this
compute is invoked will be permanent, and never be re-computed.</p>
<p>If the setting is <em>nfreq</em> and if a <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a>
command is using this compute, then in each of the <em>Nchunk</em> = constant
time windows (discussed above), the chunk ID’s assigned to atoms on
the first step of the time window will persist until the end of the
time window.</p>
<p>If the setting is <em>every</em>, which is the default, then chunk IDs are
re-calculated on any timestep this compute is invoked.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the persistent chunk-IDs calculated by this compute
to be continuous when running from a <a class="reference internal" href="read_restart.html"><span class="doc">restart file</span></a>,
then you should use the same ID for this compute, as in the original
run. This is so that the fix this compute creates to store per-atom
quantities will also have the same ID, and thus be initialized
correctly with chunk IDs from the restart file.</p>
</div>
<hr class="docutils" />
<p>The <em>compress</em> keyword applies to all chunk styles and affects how
<em>Nchunk</em> is calculated, which in turn affects the chunk IDs assigned
to each atom. It is useful for converting a “sparse” set of chunk IDs
(with many IDs that have no atoms assigned to them), into a “dense”
set of IDs, where every chunk has one or more atoms assigned to it.</p>
<p>Two possible use cases are as follows. If a large simulation box is
mostly empty space, then the <em>binning</em> style may produce many bins
with no atoms. If <em>compress</em> is set to <em>yes</em>, only bins with atoms
will be contribute to <em>Nchunk</em>. Likewise, the <em>molecule</em> or
<em>compute/fix/variable</em> styles may produce large <em>Nchunk</em> values. For
example, the <a class="reference internal" href="compute_cluster_atom.html"><span class="doc">compute cluster/atom</span></a> command
assigns every atom an atom ID for one of the atoms it is clustered
with. For a million-atom system with 5 clusters, there would only be
5 unique chunk IDs, but the largest chunk ID might be 1 million,
resulting in <em>Nchunk</em> = 1 million. If <em>compress</em> is set to <em>yes</em>,
<em>Nchunk</em> will be reset to 5.</p>
<p>If <em>compress</em> is set to <em>no</em>, which is the default, no compression is
done. If it is set to <em>yes</em>, all chunk IDs with no atoms are removed
from the list of chunk IDs, and the list is sorted. The remaining
chunk IDs are renumbered from 1 to <em>Nchunk</em> where <em>Nchunk</em> is the new
length of the list. The chunk IDs assigned to each atom reflect
the new renumbering from 1 to <em>Nchunk</em>.</p>
<p>The original chunk IDs (before renumbering) can be accessed by the
<a class="reference internal" href="compute_property_chunk.html"><span class="doc">compute property/chunk</span></a> command and its
<em>id</em> keyword, or by the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command
which outputs the original IDs as one of the columns in its global
output array. For example, using the “compute cluster/atom” command
discussed above, the original 5 unique chunk IDs might be atom IDs
(27,4982,58374,857838,1000000). After compresion, these will be
renumbered to (1,2,3,4,5). The original values (27,...,1000000) can
be output to a file by the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> command,
or by using the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a> command in
conjunction with the <a class="reference internal" href="compute_property_chunk.html"><span class="doc">compute property/chunk</span></a> command.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The compression operation requires global communication across
all processors to share their chunk ID values. It can require large
memory on every processor to store them, even after they are
compressed, if there are are a large number of unique chunk IDs with
atoms assigned to them. It uses a STL map to find unique chunk IDs
and store them in sorted order. Each time an atom is assigned a
compressed chunk ID, it must access the STL map. All of this means
that compression can be expensive, both in memory and CPU time. The
use of the <em>limit</em> keyword in conjunction with the <em>compress</em> keyword
can affect these costs, depending on which keyword is used first. So
use this option with care.</p>
</div>
<hr class="docutils" />
<p>The <em>discard</em> keyword applies to all chunk styles. It affects what
chunk IDs are assigned to atoms that do not match one of the valid
chunk IDs from 1 to <em>Nchunk</em>. Note that it does not apply to atoms
that are not in the specified group or optionally specified region.
Those atoms are always assigned a chunk ID = 0.</p>
<p>If the calculated chunk ID for an atom is not within the range 1 to
<em>Nchunk</em> then it is a “discard” atom. Note that <em>Nchunk</em> may have
been shrunk by the <em>limit</em> keyword. Or the <em>compress</em> keyword may
have eliminated chunk IDs that were valid before the compression took
place, and are now not in the compressed list. Also note that for the
<em>molecule</em> chunk style, if new molecules are added to the system,
their chunk IDs may exceed a previously calculated <em>Nchunk</em>.
Likewise, evaluation of a compute/fix/variable on a later timestep may
return chunk IDs that are invalid for the previously calculated
<em>Nchunk</em>.</p>
<p>All the chunk styles except the <em>binning</em> styles, must use <em>discard</em>
set to either <em>yes</em> or <em>no</em>. If <em>discard</em> is set to <em>yes</em>, which is
the default, then every “discard” atom has its chunk ID set to 0. If
<em>discard</em> is set to <em>no</em>, every “discard” atom has its chunk ID set to
<em>Nchunk</em>. I.e. it becomes part of the last chunk.</p>
<p>The <em>binning</em> styles use the <em>discard</em> keyword to decide whether to
discard atoms outside the spatial domain covered by bins, or to assign
them to the bin they are nearest to.</p>
<p>For the <em>bin/1d</em>, <em>bin/2d</em>, <em>bin/3d</em> styles the details are as
follows. If <em>discard</em> is set to <em>yes</em>, an out-of-domain atom will
have its chunk ID set to 0. If <em>discard</em> is set to <em>no</em>, the atom
will have its chunk ID set to the first or last bin in that dimension.
If <em>discard</em> is set to <em>mixed</em>, which is the default, it will only
have its chunk ID set to the first or last bin if bins extend to the
simulation box boundary in that dimension. This is the case if the
<em>bound</em> keyword settings are <em>lower</em> and <em>upper</em>, which is the
default. If the <em>bound</em> keyword settings are numeric values, then the
atom will have its chunk ID set to 0 if it is outside the bounds of
any bin. Note that in this case, it is possible that the first or
last bin extends beyond the numeric <em>bounds</em> settings, depending on
the specified <em>origin</em>. If this is the case, the chunk ID of the atom
is only set to 0 if it is outside the first or last bin, not if it is
simply outside the numeric <em>bounds</em> setting.</p>
<p>For the <em>bin/sphere</em> style the details are as follows. If <em>discard</em>
is set to <em>yes</em>, an out-of-domain atom will have its chunk ID set to
0. If <em>discard</em> is set to <em>no</em> or <em>mixed</em>, the atom will have its
chunk ID set to the first or last bin, i.e. the innermost or outermost
spherical shell. If the distance of the atom from the origin is less
than <em>rmin</em>, it will be assigned to the first bin. If the distance of
the atom from the origin is greater than <em>rmax</em>, it will be assigned
to the last bin.</p>
<p>For the <em>bin/cylinder</em> style the details are as follows. If <em>discard</em>
is set to <em>yes</em>, an out-of-domain atom will have its chunk ID set to
0. If <em>discard</em> is set to <em>no</em>, the atom will have its chunk ID set
to the first or last bin in both the radial and axis dimensions. If
<em>discard</em> is set to <em>mixed</em>, which is the default, the the radial
dimension is treated the same as for <em>discard</em> = no. But for the axis
dimensinon, it will only have its chunk ID set to the first or last
bin if bins extend to the simulation box boundary in the axis
dimension. This is the case if the <em>bound</em> keyword settings are
<em>lower</em> and <em>upper</em>, which is the default. If the <em>bound</em> keyword
settings are numeric values, then the atom will have its chunk ID set
to 0 if it is outside the bounds of any bin. Note that in this case,
it is possible that the first or last bin extends beyond the numeric
<em>bounds</em> settings, depending on the specified <em>origin</em>. If this is
the case, the chunk ID of the atom is only set to 0 if it is outside
the first or last bin, not if it is simply outside the numeric
<em>bounds</em> setting.</p>
<p>If <em>discard</em> is set to <em>no</em> or <em>mixed</em>, the atom will have its
chunk ID set to the first or last bin, i.e. the innermost or outermost
spherical shell. If the distance of the atom from the origin is less
than <em>rmin</em>, it will be assigned to the first bin. If the distance of
the atom from the origin is greater than <em>rmax</em>, it will be assigned
to the last bin.</p>
<hr class="docutils" />
<p>The <em>bound</em> keyword only applies to the <em>bin/1d</em>, <em>bin/2d</em>, <em>bin/3d</em>
styles and to the axis dimension of the <em>bin/cylinder</em> style;
otherwise it is ignored. It can be used one or more times to limit
the extent of bin coverage in a specified dimension, i.e. to only bin
a portion of the box. If the <em>lo</em> setting is <em>lower</em> or the <em>hi</em>
setting is <em>upper</em>, the bin extent in that direction extends to the
box boundary. If a numeric value is used for <em>lo</em> and/or <em>hi</em>, then
the bin extent in the <em>lo</em> or <em>hi</em> direction extends only to that
value, which is assumed to be inside (or at least near) the simulation
box boundaries, though LAMMPS does not check for this. Note that
using the <em>bound</em> keyword typically reduces the total number of bins
and thus the number of chunks <em>Nchunk</em>.</p>
<p>The <em>pbc</em> keyword only applies to the <em>bin/sphere</em> and <em>bin/cylinder</em>
styles. If set to <em>yes</em>, the distance an atom is from the sphere
origin or cylinder axis is calculated in a minimum image sense with
respect to periodic dimensions, when determining which bin the atom is
in. I.e. if x is a periodic dimension and the distance between the
atom and the sphere center in the x dimension is greater than 0.5 *
simulation box length in x, then a box length is subtracted to give a
distance < 0.5 * simulation box length. This allosws the sphere or
cylinder center to be near a box edge, and atoms on the other side of
the periodic box will still be close to the center point/axis. Note
that with a setting of <em>yes</em>, the outer sphere or cylinder radius must
also be <= 0.5 * simulation box length in any periodic dimension
except for the cylinder axis dimension, or an error is generated.</p>
<p>The <em>units</em> keyword only applies to the <em>binning</em> styles; otherwise it
is ignored. For the <em>bin/1d</em>, <em>bin/2d</em>, <em>bin/3d</em> styles, it
determines the meaning of the distance units used for the bin sizes
<em>delta</em> and for <em>origin</em> and <em>bounds</em> values if they are coordinate
values. For the <em>bin/sphere</em> style it determines the meaning of the
distance units used for <em>xorig</em>,<em>yorig</em>,<em>zorig</em> and the radii <em>srmin</em>
and <em>srmax</em>. For the <em>bin/cylinder</em> style it determines the meaning
of the distance units used for <em>delta</em>,<em>c1</em>,<em>c2</em> and the radii <em>crmin</em>
and <em>crmax</em>.</p>
<p>For orthogonal simulation boxes, any of the 3 options may
be used. For non-orthogonal (triclinic) simulation boxes, only the
<em>reduced</em> option may be used.</p>
<p>A <em>box</em> value selects standard distance units as defined by the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or metal.
A <em>lattice</em> value means the distance units are in lattice spacings.
The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have been previously used to
define the lattice spacing. A <em>reduced</em> value means normalized
unitless values between 0 and 1, which represent the lower and upper
faces of the simulation box respectively. Thus an <em>origin</em> value of
0.5 means the center of the box in any dimension. A <em>delta</em> value of
0.1 means 10 bins span the box in that dimension.</p>
<p>Note that for the <em>bin/sphere</em> style, the radii <em>srmin</em> and <em>srmax</em> are
scaled by the lattice spacing or reduced value of the <em>x</em> dimension.</p>
<p>Note that for the <em>bin/cylinder</em> style, the radii <em>crmin</em> and <em>crmax</em>
are scaled by the lattice spacing or reduced value of the 1st
dimension perpendicular to the cylinder axis. E.g. y for an x-axis
cylinder, x for a y-axis cylinder, and x for a z-axis cylinder.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values are unitless chunk IDs, ranging from 1 to
<em>Nchunk</em> (inclusive) for atoms assigned to chunks, and 0 for atoms not
belonging to a chunk.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>Even if the <em>nchunk</em> keyword is set to <em>once</em>, the chunk IDs assigned
to each atom are not stored in a restart files. This means you cannot
expect those assignments to persist in a restarted simulation.
Instead you must re-specify this command and assign atoms to chunks when
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>.
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>.
<p>Define a computation that calculates the center-of-mass for multiple
chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the x,y,z coordinates of the center-of-mass
for each chunk, which includes all effects due to atoms passing thru
periodic boundaries.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The coordinates of an atom contribute to the chunk’s
center-of-mass in “unwrapped” form, by using the image flags
associated with each atom. See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command
for a discussion of “unwrapped” coordinates. See the Atoms section of
the <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags
and how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<p>The simplest way to output the results of the compute com/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
3 for the x,y,z center-of-mass coordinates of each chunk. These
values can be accessed by any command that uses global array values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</li>
<li>coord/atom = style name of this compute command</li>
<li>cutoff = distance within which to count coordination neighbors (distance units)</li>
<li>typeN = atom type for Nth coordination count (see asterisk form below)</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
compute 1 all coord/atom 2.0
compute 1 all coord/atom 6.0 1 2
compute 1 all coord/atom 6.0 2*4 5*8 *
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define a computation that calculates one or more coordination numbers
for each atom in a group.</p>
<p>A coordination number is defined as the number of neighbor atoms with
specified atom type(s) that are within the specified cutoff distance
from the central atom. Atoms not in the group are included in a
coordination number of atoms in the group.</p>
<p>The <em>typeN</em> keywords allow you to specify which atom types contribute
to each coordination number. One coordination number is computed for
each of the <em>typeN</em> keywords listed. If no <em>typeN</em> keywords are
listed, a single coordination number is calculated, which includes
atoms of all types (same as the “*” format, see below).</p>
<p>The <em>typeN</em> keywords can be specified in one of two ways. An explicit
numeric value can be used, as in the 2nd example above. Or a
wild-card asterisk can be used to specify a range of atom types. This
takes the form “*” or “*n” or “n*” or “m*n”. If N = the number of
atom types, then an asterisk with no numeric values means all types
from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).</p>
<p>The value of all coordination numbers will be 0.0 for atoms not in the
specified compute group.</p>
<p>The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you have a bonded system, then the settings of
<a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the <a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a>
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included in the coordination count. One way
to get around this, is to write a dump file, and use the
<a class="reference internal" href="rerun.html"><span class="doc">rerun</span></a> command to compute the coordination for snapshots
in the dump file. The rerun script can use a
<a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> command that includes all pairs in
the neighbor list.</p>
</div>
<p><strong>Output info:</strong></p>
<p>If single <em>type1</em> keyword is specified (or if none are specified),
this compute calculates a per-atom vector. If multiple <em>typeN</em>
keywords are specified, this compute calculates a per-atom array, with
N columns. These values can be accessed by any command that uses
per-atom values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The per-atom vector or array values will be a number >= 0.0, as
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>.
<p>Define a computation that calculates the per-atom damage for each atom
in a group. This is a quantity relevant for <a class="reference internal" href="pair_peri.html"><span class="doc">Peridynamics models</span></a>. See <a class="reference external" href="PDF/PDLammps_overview.pdf">this document</a>
for an overview of LAMMPS commands for Peridynamics modeling.</p>
<p>The “damage” of a Peridymaics particles is based on the bond breakage
between the particle and its neighbors. If all the bonds are broken
the particle is considered to be fully damaged.</p>
<p>See the <a class="reference external" href="http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf">PDLAMMPS user guide</a> for a formal
definition of “damage” and more details about Peridynamics as it is
implemented in LAMMPS.</p>
<p>This command can be used with all the Peridynamic pair styles.</p>
<p>The damage value will be 0.0 for atoms not in the specified compute
group.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values are unitlesss numbers (damage) >= 0.0.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the dipole vector and total dipole
for multiple chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the x,y,z coordinates of the dipole vector
and the total dipole moment for each chunk, which includes all effects
due to atoms passing thru periodic boundaries. For chunks with a net
charge the resulting dipole is made position independent by subtracting
the position vector of the center of mass or geometric center times the
net charge from the computed dipole vector.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The coordinates of an atom contribute to the chunk’s
dipole in “unwrapped” form, by using the image flags
associated with each atom. See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command
for a discussion of “unwrapped” coordinates. See the Atoms section of
the <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags
and how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<p>The simplest way to output the results of the compute com/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
4 for the x,y,z dipole vector components and the total dipole of each
chunk. These values can be accessed by any command that uses global
array values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The array values are “intensive”. The array values will be in
dipole units, i.e. charge units times distance <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</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>.
<p>Define a computation that calculates the current displacement of each
atom in the group from its original coordinates, including all effects
due to atoms passing thru periodic boundaries.</p>
<p>A vector of four quantites per atom is calculated by this compute.
The first 3 elements of the vector are the dx,dy,dz displacements.
The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy +
dz*dz).</p>
<p>The displacement of an atom is from its original position at the time
the compute command was issued. The value of the displacement will be
0.0 for atoms not in the specified compute group.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Initial coordinates are stored in “unwrapped” form, by using the
image flags associated with each atom. See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command for a discussion of “unwrapped” coordinates.
See the Atoms section of the <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the quantities calculated by this compute to be
continuous when running from a <a class="reference internal" href="read_restart.html"><span class="doc">restart file</span></a>, then
you should use the same ID for this compute, as in the original run.
This is so that the fix this compute creates to store per-atom
quantities will also have the same ID, and thus be initialized
correctly with time=0 atom coordinates from the restart file.</p>
</div>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom array with 4 columns, which can be
accessed by indices 1-4 by any command that uses per-atom values from
a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The per-atom array values will be in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</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>.
<li>ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</li>
<li>dpd/atom = style name of this compute command</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<p>compute 1 all dpd/atom</p>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define a computation that accesses the per-particle internal
conductive energy (u_cond), internal mechanical energy (u_mech),
internal chemical energy (u_chem) and
internal temperatures (dpdTheta) for each particle in a group. See
the <a class="reference internal" href="compute_dpd.html"><span class="doc">compute dpd</span></a> command if you want the total
internal conductive energy, the total internal mechanical energy, the
total chemical energy and
average internal temperature of the entire system or group of dpd
particles.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-particle array with 4 columns (u_cond,
u_mech, u_chem, dpdTheta), which can be accessed by indices 1-4 by any command
that uses per-particle values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-particle array values will be in energy (u_cond, u_mech, u_chem)
and temperature (dpdTheta) <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command is part of the USER-DPD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This command also requires use of the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style dpd</span></a>
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>.
<p>This compute requires that line segment particles atoms store a length
and orientation and angular velocity as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style line</span></a> command.</p>
<p>This compute requires that triangular particles atoms store a size and
shape and quaternion orientation and angular momentum as defined by
the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style tri</span></a> command.</p>
<p>All particles in the group must be finite-size. They cannot be point
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>.
<p>Define a computation that calculates the rotational kinetic energy of
a collection of rigid bodies, as defined by one of the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command variants.</p>
<p>The rotational energy of each rigid body is computed as 1/2 I Wbody^2,
where I is the inertia tensor for the rigid body, and Wbody is its
angular velocity vector. Both I and Wbody are in the frame of
reference of the rigid body, i.e. I is diagonalized.</p>
<p>The <em>fix-ID</em> should be the ID of one of the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>
commands which defines the rigid bodies. The group specified in the
compute command is ignored. The rotational energy of all the rigid
bodies defined by the fix rigid command in included in the
calculation.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the summed rotational energy
of all the rigid bodies). This value can be used by any command that
uses a global scalar value from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The scalar value calculated by this compute is “extensive”. The
scalar value will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the RIGID package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
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>.
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>.
<p>Define a computation that flags an “event” if any particle in the
group has moved a distance greater than the specified threshold
distance when compared to a previously stored reference state
(i.e. the previous event). This compute is typically used in
conjunction with the <a class="reference internal" href="prd.html"><span class="doc">prd</span></a> and <a class="reference internal" href="tad.html"><span class="doc">tad</span></a> commands,
to detect if a transition
to a new minimum energy basin has occurred.</p>
<p>This value calculated by the compute is equal to 0 if no particle has
moved far enough, and equal to 1 if one or more particles have moved
further than the threshold distance.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the system is undergoing significant center-of-mass motion,
due to thermal motion, an external force, or an initial net momentum,
then this compute will not be able to distinguish that motion from
local atom displacements and may generate “false postives.”</p>
</div>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the flag). This value can be
used by any command that uses a global scalar value from a compute as
input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an
overview of LAMMPS output options.</p>
<p>The scalar value calculated by this compute is “intensive”. The
scalar value will be a 0 or 1 as explained above.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command can only be used if LAMMPS was built with the REPLICA
package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section
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>.
<p>Define a computation that calculates the inertia tensor for multiple
chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the 6 components of the symmetric intertia
tensor for each chunk, ordered Ixx,Iyy,Izz,Ixy,Iyz,Ixz. The
calculation includes all effects due to atoms passing thru periodic
boundaries.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The coordinates of an atom contribute to the chunk’s inertia
tensor in “unwrapped” form, by using the image flags associated with
each atom. See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command for a discussion
of “unwrapped” coordinates. See the Atoms section of the
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<p>The simplest way to output the results of the compute inertia/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
6 for the 6 components of the inertia tensor for each chunk, ordered
as listed above. These values can be accessed by any command that
uses global array values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
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>.
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>.
<p>Define a computation that calculates the per-atom translational
(nuclei and electrons) and radial kinetic energy (electron only) in a
group. The particles are assumed to be nuclei and electrons modeled
with the <a class="reference internal" href="pair_eff.html"><span class="doc">electronic force field</span></a>.</p>
<p>The kinetic energy for each nucleus is computed as 1/2 m v^2, where m
corresponds to the corresponding nuclear mass, and the kinetic energy
for each electron is computed as 1/2 (me v^2 + 3/4 me s^2), where me
and v correspond to the mass and translational velocity of each
electron, and s to its radial velocity, respectively.</p>
<p>There is a subtle difference between the quantity calculated by this
compute and the kinetic energy calculated by the <em>ke</em> or <em>etotal</em>
keyword used in thermodynamic output, as specified by the
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command. For this compute, kinetic
energy is “translational” plus electronic “radial” kinetic energy,
calculated by the simple formula above. For thermodynamic output, the
<em>ke</em> keyword infers kinetic energy from the temperature of the system
with 1/2 Kb T of energy for each (nuclear-only) degree of freedom in
eFF.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The temperature in eFF should be monitored via the <a class="reference internal" href="compute_temp_eff.html"><span class="doc">compute temp/eff</span></a> command, which can be printed with
thermodynamic output by using the <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify</span></a>
command, as shown in the following example:</p>
</div>
<pre class="literal-block">
compute effTemp all temp/eff
thermo_style custom step etotal pe ke temp press
thermo_modify temp effTemp
</pre>
<p>The value of the kinetic energy will be 0.0 for atoms (nuclei or
electrons) not in the specified compute group.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a scalar quantity for each atom, which can be
accessed by any command that uses per-atom computes as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-EFF package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the kinetic energy of motion of a
group of eFF particles (nuclei and electrons), as modeled with the
<a class="reference internal" href="pair_eff.html"><span class="doc">electronic force field</span></a>.</p>
<p>The kinetic energy for each nucleus is computed as 1/2 m v^2 and the
kinetic energy for each electron is computed as 1/2(me v^2 + 3/4 me
s^2), where m corresponds to the nuclear mass, me to the electron
mass, v to the translational velocity of each particle, and s to the
radial velocity of the electron, respectively.</p>
<p>There is a subtle difference between the quantity calculated by this
compute and the kinetic energy calculated by the <em>ke</em> or <em>etotal</em>
keyword used in thermodynamic output, as specified by the
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command. For this compute, kinetic
energy is “translational” and “radial” (only for electrons) kinetic
energy, calculated by the simple formula above. For thermodynamic
output, the <em>ke</em> keyword infers kinetic energy from the temperature of
the system with 1/2 Kb T of energy for each degree of freedom. For
the eFF temperature computation via the <a class="reference internal" href="compute_temp_eff.html"><span class="doc">compute temp_eff</span></a> command, these are the same. But
different computes that calculate temperature can subtract out
different non-thermal components of velocity and/or include other
degrees of freedom.</p>
<p>IMPRORTANT NOTE: The temperature in eFF models should be monitored via
the <a class="reference internal" href="compute_temp_eff.html"><span class="doc">compute temp/eff</span></a> command, which can be
printed with thermodynamic output by using the
<a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify</span></a> command, as shown in the following
<p>This compute calculates a global scalar (the KE). This value can be
used by any command that uses a global scalar value from a compute as
input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an
overview of LAMMPS output options.</p>
<p>The scalar value calculated by this compute is “extensive”. The
scalar value will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-EFF package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the translational kinetic energy
of a collection of rigid bodies, as defined by one of the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command variants.</p>
<p>The kinetic energy of each rigid body is computed as 1/2 M Vcm^2,
where M is the total mass of the rigid body, and Vcm is its
center-of-mass velocity.</p>
<p>The <em>fix-ID</em> should be the ID of one of the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>
commands which defines the rigid bodies. The group specified in the
compute command is ignored. The kinetic energy of all the rigid
bodies defined by the fix rigid command in included in the
calculation.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the summed KE of all the
rigid bodies). This value can be used by any command that uses a
global scalar value from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The scalar value calculated by this compute is “extensive”. The
scalar value will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the RIGID package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the per-atom internal energy
for each atom in a group.</p>
<p>The internal energy is the energy associated with the internal degrees
of freedom of a mesoscopic particles, e.g. a Smooth-Particle
Hydrodynamics particle.</p>
<p>See <a class="reference external" href="USER/sph/SPH_LAMMPS_userguide.pdf">this PDF guide</a> to using SPH in
LAMMPS.</p>
<p>The value of the internal energy will be 0.0 for atoms not in the
specified compute group.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SPH package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the per-atom mesoscopic density
for each atom in a group.</p>
<p>The mesoscopic density is the mass density of a mesoscopic particle,
calculated by kernel function interpolation using “pair style
sph/rhosum”.</p>
<p>See <a class="reference external" href="USER/sph/SPH_LAMMPS_userguide.pdf">this PDF guide</a> to using SPH in
LAMMPS.</p>
<p>The value of the mesoscopic density will be 0.0 for atoms not in the
specified compute group.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values will be in mass/volume <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SPH package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>See <a class="reference external" href="USER/sph/SPH_LAMMPS_userguide.pdf">this PDF guide</a> to using SPH in
LAMMPS.</p>
<p>The value of the internal energy will be 0.0 for atoms not in the
specified compute group.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values will be in temperature <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SPH package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the mean-squared displacement
(MSD) for multiple chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>Four quantites are calculated by this compute for each chunk. The
first 3 quantities are the squared dx,dy,dz displacements of the
center-of-mass. The 4th component is the total squared displacement,
i.e. (dx*dx + dy*dy + dz*dz) of the center-of-mass. These
calculations include all effects due to atoms passing thru periodic
boundaries.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<p>The slope of the mean-squared displacement (MSD) versus time is
proportional to the diffusion coefficient of the diffusing chunks.</p>
<p>The displacement of the center-of-mass of the chunk is from its
original center-of-mass position, calculated on the timestep this
compute command was first invoked.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The number of chunks <em>Nchunk</em> calculated by the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command must remain constant each
time this compute is invoked, so that the displacement for each chunk
from its original position can be computed consistently. If <em>Nchunk</em>
does not remain constant, an error will be generated. If needed, you
can enforce a constant <em>Nchunk</em> by using the <em>nchunk once</em> or <em>ids
once</em> options when specifying the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This compute stores the original position (of the
center-of-mass) of each chunk. When a displacement is calculated on a
later timestep, it is assumed that the same atoms are assigned to the
same chunk ID. However LAMMPS has no simple way to insure this is the
case, though you can use the <em>ids once</em> option when specifying the
<a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. Note that if
this is not the case, the MSD calculation does not have a sensible
meaning.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The initial coordinates of the atoms in each chunk are stored in
“unwrapped” form, by using the image flags associated with each atom.
See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command for a discussion of
“unwrapped” coordinates. See the Atoms section of the
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the quantities calculated by this compute to be
continuous when running from a <a class="reference internal" href="read_restart.html"><span class="doc">restart file</span></a>, then
you should use the same ID for this compute, as in the original run.
This is so that the fix this compute creates to store per-chunk
quantities will also have the same ID, and thus be initialized
correctly with chunk reference positions from the restart file.</p>
</div>
<p>The simplest way to output the results of the compute com/msd
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
4 for dx,dy,dz and the total displacement. These values can be
accessed by any command that uses global array values from a compute
as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an
overview of LAMMPS output options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
<p>The NGP is a commonly used quantity in studies of dynamical
heterogeneity. Its minimum theoretical value (-0.4) occurs when all
atoms have the same displacement magnitude. NGP=0 for Brownian
diffusion, while NGP > 0 when some mobile atoms move faster than
others.</p>
<p>If the <em>com</em> option is set to <em>yes</em> then the effect of any drift in
the center-of-mass of the group of atoms is subtracted out before the
displacment of each atom is calcluated.</p>
<p>See the <a class="reference internal" href="compute_msd.html"><span class="doc">compute msd</span></a> doc page for further important
NOTEs, which also apply to this compute.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global vector of length 3, which can be
accessed by indices 1-3 by any command that uses global vector values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options.</p>
<p>The vector values are “intensive”. The first vector value will be in
distance^2 <a class="reference internal" href="units.html"><span class="doc">units</span></a>, the second is in distance^4 units, and
the 3rd is dimensionless.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the MISC package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the angular velocity (omega) of
multiple chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the 3 components of the angular velocity
vector for each chunk, via the formula L = Iw where L is the angular
momentum vector of the chunk, I is its moment of inertia tensor, and w
is omega = angular velocity of the chunk. The calculation includes
all effects due to atoms passing thru periodic boundaries.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The coordinates of an atom contribute to the chunk’s angular
velocity in “unwrapped” form, by using the image flags associated with
each atom. See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command for a discussion
of “unwrapped” coordinates. See the Atoms section of the
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<p>The simplest way to output the results of the compute omega/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
3 for the 3 xyz components of the angular velocity for each chunk.
These values can be accessed by any command that uses global array
values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
<p>Define a computation that calculates the potential energy of the
entire system of atoms. The specified group must be “all”. See the
<a class="reference internal" href="compute_pe_atom.html"><span class="doc">compute pe/atom</span></a> command if you want per-atom
energies. These per-atom values could be summed for a group of atoms
via the <a class="reference internal" href="compute_reduce.html"><span class="doc">compute reduce</span></a> command.</p>
<p>The energy is calculated by the various pair, bond, etc potentials
defined for the simulation. If no extra keywords are listed, then the
potential energy is the sum of pair, bond, angle, dihedral, improper,
kspace (long-range), and fix energy. I.e. it is as if all the
keywords were listed. If any extra keywords are listed, then only
those components are summed to compute the potential energy.</p>
<p>The Kspace contribution requires 1 extra FFT each timestep the energy
is calculated, if using the PPPM solver via the <a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style pppm</span></a> command. Thus it can increase the cost of the
PPPM calculation if it is needed on a large fraction of the simulation
timesteps.</p>
<p>Various fixes can contribute to the total potential energy of the
system if the <em>fix</em> contribution is included. See the doc pages for
<a class="reference internal" href="fix.html"><span class="doc">individual fixes</span></a> for details of which ones compute a
potential energy.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify energy yes</span></a> command must also be
specified if a fix is to contribute potential energy to this command.</p>
</div>
<p>A compute of this style with the ID of “thermo_pe” is created when
LAMMPS starts up, as if this command were in the input script:</p>
<pre class="literal-block">
compute thermo_pe all pe
</pre>
<p>See the “thermo_style” command for more details.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the potential energy). This
value can be used by any command that uses a global scalar value from
a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The scalar value calculated by this compute is “extensive”. The
scalar value will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</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>.
pairwise interactions between 1-4 atoms. The energy contribution of
these terms is included in the pair energy, not the dihedral energy.</p>
<p>The KSpace contribution is calculated using the method in
<a class="reference internal" href="compute_stress_atom.html#heyes"><span class="std std-ref">(Heyes)</span></a> for the Ewald method and a related method for PPPM,
as specified by the <a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style pppm</span></a> command.
For PPPM, the calcluation requires 1 extra FFT each timestep that
per-atom energy is calculated. Thie <a class="reference external" href="PDF/kspace.pdf">document</a>
describes how the long-range per-atom energy calculation is performed.</p>
<p>Various fixes can contribute to the per-atom potential energy of the
system if the <em>fix</em> contribution is included. See the doc pages for
<a class="reference internal" href="fix.html"><span class="doc">individual fixes</span></a> for details of which ones compute a
per-atom potential energy.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify energy yes</span></a> command must also be
specified if a fix is to contribute per-atom potential energy to this
command.</p>
</div>
<p>As an example of per-atom potential energy compared to total potential
energy, these lines in an input script should yield the same result
in the last 2 columns of thermo output:</p>
<pre class="literal-block">
compute peratom all pe/atom
compute pe all reduce sum c_peratom
thermo_style custom step temp etotal press pe c_pe
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The per-atom energy does not any Lennard-Jones tail corrections
invoked by the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify tail yes</span></a> command, since
those are global contributions to the system energy.</p>
</div>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-atom vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</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>.
<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</p>
</li>
<li><p class="first">property/chunk = style name of this compute command</p>
</li>
<li><p class="first">input = one or more attributes</p>
<pre class="literal-block">
attributes = count, id, coord1, coord2, coord3
count = # of atoms in chunk
id = original chunk IDs before compression by <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a>
coord123 = coordinates for spatial bins calculated by <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a>
<p>Define a computation that stores the specified attributes of chunks of
atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates and stores the specified attributes of chunks
as global data so they can be accessed by other <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a> and used in conjunction with
other commands that generate per-chunk data, such as <a class="reference internal" href="compute_com_chunk.html"><span class="doc">compute com/chunk</span></a> or <a class="reference internal" href="compute_msd_chunk.html"><span class="doc">compute msd/chunk</span></a>.</p>
<p>Note that only atoms in the specified group contribute to the
calculation of the <em>count</em> attribute. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command defines its own group;
atoms will have a chunk ID = 0 if they are not in that group,
signifying they are not assigned to a chunk, and will thus also not
contribute to this calculation. You can specify the “all” group for
this command if you simply want to include atoms with non-zero chunk
IDs.</p>
<p>The <em>count</em> attribute is the number of atoms in the chunk.</p>
<p>The <em>id</em> attribute stores the original chunk ID for each chunk. It
can only be used if the <em>compress</em> keyword was set to <em>yes</em> for the
<a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command referenced by
chunkID. This means that the original chunk IDs (e.g. molecule IDs)
will have been compressed to remove chunk IDs with no atoms assigned
to them. Thus a compresed chunk ID of 3 may correspond to an original
chunk ID (molecule ID in this case) of 415. The <em>id</em> attribute will
then be 415 for the 3rd chunk.</p>
<p>The <em>coordN</em> attributes can only be used if a <em>binning</em> style was used
in the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command referenced
by chunkID. For <em>bin/1d</em>, <em>bin/2d</em>, and <em>bin/3d</em> styles the attribute
is the center point of the bin in the corresponding dimension. Style
<em>bin/1d</em> only defines a <em>coord1</em> attribute. Style <em>bin/2d</em> adds a
<em>coord2</em> attribute. Style <em>bin/3d</em> adds a <em>coord3</em> attribute.</p>
<p>Note that if the value of the <em>units</em> keyword used in the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom command</span></a> is <em>box</em> or <em>lattice</em>, the
<em>coordN</em> attributes will be in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a>. If the
value of the <em>units</em> keyword is <em>reduced</em>, the <em>coordN</em> attributes
will be in unitless reduced units (0-1).</p>
<p>The simplest way to output the results of the compute property/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
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>.
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>.
<p>Define a calculation that “reduces” one or more vector inputs into
scalar values, one per listed input. The inputs can be per-atom or
local quantities; they cannot be global quantities. Atom attributes
are per-atom quantities, <a class="reference internal" href="compute.html"><span class="doc">computes</span></a> and <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a>
may generate any of the three kinds of quantities, and <a class="reference internal" href="variable.html"><span class="doc">atom-style variables</span></a> generate per-atom quantities. See the
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command and its special functions which can
perform the same operations as the compute reduce command on global
vectors.</p>
<p>The reduction operation is specified by the <em>mode</em> setting. The <em>sum</em>
option adds the values in the vector into a global total. The <em>min</em>
or <em>max</em> options find the minimum or maximum value across all vector
values. The <em>ave</em> setting adds the vector values into a global total,
then divides by the number of values in the vector. The <em>sumsq</em>
option sums the square of the values in the vector into a global
total. The <em>avesq</em> setting does the same as <em>sumsq</em>, then divdes the
sum of squares by the number of values. The last two options can be
useful for calculating the variance of some quantity, e.g. variance =
sumsq - ave^2.</p>
<p>Each listed input is operated on independently. For per-atom inputs,
the group specified with this command means only atoms within the
group contribute to the result. For per-atom inputs, if the compute
reduce/region command is used, the atoms must also currently be within
the region. Note that an input that produces per-atom quantities may
define its own group which affects the quantities it returns. For
example, if a compute is used as an input which generates a per-atom
vector, it will generate values of 0.0 for atoms that are not in the
group specified for that compute.</p>
<p>Each listed input can be an atom attribute (position, velocity, force
component) or can be the result of a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> or
<a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or the evaluation of an atom-style
<p>Note that for values from a compute or fix, the bracketed index I can
be specified using a wildcard asterisk with the index to effectively
specify multiple values. This takes the form “*” or “*n” or “n*” or
“m*n”. If N = the size of the vector (for <em>mode</em> = scalar) or the
number of columns in the array (for <em>mode</em> = vector), then an asterisk
with no numeric values means all indices from 1 to N. A leading
asterisk means all indices from 1 to n (inclusive). A trailing
asterisk means all indices from n to N (inclusive). A middle asterisk
means all indices from m to n (inclusive).</p>
<p>Using a wildcard is the same as if the individual columns of the array
had been listed one by one. E.g. these 2 compute reduce commands are
equivalent, since the <a class="reference internal" href="compute_stress_atom.html"><span class="doc">compute stress/atom</span></a>
command creates a per-atom array with 6 columns:</p>
<pre class="literal-block">
compute myPress all stress/atom NULL
compute 2 all reduce min myPress[*]
compute 2 all reduce min myPress[1] myPress[2] myPress[3] &
myPress[4] myPress[5] myPress[6]
</pre>
<hr class="docutils" />
<p>The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are
self-explanatory. Note that other atom attributes can be used as
inputs to this fix by using the <a class="reference internal" href="compute_property_atom.html"><span class="doc">compute property/atom</span></a> command and then specifying
an input value from that compute.</p>
<p>If a value begins with “c_”, a compute ID must follow which has been
previously defined in the input script. Computes can generate
per-atom or local quantities. See the individual
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> doc page for details. If no bracketed integer
is appended, the vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the array calculated
by the compute is used. Users can also write code for their own
compute styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>. See the
discussion above for how I can be specified with a wildcard asterisk
to effectively specify multiple values.</p>
<p>If a value begins with “f_”, a fix ID must follow which has been
previously defined in the input script. Fixes can generate per-atom
or local quantities. See the individual <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> doc page for
details. Note that some fixes only produce their values on certain
timesteps, which must be compatible with when compute reduce
references the values, else an error results. If no bracketed integer
is appended, the vector calculated by the fix is used. If a bracketed
integer is appended, the Ith column of the array calculated by the fix
is used. Users can also write code for their own fix style and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>. See the discussion above for how
I can be specified with a wildcard asterisk to effectively specify
multiple values.</p>
<p>If a value begins with “v_”, a variable name must follow which has
been previously defined in the input script. It must be an
<a class="reference internal" href="variable.html"><span class="doc">atom-style variable</span></a>. Atom-style variables can
reference thermodynamic keywords and various per-atom attributes, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of generating per-atom quantities to
reduce.</p>
<hr class="docutils" />
<p>If the <em>replace</em> keyword is used, two indices <em>vec1</em> and <em>vec2</em> are
specified, where each index ranges from 1 to the # of input values.
The replace keyword can only be used if the <em>mode</em> is <em>min</em> or <em>max</em>.
It works as follows. A min/max is computed as usual on the <em>vec2</em>
input vector. The index N of that value within <em>vec2</em> is also stored.
Then, instead of performing a min/max on the <em>vec1</em> input vector, the
stored index is used to select the Nth element of the <em>vec1</em> vector.</p>
<p>Thus, for example, if you wish to use this compute to find the bond
with maximum stretch, you can do it as follows:</p>
<pre class="literal-block">
compute 1 all property/local batom1 batom2
compute 2 all bond/local dist
compute 3 all reduce max c_1[1] c_1[2] c_2 replace 1 3 replace 2 3
<p>The first two input values in the compute reduce command are vectors
with the IDs of the 2 atoms in each bond, using the <a class="reference internal" href="compute_property_local.html"><span class="doc">compute property/local</span></a> command. The last input
value is bond distance, using the <a class="reference internal" href="compute_bond_local.html"><span class="doc">compute bond/local</span></a> command. Instead of taking the
max of the two atom ID vectors, which does not yield useful
information in this context, the <em>replace</em> keywords will extract the
atom IDs for the two atoms in the bond of maximum stretch. These atom
IDs and the bond stretch will be printed with thermodynamic output.</p>
<hr class="docutils" />
<p>If a single input is specified this compute produces a global scalar
value. If multiple inputs are specified, this compute produces a
global vector of values, the length of which is equal to the number of
inputs specified.</p>
<p>As discussed below, for the <em>sum</em> and <em>sumsq</em> modes, the value(s)
produced by this compute are all “extensive”, meaning their value
scales linearly with the number of atoms involved. If normalized
values are desired, this compute can be accessed by the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command with <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify norm yes</span></a> set as an option. Or it can be accessed by a
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a> that divides by the appropriate atom count.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar if a single input value is
specified or a global vector of length N where N is the number of
inputs, and which can be accessed by indices 1 to N. These values can
be used by any command that uses global scalar or vector values from a
compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a>
for an overview of LAMMPS output options.</p>
<p>All the scalar or vector values calculated by this compute are
“intensive”, except when the <em>sum</em> or <em>sumsq</em> modes are used on
per-atom or local vectors, in which case the calculated values are
“extensive”.</p>
<p>The scalar or vector values will be in whatever <a class="reference internal" href="units.html"><span class="doc">units</span></a> the
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>.
<p>Coefficients parameterized by <a class="reference internal" href="#fox"><span class="std std-ref">(Fox)</span></a> are assigned for each
atom type designating the chemical symbol and charge of each atom
type. Valid chemical symbols for compute saed are:</p>
<dl class="docutils">
<dt>H: He: Li: Be: B:</dt>
<dd><blockquote class="first">
<div>C: N: O: F: Ne:</div></blockquote>
<dl class="docutils">
<dt>Na: Mg: Al: Si: P:</dt>
<dd>S: Cl: Ar: K: Ca:</dd>
</dl>
<p class="last">Sc: Ti: V: Cr: Mn:
Fe: Co: Ni: Cu: Zn:
Ga: Ge: As: Se: Br:
Kr: Rb: Sr: Y: Zr:
Nb: Mo: Tc: Ru: Rh:
Pd: Ag: Cd: In: Sn:
Sb: Te: I: Xe: Cs:
Ba: La: Ce: Pr: Nd:
Pm: Sm: Eu: Gd: Tb:
Dy: Ho: Er: Tm: Yb:
Lu: Hf: Ta: W: Re:
Os: Ir: Pt: Au: Hg:
Tl: Pb: Bi: Po: At:
Rn: Fr: Ra: Ac: Th:
Pa: U: Np: Pu: Am:
Cm: Bk: Cf:tb(c=5,s=:)</p>
</dd>
</dl>
<p>If the <em>echo</em> keyword is specified, compute saed will provide extra
reporting information to the screen.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global vector. The length of the vector is
the number of reciprocal lattice nodes that are explored by the mesh.
The entries of the global vector are the computed diffraction
intensities as described above.</p>
<p>The vector can be accessed by any command that uses global values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options.</p>
<p>All array values calculated by this compute are “intensive”.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-DIFFRACTION package. It is only
enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The compute_saed command does not work for triclinic cells.</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>.
<p>Define a computation which outputs the contact radius, i.e., the
radius used to prevent particles from penetrating each other. The
contact radius is used only to prevent particles belonging to
different physical bodies from penetrating each other. It is used by
the contact pair styles, e.g., smd/hertz and smd/tri_surface.</p>
<p>See <a class="reference external" href="USER/smd/SMD_LAMMPS_userguide.pdf">this PDF guide</a> to using Smooth
Mach Dynamics in LAMMPS.</p>
<p>The value of the contact radius will be 0.0 for particles not in the
specified compute group.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-particle vector, which can be accessed by
any command that uses per-particle values from a compute as input. See
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-particle vector values will be in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SMD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that returns the coordinates of the vertices
corresponding to the triangle-elements of a mesh created by the <a class="reference internal" href="fix_smd_wall_surface.html"><span class="doc">fix smd/wall_surface</span></a>.</p>
<p>See <a class="reference external" href="USER/smd/SMD_LAMMPS_userguide.pdf">this PDF guide</a> to using Smooth
Mach Dynamics in LAMMPS.</p>
<p><strong>Output info:</strong></p>
<p>This compute returns a per-particle vector of vectors, which can be
accessed by any command that uses per-particle values from a compute as
<p>The per-particle vector has nine entries, (x1/y1/z1), (x2/y2/z2), and
(x3/y3/z3) corresponding to the first, second, and third vertex of
each triangle.</p>
<p>It is only meaningful to use this compute for a group of particles
which is created via the <a class="reference internal" href="fix_smd_wall_surface.html"><span class="doc">fix smd/wall_surface</span></a> command.</p>
<p>The output of this compute can be used with the dump2vtk_tris tool to
generate a VTK representation of the smd/wall_surface mesh for
visualization purposes.</p>
<p>The values will be given in <a class="reference internal" href="units.html"><span class="doc">units</span></a> of distance.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SMD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that returns the number of neighbor particles
inside of the smoothing kernel radius for particles interacting via
the updated Lagrangian SPH pair style.</p>
<p>See <a class="reference external" href="USER/smd/SMD_LAMMPS_userguide.pdf">this PDF guide</a> to using Smooth
Mach Dynamics in LAMMPS.</p>
<p><strong>Output info:</strong></p>
<p>This compute returns a per-particle vector, which can be accessed by
any command that uses per-particle values from a compute as input.
See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of
LAMMPS output options.</p>
<p>The per-particle values will be given dimentionless, see <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SMD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-2"><span class="std std-ref">Making LAMMPS</span></a> section for more info. This compute
can only be used for particles which interact with the updated
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>.
<p>This compute is part of the USER-SMD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info. This compute
can only be used for particles which interact with the updated
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>.
<p>Define a computation that outputs the rate of the logarithmic strain
tensor for particles interacting via the updated Lagrangian SPH pair
style.</p>
<p>See <a class="reference external" href="USER/smd/SMD_LAMMPS_userguide.pdf">this PDF guide</a> to using Smooth
Mach Dynamics in LAMMPS.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-particle vector of vectors (tensors),
which can be accessed by any command that uses per-particle values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The values will be given in <a class="reference internal" href="units.html"><span class="doc">units</span></a> of one over time.</p>
<p>The per-particle vector has 6 entries, corresponding to the xx, yy,
zz, xy, xz, yz components of the symmetric strain rate tensor.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SMD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-2"><span class="std std-ref">Making LAMMPS</span></a> section for more info. This compute
can only be used for particles which interact with the updated
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>.
<p>Define a computation that outputs the Cauchy stress tensor.</p>
<p>See <a class="reference external" href="USER/smd/SMD_LAMMPS_userguide.pdf">this PDF guide</a> to using Smooth
Mach Dynamics in LAMMPS.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a per-particle vector of vectors (tensors),
which can be accessed by any command that uses per-particle values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The values will be given in <a class="reference internal" href="units.html"><span class="doc">units</span></a> of pressure.</p>
<p>The per-particle vector has 7 entries. The first six entries
correspond to the xx, yy, zz, xy, xz, yz components of the symmetric
Cauchy stress tensor. The seventh entry is the second invariant of the
stress tensor, i.e., the von Mises equivalent stress.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the USER-SMD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info. This compute
can only be used for particles which interact with the updated
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>.
<p>The temperature is calculated by the formula KE = dim/2 N k T, where
KE = total kinetic energy of the group of atoms (sum of 1/2 m v^2),
dim = 2 or 3 = dimensionality of the simulation, N = number of atoms
in the group, k = Boltzmann constant, and T = temperature.</p>
<p>A kinetic energy tensor, stored as a 6-element vector, is also
calculated by this compute for use in the computation of a pressure
tensor. The formula for the components of the tensor is the same as
the above formula, except that v^2 is replaced by vx*vy for the xy
component, etc. The 6 components of the vector are ordered xx, yy,
zz, xy, xz, yz.</p>
<p>The number of atoms contributing to the temperature is assumed to be
constant for the duration of the run; use the <em>dynamic</em> option of the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command if this is not the case.</p>
<p>This compute subtracts out degrees-of-freedom due to fixes that
constrain molecular motion, such as <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> and
<a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>. This means the temperature of groups of
atoms that include these constraints will be computed correctly. If
needed, the subtracted degrees-of-freedom can be altered using the
<em>extra</em> option of the <a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command.</p>
<p>A compute of this style with the ID of “thermo_temp” is created when
LAMMPS starts up, as if this command were in the input script:</p>
<pre class="literal-block">
compute thermo_temp all temp
</pre>
<p>See the “thermo_style” command for more details.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-16"><span class="std std-ref">this howto section</span></a> of the manual for
a discussion of different ways to compute temperature and perform
thermostatting.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the temperature) and a global
vector of length 6 (KE tensor), which can be accessed by indices 1-6.
These values can be used by any command that uses global scalar or
vector values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options.</p>
<p>The scalar value calculated by this compute is “intensive”. The
vector values are “extensive”.</p>
<p>The scalar value will be in temperature <a class="reference internal" href="units.html"><span class="doc">units</span></a>. The
vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</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>.
<p>Define a computation that calculates the temperature of a group of
atoms that are also in chunks, after optionally subtracting out the
center-of-mass velocity of each chunk. By specifying optional values,
it can also calulate the per-chunk temperature or energies of the
multiple chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>The temperature is calculated by the formula KE = DOF/2 k T, where KE =
total kinetic energy of all atoms assigned to chunks (sum of 1/2 m
v^2), DOF = the total number of degrees of freedom for those atoms, k
= Boltzmann constant, and T = temperature.</p>
<p>The DOF is calculated as N*adof + Nchunk*cdof, where N = number of
atoms contributing to the KE, adof = degrees of freedom per atom, and
cdof = degrees of freedom per chunk. By default adof = 2 or 3 =
dimensionality of system, as set via the <a class="reference internal" href="dimension.html"><span class="doc">dimension</span></a>
command, and cdof = 0.0. This gives the usual formula for
temperature.</p>
<p>A kinetic energy tensor, stored as a 6-element vector, is also
calculated by this compute for use in the computation of a pressure
tensor. The formula for the components of the tensor is the same as
the above formula, except that v^2 is replaced by vx*vy for the xy
component, etc. The 6 components of the vector are ordered xx, yy,
zz, xy, xz, yz.</p>
<p>Note that the number of atoms contributing to the temperature is
calculated each time the temperature is evaluated since it is assumed
the atoms may be dynamically assigned to chunks. Thus there is no
need to use the <em>dynamic</em> option of the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command for this compute style.</p>
<p>If any optional values are specified, then per-chunk quantities are
also calculated and stored in a global array, as described below.</p>
<p>The <em>temp</em> value calculates the temperature for each chunk by the
formula KE = DOF/2 k T, where KE = total kinetic energy of the chunk
of atoms (sum of 1/2 m v^2), DOF = the total number of degrees of
freedom for all atoms in the chunk, k = Boltzmann constant, and T =
temperature.</p>
<p>The DOF in this case is calculated as N*adof + cdof, where N = number
of atoms in the chunk, adof = degrees of freedom per atom, and cdof =
degrees of freedom per chunk. By default adof = 2 or 3 =
dimensionality of system, as set via the <a class="reference internal" href="dimension.html"><span class="doc">dimension</span></a>
command, and cdof = 0.0. This gives the usual formula for
temperature.</p>
<p>The <em>kecom</em> value calculates the kinetic energy of each chunk as if
all its atoms were moving with the velocity of the center-of-mass of
the chunk.</p>
<p>The <em>internal</em> value calculates the internal kinetic energy of each
chunk. The interal KE is summed over the atoms in the chunk using an
internal “thermal” velocity for each atom, which is its velocity minus
the center-of-mass velocity of the chunk.</p>
<hr class="docutils" />
<p>Note that currently the global and per-chunk temperatures calculated
by this compute only include translational degrees of freedom for each
atom. No rotational degrees of freedom are included for finite-size
particles. Also no degrees of freedom are subtracted for any velocity
bias or constraints that are applied, such as <a class="reference internal" href="compute_temp_partial.html"><span class="doc">compute temp/partial</span></a>, or <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a>
or <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>. This is because those degrees of
freedom (e.g. a constrained bond) could apply to sets of atoms that
are both included and excluded from a specific chunk, and hence the
concept is somewhat ill-defined. In some cases, you can use the
<em>adof</em> and <em>cdof</em> keywords to adjust the calculated degress of freedom
appropriately, as explained below.</p>
<p>Note that the per-chunk temperature calulated by this compute and the
<a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk temp</span></a> command can be different.
This compute calculates the temperature for each chunk for a single
snapshot. Fix ave/chunk can do that but can also time average those
values over many snapshots, or it can compute a temperature as if the
atoms in the chunk on different timesteps were collected together as
one set of atoms to calculate their temperature. This compute allows
the center-of-mass velocity of each chunk to be subtracted before
calculating the temperature; fix ave/chunk does not.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Only atoms in the specified group contribute to the calculations
performed by this compute. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command defines its own group;
atoms will have a chunk ID = 0 if they are not in that group,
signifying they are not assigned to a chunk, and will thus also not
contribute to this calculation. You can specify the “all” group for
this command if you simply want to include atoms with non-zero chunk
IDs.</p>
</div>
<p>The simplest way to output the per-chunk results of the compute
temp/chunk calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a> command, for example:</p>
<p>The keyword/value option pairs are used in the following ways.</p>
<p>The <em>com</em> keyword can be used with a value of <em>yes</em> to subtract the
velocity of the center-of-mass for each chunk from the velocity of the
atoms in that chunk, before calculating either the global or per-chunk
temperature. This can be useful if the atoms are streaming or
otherwise moving collectively, and you wish to calculate only the
thermal temperature.</p>
<p>For the <em>bias</em> keyword, <em>bias-ID</em> refers to the ID of a temperature
compute that removes a “bias” velocity from each atom. This also
allows calculation of the global or per-chunk temperature using only
the thermal temperature of atoms in each chunk after the translational
kinetic energy components have been altered in a prescribed way,
e.g. to remove a velocity profile. It also applies to the calculation
of the other per-chunk values, such as <em>kecom</em> or <em>internal</em>, which
involve the center-of-mass velocity of each chunk, which is calculated
after the velocity bias is removed from each atom. Note that the
temperature compute will apply its bias globally to the entire system,
not on a per-chunk basis.</p>
<p>The <em>adof</em> and <em>cdof</em> keywords define the values used in the degree of
freedom (DOF) formulas used for the global or per-chunk temperature,
as described above. They can be used to calculate a more appropriate
temperature for some kinds of chunks. Here are 3 examples:</p>
<p>If spatially binned chunks contain some number of water molecules and
<a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> is used to make each molecule rigid, then
you could calculate a temperature with 6 degrees of freedom (DOF) (3
translational, 3 rotational) per molecule by setting <em>adof</em> to 2.0.</p>
<p>If <a class="reference internal" href="compute_temp_partial.html"><span class="doc">compute temp/partial</span></a> is used with the
<em>bias</em> keyword to only allow the x component of velocity to contribute
to the temperature, then <em>adof</em> = 1.0 would be appropriate.</p>
<p>If each chunk consists of a large molecule, with some number of its
bonds constrained by <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> or the entire molecule
by <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid/small</span></a>, <em>adof</em> = 0.0 and <em>cdof</em> could be
set to the remaining degrees of freedom for the entire molecule
(entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid
molecule.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the temperature) and a global
vector of length 6 (KE tensor), which can be accessed by indices 1-6.
These values can be used by any command that uses global scalar or
vector values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options.</p>
<p>This compute also optionally calculates a global array, if one or more
of the optional values are specified. The number of rows in the array
= the number of chunks <em>Nchunk</em> as calculated by the specified
<a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of
columns is the number of specifed values (1 or more). These values
can be accessed by any command that uses global array values from a
compute as input. Again, see <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The scalar value calculated by this compute is “intensive”. The
vector values are “extensive”. The array values are “intensive”.</p>
<p>The scalar value will be in temperature <a class="reference internal" href="units.html"><span class="doc">units</span></a>. The
vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>. The array values
will be in temperature <a class="reference internal" href="units.html"><span class="doc">units</span></a> for the <em>temp</em> value, and in
energy <a class="reference internal" href="units.html"><span class="doc">units</span></a> for the <em>kecom</em> and <em>internal</em> values.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>The <em>com</em> and <em>bias</em> keywords cannot be used together.</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>.
<li>ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</li>
<li>temp/cs = style name of this compute command</li>
<li>group1 = group-ID of either cores or shells</li>
<li>group2 = group-ID of either shells or cores</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
compute oxygen_c-s all temp/cs O_core O_shell
compute core_shells all temp/cs cores shells
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define a computation that calculates the temperature of a system based
on the center-of-mass velocity of atom pairs that are bonded to each
other. This compute is designed to be used with the adiabatic
core/shell model of <a class="reference internal" href="pair_cs.html#mitchellfinchham"><span class="std std-ref">(Mitchell and Finchham)</span></a>. See
<a class="reference internal" href="Section_howto.html#howto-25"><span class="std std-ref">Section 6.25</span></a> of the manual for an
overview of the model as implemented in LAMMPS. Specifically, this
compute enables correct temperature calculation and thermostatting of
core/shell pairs where it is desirable for the internal degrees of
freedom of the core/shell pairs to not be influenced by a thermostat.
A compute of this style can be used by any command that computes a
temperature via <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> e.g. <a class="reference internal" href="fix_temp_rescale.html"><span class="doc">fix temp/rescale</span></a>, <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a>, etc.</p>
<p>Note that this compute does not require all ions to be polarized,
hence defined as core/shell pairs. One can mix core/shell pairs and
ions without a satellite particle if desired. The compute will
consider the non-polarized ions according to the physical system.</p>
<p>For this compute, core and shell particles are specified by two
respective group IDs, which can be defined using the
<a class="reference internal" href="group.html"><span class="doc">group</span></a> command. The number of atoms in the two groups
must be the same and there should be one bond defined between a pair
of atoms in the two groups. Non-polarized ions which might also be
included in the treated system should not be included into either of
these groups, they are taken into account by the <em>group-ID</em> (2nd
argument) of the compute.</p>
<p>The temperature is calculated by the formula KE = dim/2 N k T, where
KE = total kinetic energy of the group of atoms (sum of 1/2 m v^2),
dim = 2 or 3 = dimensionality of the simulation, N = number of atoms
in the group, k = Boltzmann constant, and T = temperature. Note that
the velocity of each core or shell atom used in the KE calculation is
the velocity of the center-of-mass (COM) of the core/shell pair the
atom is part of.</p>
<p>A kinetic energy tensor, stored as a 6-element vector, is also
calculated by this compute for use in the computation of a pressure
tensor. The formula for the components of the tensor is the same as
the above formula, except that v^2 is replaced by vx*vy for the xy
component, etc. The 6 components of the vector are ordered xx, yy,
zz, xy, xz, yz. In contrast to the temperature, the velocity of
each core or shell atom is taken individually.</p>
<p>The change this fix makes to core/shell atom velocities is essentially
computing the temperature after a “bias” has been removed from the
velocity of the atoms. This “bias” is the velocity of the atom
relative to the COM velocity of the core/shell pair. If this compute
is used with a fix command that performs thermostatting then this bias
will be subtracted from each atom, thermostatting of the remaining COM
velocity will be performed, and the bias will be added back in. This
means the thermostating will effectively be performed on the
core/shell pairs, instead of on the individual core and shell atoms.
Thermostatting fixes that work in this way include <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>, <a class="reference internal" href="fix_temp_rescale.html"><span class="doc">fix temp/rescale</span></a>, <a class="reference internal" href="fix_temp_berendsen.html"><span class="doc">fix temp/berendsen</span></a>, and <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>.</p>
<p>The internal energy of core/shell pairs can be calculated by the
<a class="reference internal" href="compute_temp_chunk.html"><span class="doc">compute temp/chunk</span></a> command, if chunks are
defined as core/shell pairs. See <a class="reference internal" href="Section_howto.html#howto-25"><span class="std std-ref">Section 6.25</span></a> for more discussion on how to do this.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the temperature) and a global
vector of length 6 (KE tensor), which can be accessed by indices 1-6.
These values can be used by any command that uses global scalar or
vector values from a compute as input.</p>
<p>The scalar value calculated by this compute is “intensive”. The
vector values are “extensive”.</p>
<p>The scalar value will be in temperature <a class="reference internal" href="units.html"><span class="doc">units</span></a>. The
vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>The number of core/shell pairs contributing to the temperature is
assumed to be constant for the duration of the run. No fixes should
be used which generate new molecules or atoms during a simulation.</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>.
<p>The temperature is calculated by the formula KE = dim/2 N k T, where
KE = total kinetic energy of the group of atoms (sum of 1/2 m v^2),
dim = dimensionality of the simulation, N = number of atoms in the
group, k = Boltzmann constant, and T = temperature. The calculation
of KE excludes the x, y, or z dimensions if xflag, yflag, or zflag =
0. The dim parameter is adjusted to give the correct number of
degrees of freedom.</p>
<p>A kinetic energy tensor, stored as a 6-element vector, is also
calculated by this compute for use in the calculation of a pressure
tensor. The formula for the components of the tensor is the same as
the above formula, except that v^2 is replaced by vx*vy for the xy
component, etc. The 6 components of the vector are ordered xx, yy,
zz, xy, xz, yz.</p>
<p>The number of atoms contributing to the temperature is assumed to be
constant for the duration of the run; use the <em>dynamic</em> option of the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command if this is not the case.</p>
<p>The removal of velocity components by this fix is essentially
computing the temperature after a “bias” has been removed from the
velocity of the atoms. If this compute is used with a fix command
that performs thermostatting then this bias will be subtracted from
each atom, thermostatting of the remaining thermal velocity will be
performed, and the bias will be added back in. Thermostatting fixes
that work in this way include <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>, <a class="reference internal" href="fix_temp_rescale.html"><span class="doc">fix temp/rescale</span></a>, <a class="reference internal" href="fix_temp_berendsen.html"><span class="doc">fix temp/berendsen</span></a>, and <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>.</p>
<p>This compute subtracts out degrees-of-freedom due to fixes that
constrain molecular motion, such as <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> and
<a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>. This means the temperature of groups of
atoms that include these constraints will be computed correctly. If
needed, the subtracted degrees-of-freedom can be altered using the
<em>extra</em> option of the <a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-16"><span class="std std-ref">this howto section</span></a> of the manual for
a discussion of different ways to compute temperature and perform
thermostatting.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar (the temperature) and a global
vector of length 6 (KE tensor), which can be accessed by indices 1-6.
These values can be used by any command that uses global scalar or
vector values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options.</p>
<p>The scalar value calculated by this compute is “intensive”. The
vector values are “extensive”.</p>
<p>The scalar value will be in temperature <a class="reference internal" href="units.html"><span class="doc">units</span></a>. The
vector values will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</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>.
<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</p>
</li>
<li><p class="first">ti = style name of this compute command</p>
</li>
<li><p class="first">one or more attribute/arg pairs may be appended</p>
</li>
<li><p class="first">keyword = pair style (lj/cut, gauss, born, etc) or <em>tail</em> or <em>kspace</em></p>
<pre class="literal-block">
pair style args = atype v_name1 v_name2
atype = atom type (see asterisk form below)
v_name1 = variable with name1 that is energy scale factor and function of lambda
v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda
<em>tail</em> args = atype v_name1 v_name2
atype = atom type (see asterisk form below)
v_name1 = variable with name1 that is energy tail correction scale factor and function of lambda
v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda
<em>kspace</em> args = atype v_name1 v_name2
atype = atom type (see asterisk form below)
v_name1 = variable with name1 that is K-Space scale factor and function of lambda
v_name2 = variable with name2 that is derivative of v_name1 with respect to lambda
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
compute 1 all ti lj/cut 1 v_lj v_dlj coul/long 2 v_c v_dc kspace 1 v_ks v_dks
compute 1 all ti lj/cut 1*3 v_lj v_dlj coul/long * v_c v_dc kspace * v_ks v_dks
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define a computation that calculates the derivative of the interaction
potential with respect to <em>lambda</em>, the coupling parameter used in a
thermodynamic integration. This derivative can be used to infer a
free energy difference resulting from an alchemical simulation, as
described in <a class="reference internal" href="#eike"><span class="std std-ref">Eike</span></a>.</p>
<p>Typically this compute will be used in conjunction with the <a class="reference internal" href="fix_adapt.html"><span class="doc">fix adapt</span></a> command which can perform alchemical
transformations by adusting the strength of an interaction potential
<p>which is the derivative of the system’s scaled potential energy Us
with respect to <em>lambda</em>.</p>
<p>To perform this calculation, you provide one or more atom types as
<em>atype</em>. <em>Atype</em> can be specified in one of two ways. An explicit
numeric values can be used, as in the 1st example above. Or a
wildcard asterisk can be used in place of or in conjunction with the
<em>atype</em> argument to select multiple atom types. This takes the form
“*” or “*n” or “n*” or “m*n”. If N = the number of atom types, then
an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to N (inclusive). A middle asterisk
means all types from m to n (inclusive).</p>
<p>You also specify two functions, as <a class="reference internal" href="variable.html"><span class="doc">equal-style variables</span></a>. The first is specified as <em>v_name1</em>, where
<em>name1</em> is the name of the variable, and is f(lambda) in the notation
above. The second is specified as <em>v_name2</em>, where <em>name2</em> is the
name of the variable, and is df(lambda) / dlambda in the notation
above. I.e. it is the analytic derivative of f() with respect to
lambda. Note that the <em>name1</em> variable is also typically given as an
argument to the <a class="reference internal" href="fix_adapt.html"><span class="doc">fix adapt</span></a> command.</p>
<p>An alchemical simulation may use several pair potentials together,
invoked via the <a class="reference internal" href="pair_hybrid.html"><span class="doc">pair_style hybrid or hybrid/overlay</span></a>
command. The total dUs/dlambda for the overall system is calculated
as the sum of each contributing term as listed by the keywords in the
compute ti command. Individual pair potentials can be listed, which
will be sub-styles in the hybrid case. You can also include a K-space
term via the <em>kspace</em> keyword. You can also include a pairwise
long-range tail correction to the energy via the <em>tail</em> keyword.</p>
<p>For each term you can specify a different (or the same) scale factor
by the two variables that you list. Again, these will typically
correspond toe the scale factors applied to these various potentials
and the K-Space contribution via the <a class="reference internal" href="fix_adapt.html"><span class="doc">fix adapt</span></a>
command.</p>
<p>More details about the exact functional forms for the computation of
du/dl can be found in the paper by <a class="reference internal" href="#eike"><span class="std std-ref">Eike</span></a>.</p>
<hr class="docutils" />
<p><strong>Output info:</strong></p>
<p>This compute calculates a global scalar, namely dUs/dlambda. This
value can be used by any command that uses a global scalar value from
a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The scalar value calculated by this compute is “extensive”.</p>
<p>The scalar value will be in energy <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the MISC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Define a computation that calculates the torque on multiple chunks of
atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the 3 components of the torque vector for eqch
chunk, due to the forces on the individual atoms in the chunk around
the center-of-mass of the chunk. The calculation includes all effects
due to atoms passing thru periodic boundaries.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The coordinates of an atom contribute to the chunk’s torque in
“unwrapped” form, by using the image flags associated with each atom.
See the <a class="reference internal" href="dump.html"><span class="doc">dump custom</span></a> command for a discussion of
“unwrapped” coordinates. See the Atoms section of the
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command for a discussion of image flags and
how they are set for each atom. You can reset the image flags
(e.g. to 0) before invoking this compute by using the <a class="reference internal" href="set.html"><span class="doc">set image</span></a> command.</p>
</div>
<p>The simplest way to output the results of the compute torque/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
3 for the 3 xyz components of the torque for each chunk. These values
can be accessed by any command that uses global array values from a
compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a>
for an overview of LAMMPS output options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
<p>Define a computation that calculates the center-of-mass velocity for
multiple chunks of atoms.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>This compute calculates the x,y,z components of the center-of-mass
velocity for each chunk. This is done by summing mass*velocity for
each atom in the chunk and dividing the sum by the total mass of the
chunk.</p>
<p>Note that only atoms in the specified group contribute to the
calculation. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command
defines its own group; atoms will have a chunk ID = 0 if they are not
in that group, signifying they are not assigned to a chunk, and will
thus also not contribute to this calculation. You can specify the
“all” group for this command if you simply want to include atoms with
non-zero chunk IDs.</p>
<p>The simplest way to output the results of the compute vcm/chunk
calculation to a file is to use the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>
<p>This compute calculates a global array where the number of rows = the
number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The number of columns =
3 for the x,y,z center-of-mass velocity coordinates of each chunk.
These values can be accessed by any command that uses global array
values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options.</p>
<p>The array values are “intensive”. The array values will be in
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>.
<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command</p>
</li>
<li><p class="first">voronoi/atom = style name of this compute command</p>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>only_group</em> or <em>surface</em> or <em>radius</em> or <em>edge_histo</em> or <em>edge_threshold</em>
or <em>face_threshold</em> or <em>neighbors</em> or <em>peratom</em></p>
<pre class="literal-block">
<em>only_group</em> = no arg
<em>occupation</em> = no arg
<em>surface</em> arg = sgroup-ID
sgroup-ID = compute the dividing surface between group-ID and sgroup-ID
this keyword adds a third column to the compute output
<em>radius</em> arg = v_r
v_r = radius atom style variable for a poly-disperse Voronoi tessellation
<em>edge_histo</em> arg = maxedge
maxedge = maximum number of Voronoi cell edges to be accounted in the histogram
<em>edge_threshold</em> arg = minlength
minlength = minimum length for an edge to be counted
<em>face_threshold</em> arg = minarea
minarea = minimum area for a face to be counted
<em>neighbors</em> value = <em>yes</em> or <em>no</em> = store list of all neighbors or no
<em>peratom</em> value = <em>yes</em> or <em>no</em> = per-atom quantities accessible or no
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
compute 1 all voronoi/atom
compute 2 precipitate voronoi/atom surface matrix
compute 3b precipitate voronoi/atom radius v_r
compute 4 solute voronoi/atom only_group
compute 5 defects voronoi/atom occupation
compute 6 all voronoi/atom neighbors yes
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define a computation that calculates the Voronoi tessellation of the
atoms in the simulation box. The tessellation is calculated using all
atoms in the simulation, but non-zero values are only stored for atoms
in the group.</p>
<p>By default two per-atom quantities are calculated by this compute.
The first is the volume of the Voronoi cell around each atom. Any
point in an atom’s Voronoi cell is closer to that atom than any other.
The second is the number of faces of the Voronoi cell. This is
equal to the number of nearest neighbors of the central atom,
plus any exterior faces (see note below). If the <em>peratom</em> keyword
is set to “no”, the per-atom quantities are still calculated,
but they are not accessible.</p>
<hr class="docutils" />
<p>If the <em>only_group</em> keyword is specified the tessellation is performed
only with respect to the atoms contained in the compute group. This is
equivalent to deleting all atoms not contained in the group prior to
evaluating the tessellation.</p>
<p>If the <em>surface</em> keyword is specified a third quantity per atom is
computed: the Voronoi cell surface of the given atom. <em>surface</em> takes
a group ID as an argument. If a group other than <em>all</em> is specified,
only the Voronoi cell facets facing a neighbor atom from the specified
group are counted towards the surface area.</p>
<p>In the example above, a precipitate embedded in a matrix, only atoms
at the surface of the precipitate will have non-zero surface area, and
only the outward facing facets of the Voronoi cells are counted (the
hull of the precipitate). The total surface area of the precipitate
can be obtained by running a “reduce sum” compute on c_2[3]</p>
<p>If the <em>radius</em> keyword is specified with an atom style variable as
the argument, a poly-disperse Voronoi tessellation is
performed. Examples for radius variables are</p>
<pre class="literal-block">
variable r1 atom (type==1)*0.1+(type==2)*0.4
compute radius all property/atom radius
variable r2 atom c_radius
</pre>
<p>Here v_r1 specifies a per-type radius of 0.1 units for type 1 atoms
and 0.4 units for type 2 atoms, and v_r2 accesses the radius property
present in atom_style sphere for granular models.</p>
<p>The <em>edge_histo</em> keyword activates the compilation of a histogram of
number of edges on the faces of the Voronoi cells in the compute
group. The argument <em>maxedge</em> of the this keyword is the largest number
of edges on a single Voronoi cell face expected to occur in the
sample. This keyword adds the generation of a global vector with
<em>maxedge</em>+1 entries. The last entry in the vector contains the number of
faces with with more than <em>maxedge</em> edges. Since the polygon with the
smallest amount of edges is a triangle, entries 1 and 2 of the vector
will always be zero.</p>
<p>The <em>edge_threshold</em> and <em>face_threshold</em> keywords allow the
suppression of edges below a given minimum length and faces below a
given minimum area. Ultra short edges and ultra small faces can occur
as artifacts of the Voronoi tessellation. These keywords will affect
the neighbor count and edge histogram outputs.</p>
<p>If the <em>occupation</em> keyword is specified the tessellation is only
performed for the first invocation of the compute and then stored.
For all following invocations of the compute the number of atoms in
each Voronoi cell in the stored tessellation is counted. In this mode
the compute returns a per-atom array with 2 columns. The first column
is the number of atoms currently in the Voronoi volume defined by this
atom at the time of the first invocation of the compute (note that the
atom may have moved significantly). The second column contains the
total number of atoms sharing the Voronoi cell of the stored
tessellation at the location of the current atom. Numbers in column
one can be any positive integer including zero, while column two
values will always be greater than zero. Column one data can be used
to locate vacancies (the coordinates are given by the atom coordinates
at the time step when the compute was first invoked), while column two
data can be used to identify interstitial atoms.</p>
<p>If the <em>neighbors</em> value is set to yes, then
this compute creates a local array with 3 columns. There
is one row for each face of each Voronoi cell. The
3 columns are the atom ID of the atom that owns the cell,
the atom ID of the atom in the neighboring cell
(or zero if the face is external), and the area of the face.
The array can be accessed by any command that
uses local values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">this section</span></a> for an overview of LAMMPS output
options. More specifically, the array can be accessed by a
<a class="reference internal" href="dump.html"><span class="doc">dump local</span></a> command to write a file containing
all the Voronoi neighbors in a system:</p>
<pre class="literal-block">
compute 6 all voronoi/atom neighbors yes
dump d2 all local 1 dump.neighbors index c_6[1] c_6[2] c_6[3]
</pre>
<p>If the <em>face_threshold</em> keyword is used, then only faces
with areas greater than the threshold are stored.</p>
<hr class="docutils" />
<p>The Voronoi calculation is performed by the freely available <a class="reference external" href="http://math.lbl.gov/voro++/">Voro++ package</a>, written by Chris Rycroft at UC Berkeley and LBL,
which must be installed on your system when building LAMMPS for use
with this compute. See instructions on obtaining and installing the
Voro++ software in the src/VORONOI/README file.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The calculation of Voronoi volumes is performed by each
processor for the atoms it owns, and includes the effect of ghost
atoms stored by the processor. This assumes that the Voronoi cells of
owned atoms are not affected by atoms beyond the ghost atom cut-off
distance. This is usually a good assumption for liquid and solid
systems, but may lead to underestimation of Voronoi volumes in low
density systems. By default, the set of ghost atoms stored by each
processor is determined by the cutoff used for
<a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> interactions. The cutoff can be set
explicitly via the <a class="reference internal" href="comm_modify.html"><span class="doc">comm_modify cutoff</span></a> command. The
Voronoi cells for atoms adjacent to empty regions will extend into
those regions up to the communication cutoff in x, y, or z. In that
situation, an exterior face is created at the cutoff distance normal
to the x, y, or z direction. For triclinic systems, the exterior face
is parallel to the corresponding reciprocal lattice vector.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The Voro++ package performs its calculation in 3d. This will
still work for a 2d LAMMPS simulation, provided all the atoms have the
same z coordinate. The Voronoi cell of each atom will be a columnar
polyhedron with constant cross-sectional area along the z direction
and two exterior faces at the top and bottom of the simulation box. If
the atoms do not all have the same z coordinate, then the columnar
cells will be accordingly distorted. The cross-sectional area of each
Voronoi cell can be obtained by dividing its volume by the z extent of
the simulation box. Note that you define the z extent of the
<p>By default, this compute calculates a per-atom array with 2
columns. In regular dynamic tessellation mode the first column is the
Voronoi volume, the second is the neighbor count, as described above
(read above for the output data in case the <em>occupation</em> keyword is
specified). These values can be accessed by any command that uses
per-atom values from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">Section 6.15</span></a> for an overview of LAMMPS output
options. If the <em>peratom</em> keyword is set to “no”, the per-atom array
is still created, but it is not accessible.</p>
<p>If the <em>edge_histo</em> keyword is used, then this compute generates a
global vector of length <em>maxedge</em>+1, containing a histogram of the
number of edges per face.</p>
<p>If the <em>neighbors</em> value is set to yes, then this compute calculates a
local array with 3 columns. There is one row for each face of each
Voronoi cell.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Some LAMMPS commands such as the <a class="reference internal" href="compute_reduce.html"><span class="doc">compute reduce</span></a> command can accept either a per-atom or
local quantity. If this compute produces both quantities, the command
may access the per-atom quantity, even if you want to access the local
quantity. This effect can be eliminated by using the <em>peratom</em>
keyword to turn off the production of the per-atom quantities. For
the default value <em>yes</em> both quantities are produced. For the value
<em>no</em>, only the local array is produced.</p>
</div>
<p>The Voronoi cell volume will be in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a> cubed.
The Voronoi face area will be in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a> squared.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This compute is part of the VORONOI package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
-<li><p class="first">type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)</p>
-</li>
-<li><p class="first">style = <em>box</em> or <em>region</em> or <em>single</em> or <em>random</em></p>
+<ul class="simple">
+<li>type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)</li>
+<li>style = <em>box</em> or <em>region</em> or <em>single</em> or <em>random</em></li>
+</ul>
<pre class="literal-block">
<em>box</em> args = none
<em>region</em> args = region-ID
region-ID = particles will only be created if contained in the region
<em>single</em> args = x y z
x,y,z = coordinates of a single particle (distance units)
<em>random</em> args = N seed region-ID
N = number of particles to create
seed = random # seed (positive integer)
region-ID = create atoms within this region, use NULL for entire simulation box
</pre>
-</li>
-<li><p class="first">zero or more keyword/value pairs may be appended</p>
-</li>
-<li><p class="first">keyword = <em>mol</em> or <em>basis</em> or <em>remap</em> or <em>var</em> or <em>set</em> or <em>units</em></p>
+<ul class="simple">
+<li>zero or more keyword/value pairs may be appended</li>
+<li>keyword = <em>mol</em> or <em>basis</em> or <em>remap</em> or <em>var</em> or <em>set</em> or <em>units</em></li>
+</ul>
<pre class="literal-block">
<em>mol</em> value = template-ID seed
template-ID = ID of molecule template specified in a separate <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command
seed = random # seed (positive integer)
<em>basis</em> values = M itype
M = which basis atom
itype = atom type (1-N) to assign to this basis atom
<em>remap</em> value = <em>yes</em> or <em>no</em>
<em>var</em> value = name = variable name to evaluate for test of atom creation
<em>set</em> values = dim name
dim = <em>x</em> or <em>y</em> or <em>z</em>
name = name of variable to set with x, y, or z atom position
<em>rotate</em> values = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees)
<em>units</em> value = <em>lattice</em> or <em>box</em>
<em>lattice</em> = the geometry is defined in lattice units
<em>box</em> = the geometry is defined in simulation box units
</pre>
-</li>
-</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>This command creates atoms (or molecules) on a lattice, or a single
atom (or molecule), or a random collection of atoms (or molecules), as
an alternative to reading in their coordinates explicitly via a
command. A simulation box must already exist, which is typically
created via the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command. Before using
this command, a lattice must also be defined using the
<a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command, unless you specify the <em>single</em> style
with units = box or the <em>random</em> style. For the remainder of this doc
page, a created atom or molecule is referred to as a “particle”.</p>
<p>If created particles are individual atoms, they are assigned the
specified atom <em>type</em>, though this can be altered via the <em>basis</em>
keyword as discussed below. If molecules are being created, the type
of each atom in the created molecule is specified in the file read by
the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command, and those values are added to
the specified atom <em>type</em>. E.g. if <em>type</em> = 2, and the file specifies
atom types 1,2,3, then each created molecule will have atom types
3,4,5.</p>
<p>For the <em>box</em> style, the create_atoms command fills the entire
simulation box with particles on the lattice. If your simulation box
is periodic, you should insure its size is a multiple of the lattice
spacings, to avoid unwanted atom overlaps at the box boundaries. If
your box is periodic and a multiple of the lattice spacing in a
particular dimension, LAMMPS is careful to put exactly one particle at
the boundary (on either side of the box), not zero or two.</p>
<p>For the <em>region</em> style, a geometric volume is filled with particles on
the lattice. This volume what is inside the simulation box and is
also consistent with the region volume. See the <a class="reference internal" href="region.html"><span class="doc">region</span></a>
command for details. Note that a region can be specified so that its
“volume” is either inside or outside a geometric boundary. Also note
that if your region is the same size as a periodic simulation box (in
some dimension), LAMMPS does not implement the same logic described
above as for the <em>box</em> style, to insure exactly one particle at
periodic boundaries. if this is what you desire, you should either
use the <em>box</em> style, or tweak the region size to get precisely the
particles you want.</p>
<p>For the <em>single</em> style, a single particle is added to the system at
the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.</p>
<p>For the <em>random</em> style, N particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
speficied random number <em>seed</em>, resulting in the same set of particles
coordinates, independent of how many processors are being used in the
simulation. If the <em>region-ID</em> argument is specified as NULL, then
the created particles will be anywhere in the simulation box. If a
<em>region-ID</em> is specified, a geometric volume is filled which is both
inside the simulation box and is also consistent with the region
volume. See the <a class="reference internal" href="region.html"><span class="doc">region</span></a> command for details. Note that
a region can be specified so that its “volume” is either inside or
outside a geometric boundary.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Particles generated by the <em>random</em> style will typically be
highly overlapped which will cause many interatomic potentials to
compute large energies and forces. Thus you should either perform an
<a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a> or run dynamics with <a class="reference internal" href="fix_nve_limit.html"><span class="doc">fix nve/limit</span></a> to equilibrate such a system, before
running normal dynamics.</p>
</div>
<p>Note that this command adds particles to those that already exist.
This means it can be used to add particles to a system previously read
in from a data or restart file. Or the create_atoms command can be
used multiple times, to add multiple sets of particles to the
simulation. For example, grain boundaries can be created, by
interleaving create_atoms with <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> commands
specifying different orientations. By using the create_atoms command
in conjunction with the <a class="reference internal" href="delete_atoms.html"><span class="doc">delete_atoms</span></a> command,
reasonably complex geometries can be created, or a protein can be
solvated with a surrounding box of water molecules.</p>
<p>In all these cases, care should be taken to insure that new atoms do
not overlap existing atoms inappropriately, especially if molecules
are being added. The <a class="reference internal" href="delete_atoms.html"><span class="doc">delete_atoms</span></a> command can be
used to remove overlapping atoms or molecules.</p>
<hr class="docutils" />
<p>Individual atoms are inserted by this command, unless the <em>mol</em>
keyword is used. It specifies a <em>template-ID</em> previously defined
using the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command, which reads a file that
defines the molecule. The coordinates, atom types, charges, etc, as
well as any bond/angle/etc and special neighbor information for the
molecule can be specified in the molecule file. See the
<a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command for details. The only settings
required to be in this file are the coordinates and types of atoms in
the molecule.</p>
<p>Using a lattice to add molecules, e.g. via the <em>box</em> or <em>region</em> or
<em>single</em> styles, is exactly the same as adding atoms on lattice
points, except that entire molecules are added at each point, i.e. on
the point defined by each basis atom in the unit cell as it tiles the
simulation box or region. This is done by placing the geometric
center of the molecule at the lattice point, and giving the molecule a
random orientation about the point. The random <em>seed</em> specified with
the <em>mol</em> keyword is used for this operation, and the random numbers
generated by each processor are different. This means the coordinates
of individual atoms (in the molecules) will be different when running
on different numbers of processors, unlike when atoms are being
created in parallel.</p>
<p>Also note that because of the random rotations, it may be important to
use a lattice with a large enough spacing that adjacent molecules will
not overlap, regardless of their relative orientations.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command is used to create
the simulation box, followed by the create_atoms command with its
<em>mol</em> option for adding molecules, then you typically need to use the
optional keywords allowed by the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command
for extra bonds (angles,etc) or extra special neighbors. This is
because by default, the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command sets up a
non-molecular system which doesn’t allow molecules to be added.</p>
</div>
<hr class="docutils" />
<p>This is the meaning of the other allowed keywords.</p>
<p>The <em>basis</em> keyword is only used when atoms (not molecules) are being
created. It specifies an atom type that will be assigned to specific
basis atoms as they are created. See the <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a>
command for specifics on how basis atoms are defined for the unit cell
of the lattice. By default, all created atoms are assigned the
argument <em>type</em> as their atom type.</p>
<p>The <em>remap</em> keyword only applies to the <em>single</em> style. If it is set
to <em>yes</em>, then if the specified position is outside the simulation
box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to <em>no</em>, no remapping is done
and no particle is created if its position is outside the box.</p>
<p>The <em>var</em> and <em>set</em> keywords can be used together to provide a
criterion for accepting or rejecting the addition of an individual
atom, based on its coordinates. The <em>name</em> specified for the <em>var</em>
keyword is the name of an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> which
should evaluate to a zero or non-zero value based on one or two or
three variables which will store the x, y, or z coordinates of an atom
(one variable per coordinate). If used, these other variables must be
<a class="reference internal" href="variable.html"><span class="doc">internal-style variables</span></a> defined in the input script;
their initial numeric value can be anything. They must be
internal-style variables, because this command resets their values
directly. The <em>set</em> keyword is used to identify the names of these
other variables, one variable for the x-coordinate of a created atom,
one for y, and one for z.</p>
<p>When an atom is created, its x,y,z coordinates become the values for
any <em>set</em> variable that is defined. The <em>var</em> variable is then
evaluated. If the returned value is 0.0, the atom is not created. If
it is non-zero, the atom is created.</p>
<p>As an example, these commands can be used in a 2d simulation, to
create a sinusoidal surface. Note that the surface is “rough” due to
individual lattice points being “above” or “below” the mathematical
expression for the sinusoidal curve. If a finer lattice were used,
the sinusoid would appear to be “smoother”. Also note the use of the
“xlat” and “ylat” <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> keywords which
converts lattice spacings to distance. Click on the image for a
</a><p>The <em>rotate</em> keyword can be used with the <em>single</em> style, when adding
a single molecule to specify the orientation at which the molecule is
inserted. The axis of rotation is determined by the rotation vector
(Rx,Ry,Rz) that goes through the insertion point. The specified
<em>theta</em> determines the angle of rotation around that axis. Note that
the direction of rotation for the atoms around the rotation axis is
consistent with the right-hand rule: if your right-hand’s thumb points
along <em>R</em>, then your fingers wrap around the axis in the direction of
rotation.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the <em>single</em>
style. A <em>box</em> value selects standard distance units as defined by
the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or
metal. A <em>lattice</em> value means the distance units are in lattice
spacings.</p>
<hr class="docutils" />
<p>Atom IDs are assigned to created atoms in the following way. The
collection of created atoms are assigned consecutive IDs that start
immediately following the largest atom ID existing before the
create_atoms command was invoked. When a simulation is performed on
different numbers of processors, there is no guarantee a particular
created atom will be assigned the same ID. If molecules are being
created, molecule IDs are assigned to created molecules in a similar
fashion.</p>
<p>Aside from their ID, atom type, and xyz position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen <a class="reference internal" href="atom_style.html"><span class="doc">atom style</span></a>. See the <a class="reference internal" href="atom_style.html"><span class="doc">atom style</span></a> command for more details. See the
<a class="reference internal" href="set.html"><span class="doc">set</span></a> and <a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> commands for info on how
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>.
<li><p class="first">N = # of atom types to use in this simulation</p>
</li>
<li><p class="first">region-ID = ID of region to use as simulation domain</p>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>bond/types</em> or <em>angle/types</em> or <em>dihedral/types</em> or <em>improper/types</em> or <em>extra/bond/per/atom</em> or <em>extra/angle/per/atom</em> or <em>extra/dihedral/per/atom</em> or <em>extra/improper/per/atom</em></p>
<pre class="literal-block">
<em>bond/types</em> value = # of bond types
<em>angle/types</em> value = # of angle types
<em>dihedral/types</em> value = # of dihedral types
<em>improper/types</em> value = # of improper types
<em>extra/bond/per/atom</em> value = # of bonds per atom
<em>extra/angle/per/atom</em> value = # of angles per atom
<em>extra/dihedral/per/atom</em> value = # of dihedrals per atom
<em>extra/improper/per/atom</em> value = # of impropers per atom
<em>extra/special/per/atom</em> value = # of special neighbors per atom
<p>This command creates a simulation box based on the specified region.
Thus a <a class="reference internal" href="region.html"><span class="doc">region</span></a> command must first be used to define a
geometric domain. It also partitions the simulation box into a
regular 3d grid of rectangular bricks, one per processor, based on the
number of processors being used and the settings of the
<a class="reference internal" href="processors.html"><span class="doc">processors</span></a> command. The partitioning can later be
changed by the <a class="reference internal" href="balance.html"><span class="doc">balance</span></a> or <a class="reference internal" href="fix_balance.html"><span class="doc">fix balance</span></a> commands.</p>
<p>The argument N is the number of atom types that will be used in the
simulation.</p>
<p>If the region is not of style <em>prism</em>, then LAMMPS encloses the region
(block, sphere, etc) with an axis-aligned orthogonal bounding box
which becomes the simulation domain.</p>
<p>If the region is of style <em>prism</em>, LAMMPS creates a non-orthogonal
simulation domain shaped as a parallelepiped with triclinic symmetry.
As defined by the <a class="reference internal" href="region.html"><span class="doc">region prism</span></a> command, the
parallelepiped has its “origin” at (xlo,ylo,zlo) and is defined by 3
edge vectors starting from the origin given by A = (xhi-xlo,0,0); B =
(xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). <em>Xy,xz,yz</em> can be 0.0 or
positive or negative values and are called “tilt factors” because they
are the amount of displacement applied to faces of an originally
orthogonal box to transform it into the parallelipiped.</p>
<p>By default, a <em>prism</em> region used with the create_box command must
have tilt factors (xy,xz,yz) that do not skew the box more than half
the distance of the parallel box length. For example, if xlo = 2 and
xhi = 12, then the x box length is 10 and the xy tilt factor must be
between -5 and 5. Similarly, both xz and yz must be between
-(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation,
since if the maximum tilt factor is 5 (as in this example), then
configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all
geometrically equivalent. If you wish to define a box with tilt
factors that exceed these limits, you can use the <a class="reference internal" href="box.html"><span class="doc">box tilt</span></a>
command, with a setting of <em>large</em>; a setting of <em>small</em> is the
default.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">Section 6.12</span></a> of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.</p>
<p>When a prism region is used, the simulation domain should normally be
periodic in the dimension that the tilt is applied to, which is given
by the second dimension of the tilt factor (e.g. y for xy tilt). This
is so that pairs of atoms interacting across that boundary will have
one of them shifted by the tilt factor. Periodicity is set by the
<a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command. For example, if the xy tilt factor
is non-zero, then the y dimension should be periodic. Similarly, the
z dimension should be periodic if xz or yz is non-zero. LAMMPS does
not require this periodicity, but you may lose atoms if this is not
the case.</p>
<p>Also note that if your simulation will tilt the box, e.g. via the <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> command, the simulation box must be setup to
be triclinic, even if the tilt factors are initially 0.0. You can
also change an orthogonal box to a triclinic box or vice versa by
using the <a class="reference internal" href="change_box.html"><span class="doc">change box</span></a> command with its <em>ortho</em> and
<em>triclinic</em> options.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the system is non-periodic (in a dimension), then you should
not make the lo/hi box dimensions (as defined in your
<a class="reference internal" href="region.html"><span class="doc">region</span></a> command) radically smaller/larger than the extent
of the atoms you eventually plan to create, e.g. via the
<a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> command. For example, if your atoms
extend from 0 to 50, you should not specify the box bounds as -10000
and 10000. This is because as described above, LAMMPS uses the
specified box size to layout the 3d grid of processors. A huge
(mostly empty) box will be sub-optimal for performance when using
“fixed” boundary conditions (see the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a>
command). When using “shrink-wrap” boundary conditions (see the
<a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command), a huge (mostly empty) box may cause
a parallel simulation to lose atoms the first time that LAMMPS
shrink-wraps the box around the atoms.</p>
</div>
<hr class="docutils" />
<p>The optional keywords can be used to create a system that allows for
bond (angle, dihedral, improper) interactions, or for molecules with
special 1-2,1-3,1-4 neighbors to be added later. These optional
keywords serve the same purpose as the analogous keywords that can be
used in a data file which are recognized by the
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command when it sets up a system.</p>
<p>Note that if these keywords are not used, then the create_box command
creates an atomic (non-molecular) simulation that does not allow bonds
between pairs of atoms to be defined, or a <a class="reference internal" href="bond_style.html"><span class="doc">bond potential</span></a> to be specified, or for molecules with
special neighbors to be added to the system by commands such as
or <a class="reference internal" href="fix_pour.html"><span class="doc">fix pour</span></a>.</p>
<p>As an example, see the examples/deposit/in.deposit.molecule script,
which deposits molecules onto a substrate. Initially there are no
molecules in the system, but they are added later by the <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a> command. The create_box command in the
script uses the bond/types and extra/bond/per/atom keywords to allow
this. If the added molecule contained more than 1 special bond
(allowed by default), an extra/special/per/atom keyword would also
need to be specified.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>An <a class="reference internal" href="atom_style.html"><span class="doc">atom_style</span></a> and <a class="reference internal" href="region.html"><span class="doc">region</span></a> must have
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>.
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>.
<p>A section begins with a non-blank line whose 1st character is not a
“#”; blank lines or lines starting with “#” can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the
<a class="reference internal" href="dihedral_coeff.html"><span class="doc">dihedral_coeff</span></a> command. The next line lists (in
any order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.</p>
<p>Following a blank line, the next N lines list the tabulated values. On
each line, the 1st value is the index from 1 to N, the 2nd value is
the angle value, the 3rd value is the energy (in energy units), and
the 4th is -dE/d(phi) also in energy units). The 3rd term is the
energy of the 4-atom configuration for the specified angle. The 4th
term (when present) is the negative derivative of the energy with
respect to the angle (in degrees, or radians depending on whether the
user selected DEGREES or RADIANS). Thus the units of the last term
are still energy, not force. The dihedral angle values must increase
from one line to the next.</p>
<p>Dihedral table splines are cyclic. There is no discontinuity at 180
degrees (or at any other angle). Although in the examples above, the
angles range from -180 to 180 degrees, in general, the first angle in
the list can have any value (positive, zero, or negative). However
the <em>range</em> of angles represented in the table must be <em>strictly</em> less
than 360 degrees (2pi radians) to avoid angle overlap. (You may not
supply entries in the table for both 180 and -180, for example.) If
the user’s table covers only a narrow range of dihedral angles,
strange numerical behavior can occur in the large remaining gap.</p>
<p><strong>Parameters:</strong></p>
<p>The parameter “N” is required and its value is the number of table
entries that follow. Note that this may be different than the N
specified in the <a class="reference internal" href="dihedral_style.html"><span class="doc">dihedral_style table</span></a> command.
Let <em>Ntable</em> is the number of table entries requested dihedral_style
command, and let <em>Nfile</em> be the parameter following “N” in the
tabulated file (“30” in the sparse example above). What LAMMPS does
is a preliminary interpolation by creating splines using the <em>Nfile</em>
tabulated values as nodal points. It uses these to interpolate as
needed to generate energy and derivative values at <em>Ntable</em> different
points (which are evenly spaced over a 360 degree range, even if the
angles in the file are not). The resulting tables of length <em>Ntable</em>
are then used as described above, when computing energy and force for
individual dihedral angles and their atoms. This means that if you
want the interpolation tables of length <em>Ntable</em> to match exactly what
is in the tabulated file (with effectively nopreliminary
interpolation), you should set <em>Ntable</em> = <em>Nfile</em>. To insure the
nodal points in the user’s file are aligned with the interpolated
table entries, the angles in the table should be integer multiples of
360/<em>Ntable</em> degrees, or 2*PI/<em>Ntable</em> radians (depending on your
choice of angle units).</p>
<p>The optional “NOF” keyword allows the user to omit the forces
(negative energy derivatives) from the table file (normally located in
the 4th column). In their place, forces will be calculated
automatically by differentiating the potential energy function
indicated by the 3rd column of the table (using either linear or
spline interpolation).</p>
<p>The optional “DEGREES” keyword allows the user to specify angles in
degrees instead of radians (default).</p>
<p>The optional “RADIANS” keyword allows the user to specify angles in
radians instead of degrees. (Note: This changes the way the forces
are scaled in the 4th column of the data file.)</p>
<p>The optional “CHECKU” keyword is followed by a filename. This allows
the user to save all of the the <em>Ntable</em> different entries in the
interpolated energy table to a file to make sure that the interpolated
function agrees with the user’s expectations. (Note: You can
temporarily increase the <em>Ntable</em> parameter to a high value for this
purpose. “<em>Ntable</em>” is explained above.)</p>
<p>The optional “CHECKF” keyword is analogous to the “CHECKU” keyword.
It is followed by a filename, and it allows the user to check the
interpolated force table. This option is available even if the user
selected the “NOF” option.</p>
<p>Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds one
that matches the specified keyword.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-6"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This dihedral style can only be used if LAMMPS was built with the
USER-MISC package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a>
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>.
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>.
<li><p class="first">ID = user-assigned name for the dump</p>
</li>
<li><p class="first">group-ID = ID of the group of atoms to be dumped</p>
</li>
<li><p class="first">style = <em>atom</em> or <em>atom/gz</em> or <em>atom/mpiio</em> or <em>cfg</em> or <em>cfg/gz</em> or <em>cfg/mpiio</em> or <em>dcd</em> or <em>xtc</em> or <em>xyz</em> or <em>xyz/gz</em> or <em>xyz/mpiio</em> or <em>h5md</em> or <em>image</em> or <em>movie</em> or <em>molfile</em> or <em>local</em> or <em>custom</em> or <em>custom/gz</em> or <em>custom/mpiio</em></p>
</li>
<li><p class="first">N = dump every this many timesteps</p>
</li>
<li><p class="first">file = name of file to write dump info to</p>
</li>
<li><p class="first">args = list of arguments for a particular style</p>
<pre class="literal-block">
<em>atom</em> args = none
<em>atom/gz</em> args = none
<em>atom/mpiio</em> args = none
<em>cfg</em> args = same as <em>custom</em> args, see below
<em>cfg/gz</em> args = same as <em>custom</em> args, see below
<em>cfg/mpiio</em> args = same as <em>custom</em> args, see below
<em>dcd</em> args = none
<em>xtc</em> args = none
<em>xyz</em> args = none
</pre>
<pre class="literal-block">
<em>xyz/gz</em> args = none
</pre>
<pre class="literal-block">
<em>xyz/mpiio</em> args = none
</pre>
<pre class="literal-block">
<em>custom/vtk</em> args = similar to custom args below, discussed on <a class="reference internal" href="dump_custom_vtk.html"><span class="doc">dump custom/vtk</span></a> doc page
possible attributes = index, c_ID, c_ID[I], f_ID, f_ID[I]
index = enumeration of local values
c_ID = local vector calculated by a compute with ID
c_ID[I] = Ith column of local array calculated by a compute with ID, I can include wildcard (see below)
f_ID = local vector calculated by a fix with ID
f_ID[I] = Ith column of local array calculated by a fix with ID, I can include wildcard (see below)
</pre>
<pre class="literal-block">
<em>custom</em> or <em>custom/gz</em> or <em>custom/mpiio</em> args = list of atom attributes
possible attributes = id, mol, proc, procp1, type, element, mass,
x, y, z, xs, ys, zs, xu, yu, zu,
xsu, ysu, zsu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
c_ID, c_ID[N], f_ID, f_ID[N], v_name
</pre>
<pre class="literal-block">
id = atom ID
mol = molecule ID
proc = ID of processor that owns atom
procp1 = ID+1 of processor that owns atom
type = atom type
element = name of atom element, as defined by <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command
mass = atom mass
x,y,z = unscaled atom coordinates
xs,ys,zs = scaled atom coordinates
xu,yu,zu = unwrapped atom coordinates
xsu,ysu,zsu = scaled unwrapped atom coordinates
ix,iy,iz = box image that the atom is in
vx,vy,vz = atom velocities
fx,fy,fz = forces on atoms
q = atom charge
mux,muy,muz = orientation of dipole moment of atom
mu = magnitude of dipole moment of atom
radius,diameter = radius,diameter of spherical particle
omegax,omegay,omegaz = angular velocity of spherical particle
angmomx,angmomy,angmomz = angular momentum of aspherical particle
tqx,tqy,tqz = torque on finite-size particles
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below)
v_name = per-atom vector calculated by an atom-style variable with name
d_name = per-atom floating point vector with name, managed by fix property/atom
i_name = per-atom integer vector with name, managed by fix property/atom
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
dump myDump all atom 100 dump.atom
dump myDump all atom/mpiio 100 dump.atom.mpiio
dump myDump all atom/gz 100 dump.atom.gz
dump 2 subgroup atom 50 dump.run.bin
dump 2 subgroup atom 50 dump.run.mpiio.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
dump 4b flow custom 100 dump.%.myforce id type c_myF[*] v_ke
dump 2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz
dump snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress[2]
dump 1 all xtc 1000 file.xtc
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Dump a snapshot of atom quantities to one or more files every N
timesteps in one of several styles. The <em>image</em> and <em>movie</em> styles are
the exception: the <em>image</em> style renders a JPG, PNG, or PPM image file
of the atom configuration every N timesteps while the <em>movie</em> style
combines and compresses them into a movie file; both are discussed in
detail on the <a class="reference internal" href="dump_image.html"><span class="doc">dump image</span></a> doc page. The timesteps on
which dump output is written can also be controlled by a variable.
See the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify every</span></a> command.</p>
<p>Only information for atoms in the specified group is dumped. The
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify thresh and region</span></a> commands can also
alter what atoms are included. Not all styles support all these
options; see details below.</p>
<p>As described below, the filename determines the kind of output (text
or binary or gzipped, one big file or one per timestep, one big file
or multiple smaller files).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because periodic boundary conditions are enforced only on
timesteps when neighbor lists are rebuilt, the coordinates of an atom
written to a dump file may be slightly outside the simulation box.
Re-neighbor timesteps will not typically coincide with the timesteps
dump snapshots are written. See the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify pbc</span></a> command if you with to force coordinates to be
strictly inside the simulation box.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unless the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify sort</span></a> option is
invoked, the lines of atom information written to dump files
(typically one line per atom) will be in an indeterminate order for
each snapshot. This is even true when running on a single processor,
if the <a class="reference internal" href="atom_modify.html"><span class="doc">atom_modify sort</span></a> option is on, which it is
by default. In this case atoms are re-ordered periodically during a
simulation, due to spatial sorting. It is also true when running in
parallel, because data for a single snapshot is collected from
multiple processors, each of which owns a subset of the atoms.</p>
</div>
<p>For the <em>atom</em>, <em>custom</em>, <em>cfg</em>, and <em>local</em> styles, sorting is off by
default. For the <em>dcd</em>, <em>xtc</em>, <em>xyz</em>, and <em>molfile</em> styles, sorting by
atom ID is on by default. See the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> doc
page for details.</p>
<p>The <em>atom/gz</em>, <em>cfg/gz</em>, <em>custom/gz</em>, and <em>xyz/gz</em> styles are identical
in command syntax to the corresponding styles without “gz”, however,
they generate compressed files using the zlib library. Thus the filename
suffix ”.gz” is mandatory. This is an alternative approach to writing
compressed files via a pipe, as done by the regular dump styles, which
may be required on clusters where the interface to the high-speed network
disallows using the fork() library call (which is needed for a pipe).
For the remainder of this doc page, you should thus consider the <em>atom</em>
and <em>atom/gz</em> styles (etc) to be inter-changeable, with the exception
of the required filename suffix.</p>
<p>As explained below, the <em>atom/mpiio</em>, <em>cfg/mpiio</em>, <em>custom/mpiio</em>, and
<em>xyz/mpiio</em> styles are identical in command syntax and in the format
of the dump files they create, to the corresponding styles without
“mpiio”, except the single dump file they produce is written in
parallel via the MPI-IO library. For the remainder of this doc page,
you should thus consider the <em>atom</em> and <em>atom/mpiio</em> styles (etc) to
be inter-changeable. The one exception is how the filename is
specified for the MPI-IO styles, as explained below.</p>
<p>The precision of values output to text-based dump files can be
controlled by the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify format</span></a> command and
its options.</p>
<hr class="docutils" />
<p>The <em>style</em> keyword determines what atom quantities are written to the
file and in what format. Settings made via the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command can also alter the format of
individual values and the file itself.</p>
<p>The <em>atom</em>, <em>local</em>, and <em>custom</em> styles create files in a simple text
format that is self-explanatory when viewing a dump file. Many of the
LAMMPS <a class="reference internal" href="Section_tools.html"><span class="doc">post-processing tools</span></a>, including
<a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a>, work with this
format, as does the <a class="reference internal" href="rerun.html"><span class="doc">rerun</span></a> command.</p>
<p>For post-processing purposes the <em>atom</em>, <em>local</em>, and <em>custom</em> text
files are self-describing in the following sense.</p>
<p>The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:</p>
<p>where xlo,xhi are the maximum extents of the simulation box in the
x-dimension, and similarly for y and z. The “xx yy zz” represent 6
characters that encode the style of boundary for each of the 6
simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each of
the 6 characters is either p = periodic, f = fixed, s = shrink wrap,
or m = shrink wrapped with a minimum value. See the
<a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command for details.</p>
<p>For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
formatted as follows:</p>
<pre class="literal-block">
ITEM: BOX BOUNDS xy xz yz xx yy zz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz
</pre>
<p>The presence of the text “xy xz yz” in the ITEM line indicates that
the 3 tilt factors will be included on each of the 3 following lines.
This bounding box is convenient for many visualization programs. The
meaning of the 6 character flags for “xx yy zz” is the same as above.</p>
<p>Note that the first two numbers on each line are now xlo_bound instead
of xlo, etc, since they repesent a bounding box. See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">this section</span></a> of the doc pages for a geometric
description of triclinic boxes, as defined by LAMMPS, simple formulas
for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) are
calculated from the triclinic parameters, and how to transform those
parameters to and from other commonly used triclinic representations.</p>
<p>The “ITEM: ATOMS” line in each snapshot lists column descriptors for
the per-atom lines that follow. For example, the descriptors would be
“id type xs ys zs” for the default <em>atom</em> style, and would be the atom
attributes you specify in the dump command for the <em>custom</em> style.</p>
<p>For style <em>atom</em>, atom coordinates are written to the file, along with
the atom ID and atom type. By default, atom coords are written in a
scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom
is at a location 1/4 of the distance from xlo to xhi of the box
boundaries. The format can be changed to unscaled coords via the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> settings. Image flags can also be
added for each atom via dump_modify.</p>
<p>Style <em>custom</em> allows you to specify a list of atom attributes to be
written to the dump file for each atom. Possible attributes are
listed above and will appear in the order specified. You cannot
specify a quantity that is not defined for a particular simulation -
such as <em>q</em> for atom style <em>bond</em>, since that atom style doesn’t
assign charges. Dumps occur at the very end of a timestep, so atom
attributes will include effects due to fixes that are applied during
the timestep. An explanation of the possible dump custom attributes
is given below.</p>
<p>For style <em>local</em>, local output generated by <a class="reference internal" href="compute.html"><span class="doc">computes</span></a>
and <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a> is used to generate lines of output that is
written to the dump file. This local data is typically calculated by
each processor based on the atoms it owns, but there may be zero or
more entities per atom, e.g. a list of bond distances. An explanation
of the possible dump local attributes is given below. Note that by
using input from the <a class="reference internal" href="compute_property_local.html"><span class="doc">compute property/local</span></a> command with dump local,
it is possible to generate information on bonds, angles, etc that can
be cut and pasted directly into a data file read by the
The precision used in XTC files can be adjusted via the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command. The default value of 1000
means that coordinates are stored to 1/1000 nanometer accuracy. XTC
files are portable binary files written in the NFS XDR data format,
so that any machine which supports XDR should be able to read them.
The number of atoms per snapshot cannot change with the <em>xtc</em> style.
The <em>unwrap</em> option of the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command allows
XTC coordinates to be written “unwrapped” by the image flags for each
atom. Unwrapped means that if the atom has passed thru a periodic
boundary one or more times, the value is printed for what the
coordinate would be if it had not been wrapped back into the periodic
box. Note that these coordinates may thus be far outside the box size
stored with the snapshot.</p>
<p>The <em>xyz</em> style writes XYZ files, which is a simple text-based
coordinate format that many codes can read. Specifically it has
a line with the number of atoms, then a comment line that is
usually ignored followed by one line per atom with the atom type
and the x-, y-, and z-coordinate of that atom. You can use the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify element</span></a> option to change the output
from using the (numerical) atom type to an element name (or some
other label). This will help many visualization programs to guess
bonds and colors.</p>
<p>Note that <em>atom</em>, <em>custom</em>, <em>dcd</em>, <em>xtc</em>, and <em>xyz</em> style dump files
can be read directly by <a class="reference external" href="http://www.ks.uiuc.edu/Research/vmd">VMD</a>, a
popular molecular viewing program. See <a class="reference internal" href="Section_tools.html#vmd"><span class="std std-ref">Section tools</span></a> of the manual and the
tools/lmp2vmd/README.txt file for more information about support in
VMD for reading and visualizing LAMMPS dump files.</p>
<hr class="docutils" />
<p>Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify first</span></a> command, which
can also be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify every</span></a> command (not allowed
for <em>dcd</em> style). The <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify every</span></a> command
also allows a variable to be used to determine the sequence of
timesteps on which dump files are written. In this mode a dump on the
first timestep of a run will also not be written unless the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify first</span></a> command is used.</p>
<p>The specified filename determines how the dump file(s) is written.
The default is to write one large text file, which is opened when the
dump command is invoked and closed when an <a class="reference internal" href="undump.html"><span class="doc">undump</span></a>
command is used or when LAMMPS exits. For the <em>dcd</em> and <em>xtc</em> styles,
this is a single large binary file.</p>
<p>Dump filenames can contain two wildcard characters. If a “*”
character appears in the filename, then one file per snapshot is
written and the “*” character is replaced with the timestep value.
For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc. This option is not available for the <em>dcd</em> and
<em>xtc</em> styles. Note that the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify pad</span></a>
command can be used to insure all timestep numbers are the same length
(e.g. 00010), which can make it easier to read a series of dump files
in order with some post-processing tools.</p>
<p>If a “%” character appears in the filename, then each of P processors
writes a portion of the dump file, and the “%” character is replaced
with the processor ID from 0 to P-1. For example, tmp.dump.% becomes
tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller
files and can be a fast mode of output on parallel machines that
support parallel I/O for output. This option is not available for the
<em>dcd</em>, <em>xtc</em>, and <em>xyz</em> styles.</p>
<p>By default, P = the number of processors meaning one file per
processor, but P can be set to a smaller value via the <em>nfile</em> or
<em>fileper</em> keywords of the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command.
These options can be the most efficient way of writing out dump files
when running on large numbers of processors.</p>
<p>Note that using the “*” and “%” characters together can produce a
large number of small dump files!</p>
<p>For the <em>atom/mpiio</em>, <em>cfg/mpiio</em>, <em>custom/mpiio</em>, and <em>xyz/mpiio</em>
styles, a single dump file is written in parallel via the MPI-IO
library, which is part of the MPI standard for versions 2.0 and above.
Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO
<span class="n">make</span> <span class="n">g</span><span class="o">++</span> <span class="c1"># build LAMMPS for your platform</span>
</pre></div>
</div>
<p>Second, use a dump filename which contains ”.mpiio”. Note that it
does not have to end in ”.mpiio”, just contain those characters.
Unlike MPI-IO restart files, which must be both written and read using
MPI-IO, the dump files produced by these MPI-IO styles are identical
in format to the files produced by their non-MPI-IO style
counterparts. This means you can write a dump file using MPI-IO and
use the <a class="reference internal" href="read_dump.html"><span class="doc">read_dump</span></a> command or perform other
post-processing, just as if the dump file was not written using
MPI-IO.</p>
<p>Note that MPI-IO dump files are one large file which all processors
write to. You thus cannot use the “%” wildcard character described
above in the filename since that specifies generation of multiple
files. You can use the ”.bin” suffix described below in an MPI-IO
dump file; again this file will be written in parallel and have the
same binary format as if it were written without MPI-IO.</p>
<p>If the filename ends with ”.bin”, the dump file (or files, if “*” or
“%” is also used) is written in binary format. A binary dump file
will be about the same size as a text version, but will typically
write out much faster. Of course, when post-processing, you will need
to convert it back to text format (see the <a class="reference internal" href="Section_tools.html#binary"><span class="std std-ref">binary2txt tool</span></a>) or write your own code to read the
binary file. The format of the binary file can be understood by
looking at the tools/binary2txt.cpp file. This option is only
available for the <em>atom</em> and <em>custom</em> styles.</p>
<p>If the filename ends with ”.gz”, the dump file (or files, if “*” or “%”
is also used) is written in gzipped format. A gzipped dump file will
be about 3x smaller than the text version, but will also take longer
to write. This option is not available for the <em>dcd</em> and <em>xtc</em>
styles.</p>
<hr class="docutils" />
<p>Note that in the discussion which follows, for styles which can
reference values from a compute or fix, like the <em>custom</em>, <em>cfg</em>, or
<em>local</em> styles, the bracketed index I can be specified using a
wildcard asterisk with the index to effectively specify multiple
values. This takes the form “*” or “*n” or “n*” or “m*n”. If N = the
size of the vector (for <em>mode</em> = scalar) or the number of columns in
the array (for <em>mode</em> = vector), then an asterisk with no numeric
values means all indices from 1 to N. A leading asterisk means all
indices from 1 to n (inclusive). A trailing asterisk means all
indices from n to N (inclusive). A middle asterisk means all indices
from m to n (inclusive).</p>
<p>Using a wildcard is the same as if the individual columns of the array
had been listed one by one. E.g. these 2 dump commands are
equivalent, since the <a class="reference internal" href="compute_stress_atom.html"><span class="doc">compute stress/atom</span></a>
command creates a per-atom array with 6 columns:</p>
<pre class="literal-block">
compute myPress all stress/atom NULL
dump 2 all custom 100 tmp.dump id myPress[*]
dump 2 all custom 100 tmp.dump id myPress[1] myPress[2] myPress[3] &
myPress[4] myPress[5] myPress[6]
</pre>
<hr class="docutils" />
<p>This section explains the local attributes that can be specified as
part of the <em>local</em> style.</p>
<p>The <em>index</em> attribute can be used to generate an index number from 1
to N for each line written into the dump file, where N is the total
number of local datums from all processors, or lines of output that
will appear in the snapshot. Note that because data from different
processors depend on what atoms they currently own, and atoms migrate
between processor, there is no guarantee that the same index will be
used for the same info (e.g. a particular bond) in successive
snapshots.</p>
<p>The <em>c_ID</em> and <em>c_ID[I]</em> attributes allow local vectors or arrays
calculated by a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command for details. There are computes for
calculating local information such as indices, types, and energies for
bonds and angles.</p>
<p>Note that computes which calculate global or per-atom quantities, as
opposed to local quantities, cannot be output in a dump local command.
Instead, global quantities can be output by the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command, and per-atom quantities can be
output by the dump custom command.</p>
<p>If <em>c_ID</em> is used as a attribute, then the local vector calculated by
the compute is printed. If <em>c_ID[I]</em> is used, then I must be in the
range from 1-M, which will print the Ith column of the local array
with M columns calculated by the compute. See the discussion above
for how I can be specified with a wildcard asterisk to effectively
specify multiple values.</p>
<p>The <em>f_ID</em> and <em>f_ID[I]</em> attributes allow local vectors or arrays
calculated by a <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> to be output. The ID in the attribute
should be replaced by the actual ID of the fix that has been defined
previously in the input script.</p>
<p>If <em>f_ID</em> is used as a attribute, then the local vector calculated by
the fix is printed. If <em>f_ID[I]</em> is used, then I must be in the
range from 1-M, which will print the Ith column of the local with M
columns calculated by the fix. See the discussion above for how I can
be specified with a wildcard asterisk to effectively specify multiple
values.</p>
<p>Here is an example of how to dump bond info for a system, including
the distance and energy of each bond:</p>
<pre class="literal-block">
compute 1 all property/local batom1 batom2 btype
compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]
</pre>
<hr class="docutils" />
<p>This section explains the atom attributes that can be specified as
part of the <em>custom</em> and <em>cfg</em> styles.</p>
<em>vy</em>, <em>vz</em>, <em>fx</em>, <em>fy</em>, <em>fz</em>, <em>q</em> attributes are self-explanatory.</p>
<p><em>Id</em> is the atom ID. <em>Mol</em> is the molecule ID, included in the data
file for molecular systems. <em>Proc</em> is the ID of the processor (0 to
Nprocs-1) that currently owns the atom. <em>Procp1</em> is the proc ID+1,
which can be convenient in place of a <em>type</em> attribute (1 to Ntypes)
for coloring atoms in a visualization program. <em>Type</em> is the atom
type (1 to Ntypes). <em>Element</em> is typically the chemical name of an
element, which you must assign to each type via the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify element</span></a> command. More generally, it can be any
string you wish to associated with an atom type. <em>Mass</em> is the atom
mass. <em>Vx</em>, <em>vy</em>, <em>vz</em>, <em>fx</em>, <em>fy</em>, <em>fz</em>, and <em>q</em> are components of
atom velocity and force and atomic charge.</p>
<p>There are several options for outputting atom coordinates. The <em>x</em>,
<em>y</em>, <em>z</em> attributes write atom coordinates “unscaled”, in the
<em>xs</em>, <em>ys</em>, <em>zs</em> if you want the coordinates “scaled” to the box size,
so that each value is 0.0 to 1.0. If the simulation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0.
I.e. actual unscaled (x,y,z) = xs*A + ys*B + zs*C, where (A,B,C) are
the non-orthogonal vectors of the simulation box edges, as discussed
in <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">Section howto 6.12</span></a>.</p>
<p>Use <em>xu</em>, <em>yu</em>, <em>zu</em> if you want the coordinates “unwrapped” by the
image flags for each atom. Unwrapped means that if the atom has
passed thru a periodic boundary one or more times, the value is
printed for what the coordinate would be if it had not been wrapped
back into the periodic box. Note that using <em>xu</em>, <em>yu</em>, <em>zu</em> means
that the coordinate values may be far outside the box bounds printed
with the snapshot. Using <em>xsu</em>, <em>ysu</em>, <em>zsu</em> is similar to using
<em>xu</em>, <em>yu</em>, <em>zu</em>, except that the unwrapped coordinates are scaled by
the box size. Atoms that have passed through a periodic boundary will
have the corresponding cooordinate increased or decreased by 1.0.</p>
<p>The image flags can be printed directly using the <em>ix</em>, <em>iy</em>, <em>iz</em>
attributes. For periodic dimensions, they specify which image of the
simulation box the atom is considered to be in. An image of 0 means
it is inside the box as defined. A value of 2 means add 2 box lengths
to get the true value. A value of -1 means subtract 1 box length to
get the true value. LAMMPS updates these flags as atoms cross
periodic boundaries during the simulation.</p>
<p>The <em>mux</em>, <em>muy</em>, <em>muz</em> attributes are specific to dipolar systems
defined with an atom style of <em>dipole</em>. They give the orientation of
the atom’s point dipole moment. The <em>mu</em> attribute gives the
magnitude of the atom’s dipole moment.</p>
<p>The <em>radius</em> and <em>diameter</em> attributes are specific to spherical
particles that have a finite size, such as those defined with an atom
style of <em>sphere</em>.</p>
<p>The <em>omegax</em>, <em>omegay</em>, and <em>omegaz</em> attributes are specific to
finite-size spherical particles that have an angular velocity. Only
certain atom styles, such as <em>sphere</em> define this quantity.</p>
<p>The <em>angmomx</em>, <em>angmomy</em>, and <em>angmomz</em> attributes are specific to
finite-size aspherical particles that have an angular momentum. Only
the <em>ellipsoid</em> atom style defines this quantity.</p>
<p>The <em>tqx</em>, <em>tqy</em>, <em>tqz</em> attributes are for finite-size particles that
can sustain a rotational torque due to interactions with other
particles.</p>
<p>The <em>c_ID</em> and <em>c_ID[I]</em> attributes allow per-atom vectors or arrays
calculated by a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command for details. There are computes for
calculating the per-atom energy, stress, centro-symmetry parameter,
and coordination number of individual atoms.</p>
<p>Note that computes which calculate global or local quantities, as
opposed to per-atom quantities, cannot be output in a dump custom
command. Instead, global quantities can be output by the
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command, and local quantities
can be output by the dump local command.</p>
<p>If <em>c_ID</em> is used as a attribute, then the per-atom vector calculated
by the compute is printed. If <em>c_ID[I]</em> is used, then I must be in
the range from 1-M, which will print the Ith column of the per-atom
array with M columns calculated by the compute. See the discussion
above for how I can be specified with a wildcard asterisk to
effectively specify multiple values.</p>
<p>The <em>f_ID</em> and <em>f_ID[I]</em> attributes allow vector or array per-atom
quantities calculated by a <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> to be output. The ID in the
attribute should be replaced by the actual ID of the fix that has been
defined previously in the input script. The <a class="reference internal" href="fix_ave_atom.html"><span class="doc">fix ave/atom</span></a> command is one that calculates per-atom
quantities. Since it can time-average per-atom quantities produced by
any <a class="reference internal" href="compute.html"><span class="doc">compute</span></a>, <a class="reference internal" href="fix.html"><span class="doc">fix</span></a>, or atom-style
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, this allows those time-averaged results to
be written to a dump file.</p>
<p>If <em>f_ID</em> is used as a attribute, then the per-atom vector calculated
by the fix is printed. If <em>f_ID[I]</em> is used, then I must be in the
range from 1-M, which will print the Ith column of the per-atom array
with M columns calculated by the fix. See the discussion above for
how I can be specified with a wildcard asterisk to effectively specify
multiple values.</p>
<p>The <em>v_name</em> attribute allows per-atom vectors calculated by a
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a> to be output. The name in the attribute
should be replaced by the actual name of the variable that has been
defined previously in the input script. Only an atom-style variable
can be referenced, since it is the only style that generates per-atom
values. Variables of style <em>atom</em> can reference individual atom
attributes, per-atom atom attributes, thermodynamic keywords, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of creating quantities to output to a
dump file.</p>
<p>The <em>d_name</em> and <em>i_name</em> attributes allow to output custom per atom
floating point or integer properties that are managed by
<p>See <a class="reference internal" href="Section_modify.html"><span class="doc">Section 10</span></a> of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>To write gzipped dump files, you must either compile LAMMPS with the
-DLAMMPS_GZIP option or use the styles from the COMPRESS package
- see the <a class="reference internal" href="Section_start.html#start-2"><span class="std std-ref">Making LAMMPS</span></a> section of
the documentation.</p>
<p>The <em>atom/gz</em>, <em>cfg/gz</em>, <em>custom/gz</em>, and <em>xyz/gz</em> styles are part
of the COMPRESS package. They are only enabled if LAMMPS was built
with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The <em>atom/mpiio</em>, <em>cfg/mpiio</em>, <em>custom/mpiio</em>, and <em>xyz/mpiio</em> styles
are part of the MPIIO package. They are only enabled if LAMMPS was
built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The <em>xtc</em> style is part of the MISC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info. This is
because some machines may not support the low-level XDR data format
that XTC files are written with, which will result in a compile-time
error when a low-level include file is not found. Putting this style
in a package makes it easy to exclude from a LAMMPS build for those
machines. However, the MISC package also includes two compatibility
header files and associated functions, which should be a suitable
substitute on machines that do not have the appropriate native header
files. This option can be invoked at build time by adding
-DLAMMPS_XDR to the CCFLAGS variable in the appropriate low-level
Makefile, e.g. src/MAKE/Makefile.foo. This compatibility mode has
been tested successfully on Cray XT3/XT4/XT5 and IBM BlueGene/L
machines and should also work on IBM BG/P, and Windows XP/Vista/7
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>.
<li><p class="first">N = dump every this many timesteps</p>
</li>
<li><p class="first">file = name of file to write dump info to</p>
</li>
<li><p class="first">args = list of arguments for a particular style</p>
<pre class="literal-block">
<em>custom/vtk</em> args = list of atom attributes
possible attributes = id, mol, proc, procp1, type, element, mass,
x, y, z, xs, ys, zs, xu, yu, zu,
xsu, ysu, zsu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
spin, eradius, ervel, erforce,
c_ID, c_ID[N], f_ID, f_ID[N], v_name
</pre>
<pre class="literal-block">
id = atom ID
mol = molecule ID
proc = ID of processor that owns atom
procp1 = ID+1 of processor that owns atom
type = atom type
element = name of atom element, as defined by <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command
mass = atom mass
x,y,z = unscaled atom coordinates
xs,ys,zs = scaled atom coordinates
xu,yu,zu = unwrapped atom coordinates
xsu,ysu,zsu = scaled unwrapped atom coordinates
ix,iy,iz = box image that the atom is in
vx,vy,vz = atom velocities
fx,fy,fz = forces on atoms
q = atom charge
mux,muy,muz = orientation of dipole moment of atom
mu = magnitude of dipole moment of atom
radius,diameter = radius,diameter of spherical particle
omegax,omegay,omegaz = angular velocity of spherical particle
angmomx,angmomy,angmomz = angular momentum of aspherical particle
tqx,tqy,tqz = torque on finite-size particles
c_ID = per-atom vector calculated by a compute with ID
c_ID[N] = Nth column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[N] = Nth column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
dump dmpvtk all custom/vtk 100 dump*.myforce.vtk id type vx fx
dump dmpvtp flow custom/vtk 100 dump*.%.displace.vtp id type c_myD[1] c_myD[2] c_myD[3] v_ke
dump e_data all custom/vtk 100 dump*.vtu id type spin eradius fx fy fz eforce
</pre>
<p>The style <em>custom/vtk</em> is similar to the <a class="reference internal" href="dump.html"><span class="doc">custom</span></a> style but
uses the VTK library to write data to VTK simple legacy or XML format
depending on the filename extension specified. This can be either
<em>*.vtk</em> for the legacy format or <em>*.vtp</em> and <em>*.vtu</em>, respectively,
for the XML format; see the <a class="reference external" href="http://www.vtk.org/VTK/img/file-formats.pdf">VTK homepage</a> for a detailed
description of these formats. Since this naming convention conflicts
with the way binary output is usually specified (see below),
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify binary</span></a> allows to set the binary
flag for this dump style explicitly.</p>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Dump a snapshot of atom quantities to one or more files every N
timesteps in a format readable by the <a class="reference external" href="http://www.vtk.org">VTK visualization toolkit</a> or other visualization tools that use it,
e.g. <a class="reference external" href="http://www.paraview.org">ParaView</a>. The timesteps on which dump
output is written can also be controlled by a variable; see the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify every</span></a> command for details.</p>
<p>Only information for atoms in the specified group is dumped. The
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify thresh and region</span></a> commands can also
alter what atoms are included; see details below.</p>
<p>As described below, special characters (“*”, “%”) in the filename
determine the kind of output.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom written to a dump file may be slightly outside the simulation
box.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Unless the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify sort</span></a>
option is invoked, the lines of atom information written to dump files
will be in an indeterminate order for each snapshot. This is even
true when running on a single processor, if the <a class="reference internal" href="atom_modify.html"><span class="doc">atom_modify sort</span></a> option is on, which it is by default. In this
case atoms are re-ordered periodically during a simulation, due to
spatial sorting. It is also true when running in parallel, because
data for a single snapshot is collected from multiple processors, each
of which owns a subset of the atoms.</p>
</div>
<p>For the <em>custom/vtk</em> style, sorting is off by default. See the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> doc page for details.</p>
<hr class="docutils" />
<p>The dimensions of the simulation box are written to a separate file
for each snapshot (either in legacy VTK or XML format depending on
the format of the main dump file) with the suffix <em>_boundingBox</em>
appended to the given dump filename.</p>
<p>For an orthogonal simulation box this information is saved as a
rectilinear grid (legacy .vtk or .vtr XML format).</p>
<p>Triclinic simulation boxes (non-orthogonal) are saved as
hexahedrons in either legacy .vtk or .vtu XML format.</p>
<p>Style <em>custom/vtk</em> allows you to specify a list of atom attributes
to be written to the dump file for each atom. Possible attributes
are listed above. In contrast to the <em>custom</em> style, the attributes
are rearranged to ensure correct ordering of vector components
(except for computes and fixes - these have to be given in the right
order) and duplicate entries are removed.</p>
<p>You cannot specify a quantity that is not defined for a particular
simulation - such as <em>q</em> for atom style <em>bond</em>, since that atom style
doesn’t assign charges. Dumps occur at the very end of a timestep,
so atom attributes will include effects due to fixes that are applied
during the timestep. An explanation of the possible dump custom/vtk attributes
is given below. Since position data is required to write VTK files “x y z”
do not have to be specified explicitly.</p>
<p>The VTK format uses a single snapshot of the system per file, thus
a wildcard “*” must be included in the filename, as discussed below.
Otherwise the dump files will get overwritten with the new snapshot
each time.</p>
<hr class="docutils" />
<p>Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify first</span></a> command, which
can also be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify every</span></a> command.
The <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify every</span></a> command
also allows a variable to be used to determine the sequence of
timesteps on which dump files are written. In this mode a dump on the
first timestep of a run will also not be written unless the
<a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify first</span></a> command is used.</p>
<p>Dump filenames can contain two wildcard characters. If a “*”
character appears in the filename, then one file per snapshot is
written and the “*” character is replaced with the timestep value.
For example, tmp.dump*.vtk becomes tmp.dump0.vtk, tmp.dump10000.vtk,
tmp.dump20000.vtk, etc. Note that the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify pad</span></a>
command can be used to insure all timestep numbers are the same length
(e.g. 00010), which can make it easier to read a series of dump files
in order with some post-processing tools.</p>
<p>If a “%” character appears in the filename, then each of P processors
writes a portion of the dump file, and the “%” character is replaced
with the processor ID from 0 to P-1 preceded by an underscore character.
For example, tmp.dump%.vtp becomes tmp.dump_0.vtp, tmp.dump_1.vtp, ...
tmp.dump_P-1.vtp, etc. This creates smaller files and can be a fast
mode of output on parallel machines that support parallel I/O for output.</p>
<p>By default, P = the number of processors meaning one file per
processor, but P can be set to a smaller value via the <em>nfile</em> or
<em>fileper</em> keywords of the <a class="reference internal" href="dump_modify.html"><span class="doc">dump_modify</span></a> command.
These options can be the most efficient way of writing out dump files
when running on large numbers of processors.</p>
<p>For the legacy VTK format “%” is ignored and P = 1, i.e., only
processor 0 does write files.</p>
<p>Note that using the “*” and “%” characters together can produce a
large number of small dump files!</p>
<p>If <em>dump_modify binary</em> is used, the dump file (or files, if “*” or
“%” is also used) is written in binary format. A binary dump file
will be about the same size as a text version, but will typically
write out much faster.</p>
<hr class="docutils" />
<p>This section explains the atom attributes that can be specified as
Additionaly, you can use <em>xs</em>, <em>ys</em>, <em>zs</em> if you want to also save the
coordinates “scaled” to the box size, so that each value is 0.0 to
1.0. If the simulation box is triclinic (tilted), then all atom
coords will still be between 0.0 and 1.0. Use <em>xu</em>, <em>yu</em>, <em>zu</em> if you
want the coordinates “unwrapped” by the image flags for each atom.
Unwrapped means that if the atom has passed through a periodic
boundary one or more times, the value is printed for what the
coordinate would be if it had not been wrapped back into the periodic
box. Note that using <em>xu</em>, <em>yu</em>, <em>zu</em> means that the coordinate
values may be far outside the box bounds printed with the snapshot.
Using <em>xsu</em>, <em>ysu</em>, <em>zsu</em> is similar to using <em>xu</em>, <em>yu</em>, <em>zu</em>, except
that the unwrapped coordinates are scaled by the box size. Atoms that
have passed through a periodic boundary will have the corresponding
cooordinate increased or decreased by 1.0.</p>
<p>The image flags can be printed directly using the <em>ix</em>, <em>iy</em>, <em>iz</em>
attributes. For periodic dimensions, they specify which image of the
simulation box the atom is considered to be in. An image of 0 means
it is inside the box as defined. A value of 2 means add 2 box lengths
to get the true value. A value of -1 means subtract 1 box length to
get the true value. LAMMPS updates these flags as atoms cross
periodic boundaries during the simulation.</p>
<p>The <em>mux</em>, <em>muy</em>, <em>muz</em> attributes are specific to dipolar systems
defined with an atom style of <em>dipole</em>. They give the orientation of
the atom’s point dipole moment. The <em>mu</em> attribute gives the
magnitude of the atom’s dipole moment.</p>
<p>The <em>radius</em> and <em>diameter</em> attributes are specific to spherical
particles that have a finite size, such as those defined with an atom
style of <em>sphere</em>.</p>
<p>The <em>omegax</em>, <em>omegay</em>, and <em>omegaz</em> attributes are specific to
finite-size spherical particles that have an angular velocity. Only
certain atom styles, such as <em>sphere</em> define this quantity.</p>
<p>The <em>angmomx</em>, <em>angmomy</em>, and <em>angmomz</em> attributes are specific to
finite-size aspherical particles that have an angular momentum. Only
the <em>ellipsoid</em> atom style defines this quantity.</p>
<p>The <em>tqx</em>, <em>tqy</em>, <em>tqz</em> attributes are for finite-size particles that
can sustain a rotational torque due to interactions with other
particles.</p>
<p>The <em>spin</em>, <em>eradius</em>, <em>ervel</em>, and <em>erforce</em> attributes are for
particles that represent nuclei and electrons modeled with the
electronic force field (EFF). See <a class="reference internal" href="atom_style.html"><span class="doc">atom_style electron</span></a> and <a class="reference internal" href="pair_eff.html"><span class="doc">pair_style eff</span></a> for more
details.</p>
<p>The <em>c_ID</em> and <em>c_ID[N]</em> attributes allow per-atom vectors or arrays
calculated by a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command for details. There are computes for
calculating the per-atom energy, stress, centro-symmetry parameter,
and coordination number of individual atoms.</p>
<p>Note that computes which calculate global or local quantities, as
opposed to per-atom quantities, cannot be output in a dump custom/vtk
command. Instead, global quantities can be output by the
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command, and local quantities
can be output by the dump local command.</p>
<p>If <em>c_ID</em> is used as an attribute, then the per-atom vector calculated
by the compute is printed. If <em>c_ID[N]</em> is used, then N must be in
the range from 1-M, which will print the Nth column of the M-length
per-atom array calculated by the compute.</p>
<p>The <em>f_ID</em> and <em>f_ID[N]</em> attributes allow vector or array per-atom
quantities calculated by a <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> to be output. The ID in the
attribute should be replaced by the actual ID of the fix that has been
defined previously in the input script. The <a class="reference internal" href="fix_ave_atom.html"><span class="doc">fix ave/atom</span></a> command is one that calculates per-atom
quantities. Since it can time-average per-atom quantities produced by
any <a class="reference internal" href="compute.html"><span class="doc">compute</span></a>, <a class="reference internal" href="fix.html"><span class="doc">fix</span></a>, or atom-style
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, this allows those time-averaged results to
be written to a dump file.</p>
<p>If <em>f_ID</em> is used as a attribute, then the per-atom vector calculated
by the fix is printed. If <em>f_ID[N]</em> is used, then N must be in the
range from 1-M, which will print the Nth column of the M-length
per-atom array calculated by the fix.</p>
<p>The <em>v_name</em> attribute allows per-atom vectors calculated by a
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a> to be output. The name in the attribute
should be replaced by the actual name of the variable that has been
defined previously in the input script. Only an atom-style variable
can be referenced, since it is the only style that generates per-atom
values. Variables of style <em>atom</em> can reference individual atom
attributes, per-atom atom attributes, thermodynamic keywords, or
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of creating quantities to output to a
dump file.</p>
<p>See <a class="reference internal" href="Section_modify.html"><span class="doc">Section 10</span></a> of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>The <em>custom/vtk</em> style does not support writing of gzipped dump files.</p>
<p>The <em>custom/vtk</em> dump style is part of the USER-VTK package. It is
only enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>To use this dump style, you also must link to the VTK library. See
the info in lib/vtk/README and insure the Makefile.lammps file in that
directory is appropriate for your machine.</p>
<p>The <em>custom/vtk</em> dump style neither supports buffering nor custom
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>.
<li><p class="first">zero or more keyword/value pairs may be appended to args</p>
</li>
<li><p class="first">keyword = <em>every</em> or <em>region</em> or <em>energy</em></p>
<pre class="literal-block">
<em>every</em> value = Nevery
Nevery = add force every this many timesteps
<em>region</em> value = region-ID
region-ID = ID of region atoms must be in to have added force
<em>energy</em> value = v_name
v_name = variable with name that calculates the potential energy of each atom in the added force field
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix kick flow addforce 1.0 0.0 0.0
fix kick flow addforce 1.0 0.0 v_oscillate
fix ff boundary addforce 0.0 0.0 v_push energy v_espace
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Add fx,fy,fz to the corresponding component of force for each atom in
the group. This command can be used to give an additional push to
atoms in a simulation, such as for a simulation of Poiseuille flow in
a channel.</p>
<p>Any of the 3 quantities defining the force components can be specified
as an equal-style or atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, namely <em>fx</em>,
<em>fy</em>, <em>fz</em>. If the value is a variable, it should be specified as
v_name, where name is the variable name. In this case, the variable
will be evaluated each timestep, and its value(s) used to determine
the force component.</p>
<p>Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent force field.</p>
<p>Atom-style variables can specify the same formulas as equal-style
variables but can also include per-atom values, such as atom
coordinates. Thus it is easy to specify a spatially-dependent force
field with optional time-dependence as well.</p>
<p>If the <em>every</em> keyword is used, the <em>Nevery</em> setting determines how
often the forces are applied. The default value is 1, for every
timestep.</p>
<p>If the <em>region</em> keyword is used, the atom must also be in the
specified geometric <a class="reference internal" href="region.html"><span class="doc">region</span></a> in order to have force added
to it.</p>
<hr class="docutils" />
<p>Adding a force to atoms implies a change in their potential energy as
they move due to the applied force field. For dynamics via the “run”
command, this energy can be optionally added to the system’s potential
energy for thermodynamic output (see below). For energy minimization
via the “minimize” command, this energy must be added to the system’s
potential energy to formulate a self-consistent minimization problem
(see below).</p>
<p>The <em>energy</em> keyword is not allowed if the added force is a constant
vector F = (fx,fy,fz), with all components defined as numeric
constants and not as variables. This is because LAMMPS can compute
the energy for each atom directly as E = -x dot F = -(x*fx + y*fy +
z*fz), so that -Grad(E) = F.</p>
<p>The <em>energy</em> keyword is optional if the added force is defined with
one or more variables, and if you are performing dynamics via the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command. If the keyword is not used, LAMMPS will set
the energy to 0.0, which is typically fine for dynamics.</p>
<p>The <em>energy</em> keyword is required if the added force is defined with
one or more variables, and you are performing energy minimization via
the “minimize” command. The keyword specifies the name of an
atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> which is used to compute the
energy of each atom as function of its position. Like variables used
for <em>fx</em>, <em>fy</em>, <em>fz</em>, the energy variable is specified as v_name,
where name is the variable name.</p>
<p>Note that when the <em>energy</em> keyword is used during an energy
minimization, you must insure that the formula defined for the
atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> is consistent with the force
variable formulas, i.e. that -Grad(E) = F. For example, if the force
were a spring-like F = kx, then the energy formula should be E =
-0.5kx^2. If you don’t do this correctly, the minimization will not
converge properly.</p>
<hr class="docutils" />
<p>Styles with a suffix are functionally the same as the corresponding
style without the suffix. They have been optimized to run faster,
depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the potential “energy” inferred by the added force to the
system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>. This is a fictitious quantity but is
needed so that the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command can include the
forces added by this fix in a consistent manner. I.e. there is a
decrease in potential energy when atoms move in the direction of the
added force.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is adding its forces. Default is the outermost
level.</p>
<p>This fix computes a global scalar and a global 3-vector of forces,
which can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is the potential
energy discussed above. The vector is the total force on the group of
atoms before the forces on individual atoms are changed by the fix.
The scalar and vector values calculated by this fix are “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command. You should not
specify force components with a variable that has time-dependence for
use with a minimizer, since the minimizer increments the timestep as
the iteration count during the minimization.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the fictitious potential energy associated with the
added forces to be included in the total potential energy of the
system (the quantity being minimized), you MUST enable the
<a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option for this fix.</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>.
vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
density/number, density/mass = number or mass density
temp = temperature
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below)
v_name = per-atom vector calculated by an atom-style variable with name
</pre>
</li>
<li><p class="first">zero or more keyword/arg pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>norm</em> or <em>ave</em> or <em>bias</em> or <em>adof</em> or <em>cdof</em> or <em>file</em> or <em>overwrite</em> or <em>title1</em> or <em>title2</em> or <em>title3</em></p>
<pre class="literal-block">
<em>norm</em> arg = <em>all</em> or <em>sample</em> or <em>none</em> = how output on <em>Nfreq</em> steps is normalized
all = output is sum of atoms across all <em>Nrepeat</em> samples, divided by atom count
sample = output is sum of <em>Nrepeat</em> sample averages, divided by <em>Nrepeat</em>
none = output is sum of <em>Nrepeat</em> sample sums, divided by <em>Nrepeat</em>
<em>ave</em> args = <em>one</em> or <em>running</em> or <em>window M</em>
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
<em>bias</em> arg = bias-ID
bias-ID = ID of a temperature compute that removes a velocity bias for temperature calculation
<em>adof</em> value = dof_per_atom
dof_per_atom = define this many degrees-of-freedom per atom for temperature calculation
<em>cdof</em> value = dof_per_chunk
dof_per_chunk = define this many degrees-of-freedom per chunk for temperature calculation
<em>file</em> arg = filename
filename = file to write results to
<em>overwrite</em> arg = none = overwrite output file with only latest output
<p>If you are trying to replace a deprectated fix ave/spatial command
with the newer, more flexible fix ave/chunk and <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> commands, you simply need to split
the fix ave/spatial arguments across the two new commands. For
<p>Use one or more per-atom vectors as inputs every few timesteps, sum
the values over the atoms in each chunk at each timestep, then average
the per-chunk values over longer timescales. The resulting chunk
averages can be used by other <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a> such as <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a>, and can also be written to a file.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page and <a class="reference internal" href="Section_howto.html#howto-23"><span class="std std-ref">Section 6.23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>Note that only atoms in the specified group contribute to the summing
and averaging calculations. The <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command defines its own group as
well as an optional region. Atoms will have a chunk ID = 0, meaning
they belong to no chunk, if they are not in that group or region.
Thus you can specify the “all” group for this command if you simply
want to use the chunk definitions provided by chunkID.</p>
<p>Each specified per-atom value can be an atom attribute (position,
velocity, force component), a mass or number density, or the result of
a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> or <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or the evaluation of an
atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. Note that the <a class="reference internal" href="compute_property_atom.html"><span class="doc">compute property/atom</span></a> command provides access to
any attribute defined and stored by atoms. If you wish to
time-average global quantities from a compute, fix, or variable, then
see the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a> command.</p>
<p>The per-atom values of each input vector are summed and averaged
independently of the per-atom values in other input vectors.</p>
<p><a class="reference internal" href="compute.html"><span class="doc">Computes</span></a> that produce per-atom quantities are those
which have the word <em>atom</em> in their style name. See the doc pages for
individual <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a> to determine which ones produce per-atom
quantities. <a class="reference internal" href="variable.html"><span class="doc">Variables</span></a> of style <em>atom</em> are the only
ones that can be used with this fix since all other styles of variable
produce global quantities.</p>
<p>Note that for values from a compute or fix, the bracketed index I can
be specified using a wildcard asterisk with the index to effectively
specify multiple values. This takes the form “*” or “*n” or “n*” or
“m*n”. If N = the size of the vector (for <em>mode</em> = scalar) or the
number of columns in the array (for <em>mode</em> = vector), then an asterisk
with no numeric values means all indices from 1 to N. A leading
asterisk means all indices from 1 to n (inclusive). A trailing
asterisk means all indices from n to N (inclusive). A middle asterisk
means all indices from m to n (inclusive).</p>
<p>Using a wildcard is the same as if the individual columns of the array
had been listed one by one. E.g. these 2 fix ave/chunk commands are
equivalent, since the <a class="reference internal" href="compute_property_atom.html"><span class="doc">compute property/atom</span></a> command creates, in this
case, a per-atom array with 3 columns:</p>
<pre class="literal-block">
compute myAng all property/atom angmomx angmomy angmomz
<p class="last">This fix works by creating an array of size <em>Nchunk</em> by Nvalues
on each processor. <em>Nchunk</em> is the number of chunks which is defined
by the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command.
Nvalues is the number of input values specified. Each processor loops
over its atoms, tallying its values to the appropriate chunk. Then
the entire array is summed across all processors. This means that
using a large number of chunks will incur an overhead in memory and
computational cost (summing across processors), so be careful to
define a reasonable number of chunks.</p>
</div>
<hr class="docutils" />
<p>The <em>Nevery</em>, <em>Nrepeat</em>, and <em>Nfreq</em> arguments specify on what
timesteps the input values will be accessed and contribute to the
average. The final averaged quantities are generated on timesteps
that are a multiples of <em>Nfreq</em>. The average is over <em>Nrepeat</em>
quantities, computed in the preceding portion of the simulation every
<em>Nevery</em> timesteps. <em>Nfreq</em> must be a multiple of <em>Nevery</em> and
<em>Nevery</em> must be non-zero even if <em>Nrepeat</em> is 1. Also, the timesteps
contributing to the average value cannot overlap, i.e. Nrepeat*Nevery
can not exceed Nfreq.</p>
<p>For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
timesteps 90,92,94,96,98,100 will be used to compute the final average
on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on
timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time
averaging is done; values are simply generated on timesteps
100,200,etc.</p>
<p>Each input value can also be averaged over the atoms in each chunk.
The way the averaging is done across the <em>Nrepeat</em> timesteps to
produce output on the <em>Nfreq</em> timesteps, and across multiple <em>Nfreq</em>
outputs, is determined by the <em>norm</em> and <em>ave</em> keyword settings, as
discussed below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To perform per-chunk averaging within a <em>Nfreq</em> time window, the
number of chunks <em>Nchunk</em> defined by the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command must remain constant. If
the <em>ave</em> keyword is set to <em>running</em> or <em>window</em> then <em>Nchunk</em> must
remain constant for the duration of the simulation. This fix forces
the chunk/atom compute specified by chunkID to hold <em>Nchunk</em> constant
for the appropriate time windows, by not allowing it to re-calcualte
<em>Nchunk</em>, which can also affect how it assigns chunk IDs to atoms.
More details are given on the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> doc page.</p>
</div>
<hr class="docutils" />
<p>The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
As noted above, any other atom attributes can be used as input values
to this fix by using the <a class="reference internal" href="compute_property_atom.html"><span class="doc">compute property/atom</span></a> command and then specifying
an input value from that compute.</p>
<p>The <em>density/number</em> value means the number density is computed for
each chunk, i.e. number/volume. The <em>density/mass</em> value means the
mass density is computed for each chunk, i.e. total-mass/volume. The
output values are in units of 1/volume or density (mass/volume). See
the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command doc page for the definition of density
for each choice of units, e.g. gram/cm^3. If the chunks defined by
the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command are spatial
bins, the volume is the bin volume. Otherwise it is the volume of the
entire simulation box.</p>
<p>The <em>temp</em> value means the temperature is computed for each chunk, by
the formula KE = DOF/2 k T, where KE = total kinetic energy of the
chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees
of freedom for all atoms in the chunk, k = Boltzmann constant, and T =
temperature.</p>
<p>The DOF is calculated as N*adof + cdof, where N = number of atoms in
the chunk, adof = degrees of freedom per atom, and cdof = degrees of
freedom per chunk. By default adof = 2 or 3 = dimensionality of
system, as set via the <a class="reference internal" href="dimension.html"><span class="doc">dimension</span></a> command, and cdof =
0.0. This gives the usual formula for temperature.</p>
<p>Note that currently this temperature only includes translational
degrees of freedom for each atom. No rotational degrees of freedom
are included for finite-size particles. Also no degrees of freedom
are subtracted for any velocity bias or constraints that are applied,
such as <a class="reference internal" href="compute_temp_partial.html"><span class="doc">compute temp/partial</span></a>, or <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> or <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>. This is because
those degrees of freedom (e.g. a constrained bond) could apply to sets
of atoms that are both included and excluded from a specific chunk,
and hence the concept is somewhat ill-defined. In some cases, you can
use the <em>adof</em> and <em>cdof</em> keywords to adjust the calculated degress of
freedom appropriately, as explained below.</p>
<p>Also note that a bias can be subtracted from atom velocities before
they are used in the above formula for KE, by using the <em>bias</em>
keyword. This allows, for example, a thermal temperature to be
computed after removal of a flow velocity profile.</p>
<p>Note that the per-chunk temperature calculated by this fix and the
<a class="reference internal" href="compute_temp_chunk.html"><span class="doc">compute temp/chunk</span></a> command can be different.
The compute calculates the temperature for each chunk for a single
snapshot. This fix can do that but can also time average those values
over many snapshots, or it can compute a temperature as if the atoms
in the chunk on different timesteps were collected together as one set
of atoms to calculate their temperature. The compute allows the
center-of-mass velocity of each chunk to be subtracted before
calculating the temperature; this fix does not.</p>
<p>If a value begins with “c_”, a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.
See the discussion above for how I can be specified with a wildcard
asterisk to effectively specify multiple values.</p>
<p>If a value begins with “f_”, a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
<em>Nevery</em>, else an error results. Users can also write code for their
own fix styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>. See the
discussion above for how I can be specified with a wildcard asterisk
to effectively specify multiple values.</p>
<p>If a value begins with “v_”, a variable name must follow which has
been previously defined in the input script. Variables of style
<em>atom</em> can reference thermodynamic keywords and various per-atom
attributes, or invoke other computes, fixes, or variables when they
are evaluated, so this is a very general means of generating per-atom
quantities to average within chunks.</p>
<hr class="docutils" />
<p>Additional optional keywords also affect the operation of this fix
and its outputs.</p>
<p>The <em>norm</em> keyword affects how averaging is done for the per-chunk
values that are output every <em>Nfreq</em> timesteps.</p>
<p>It the <em>norm</em> setting is <em>all</em>, which is the default, a chunk value is
summed over all atoms in all <em>Nrepeat</em> samples, as is the count of
atoms in the chunk. The averaged output value for the chunk on the
<em>Nfreq</em> timesteps is Total-sum / Total-count. In other words it is an
average over atoms across the entire <em>Nfreq</em> timescale.</p>
<p>If the <em>norm</em> setting is <em>sample</em>, the chunk value is summed over atoms
for each sample, as is the count, and an “average sample value” is
computed for each sample, i.e. Sample-sum / Sample-count. The output
value for the chunk on the <em>Nfreq</em> timesteps is the average of the
<em>Nrepeat</em> “average sample values”, i.e. the sum of <em>Nrepeat</em> “average
sample values” divided by <em>Nrepeat</em>. In other words it is an average
of an average.</p>
<p>If the <em>norm</em> setting is <em>none</em>, a similar computation as for the
<em>sample</em> seting is done, except the individual “average sample values”
are “summed sample values”. A summed sample value is simply the chunk
value summed over atoms in the sample, without dividing by the number
of atoms in the sample. The output value for the chunk on the
<em>Nfreq</em> timesteps is the average of the <em>Nrepeat</em> “summed sample
values”, i.e. the sum of <em>Nrepeat</em> “summed sample values” divided by
<em>Nrepeat</em>.</p>
<p>The <em>ave</em> keyword determines how the per-chunk values produced every
<em>Nfreq</em> steps are averaged with values produced on previous steps that
were multiples of <em>Nfreq</em>, before they are accessed by another output
command or written to a file.</p>
<p>If the <em>ave</em> setting is <em>one</em>, which is the default, then the chunk
values produced on timesteps that are multiples of <em>Nfreq</em> are
independent of each other; they are output as-is without further
averaging.</p>
<p>If the <em>ave</em> setting is <em>running</em>, then the chunk values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged in a
cumulative sense before being output. Each output chunk value is thus
the average of the chunk value produced on that timestep with all
preceding values for the same chunk. This running average begins when
the fix is defined; it can only be restarted by deleting the fix via
the <a class="reference internal" href="unfix.html"><span class="doc">unfix</span></a> command, or re-defining the fix by
re-specifying it.</p>
<p>If the <em>ave</em> setting is <em>window</em>, then the chunk values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged within
a moving “window” of time, so that the last M values for the same
chunk are used to produce the output. E.g. if M = 3 and Nfreq = 1000,
then the output on step 10000 will be the average of the individual
chunk values on steps 8000,9000,10000. Outputs on early steps will
average over less than M values if they are not available.</p>
<p>The <em>bias</em> keyword specifies the ID of a temperature compute that
removes a “bias” velocity from each atom, specified as <em>bias-ID</em>. It
is only used when the <em>temp</em> value is calculated, to compute the
thermal temperature of each chunk after the translational kinetic
energy components have been altered in a prescribed way, e.g. to
remove a flow velocity profile. See the doc pages for individual
computes that calculate a temperature to see which ones implement a
bias.</p>
<p>The <em>adof</em> and <em>cdof</em> keywords define the values used in the degree of
freedom (DOF) formula described above for for temperature calculation
for each chunk. They are only used when the <em>temp</em> value is
calculated. They can be used to calculate a more appropriate
temperature for some kinds of chunks. Here are 3 examples:</p>
<p>If spatially binned chunks contain some number of water molecules and
<a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> is used to make each molecule rigid, then
you could calculate a temperature with 6 degrees of freedom (DOF) (3
translational, 3 rotational) per molecule by setting <em>adof</em> to 2.0.</p>
<p>If <a class="reference internal" href="compute_temp_partial.html"><span class="doc">compute temp/partial</span></a> is used with the
<em>bias</em> keyword to only allow the x component of velocity to contribute
to the temperature, then <em>adof</em> = 1.0 would be appropriate.</p>
<p>If each chunk consists of a large molecule, with some number of its
bonds constrained by <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> or the entire molecule
by <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid/small</span></a>, <em>adof</em> = 0.0 and <em>cdof</em> could be
set to the remaining degrees of freedom for the entire molecule
(entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid
molecule.</p>
<p>The <em>file</em> keyword allows a filename to be specified. Every <em>Nfreq</em>
timesteps, a section of chunk info will be written to a text file in
the following format. A line with the timestep and number of chunks
is written. Then one line per chunk is written, containing the chunk
ID (1-Nchunk), an optional original ID value, optional coordinate
values for chunks that represent spatial bins, the number of atoms in
the chunk, and one or more calculated values. More explanation of the
optional values is given below. The number of values in each line
corresponds to the number of values specified in the fix ave/chunk
command. The number of atoms and the value(s) are summed or average
quantities, as explained above.</p>
<p>The <em>overwrite</em> keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the <em>ave running</em> setting.</p>
<p>The <em>format</em> keyword sets the numeric format of each value when it is
printed to a file via the <em>file</em> keyword. Note that all values are
floating point quantities. The default format is %g. You can specify
a higher precision if desired, e.g. %20.16g.</p>
<p>The <em>title1</em> and <em>title2</em> and <em>title3</em> keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the <em>file</em> keyword was used. LAMMPS uses default
values for each of these, so they do not need to be specified.</p>
<p>By default, these header lines are as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Chunk-averaged data for fix ID and group name</span>
<p>In the first line, ID and name are replaced with the fix-ID and group
name. The second line describes the two values that are printed at
the first of each section of output. In the third line the values are
replaced with the appropriate value names, e.g. fx or c_myCompute<strong>2</strong>.</p>
<p>The words in parenthesis only appear with corresponding columns if the
chunk style specified for the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command supports them. The OrigID
column is only used if the <em>compress</em> keyword was set to <em>yes</em> for the
<a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. This means that
the original chunk IDs (e.g. molecule IDs) will have been compressed
to remove chunk IDs with no atoms assigned to them. Thus a compresed
chunk ID of 3 may correspond to an original chunk ID or molecule ID of
415. The OrigID column will list 415 for the 3rd chunk.</p>
<p>The CoordN columns only appear if a <em>binning</em> style was used in the
<a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. For <em>bin/1d</em>,
<em>bin/2d</em>, and <em>bin/3d</em> styles the column values are the center point
of the bin in the corresponding dimension. Just Coord1 is used for
<em>bin/1d</em>, Coord2 is added for <em>bin/2d</em>, Coord3 is added for <em>bin/3d</em>.
For <em>bin/sphere</em>, just Coord1 is used, and it is the radial
coordinate. For <em>bin/cylinder</em>, Coord1 and Coord2 are used. Coord1
is the radial coordinate (away from the cylinder axis), and coord2 is
the coordinate along the cylinder axis.</p>
<p>Note that if the value of the <em>units</em> keyword used in the <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom command</span></a> is <em>box</em> or <em>lattice</em>, the
coordinate values will be in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a>. If the
value of the <em>units</em> keyword is <em>reduced</em>, the coordinate values will
be in unitless reduced units (0-1). This is not true for the Coord1 value
of style <em>bin/sphere</em> or <em>bin/cylinder</em> which both represent radial
dimensions. Those values are always in distance <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>This fix computes a global array of values which can be accessed by
various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The values can
only be accessed on timesteps that are multiples of <em>Nfreq</em> since that
is when averaging is performed. The global array has # of rows =
the number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> command. The # of columns =
M+1+Nvalues, where M = 1 to 4, depending on whether the optional
columns for OrigID and CoordN are used, as explained above.
Following the optional columns, the next column contains the count of
atoms in the chunk, and the remaining columns are the Nvalue
quantities. When the array is accessed with a row I that exceeds the
current number of chunks, than a 0.0 is returned by the fix instead of
an error, since the number of chunks can vary as a simulation runs
depending on how that value is computed by the compute chunk/atom
command.</p>
<p>The array values calculated by this fix are treated as “intensive”,
since they are typically already normalized by the count of atoms in
each chunk.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</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>.
region-ID = ID of region atoms must be in to have added force
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix pressdown topwall aveforce 0.0 -1.0 0.0
fix 2 bottomwall aveforce NULL -1.0 0.0 region top
fix 2 bottomwall aveforce NULL -1.0 v_oscillate region top
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Apply an additional external force to a group of atoms in such a way
that every atom experiences the same force. This is useful for
pushing on wall or boundary atoms so that the structure of the wall
does not change over time.</p>
<p>The existing force is averaged for the group of atoms, component by
component. The actual force on each atom is then set to the average
value plus the component specified in this command. This means each
atom in the group receives the same force.</p>
<p>Any of the fx,fy,fz values can be specified as NULL which means the
force in that dimension is not changed. Note that this is not the
same as specifying a 0.0 value, since that sets all forces to the same
average value without adding in any additional force.</p>
<p>Any of the 3 quantities defining the force components can be specified
as an equal-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, namely <em>fx</em>, <em>fy</em>, <em>fz</em>.
If the value is a variable, it should be specified as v_name, where
name is the variable name. In this case, the variable will be
evaluated each timestep, and its value used to determine the average
force.</p>
<p>Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent average force.</p>
<p>If the <em>region</em> keyword is used, the atom must also be in the
specified geometric <a class="reference internal" href="region.html"><span class="doc">region</span></a> in order to have force added
to it.</p>
<hr class="docutils" />
<p>Styles with a suffix are functionally the same as the corresponding
style without the suffix. They have been optimized to run faster,
depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is adding its forces. Default is the outermost level.</p>
<p>This fix computes a global 3-vector of forces, which can be accessed
by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. This is the
total force on the group of atoms before the forces on individual
atoms are changed by the fix. The vector values calculated by this
fix are “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command. You should not
specify force components with a variable that has time-dependence for
use with a minimizer, since the minimizer increments the timestep as
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>.
-<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</p>
-</li>
-<li><p class="first">box/relax = style name of this fix command</p>
+<ul class="simple">
+<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
+<li>box/relax = style name of this fix command</li>
+</ul>
<pre class="literal-block">
one or more keyword value pairs may be appended
keyword = <em>iso</em> or <em>aniso</em> or <em>tri</em> or <em>x</em> or <em>y</em> or <em>z</em> or <em>xy</em> or <em>yz</em> or <em>xz</em> or <em>couple</em> or <em>nreset</em> or <em>vmax</em> or <em>dilate</em> or <em>scaleyz</em> or <em>scalexz</em> or <em>scalexy</em> or <em>fixedpoint</em>
<em>iso</em> or <em>aniso</em> or <em>tri</em> value = Ptarget = desired pressure (pressure units)
<em>x</em> or <em>y</em> or <em>z</em> or <em>xy</em> or <em>yz</em> or <em>xz</em> value = Ptarget = desired pressure (pressure units)
<em>couple</em> = <em>none</em> or <em>xyz</em> or <em>xy</em> or <em>yz</em> or <em>xz</em>
<em>nreset</em> value = reset reference cell every this many minimizer iterations
<em>vmax</em> value = fraction = max allowed volume change in one iteration
<em>dilate</em> value = <em>all</em> or <em>partial</em>
<em>scaleyz</em> value = <em>yes</em> or <em>no</em> = scale yz with lz
<em>scalexz</em> value = <em>yes</em> or <em>no</em> = scale xz with lz
<em>scalexy</em> value = <em>yes</em> or <em>no</em> = scale xy with ly
<em>fixedpoint</em> values = x y z
x,y,z = perform relaxation dilation/contraction around this point (distance units)
<p>where <strong>I</strong> is the identity matrix, <strong>h</strong>_0 is the box dimension tensor of
the reference cell, and <strong>h</strong>_0<em>d</em> is the diagonal part of
<strong>h</strong>_0. <strong>S</strong>_<em>t</em> is a symmetric stress tensor that is chosen by LAMMPS
so that the upper-triangular components of <strong>P</strong> equal the stress tensor
specified by the user.</p>
<p>This equation only applies when the box dimensions are equal to those
of the reference dimensions. If this is not the case, then the
converged stress tensor will not equal that specified by the user. We
can resolve this problem by periodically resetting the reference
dimensions. The keyword <em>nreset_ref</em> controls how often this is done.
If this keyword is not used, or is given a value of zero, then the
reference dimensions are set to those of the initial simulation domain
and are never changed. A value of <em>nstep</em> means that every <em>nstep</em>
minimization steps, the reference dimensions are set to those of the
current simulation domain. Note that resetting the reference
dimensions changes the objective function and gradients, which
sometimes causes the minimization to fail. This can be resolved by
changing the value of <em>nreset</em>, or simply continuing the minimization
from a restart file.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">As normally computed, pressure includes a kinetic- energy or
temperature-dependent component; see the <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> command. However, atom velocities are
ignored during a minimization, and the applied pressure(s) specified
with this command are assumed to only be the virial component of the
pressure (the non-kinetic portion). Thus if atoms have a non-zero
temperature and you print the usual thermodynamic pressure, it may not
appear the system is converging to your specified pressure. The
solution for this is to either (a) zero the velocities of all atoms
before performing the minimization, or (b) make sure you are
monitoring the pressure without its kinetic component. The latter can
be done by outputting the pressure from the fix this command creates
(see below) or a pressure fix you define yourself.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because pressure is often a very sensitive function of volume,
it can be difficult for the minimizer to equilibrate the system the
desired pressure with high precision, particularly for solids. Some
techniques that seem to help are (a) use the “min_modify line
quadratic” option when minimizing with box relaxations, (b) minimize
several times in succession if need be, to drive the pressure closer
to the target pressure, (c) relax the atom positions before relaxing
the box, and (d) relax the box to the target hydrostatic pressure
before relaxing to a target shear stress state. Also note that some
systems (e.g. liquids) will not sustain a non-hydrostatic applied
pressure, which means the minimizer will not converge.</p>
</div>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. The
temperature is used to compute the kinetic contribution to the
pressure, even though this is subsequently ignored by default. To do
this, the fix creates its own computes of style “temp” and “pressure”,
<p>See the <a class="reference internal" href="compute_temp.html"><span class="doc">compute temp</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is the same
as the fix group. Also note that the pressure compute does not
include a kinetic component.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its temperature and pressure calculation, as described above. Note
that as described above, if you assign a pressure compute to this fix
that includes a kinetic energy component it will affect the
minimization, most likely in an undesirable way.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If both the <em>temp</em> and <em>press</em> keywords are used in a single
thermo_modify command (or in two separate commands), then the order in
which the keywords are specified is important. Note that a <a class="reference internal" href="compute_pressure.html"><span class="doc">pressure compute</span></a> defines its own temperature compute as
an argument when it is specified. The <em>temp</em> keyword will override
this (for the pressure compute being used by fix npt), but only if the
<em>temp</em> keyword comes after the <em>press</em> keyword. If the <em>temp</em> keyword
comes before the <em>press</em> keyword, then the new pressure compute
specified by the <em>press</em> keyword will be unaffected by the <em>temp</em>
setting.</p>
</div>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is the
pressure-volume energy, plus the strain energy, if it exists.</p>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is given
by the energy expression shown above. The energy values reported
at the end of a minimization run under “Minimization stats” include
this energy, and so differ from what LAMMPS normally reports as
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>.
<p>where <em>tau</em> = <em>Nevery</em> * <em>timestep</em> is the time interval between updates,
and the subscripted variables indicate the values of <em>c</em> and <em>e</em> at
successive updates.</p>
<p>From the first equation, it is clear that if the three gain values
<em>Kp</em>, <em>Ki</em>, <em>Kd</em> are dimensionless constants, then <em>alpha</em> must have
units of [unit <em>cvar</em>]/[unit <em>pvar</em>]/[unit time] e.g. [ eV/K/ps
]. The advantage of this unit scheme is that the value of the
constants should be invariant under a change of either the MD timestep
size or the value of <em>Nevery</em>. Similarly, if the LAMMPS <a class="reference internal" href="units.html"><span class="doc">unit style</span></a> is changed, it should only be necessary to change
the value of <em>alpha</em> to reflect this, while leaving <em>Kp</em>, <em>Ki</em>, and
<em>Kd</em> unaltered.</p>
<p>When choosing the values of the four constants, it is best to first
pick a value and sign for <em>alpha</em> that is consistent with the
magnitudes and signs of <em>pvar</em> and <em>cvar</em>. The magnitude of <em>Kp</em>
should then be tested over a large positive range keeping <em>Ki</em>=<em>Kd</em>=0.
A good value for <em>Kp</em> will produce a fast reponse in <em>pvar</em>, without
overshooting the <em>setpoint</em>. For many applications, proportional
feedback is sufficient, and so <em>Ki</em>=<em>Kd</em>=0 can be used. In cases where
there is a substantial lag time in the response of <em>pvar</em> to a change
in <em>cvar</em>, this can be counteracted by increasing <em>Kd</em>. In situations
where <em>pvar</em> plateaus without reaching <em>setpoint</em>, this can be
counteracted by increasing <em>Ki</em>. In the language of Charles Dickens,
<em>Kp</em> represents the error of the present, <em>Ki</em> the error of the past,
and <em>Kd</em> the error yet to come.</p>
<p>Because this fix updates <em>cvar</em>, but does not initialize its value,
the initial value is that assigned by the user in the input script via
the <a class="reference internal" href="variable.html"><span class="doc">internal-style variable</span></a> command. This value is
used (by the other LAMMPS command that used the variable) until this
fix performs its first update of <em>cvar</em> after <em>Nevery</em> timesteps. On
the first update, the value of the derivative term is set to zero,
because the value of <em>e_n-1</em> is not yet defined.</p>
<hr class="docutils" />
<p>The process variable <em>pvar</em> can be specified as the output of a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> or <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or the evaluation of a
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. In each case, the compute, fix, or variable
must produce a global quantity, not a per-atom or local quantity.</p>
<p>If <em>pvar</em> begins with “c_”, a compute ID must follow which has been
previously defined in the input script and which generates a global
scalar or vector. See the individual <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> doc page
for details. If no bracketed integer is appended, the scalar
calculated by the compute is used. If a bracketed integer is
appended, the Ith value of the vector calculated by the compute is
used. Users can also write code for their own compute styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If <em>pvar</em> begins with “f_”, a fix ID must follow which has been
previously defined in the input script and which generates a global
scalar or vector. See the individual <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> doc page for
details. Note that some fixes only produce their values on certain
timesteps, which must be compatible with when fix controller
references the values, or else an error results. If no bracketed integer
is appended, the scalar calculated by the fix is used. If a bracketed
integer is appended, the Ith value of the vector calculated by the fix
is used. Users can also write code for their own fix style and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If <em>pvar</em> begins with “v_”, a variable name must follow which has been
previously defined in the input script. Only equal-style variables
can be referenced. See the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command for
details. Note that variables of style <em>equal</em> define a formula which
can reference individual atom properties or thermodynamic keywords, or
they can invoke other computes, fixes, or variables when they are
evaluated, so this is a very general means of specifying the process
variable.</p>
<p>The target value <em>setpoint</em> for the process variable must be a numeric
value, in whatever units <em>pvar</em> is defined for.</p>
<p>The control variable <em>cvar</em> must be the name of an <a class="reference internal" href="variable.html"><span class="doc">internal-style variable</span></a> previously defined in the input script. Note
that it is not specified with a “v_” prefix, just the name of the
variable. It must be an internal-style variable, because this fix
updates its value directly. Note that other commands can use an
equal-style versus internal-style variable interchangeably.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>Currenlty, no information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>This fix produces a global vector with 3 values which can be accessed
by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The values
can be accessed on any timestep, though they are only updated on
timesteps that are a multiple of <em>Nevery</em>.</p>
<p>The three values are the most recent updates made to the control
variable by each of the 3 terms in the PID equation above. The first
value is the proportional term, the second is the integral term, the
third is the derivative term.</p>
<p>The units of the vector values will be whatever units the control
variable is in. The vector values calculated by this fix are
“extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</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>.
style = <em>final</em> or <em>delta</em> or <em>scale</em> or <em>vel</em> or <em>erate</em> or <em>trate</em> or <em>volume</em> or <em>wiggle</em> or <em>variable</em>
<em>final</em> values = lo hi
lo hi = box boundaries at end of run (distance units)
<em>delta</em> values = dlo dhi
dlo dhi = change in box boundaries at end of run (distance units)
<em>scale</em> values = factor
factor = multiplicative factor for change in box length at end of run
<em>vel</em> value = V
V = change box length at this velocity (distance/time units),
effectively an engineering strain rate
<em>erate</em> value = R
R = engineering strain rate (1/time units)
<em>trate</em> value = R
R = true strain rate (1/time units)
<em>volume</em> value = none = adjust this dim to preserve volume of system
<em>wiggle</em> values = A Tp
A = amplitude of oscillation (distance units)
Tp = period of oscillation (time units)
<em>variable</em> values = v_name1 v_name2
v_name1 = variable with name1 for box length change as function of time
v_name2 = variable with name2 for change rate as function of time
<em>xy</em>, <em>xz</em>, <em>yz</em> args = style value
style = <em>final</em> or <em>delta</em> or <em>vel</em> or <em>erate</em> or <em>trate</em> or <em>wiggle</em>
<em>final</em> value = tilt
tilt = tilt factor at end of run (distance units)
<em>delta</em> value = dtilt
dtilt = change in tilt factor at end of run (distance units)
<em>vel</em> value = V
V = change tilt factor at this velocity (distance/time units),
effectively an engineering shear strain rate
<em>erate</em> value = R
R = engineering shear strain rate (1/time units)
<em>trate</em> value = R
R = true shear strain rate (1/time units)
<em>wiggle</em> values = A Tp
A = amplitude of oscillation (distance units)
Tp = period of oscillation (time units)
<em>variable</em> values = v_name1 v_name2
v_name1 = variable with name1 for tilt change as function of time
v_name2 = variable with name2 for change rate as function of time
</pre>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>remap</em> or <em>flip</em> or <em>units</em></p>
<pre class="literal-block">
<em>remap</em> value = <em>x</em> or <em>v</em> or <em>none</em>
x = remap coords of atoms in group into deforming box
v = remap velocities of all atoms when they cross periodic boundaries
none = no remapping of x or v
<em>flip</em> value = <em>yes</em> or <em>no</em>
allow or disallow box flips when it becomes highly skewed
<em>units</em> value = <em>lattice</em> or <em>box</em>
lattice = distances are defined in lattice units
box = distances are defined in simulation box units
<p>Change the volume and/or shape of the simulation box during a dynamics
run. Orthogonal simulation boxes have 3 adjustable parameters
(x,y,z). Triclinic (non-orthogonal) simulation boxes have 6
adjustable parameters (x,y,z,xy,xz,yz). Any or all of them can be
adjusted independently and simultaneously by this command. This fix
can be used to perform non-equilibrium MD (NEMD) simulations of a
continuously strained system. See the <a class="reference internal" href="fix_nvt_sllod.html"><span class="doc">fix nvt/sllod</span></a> and <a class="reference internal" href="compute_temp_deform.html"><span class="doc">compute temp/deform</span></a> commands for more details.</p>
<p>For the <em>x</em>, <em>y</em>, <em>z</em> parameters, the associated dimension cannot be
shrink-wrapped. For the <em>xy</em>, <em>yz</em>, <em>xz</em> parameters, the associated
2nd dimension cannot be shrink-wrapped. Dimensions not varied by this
command can be periodic or non-periodic. Dimensions corresponding to
unspecified parameters can also be controlled by a <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> or <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command.</p>
<p>The size and shape of the simulation box at the beginning of the
simulation run were either specified by the
<a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> or <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> or
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command used to setup the simulation
initially if it is the first run, or they are the values from the end
of the previous run. The <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a>, <a class="reference internal" href="read_data.html"><span class="doc">read data</span></a>, and <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> commands
specify whether the simulation box is orthogonal or non-orthogonal
(triclinic) and explain the meaning of the xy,xz,yz tilt factors. If
fix deform changes the xy,xz,yz tilt factors, then the simulation box
must be triclinic, even if its initial tilt factors are 0.0.</p>
<p>As described below, the desired simulation box size and shape at the
end of the run are determined by the parameters of the fix deform
command. Every Nth timestep during the run, the simulation box is
expanded, contracted, or tilted to ramped values between the initial
and final values.</p>
<hr class="docutils" />
<p>For the <em>x</em>, <em>y</em>, and <em>z</em> parameters, this is the meaning of their
styles and values.</p>
<p>The <em>final</em>, <em>delta</em>, <em>scale</em>, <em>vel</em>, and <em>erate</em> styles all change
the specified dimension of the box via “constant displacement” which
is effectively a “constant engineering strain rate”. This means the
box dimension changes linearly with time from its initial to final
value.</p>
<p>For style <em>final</em>, the final lo and hi box boundaries of a dimension
are specified. The values can be in lattice or box distance units.
See the discussion of the units keyword below.</p>
<p>For style <em>delta</em>, plus or minus changes in the lo/hi box boundaries
of a dimension are specified. The values can be in lattice or box
distance units. See the discussion of the units keyword below.</p>
<p>For style <em>scale</em>, a multiplicative factor to apply to the box length
of a dimension is specified. For example, if the initial box length
is 10, and the factor is 1.1, then the final box length will be 11. A
factor less than 1.0 means compression.</p>
<p>For style <em>vel</em>, a velocity at which the box length changes is
specified in units of distance/time. This is effectively a “constant
engineering strain rate”, where rate = V/L0 and L0 is the initial box
length. The distance can be in lattice or box distance units. See
the discussion of the units keyword below. For example, if the
initial box length is 100 Angstroms, and V is 10 Angstroms/psec, then
after 10 psec, the box length will have doubled. After 20 psec, it
will have tripled.</p>
<p>The <em>erate</em> style changes a dimension of the the box at a “constant
engineering strain rate”. The units of the specified strain rate are
1/time. See the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command for the time units
associated with different choices of simulation units,
e.g. picoseconds for “metal” units). Tensile strain is unitless and
is defined as delta/L0, where L0 is the original box length and delta
is the change relative to the original length. The box length L as a
function of time will change as</p>
<pre class="literal-block">
L(t) = L0 (1 + erate*dt)
</pre>
<p>where dt is the elapsed time (in time units). Thus if <em>erate</em> R is
specified as 0.1 and time units are picoseconds, this means the box
length will increase by 10% of its original length every picosecond.
I.e. strain after 1 psec = 0.1, strain after 2 psec = 0.2, etc. R =
-0.01 means the box length will shrink by 1% of its original length
every picosecond. Note that for an “engineering” rate the change is
based on the original box length, so running with R = 1 for 10
picoseconds expands the box length by a factor of 11 (strain of 10),
which is different that what the <em>trate</em> style would induce.</p>
<p>The <em>trate</em> style changes a dimension of the box at a “constant true
strain rate”. Note that this is not an “engineering strain rate”, as
the other styles are. Rather, for a “true” rate, the rate of change
is constant, which means the box dimension changes non-linearly with
time from its initial to final value. The units of the specified
strain rate are 1/time. See the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command for the
time units associated with different choices of simulation units,
e.g. picoseconds for “metal” units). Tensile strain is unitless and
is defined as delta/L0, where L0 is the original box length and delta
is the change relative to the original length.</p>
<p>The box length L as a function of time will change as</p>
<pre class="literal-block">
L(t) = L0 exp(trate*dt)
</pre>
<p>where dt is the elapsed time (in time units). Thus if <em>trate</em> R is
specified as ln(1.1) and time units are picoseconds, this means the
box length will increase by 10% of its current (not original) length
every picosecond. I.e. strain after 1 psec = 0.1, strain after 2 psec
= 0.21, etc. R = ln(2) or ln(3) means the box length will double or
triple every picosecond. R = ln(0.99) means the box length will
shrink by 1% of its current length every picosecond. Note that for a
“true” rate the change is continuous and based on the current length,
so running with R = ln(2) for 10 picoseconds does not expand the box
length by a factor of 11 as it would with <em>erate</em>, but by a factor of
1024 since the box length will double every picosecond.</p>
<p>Note that to change the volume (or cross-sectional area) of the
simulation box at a constant rate, you can change multiple dimensions
via <em>erate</em> or <em>trate</em>. E.g. to double the box volume in a picosecond
picosecond, you could set “x erate M”, “y erate M”, “z erate M”, with
M = pow(2,1/3) - 1 = 0.26, since if each box dimension grows by 26%,
the box volume doubles. Or you could set “x trate M”, “y trate M”, “z
trate M”, with M = ln(1.26) = 0.231, and the box volume would double
every picosecond.</p>
<p>The <em>volume</em> style changes the specified dimension in such a way that
the box volume remains constant while other box dimensions are changed
explicitly via the styles discussed above. For example, “x scale 1.1
y scale 1.1 z volume” will shrink the z box length as the x,y box
lengths increase, to keep the volume constant (product of x,y,z
lengths). If “x scale 1.1 z volume” is specified and parameter <em>y</em> is
unspecified, then the z box length will shrink as x increases to keep
the product of x,z lengths constant. If “x scale 1.1 y volume z
volume” is specified, then both the y,z box lengths will shrink as x
increases to keep the volume constant (product of x,y,z lengths). In
this case, the y,z box lengths shrink so as to keep their relative
aspect ratio constant.</p>
<p>For solids or liquids, note that when one dimension of the box is
expanded via fix deform (i.e. tensile strain), it may be physically
undesirable to hold the other 2 box lengths constant (unspecified by
fix deform) since that implies a density change. Using the <em>volume</em>
style for those 2 dimensions to keep the box volume constant may make
more physical sense, but may also not be correct for materials and
potentials whose Poisson ratio is not 0.5. An alternative is to use
<a class="reference internal" href="fix_nh.html"><span class="doc">fix npt aniso</span></a> with zero applied pressure on those 2
dimensions, so that they respond to the tensile strain dynamically.</p>
<p>The <em>wiggle</em> style oscillates the specified box length dimension
sinusoidally with the specified amplitude and period. I.e. the box
length L as a function of time is given by</p>
<pre class="literal-block">
L(t) = L0 + A sin(2*pi t/Tp)
</pre>
<p>where L0 is its initial length. If the amplitude A is a positive
number the box initially expands, then contracts, etc. If A is
negative then the box initially contracts, then expands, etc. The
amplitude can be in lattice or box distance units. See the discussion
of the units keyword below.</p>
<p>The <em>variable</em> style changes the specified box length dimension by
evaluating a variable, which presumably is a function of time. The
variable with <em>name1</em> must be an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a>
and should calculate a change in box length in units of distance.
Note that this distance is in box units, not lattice units; see the
discussion of the <em>units</em> keyword below. The formula associated with
variable <em>name1</em> can reference the current timestep. Note that it
should return the “change” in box length, not the absolute box length.
This means it should evaluate to 0.0 when invoked on the initial
timestep of the run following the definition of fix deform. It should
evaluate to a value > 0.0 to dilate the box at future times, or a
value < 0.0 to compress the box.</p>
<p>The variable <em>name2</em> must also be an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> and should calculate the rate of box length
change, in units of distance/time, i.e. the time-derivative of the
<em>name1</em> variable. This quantity is used internally by LAMMPS to reset
atom velocities when they cross periodic boundaries. It is computed
internally for the other styles, but you must provide it when using an
arbitrary variable.</p>
<p>Here is an example of using the <em>variable</em> style to perform the same
box deformation as the <em>wiggle</em> style formula listed above, where we
fix 2 all deform 1 x variable v_displace v_rate remap v
</pre>
<p>For the <em>scale</em>, <em>vel</em>, <em>erate</em>, <em>trate</em>, <em>volume</em>, <em>wiggle</em>, and
<em>variable</em> styles, the box length is expanded or compressed around its
mid point.</p>
<hr class="docutils" />
<p>For the <em>xy</em>, <em>xz</em>, and <em>yz</em> parameters, this is the meaning of their
styles and values. Note that changing the tilt factors of a triclinic
box does not change its volume.</p>
<p>The <em>final</em>, <em>delta</em>, <em>vel</em>, and <em>erate</em> styles all change the shear
strain at a “constant engineering shear strain rate”. This means the
tilt factor changes linearly with time from its initial to final
value.</p>
<p>For style <em>final</em>, the final tilt factor is specified. The value
can be in lattice or box distance units. See the discussion of the
units keyword below.</p>
<p>For style <em>delta</em>, a plus or minus change in the tilt factor is
specified. The value can be in lattice or box distance units. See
the discussion of the units keyword below.</p>
<p>For style <em>vel</em>, a velocity at which the tilt factor changes is
specified in units of distance/time. This is effectively an
“engineering shear strain rate”, where rate = V/L0 and L0 is the
initial box length perpendicular to the direction of shear. The
distance can be in lattice or box distance units. See the discussion
of the units keyword below. For example, if the initial tilt factor
is 5 Angstroms, and the V is 10 Angstroms/psec, then after 1 psec, the
tilt factor will be 15 Angstroms. After 2 psec, it will be 25
Angstroms.</p>
<p>The <em>erate</em> style changes a tilt factor at a “constant engineering
shear strain rate”. The units of the specified shear strain rate are
1/time. See the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command for the time units
associated with different choices of simulation units,
e.g. picoseconds for “metal” units). Shear strain is unitless and is
defined as offset/length, where length is the box length perpendicular
to the shear direction (e.g. y box length for xy deformation) and
offset is the displacement distance in the shear direction (e.g. x
direction for xy deformation) from the unstrained orientation.</p>
<p>The tilt factor T as a function of time will change as</p>
<pre class="literal-block">
T(t) = T0 + L0*erate*dt
</pre>
<p>where T0 is the initial tilt factor, L0 is the original length of the
box perpendicular to the shear direction (e.g. y box length for xy
deformation), and dt is the elapsed time (in time units). Thus if
<em>erate</em> R is specified as 0.1 and time units are picoseconds, this
means the shear strain will increase by 0.1 every picosecond. I.e. if
the xy shear strain was initially 0.0, then strain after 1 psec = 0.1,
strain after 2 psec = 0.2, etc. Thus the tilt factor would be 0.0 at
time 0, 0.1*ybox at 1 psec, 0.2*ybox at 2 psec, etc, where ybox is the
original y box length. R = 1 or 2 means the tilt factor will increase
by 1 or 2 every picosecond. R = -0.01 means a decrease in shear
strain by 0.01 every picosecond.</p>
<p>The <em>trate</em> style changes a tilt factor at a “constant true shear
strain rate”. Note that this is not an “engineering shear strain
rate”, as the other styles are. Rather, for a “true” rate, the rate
of change is constant, which means the tilt factor changes
non-linearly with time from its initial to final value. The units of
the specified shear strain rate are 1/time. See the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command for the time units associated with
different choices of simulation units, e.g. picoseconds for “metal”
units). Shear strain is unitless and is defined as offset/length,
where length is the box length perpendicular to the shear direction
(e.g. y box length for xy deformation) and offset is the displacement
distance in the shear direction (e.g. x direction for xy deformation)
from the unstrained orientation.</p>
<p>The tilt factor T as a function of time will change as</p>
<pre class="literal-block">
T(t) = T0 exp(trate*dt)
</pre>
<p>where T0 is the initial tilt factor and dt is the elapsed time (in
time units). Thus if <em>trate</em> R is specified as ln(1.1) and time units
are picoseconds, this means the shear strain or tilt factor will
increase by 10% every picosecond. I.e. if the xy shear strain was
initially 0.1, then strain after 1 psec = 0.11, strain after 2 psec =
0.121, etc. R = ln(2) or ln(3) means the tilt factor will double or
triple every picosecond. R = ln(0.99) means the tilt factor will
shrink by 1% every picosecond. Note that the change is continuous, so
running with R = ln(2) for 10 picoseconds does not change the tilt
factor by a factor of 10, but by a factor of 1024 since it doubles
every picosecond. Note that the initial tilt factor must be non-zero
to use the <em>trate</em> option.</p>
<p>Note that shear strain is defined as the tilt factor divided by the
perpendicular box length. The <em>erate</em> and <em>trate</em> styles control the
tilt factor, but assume the perpendicular box length remains constant.
If this is not the case (e.g. it changes due to another fix deform
parameter), then this effect on the shear strain is ignored.</p>
<p>The <em>wiggle</em> style oscillates the specified tilt factor sinusoidally
with the specified amplitude and period. I.e. the tilt factor T as a
function of time is given by</p>
<pre class="literal-block">
T(t) = T0 + A sin(2*pi t/Tp)
</pre>
<p>where T0 is its initial value. If the amplitude A is a positive
number the tilt factor initially becomes more positive, then more
negative, etc. If A is negative then the tilt factor initially
becomes more negative, then more positive, etc. The amplitude can be
in lattice or box distance units. See the discussion of the units
keyword below.</p>
<p>The <em>variable</em> style changes the specified tilt factor by evaluating a
variable, which presumably is a function of time. The variable with
<em>name1</em> must be an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> and should
calculate a change in tilt in units of distance. Note that this
distance is in box units, not lattice units; see the discussion of the
<em>units</em> keyword below. The formula associated with variable <em>name1</em>
can reference the current timestep. Note that it should return the
“change” in tilt factor, not the absolute tilt factor. This means it
should evaluate to 0.0 when invoked on the initial timestep of the run
following the definition of fix deform.</p>
<p>The variable <em>name2</em> must also be an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> and should calculate the rate of tilt change,
in units of distance/time, i.e. the time-derivative of the <em>name1</em>
variable. This quantity is used internally by LAMMPS to reset atom
velocities when they cross periodic boundaries. It is computed
internally for the other styles, but you must provide it when using an
arbitrary variable.</p>
<p>Here is an example of using the <em>variable</em> style to perform the same
box deformation as the <em>wiggle</em> style formula listed above, where we
fix 2 all deform 1 xy variable v_displace v_rate remap v
</pre>
<hr class="docutils" />
<p>All of the tilt styles change the xy, xz, yz tilt factors during a
simulation. In LAMMPS, tilt factors (xy,xz,yz) for triclinic boxes
are normally bounded by half the distance of the parallel box length.
See the discussion of the <em>flip</em> keyword below, to allow this bound to
be exceeded, if desired.</p>
<p>For example, if xlo = 2 and xhi = 12, then the x box length is 10 and
the xy tilt factor must be between -5 and 5. Similarly, both xz and
yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is
not a limitation, since if the maximum tilt factor is 5 (as in this
example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
... are all equivalent.</p>
<p>To obey this constraint and allow for large shear deformations to be
applied via the <em>xy</em>, <em>xz</em>, or <em>yz</em> parameters, the following
algorithm is used. If <em>prd</em> is the associated parallel box length (10
in the example above), then if the tilt factor exceeds the accepted
range of -5 to 5 during the simulation, then the box is flipped to the
other limit (an equivalent box) and the simulation continues. Thus
for this example, if the initial xy tilt factor was 0.0 and “xy final
100.0” was specified, then during the simulation the xy tilt factor
would increase from 0.0 to 5.0, the box would be flipped so that the
tilt factor becomes -5.0, the tilt factor would increase from -5.0 to
5.0, the box would be flipped again, etc. The flip occurs 10 times
and the final tilt factor at the end of the simulation would be 0.0.
During each flip event, atoms are remapped into the new box in the
appropriate manner.</p>
<p>The one exception to this rule is if the 1st dimension in the tilt
factor (x for xy) is non-periodic. In that case, the limits on the
tilt factor are not enforced, since flipping the box in that dimension
does not change the atom positions due to non-periodicity. In this
mode, if you tilt the system to extreme angles, the simulation will
simply become inefficient due to the highly skewed simulation box.</p>
<hr class="docutils" />
<p>Each time the box size or shape is changed, the <em>remap</em> keyword
determines whether atom positions are remapped to the new box. If
<em>remap</em> is set to <em>x</em> (the default), atoms in the fix group are
remapped; otherwise they are not. Note that their velocities are not
changed, just their positions are altered. If <em>remap</em> is set to <em>v</em>,
then any atom in the fix group that crosses a periodic boundary will
have a delta added to its velocity equal to the difference in
velocities between the lo and hi boundaries. Note that this velocity
difference can include tilt components, e.g. a delta in the x velocity
when an atom crosses the y periodic boundary. If <em>remap</em> is set to
<em>none</em>, then neither of these remappings take place.</p>
<p>Conceptually, setting <em>remap</em> to <em>x</em> forces the atoms to deform via an
affine transformation that exactly matches the box deformation. This
setting is typically appropriate for solids. Note that though the
atoms are effectively “moving” with the box over time, it is not due
to their having a velocity that tracks the box change, but only due to
the remapping. By contrast, setting <em>remap</em> to <em>v</em> is typically
appropriate for fluids, where you want the atoms to respond to the
change in box size/shape on their own and acquire a velocity that
matches the box change, so that their motion will naturally track the
box without explicit remapping of their coordinates.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When non-equilibrium MD (NEMD) simulations are performed using
this fix, the option “remap v” should normally be used. This is
because <a class="reference internal" href="fix_nvt_sllod.html"><span class="doc">fix nvt/sllod</span></a> adjusts the atom positions
and velocities to induce a velocity profile that matches the changing
box size/shape. Thus atom coordinates should NOT be remapped by fix
deform, but velocities SHOULD be when atoms cross periodic boundaries,
since that is consistent with maintaining the velocity profile already
created by fix nvt/sllod. LAMMPS will warn you if the <em>remap</em> setting
is not consistent with fix nvt/sllod.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For non-equilibrium MD (NEMD) simulations using “remap v” it is
usually desirable that the fluid (or flowing material, e.g. granular
particles) stream with a velocity profile consistent with the
deforming box. As mentioned above, using a thermostat such as <a class="reference internal" href="fix_nvt_sllod.html"><span class="doc">fix nvt/sllod</span></a> or <a class="reference internal" href="fix_langevin.html"><span class="doc">fix lavgevin</span></a>
(with a bias provided by <a class="reference internal" href="compute_temp_deform.html"><span class="doc">compute temp/deform</span></a>), will typically accomplish
that. If you do not use a thermostat, then there is no driving force
pushing the atoms to flow in a manner consistent with the deforming
box. E.g. for a shearing system the box deformation velocity may vary
from 0 at the bottom to 10 at the top of the box. But the stream
velocity profile of the atoms may vary from -5 at the bottom to +5 at
the top. You can monitor these effects using the <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a>, <a class="reference internal" href="compute_temp_deform.html"><span class="doc">compute temp/deform</span></a>, and <a class="reference internal" href="compute_temp_profile.html"><span class="doc">compute temp/profile</span></a> commands. One way to induce
atoms to stream consistent with the box deformation is to give them an
initial velocity profile, via the <a class="reference internal" href="velocity.html"><span class="doc">velocity ramp</span></a>
command, that matches the box deformation rate. This also typically
helps the system come to equilibrium more quickly, even if a
thermostat is used.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If a <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> is defined for rigid bodies, and
<em>remap</em> is set to <em>x</em>, then the center-of-mass coordinates of rigid
bodies will be remapped to the changing simulation box. This will be
done regardless of whether atoms in the rigid bodies are in the fix
deform group or not. The velocity of the centers of mass are not
remapped even if <em>remap</em> is set to <em>v</em>, since <a class="reference internal" href="fix_nvt_sllod.html"><span class="doc">fix nvt/sllod</span></a> does not currently do anything special
for rigid particles. If you wish to perform a NEMD simulation of
rigid particles, you can either thermostat them independently or
include a background fluid and thermostat the fluid via <a class="reference internal" href="fix_nvt_sllod.html"><span class="doc">fix nvt/sllod</span></a>.</p>
</div>
<p>The <em>flip</em> keyword allows the tilt factors for a triclinic box to
exceed half the distance of the parallel box length, as discussed
above. If the <em>flip</em> value is set to <em>yes</em>, the bound is enforced by
flipping the box when it is exceeded. If the <em>flip</em> value is set to
<em>no</em>, the tilt will continue to change without flipping. Note that if
you apply large deformations, this means the box shape can tilt
dramatically LAMMPS will run less efficiently, due to the large volume
of communication needed to acquire ghost atoms around a processor’s
irregular-shaped sub-domain. For extreme values of tilt, LAMMPS may
also lose atoms and generate an error.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to define various arguments. A <em>box</em> value selects standard distance
units as defined by the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for
units = real or metal. A <em>lattice</em> value means the distance units are
in lattice spacings. The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have
been previously used to define the lattice spacing. Note that the
units choice also affects the <em>vel</em> style parameters since it is
defined in terms of distance/time. Also note that the units keyword
does not affect the <em>variable</em> style. You should use the <em>xlat</em>,
<em>ylat</em>, <em>zlat</em> keywords of the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a>
command if you want to include lattice spacings in a variable formula.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>.</p>
<p>This fix can perform deformation over multiple runs, using the <em>start</em>
and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>You cannot apply x, y, or z deformations to a dimension that is
shrink-wrapped via the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> comamnd.</p>
<p>You cannot apply xy, yz, or xz deformations to a 2nd dimension (y in
xy) that is shrink-wrapped via the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> comamnd.</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>.
<p>where <span class="math">\(m_i\)</span> is the mass and <span class="math">\(k(\mathbf r_i)\)</span> maps the particle
position to the respective reservoir. The quantity
<span class="math">\(F_{\Gamma_{k(\mathbf r_i)}}\)</span> corresponds to the input parameter
<em>F</em>, which is the energy flux into the reservoir. Furthermore,
<span class="math">\(K_{\Gamma_{k(\mathbf r_i)}}\)</span> and <span class="math">\(v_{\Gamma_{k(\mathbf r_i)}}\)</span>
denote the non-translational kinetic energy and the centre of mass
velocity of that reservoir. The thermostatting force does not affect
the centre of mass velocities of the individual reservoirs and the
entire simulation box. A derivation of the equations and details on
the numerical implementation with velocity Verlet in LAMMPS can be
found in reference “(Wirnsberger)”#_Wirnsberger.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This fix only integrates the thermostatting force and must be
combined with another integrator, such as <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>, to
solve the full equations of motion.</p>
</div>
<p>This fix is different from a thermostat such as <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>
or <a class="reference internal" href="fix_temp_rescale.html"><span class="doc">fix temp/rescale</span></a> in that energy is
added/subtracted continually. Thus if there isn’t another mechanism
in place to counterbalance this effect, the entire system will heat or
cool continuously.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If heat is subtracted from the system too aggressively so that
the group’s kinetic energy would go to zero, then LAMMPS will halt
with an error message. Increasing the value of <em>nevery</em> means that
heat is added/subtracted less frequently but in larger portions. The
resulting temperature profile will therefore be the same.</p>
</div>
<p>This fix will default to <a class="reference internal" href="fix_heat.html"><span class="doc">fix_heat</span></a> (HEX algorithm) if
the keyword <em>hex</em> is specified.</p>
<hr class="docutils" />
<p><strong>Compatibility with SHAKE and RATTLE (rigid molecules)</strong>:</p>
<p>This fix is compatible with <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> and <a class="reference internal" href="fix_shake.html"><span class="doc">fix rattle</span></a>. If either of these constraining algorithms is
specified in the input script and the keyword <em>constrain</em> is set, the
bond distances will be corrected a second time at the end of the
integration step. It is recommended to specify the keyword <em>com</em> in
addition to the keyword <em>constrain</em>. With this option all sites of a
constrained cluster are rescaled, if its centre of mass is located
inside the region. Rescaling all sites of a cluster by the same factor
does not introduce any velocity components along fixed bonds. No
rescaling takes place if the centre of mass lies outside the region.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can only use the keyword <em>com</em> along with <em>constrain</em>.</p>
</div>
<p>To achieve the highest accuracy it is recommended to use <a class="reference internal" href="fix_shake.html"><span class="doc">fix rattle</span></a> with the keywords <em>constrain</em> and <em>com</em> as
shown in the second example. Only if RATTLE is employed, the velocity
constraints will be satisfied.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Even if RATTLE is used and the keywords <em>com</em> and <em>constrain</em>
are both set, the coordinate constraints will not necessarily be
satisfied up to the target precision. The velocity constraints are
satisfied as long as all sites of a cluster are rescaled (keyword
<em>com</em>) and the cluster does not span adjacent reservoirs. The current
implementation of the eHEX algorithm introduces a small error in the
bond distances, which goes to zero with order three in the
timestep. For example, in a simulation of SPC/E water with a timestep
of 2 fs the maximum relative error in the bond distances was found to
be on the order of <span class="math">\(10^{-7}\)</span> for relatively large
temperature gradients. A higher precision can be achieved by
decreasing the timestep.</p>
</div>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the RIGID package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Zero out the z-dimension velocity and force on each atom in the group.
This is useful when running a 2d simulation to insure that atoms do
not move from their initial z coordinate.</p>
<hr class="docutils" />
<p>Styles with a suffix are functionally the same as the corresponding
style without the suffix. They have been optimized to run faster,
depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command.</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>.
<p>Zero out the force and torque on a granular particle. This is useful
for preventing certain particles from moving in a simulation. The
<a class="reference internal" href="pair_gran.html"><span class="doc">granular pair styles</span></a> also detect if this fix has been
defined and compute interactions between frozen and non-frozen
particles appropriately, as if the frozen particle has infinite mass.
A similar functionality for normal (point) particles can be obtained
using <a class="reference internal" href="fix_setforce.html"><span class="doc">fix setforce</span></a>.</p>
<hr class="docutils" />
<p>Styles with a suffix are functionally the same as the corresponding
style without the suffix. They have been optimized to run faster,
depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>This fix computes a global 3-vector of forces, which can be accessed
by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. This is the
total force on the group of atoms before the forces on individual
atoms are changed by the fix. The vector values calculated by this
fix are “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the GRANULAR package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>There can only be a single freeze fix defined. This is because other
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>.
<p>Applies Generalized Langevin Dynamics to a group of atoms, as
described in <a class="reference internal" href="#baczewski"><span class="std std-ref">(Baczewski)</span></a>. This is intended to model the
effect of an implicit solvent with a temporally non-local dissipative
force and a colored Gaussian random force, consistent with the
Fluctuation-Dissipation Theorem. The functional form of the memory
kernel associated with the temporally non-local force is constrained
to be a Prony series.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">While this fix bears many similarities to <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>, it has one significant
whereas <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> does NOT. To this end, the
specification of another fix to perform time integration, such as <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>, is NOT necessary.</p>
</div>
<p>With this fix active, the force on the <em>j</em>th atom is given as</p>
<p>The desired temperature at each timestep is ramped from <em>Tstart</em> to
<em>Tstop</em> over the course of the next run.</p>
<p>The random # <em>seed</em> must be a positive integer. A Marsaglia random
number generator is used. Each processor uses the input seed to
generate its own unique seed and its own stream of random
numbers. Thus the dynamics of the system will not be identical on two
runs on different numbers of processors.</p>
<hr class="docutils" />
<p>The keyword/value option pairs are used in the following ways.</p>
<p>The keyword <em>frozen</em> can be used to specify how the extended variables
associated with the GLD memory kernel are initialized. Specifying no
(the default), the initial values are drawn at random from an
equilibrium distribution at <em>Tstart</em>, consistent with the
Fluctuation-Dissipation Theorem. Specifying yes, initializes the
extended variables to zero.</p>
<p>The keyword <em>zero</em> can be used to eliminate drift due to the
thermostat. Because the random forces on different atoms are
independent, they do not sum exactly to zero. As a result, this fix
applies a small random force to the entire system, and the
center-of-mass of the system undergoes a slow random walk. If the
keyword <em>zero</em> is set to <em>yes</em>, the total random force is set exactly
to zero by subtracting off an equal part of it from each atom in the
group. As a result, the center-of-mass of a system with zero initial
momentum will not drift over time.</p>
<hr class="docutils" />
<p><strong>Restart, run start/stop, minimize info:</strong></p>
<p>The instantaneous values of the extended variables are written to
<a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. Because the state of the random
number generator is not saved in restart files, this means you cannot
do “exact” restarts with this fix, where the simulation continues on
the same as if no restart had taken place. However, in a statistical
sense, a restarted simulation should produce the same behavior.</p>
<p>None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options are relevant to this
fix. No global or per-atom quantities are stored by this fix for
access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the MISC package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>where F is the physical force, A is the drift matrix (that generalizes
the friction in Langevin dynamics), B is the diffusion term and dW/dt
un-correlated Gaussian random forces. The A matrix couples the physical
(q,p) dynamics with that of the additional degrees of freedom,
and makes it possible to obtain effectively a history-dependent
noise and friction kernel.</p>
<p>The drift matrix should be given as an external file <em>Afile</em>,
as a (Ns+1 x Ns+1) matrix in inverse time units. Matrices that are
optimal for a given application and the system of choice can be
obtained from <a class="reference internal" href="#gle4md"><span class="std std-ref">(GLE4MD)</span></a>.</p>
<p>Equilibrium sampling a temperature T is obtained by specifiying the
target value as the <em>Tstart</em> and <em>Tstop</em> arguments, so that the diffusion
matrix that gives canonical sampling for a given A is computed automatically.
However, the GLE framework also allow for non-equilibrium sampling, that
can be used for instance to model inexpensively zero-point energy
effects <a class="reference internal" href="#ceriotti2"><span class="std std-ref">(Ceriotti2)</span></a>. This is achieved specifying the
<em>noneq</em> keyword followed by the name of the file that contains the
static covariance matrix for the non-equilibrium dynamics.</p>
<p>Since integrating GLE dynamics can be costly when used together with
simple potentials, one can use the <em>every</em> optional keyword to
apply the Langevin terms only once every several MD steps, in a
multiple time-step fashion. This should be used with care when doing
non-equilibrium sampling, but should have no effect on equilibrium
averages when using canonical sampling.</p>
<p>The random number <em>seed</em> must be a positive integer. A Marsaglia random
number generator is used. Each processor uses the input seed to
generate its own unique seed and its own stream of random numbers.
Thus the dynamics of the system will not be identical on two runs on
different numbers of processors.</p>
<p>Note also that the Generalized Langevin Dynamics scheme that is
implemented by the <a class="reference internal" href="fix_gld.html"><span class="doc">fix gld</span></a> scheme is closely related
to the present one. In fact, it should be always possible to cast the
Prony series form of the memory kernel used by GLD into an appropriate
input matrix for <a class="reference internal" href="#"><span class="doc">fix gle</span></a>. While the GLE scheme is more
general, the form used by <a class="reference internal" href="fix_gld.html"><span class="doc">fix gld</span></a> can be more directly
related to the representation of an implicit solvent environment.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>The instantaneous values of the extended variables are written to
<a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. Because the state of the random
number generator is not saved in restart files, this means you cannot
do “exact” restarts with this fix, where the simulation continues on
the same as if no restart had taken place. However, in a statistical
sense, a restarted simulation should produce the same behavior.
Note however that you should use a different seed each time you
restart, otherwise the same sequence of random numbers will be used
each time, which might lead to stochastic synchronization and
subtle artefacts in the sampling.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Langevin thermostatting to the
system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is the
cummulative energy change due to this fix. The scalar value
calculated by this fix is “extensive”.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>The GLE thermostat in its current implementation should not be used
with rigid bodies, SHAKE or RATTLE. It is expected that all the
thermostatted degrees of freedom are fully flexible, and the sampled
ensemble will not be correct otherwise.</p>
<p>In order to perform constant-pressure simulations please use
<a class="reference internal" href="fix_press_berendsen.html"><span class="doc">fix press/berendsen</span></a>, rather than
<a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a>, to avoid duplicate integration of the
equations of motion.</p>
<p>This fix is part of the USER-MISC package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<li><p class="first">ID, group are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</p>
</li>
<li><p class="first">gravity = style name of this fix command</p>
</li>
<li><p class="first">magnitude = size of acceleration (force/mass units)</p>
</li>
<li><p class="first">magnitude can be a variable (see below)</p>
</li>
<li><p class="first">style = <em>chute</em> or <em>spherical</em> or <em>gradient</em> or <em>vector</em></p>
<pre class="literal-block">
<em>chute</em> args = angle
angle = angle in +x away from -z or -y axis in 3d/2d (in degrees)
angle can be a variable (see below)
<em>spherical</em> args = phi theta
phi = azimuthal angle from +x axis (in degrees)
theta = angle from +z or +y axis in 3d/2d (in degrees)
phi or theta can be a variable (see below)
<em>vector</em> args = x y z
x y z = vector direction to apply the acceleration
x or y or z can be a variable (see below)
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix 1 all gravity 1.0 chute 24.0
fix 1 all gravity v_increase chute 24.0
fix 1 all gravity 1.0 spherical 0.0 -180.0
fix 1 all gravity 10.0 spherical v_phi v_theta
fix 1 all gravity 100.0 vector 1 1 0
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Impose an additional acceleration on each particle in the group. This
fix is typically used with granular systems to include a “gravity”
term acting on the macroscopic particles. More generally, it can
represent any kind of driving field, e.g. a pressure gradient inducing
a Poiseuille flow in a fluid. Note that this fix operates differently
than the <a class="reference internal" href="fix_addforce.html"><span class="doc">fix addforce</span></a> command. The addforce fix
adds the same force to each atom, independent of its mass. This
command imparts the same acceleration to each atom (force/mass).</p>
<p>The <em>magnitude</em> of the acceleration is specified in force/mass units.
For granular systems (LJ units) this is typically 1.0. See the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command for details.</p>
<p>Style <em>chute</em> is typically used for simulations of chute flow where
the specified <em>angle</em> is the chute angle, with flow occurring in the +x
direction. For 3d systems, the tilt is away from the z axis; for 2d
systems, the tilt is away from the y axis.</p>
<p>Style <em>spherical</em> allows an arbitrary 3d direction to be specified for
the acceleration vector. <em>Phi</em> and <em>theta</em> are defined in the usual
spherical coordinates. Thus for acceleration acting in the -z
direction, <em>theta</em> would be 180.0 (or -180.0). <em>Theta</em> = 90.0 and
<em>phi</em> = -90.0 would mean acceleration acts in the -y direction. For
2d systems, <em>phi</em> is ignored and <em>theta</em> is an angle in the xy plane
where <em>theta</em> = 0.0 is the y-axis.</p>
<p>Style <em>vector</em> imposes an acceleration in the vector direction given
by (x,y,z). Only the direction of the vector is important; it’s
length is ignored. For 2d systems, the <em>z</em> component is ignored.</p>
<p>Any of the quantities <em>magnitude</em>, <em>angle</em>, <em>phi</em>, <em>theta</em>, <em>x</em>, <em>y</em>,
<em>z</em> which define the gravitational magnitude and direction, can be
specified as an equal-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. If the value is
a variable, it should be specified as v_name, where name is the
variable name. In this case, the variable will be evaluated each
timestep, and its value used to determine the quantity. You should
insure that the variable calculates a result in the approriate units,
e.g. force/mass or degrees.</p>
<p>Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent gravitational
field.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the gravitational potential energy of the system to the
system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is adding its forces. Default is the outermost level.</p>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. This scalar is the
gravitational potential energy of the particles in the defined field,
namely mass * (g dot x) for each particles, where x and mass are the
particles position and mass, and g is the gravitational field. The
scalar value calculated by this fix is “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>ipi = style name of this fix command</li>
<li>address = internet address (FQDN or IP), or UNIX socket name</li>
<li>port = port number (ignored for UNIX sockets)</li>
<li>optional keyword = <em>unix</em>, if present uses a unix socket</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<p>fix 1 all ipi my.server.com 12345
fix 1 all ipi mysocket 666 unix</p>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>This fix enables LAMMPS to be run as a client for the i-PI Python
wrapper <a class="reference internal" href="#ipihome"><span class="std std-ref">(IPI)</span></a> for performing a path integral molecular dynamics
(PIMD) simulation. The philosophy behind i-PI is described in the
following publication <a class="reference internal" href="#ipicpc"><span class="std std-ref">(IPI-CPC)</span></a>.</p>
<p>A version of the i-PI package, containing only files needed for use
with LAMMPS, is provided in the tools/i-pi directory. See the
tools/i-pi/manual.pdf for an introduction to i-PI. The
examples/USER/i-pi directory contains example scripts for using i-PI
with LAMMPS.</p>
<p>In brief, the path integral molecular dynamics is performed by the
Python wrapper, while the client (LAMMPS in this case) simply computes
forces and energy for each configuration. The communication between
the two components takes place using sockets, and is reduced to the
bare minimum. All the parameters of the dynamics are specified in the
input of i-PI, and all the parameters of the force field must be
specified as LAMMPS inputs, preceding the <em>fix ipi</em> command.</p>
<p>The server address must be specified by the <em>address</em> argument, and
can be either the IP address, the fully-qualified name of the server,
or the name of a UNIX socket for local, faster communication. In the
case of internet sockets, the <em>port</em> argument specifies the port
number on which i-PI is listening, while the <em>unix</em> optional switch
specifies that the socket is a UNIX socket.</p>
<p>Note that there is no check of data integrity, or that the atomic
configurations make sense. It is assumed that the species in the i-PI
input are listed in the same order as in the data file of LAMMPS. The
initial configuration is ignored, as it will be substituted with the
coordinates received from i-PI before forces are ever evaluated.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>There is no restart information associated with this fix, since all
the dynamical parameters are dealt with by i-PI.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>Using this fix on anything other than all atoms requires particular
care, since i-PI will know nothing on atoms that are not those whose
coordinates are transferred. However, one could use this strategy to
define an external potential acting on the atoms that are moved by
i-PI.</p>
<p>This fix is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info. Because of
the use of UNIX domain sockets, this fix will only work in a UNIX
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>.
-<p>Apply a Langevin thermostat as described in <a class="reference internal" href="fix_langevin_eff.html#schneider"><span class="std std-ref">(Schneider)</span></a>
+<p>Apply a Langevin thermostat as described in <a class="reference internal" href="#schneider"><span class="std std-ref">(Schneider)</span></a>
to a group of atoms which models an interaction with a background
implicit solvent. Used with <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>, this command
performs Brownian dynamics (BD), since the total force on each atom
<p>The Ff and Fr terms are added by this fix on a per-particle basis.
See the <a class="reference internal" href="pair_dpd.html"><span class="doc">pair_style dpd/tstat</span></a> command for a
thermostatting option that adds similar terms on a pairwise basis to
pairs of interacting particles.</p>
<p>Ff is a frictional drag or viscous damping term proportional to the
particle’s velocity. The proportionality constant for each atom is
computed as m/damp, where m is the mass of the particle and damp is
the damping factor specified by the user.</p>
<p>Fr is a force due to solvent atoms at a temperature T randomly bumping
into the particle. As derived from the fluctuation/dissipation
theorem, its magnitude as shown above is proportional to sqrt(Kb T m /
dt damp), where Kb is the Boltzmann constant, T is the desired
temperature, m is the mass of the particle, dt is the timestep size,
and damp is the damping factor. Random numbers are used to randomize
the direction and magnitude of this force as described in
-<a class="reference internal" href="fix_langevin_eff.html#dunweg"><span class="std std-ref">(Dunweg)</span></a>, where a uniform random number is used (instead of
+<a class="reference internal" href="#dunweg"><span class="std std-ref">(Dunweg)</span></a>, where a uniform random number is used (instead of
a Gaussian random number) for speed.</p>
<p>Note that unless you use the <em>omega</em> or <em>angmom</em> keywords, the
thermostat effect of this fix is applied to only the translational
degrees of freedom for the particles, which is an important
consideration for finite-size particles, which have rotational degrees
of freedom, are being thermostatted. The translational degrees of
freedom can also have a bias velocity removed from them before
thermostatting takes place; see the description below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unlike the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command which performs
Nose/Hoover thermostatting AND time integration, this fix does NOT
perform time integration. It only modifies forces to effect
thermostatting. Thus you must use a separate time integration fix,
like <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> to actually update the velocities and
positions of atoms using the modified forces. Likewise, this fix
should not normally be used on atoms that also have their temperature
controlled by another fix - e.g. by <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> or <a class="reference internal" href="fix_temp_rescale.html"><span class="doc">fix temp/rescale</span></a> commands.</p>
</div>
<p>See <a class="reference internal" href="Section_howto.html#howto-16"><span class="std std-ref">this howto section</span></a> of the manual for
a discussion of different ways to compute temperature and perform
thermostatting.</p>
<p>The desired temperature at each timestep is a ramped value during the
run from <em>Tstart</em> to <em>Tstop</em>.</p>
<p><em>Tstart</em> can be specified as an equal-style or atom-style
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. In this case, the <em>Tstop</em> setting is
ignored. If the value is a variable, it should be specified as
v_name, where name is the variable name. In this case, the variable
will be evaluated each timestep, and its value used to determine the
target temperature.</p>
<p>Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent temperature.</p>
<p>Atom-style variables can specify the same formulas as equal-style
variables but can also include per-atom values, such as atom
coordinates. Thus it is easy to specify a spatially-dependent
temperature with optional time-dependence as well.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that remove a “bias” from the
atom velocities. E.g. removing the center-of-mass velocity from a
group of atoms or removing the x-component of velocity from the
calculation. This is not done by default, but only if the
<a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages
for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones
include a bias. In this case, the thermostat works in the following
manner: bias is removed from each atom, thermostatting is performed on
the remaining thermal degrees of freedom, and the bias is added back
in.</p>
<p>The <em>damp</em> parameter is specified in time units and determines how
rapidly the temperature is relaxed. For example, a value of 100.0
means to relax the temperature in a timespan of (roughly) 100 time
units (tau or fmsec or psec - see the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command).
The damp factor can be thought of as inversely related to the
viscosity of the solvent. I.e. a small relaxation time implies a
hi-viscosity solvent and vice versa. See the discussion about gamma
and viscosity in the documentation for the <a class="reference internal" href="fix_viscous.html"><span class="doc">fix viscous</span></a> command for more details.</p>
<p>The random # <em>seed</em> must be a positive integer. A Marsaglia random
number generator is used. Each processor uses the input seed to
generate its own unique seed and its own stream of random numbers.
Thus the dynamics of the system will not be identical on two runs on
different numbers of processors.</p>
<hr class="docutils" />
<p>The keyword/value option pairs are used in the following ways.</p>
<p>The keyword <em>angmom</em> and <em>omega</em> keywords enable thermostatting of
rotational degrees of freedom in addition to the usual translational
degrees of freedom. This can only be done for finite-size particles.</p>
<p>A simulation using atom_style sphere defines an omega for finite-size
spheres. A simulation using atom_style ellipsoid defines a finite
size and shape for aspherical particles and an angular momentum.
The Langevin formulas for thermostatting the rotational degrees of
freedom are the same as those above, where force is replaced by
torque, m is replaced by the moment of inertia I, and v is replaced by
omega (which is derived from the angular momentum in the case of
aspherical particles).</p>
<p>The rotational temperature of the particles can be monitored by the
<a class="reference internal" href="compute_temp_sphere.html"><span class="doc">compute temp/sphere</span></a> and <a class="reference internal" href="compute_temp_asphere.html"><span class="doc">compute temp/asphere</span></a> commands with their rotate
options.</p>
<p>For the <em>omega</em> keyword there is also a scale factor of 10.0/3.0 that
is applied as a multiplier on the Ff (damping) term in the equation
above and of sqrt(10.0/3.0) as a multiplier on the Fr term. This does
not affect the thermostatting behaviour of the Langevin formalism but
insures that the randomized rotational diffusivity of spherical
particles is correct.</p>
<p>For the <em>angmom</em> keyword a similar scale factor is needed which is
10.0/3.0 for spherical particles, but is anisotropic for aspherical
particles (e.g. ellipsoids). Currently LAMMPS only applies an
isotropic scale factor, and you can choose its magnitude as the
specified value of the <em>angmom</em> keyword. If your aspherical particles
are (nearly) spherical than a value of 10.0/3.0 = 3.333 is a good
choice. If they are highly aspherical, a value of 1.0 is as good a
choice as any, since the effects on rotational diffusivity of the
particles will be incorrect regardless. Note that for any reasonable
scale factor, the thermostatting effect of the <em>angmom</em> keyword on the
rotational temperature of the aspherical particles should still be
valid.</p>
<p>The keyword <em>scale</em> allows the damp factor to be scaled up or down by
the specified factor for atoms of that type. This can be useful when
different atom types have different sizes or masses. It can be used
multiple times to adjust damp for several atom types. Note that
specifying a ratio of 2 increases the relaxation time which is
equivalent to the solvent’s viscosity acting on particles with 1/2 the
diameter. This is the opposite effect of scale factors used by the
<a class="reference internal" href="fix_viscous.html"><span class="doc">fix viscous</span></a> command, since the damp factor in fix
<em>langevin</em> is inversely related to the gamma factor in fix <em>viscous</em>.
Also note that the damping factor in fix <em>langevin</em> includes the
particle mass in Ff, unlike fix <em>viscous</em>. Thus the mass and size of
different atom types should be accounted for in the choice of ratio
values.</p>
<p>The keyword <em>tally</em> enables the calculation of the cumulative energy
added/subtracted to the atoms as they are thermostatted. Effectively
it is the energy exchanged between the infinite thermal reservoir and
the particles. As described below, this energy can then be printed
out or added to the potential energy of the system to monitor energy
conservation.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">this accumulated energy does NOT include kinetic energy removed
by the <em>zero</em> flag. LAMMPS will print a warning when both options are
active.</p>
</div>
<p>The keyword <em>zero</em> can be used to eliminate drift due to the
thermostat. Because the random forces on different atoms are
independent, they do not sum exactly to zero. As a result, this fix
applies a small random force to the entire system, and the
center-of-mass of the system undergoes a slow random walk. If the
keyword <em>zero</em> is set to <em>yes</em>, the total random force is set exactly
to zero by subtracting off an equal part of it from each atom in the
group. As a result, the center-of-mass of a system with zero initial
momentum will not drift over time.</p>
<p>The keyword <em>gjf</em> can be used to run the <a class="reference internal" href="#gronbech-jensen"><span class="std std-ref">Gronbech-Jensen/Farago</span></a> time-discretization of the Langevin model. As
described in the papers cited below, the purpose of this method is to
enable longer timesteps to be used (up to the numerical stability
limit of the integrator), while still producing the correct Boltzmann
distribution of atom positions. It is implemented within LAMMPS, by
changing how the the random force is applied so that it is composed of
the average of two random forces representing half-contributions from
the previous and current time intervals.</p>
<p>In common with all methods based on Verlet integration, the
discretized velocities generated by this method in conjunction with
velocity-Verlet time integration are not exactly conjugate to the
positions. As a result the temperature (computed from the discretized
velocities) will be systematically lower than the target temperature,
by a small amount which grows with the timestep. Nonetheless, the
distribution of atom positions will still be consistent with the
target temperature.</p>
<p>As an example of using the <em>gjf</em> keyword, for molecules containing C-H
bonds, configurational properties generated with dt = 2.5 fs and tdamp
= 100 fs are indistinguishable from dt = 0.5 fs. Because the velocity
distribution systematically decreases with increasing timestep, the
method should not be used to generate properties that depend on the
velocity distribution, such as the velocity autocorrelation function
(VACF). In this example, the velocity distribution at dt = 2.5fs
generates an average temperature of 220 K, instead of 300 K.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. Because the state of the random number generator
is not saved in restart files, this means you cannot do “exact”
restarts with this fix, where the simulation continues on the same as
if no restart had taken place. However, in a statistical sense, a
restarted simulation should produce the same behavior.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> option is supported by this
fix. You can use it to assign a temperature <a class="reference internal" href="compute.html"><span class="doc">compute</span></a>
you have defined to this fix which will be used in its thermostatting
procedure, as described above. For consistency, the group used by
this fix and by the compute should be the same.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Langevin thermostatting to the
system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>. Note that use of this option requires
setting the <em>tally</em> keyword to <em>yes</em>.</p>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is the
cummulative energy change due to this fix. The scalar value
calculated by this fix is “extensive”. Note that calculation of this
quantity requires setting the <em>tally</em> keyword to <em>yes</em>.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</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>.
-<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</p>
-</li>
-<li><p class="first">lb/fluid = style name of this fix command</p>
-</li>
-<li><p class="first">nevery = update the lattice-Boltzmann fluid every this many timesteps</p>
-</li>
-<li><p class="first">LBtype = 1 to use the standard finite difference LB integrator,
-2 to use the LB integrator of <a class="reference internal" href="#ollila"><span class="std std-ref">Ollila et al.</span></a></p>
-</li>
-<li><p class="first">viscosity = the fluid viscosity (units of mass/(time*length)).</p>
-</li>
-<li><p class="first">density = the fluid density.</p>
-</li>
-<li><p class="first">zero or more keyword/value pairs may be appended</p>
-</li>
-<li><p class="first">keyword = <em>setArea</em> or <em>setGamma</em> or <em>scaleGamma</em> or <em>dx</em> or <em>dm</em> or <em>a0</em> or <em>noise</em> or <em>calcforce</em> or <em>trilinear</em> or <em>D3Q19</em> or <em>read_restart</em> or <em>write_restart</em> or <em>zwall_velocity</em> or <em>bodyforce</em> or <em>printfluid</em></p>
+<ul class="simple">
+<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
+<li>lb/fluid = style name of this fix command</li>
+<li>nevery = update the lattice-Boltzmann fluid every this many timesteps</li>
+<li>LBtype = 1 to use the standard finite difference LB integrator,
+2 to use the LB integrator of <a class="reference internal" href="#ollila"><span class="std std-ref">Ollila et al.</span></a></li>
+<li>viscosity = the fluid viscosity (units of mass/(time*length)).</li>
+<li>density = the fluid density.</li>
+<li>zero or more keyword/value pairs may be appended</li>
+<li>keyword = <em>setArea</em> or <em>setGamma</em> or <em>scaleGamma</em> or <em>dx</em> or <em>dm</em> or <em>a0</em> or <em>noise</em> or <em>calcforce</em> or <em>trilinear</em> or <em>D3Q19</em> or <em>read_restart</em> or <em>write_restart</em> or <em>zwall_velocity</em> or <em>bodyforce</em> or <em>printfluid</em></li>
+</ul>
<pre class="literal-block">
<em>setArea</em> values = type node_area
type = atom type (1-N)
node_area = portion of the surface area of the composite object associated with the particular atom type (used when the force coupling constant is set by default).
<em>setGamma</em> values = gamma
gamma = user set value for the force coupling constant.
<em>scaleGamma</em> values = type gammaFactor
type = atom type (1-N)
gammaFactor = factor to scale the <em>setGamma</em> gamma value by, for the specified atom type.
<em>dx</em> values = dx_LB = the lattice spacing.
<em>dm</em> values = dm_LB = the lattice-Boltzmann mass unit.
<em>a0</em> values = a_0_real = the square of the speed of sound in the fluid.
<em>noise</em> values = Temperature seed
Temperature = fluid temperature.
seed = random number generator seed (positive integer)
<em>calcforce</em> values = N forcegroup-ID
N = output the force and torque every N timesteps
forcegroup-ID = ID of the particle group to calculate the force and torque of
<em>trilinear</em> values = none (used to switch from the default Peskin interpolation stencil to the trilinear stencil).
<em>D3Q19</em> values = none (used to switch from the default D3Q15, 15 velocity lattice, to the D3Q19, 19 velocity lattice).
<em>read_restart</em> values = restart file = name of the restart file to use to restart a fluid run.
<em>write_restart</em> values = N = write a restart file every N MD timesteps.
<em>zwall_velocity</em> values = velocity_bottom velocity_top = velocities along the y-direction of the bottom and top walls (located at z=zmin and z=zmax).
<em>bodyforce</em> values = bodyforcex bodyforcey bodyforcez = the x,y and z components of a constant body force added to the fluid.
<em>printfluid</em> values = N = print the fluid density and velocity at each grid point every N timesteps.
<p>Here, m_v is the mass of the MD particle, m_u is a representative
fluid mass at the particle location, and dt_collision is a collision
time, chosen such that tau/dt_collision = 1 (see <a class="reference internal" href="#mackay2"><span class="std std-ref">Mackay and Denniston</span></a> for full details). In order to calculate m_u, the
fluid density is interpolated to the MD particle location, and
multiplied by a volume, node_area*dx_lb, where node_area represents
the portion of the surface area of the composite object associated
with a given MD particle. By default, node_area is set equal to
dx_lb*dx_lb; however specific values for given atom types can be set
using the <em>setArea</em> keyword.</p>
<p>The user also has the option of specifying their own value for the
force coupling constant, for all the MD particles associated with the
fix, through the use of the <em>setGamma</em> keyword. This may be useful
when modelling porous particles. See <a class="reference internal" href="#fluid-mackay"><span class="std std-ref">Mackay et al.</span></a> for a
detailed description of the method by which the user can choose an
appropriate gamma value.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">while this fix applies the force of the particles on the fluid,
it does not apply the force of the fluid to the particles. When the
force coupling constant is set using the default method, there is only
one option to include this hydrodynamic force on the particles, and
that is through the use of the <a class="reference internal" href="fix_lb_viscous.html"><span class="doc">lb/viscous</span></a> fix.
This fix adds the hydrodynamic force to the total force acting on the
particles, after which any of the built-in LAMMPS integrators can be
used to integrate the particle motion. However, if the user specifies
their own value for the force coupling constant, as mentioned in
<a class="reference internal" href="#fluid-mackay"><span class="std std-ref">Mackay et al.</span></a>, the built-in LAMMPS integrators may prove to
be unstable. Therefore, we have included our own integrators <a class="reference internal" href="fix_lb_rigid_pc_sphere.html"><span class="doc">fix lb/rigid/pc/sphere</span></a>, and <a class="reference internal" href="fix_lb_pc.html"><span class="doc">fix lb/pc</span></a>, to solve for the particle motion in these
cases. These integrators should not be used with the
<a class="reference internal" href="fix_lb_viscous.html"><span class="doc">lb/viscous</span></a> fix, as they add hydrodynamic forces
to the particles directly. In addition, they can not be used if the
force coupling constant has been set the default way.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">if the force coupling constant is set using the default method,
and the <a class="reference internal" href="fix_lb_viscous.html"><span class="doc">lb/viscous</span></a> fix is NOT used to add the
hydrodynamic force to the total force acting on the particles, this
physically corresponds to a situation in which an infinitely massive
particle is moving through the fluid (since collisions between the
particle and the fluid do not act to change the particle’s velocity).
Therefore, the user should set the mass of the particle to be
significantly larger than the mass of the fluid at the particle
location, in order to approximate an infinitely massive particle (see
the dragforce test run for an example).</p>
</div>
<hr class="docutils" />
<p>Inside the fix, parameters are scaled by the lattice-Boltzmann
timestep, dt, grid spacing, dx, and mass unit, dm. dt is set equal to
(nevery*dt_MD), where dt_MD is the MD timestep. By default, dm is set
equal to 1.0, and dx is chosen so that tau/(dt) =
(3*eta*dt)/(rho*dx^2) is approximately equal to 1. However, the user
has the option of specifying their own values for dm, and dx, by using
the optional keywords <em>dm</em>, and <em>dx</em> respectively.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Care must be taken when choosing both a value for dx, and a
simulation domain size. This fix uses the same subdivision of the
simulation domain among processors as the main LAMMPS program. In
order to uniformly cover the simulation domain with lattice sites, the
lengths of the individual LAMMPS subdomains must all be evenly
divisible by dx. If the simulation domain size is cubic, with equal
lengths in all dimensions, and the default value for dx is used, this
will automatically be satisfied.</p>
</div>
<p>Physical parameters describing the fluid are specified through
<em>viscosity</em>, <em>density</em>, and <em>a0</em>. If the force coupling constant is
set the default way, the surface area associated with the MD particles
is specified using the <em>setArea</em> keyword. If the user chooses to
specify a value for the force coupling constant, this is set using the
<em>setGamma</em> keyword. These parameters should all be given in terms of
the mass, distance, and time units chosen for the main LAMMPS run, as
they are scaled by the LB timestep, lattice spacing, and mass unit,
inside the fix.</p>
<hr class="docutils" />
<p>The <em>setArea</em> keyword allows the user to associate a surface area with
a given atom type. For example if a spherical composite object of
radius R is represented as a spherical shell of N evenly distributed
MD particles, all of the same type, the surface area per particle
associated with that atom type should be set equal to 4*pi*R^2/N.
This keyword should only be used if the force coupling constant,
gamma, is set the default way.</p>
<p>The <em>setGamma</em> keyword allows the user to specify their own value for
the force coupling constant, gamma, instead of using the default
value.</p>
<p>The <em>scaleGamma</em> keyword should be used in conjunction with the
<em>setGamma</em> keyword, when the user wishes to specify different gamma
values for different atom types. This keyword allows the user to
scale the <em>setGamma</em> gamma value by a factor, gammaFactor, for a given
atom type.</p>
<p>The <em>dx</em> keyword allows the user to specify a value for the LB grid
spacing.</p>
<p>The <em>dm</em> keyword allows the user to specify the LB mass unit.</p>
<p>If the <em>a0</em> keyword is used, the value specified is used for the
square of the speed of sound in the fluid. If this keyword is not
present, the speed of sound squared is set equal to (1/3)*(dx/dt)^2.
Setting a0 > (dx/dt)^2 is not allowed, as this may lead to
instabilities.</p>
<p>If the <em>noise</em> keyword is used, followed by a a positive temperature
value, and a positive integer random number seed, a thermal
lattice-Boltzmann algorithm is used. If <em>LBtype</em> is set equal to 1
(i.e. the standard LB integrator is chosen), the thermal LB algorithm
of <a class="reference internal" href="#adhikari"><span class="std std-ref">Adhikari et al.</span></a> is used; however if <em>LBtype</em> is set
equal to 2 both the LB integrator, and thermal LB algorithm described
in <a class="reference internal" href="#ollila"><span class="std std-ref">Ollila et al.</span></a> are used.</p>
<p>If the <em>calcforce</em> keyword is used, both the fluid force and torque
acting on the specified particle group are printed to the screen every
N timesteps.</p>
<p>If the keyword <em>trilinear</em> is used, the trilinear stencil is used to
interpolate the particle nodes onto the fluid mesh. By default, the
immersed boundary method, Peskin stencil is used. Both of these
interpolation methods are described in <a class="reference internal" href="#fluid-mackay"><span class="std std-ref">Mackay et al.</span></a>.</p>
<p>If the keyword <em>D3Q19</em> is used, the 19 velocity (D3Q19) lattice is
used by the lattice-Boltzmann algorithm. By default, the 15 velocity
(D3Q15) lattice is used.</p>
<p>If the keyword <em>write_restart</em> is used, followed by a positive
integer, N, a binary restart file is printed every N LB timesteps.
This restart file only contains information about the fluid.
Therefore, a LAMMPS restart file should also be written in order to
print out full details of the simulation.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When a large number of lattice grid points are used, the restart
files may become quite large.</p>
</div>
<p>In order to restart the fluid portion of the simulation, the keyword
<em>read_restart</em> is specified, followed by the name of the binary
lb_fluid restart file to be used.</p>
<p>If the <em>zwall_velocity</em> keyword is used y-velocities are assigned to
the lower and upper walls. This keyword requires the presence of
walls in the z-direction. This is set by assigning fixed boundary
conditions in the z-direction. If fixed boundary conditions are
present in the z-direction, and this keyword is not used, the walls
are assumed to be stationary.</p>
<p>If the <em>bodyforce</em> keyword is used, a constant body force is added to
the fluid, defined by it’s x, y and z components.</p>
<p>If the <em>printfluid</em> keyword is used, followed by a positive integer, N,
the fluid densities and velocities at each lattice site are printed to the
screen every N timesteps.</p>
<hr class="docutils" />
<p>For further details, as well as descriptions and results of several
test runs, see <a class="reference internal" href="#fluid-mackay"><span class="std std-ref">Mackay et al.</span></a>. Please include a citation to
this paper if the lb_fluid fix is used in work contributing to
published research.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>Due to the large size of the fluid data, this fix writes it’s own
binary restart files, if requested, independent of the main LAMMPS
<a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>; no information about <em>lb_fluid</em>
is written to the main LAMMPS <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options are relevant to this
fix. No global or per-atom quantities are stored by this fix for
access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No
parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the USER-LB package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix can only be used with an orthogonal simulation domain.</p>
<p>Walls have only been implemented in the z-direction. Therefore, the
boundary conditions, as specified via the main LAMMPS boundary command
must be periodic for x and y, and either fixed or periodic for z.
Shrink-wrapped boundary conditions are not permitted with this fix.</p>
<p>This fix must be used before any of <a class="reference internal" href="fix_lb_viscous.html"><span class="doc">fix lb/viscous</span></a>, <a class="reference internal" href="fix_lb_momentum.html"><span class="doc">fix lb/momentum</span></a>, <a class="reference internal" href="fix_lb_rigid_pc_sphere.html"><span class="doc">fix lb/rigid/pc/sphere</span></a>, and/ or <a class="reference internal" href="fix_lb_pc.html"><span class="doc">fix lb/pc</span></a> , as the fluid needs to be initialized before
any of these routines try to access its properties. In addition, in
order for the hydrodynamic forces to be added to the particles, this
fix must be used in conjunction with the
<a class="reference internal" href="fix_lb_viscous.html"><span class="doc">lb/viscous</span></a> fix if the force coupling constant is
set by default, or either the <a class="reference internal" href="fix_lb_viscous.html"><span class="doc">lb/viscous</span></a> fix or
one of the <a class="reference internal" href="fix_lb_rigid_pc_sphere.html"><span class="doc">lb/rigid/pc/sphere</span></a> or
<a class="reference internal" href="fix_lb_pc.html"><span class="doc">lb/pc</span></a> integrators, if the user chooses to specifiy
their own value for the force coupling constant.</p>
<p>and an area of dx_lb^2 per node, used to calculate the fluid mass at
the particle node location, is assumed.</p>
<p>dx is chosen such that tau/(delta t_LB) =
(3 eta dt_LB)/(rho dx_lb^2) is approximately equal to 1.
dm is set equal to 1.0.
a0 is set equal to (1/3)*(dx_lb/dt_lb)^2.
The Peskin stencil is used as the default interpolation method.
The D3Q15 lattice is used for the lattice-Boltzmann algorithm.
If walls are present, they are assumed to be stationary.</p>
<hr class="docutils" />
<p id="ollila"><strong>(Ollila et al.)</strong> Ollila, S.T.T., Denniston, C., Karttunen, M., and Ala-Nissila, T., Fluctuating lattice-Boltzmann model for complex fluids, J. Chem. Phys. 134 (2011) 064902.</p>
<p id="fluid-mackay"><strong>(Mackay et al.)</strong> Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.</p>
<p id="mackay2"><strong>(Mackay and Denniston)</strong> Mackay, F. E., and Denniston, C., Coupling MD particles to a lattice-Boltzmann fluid through the use of conservative forces, J. Comput. Phys. 237 (2013) 289-298.</p>
<p id="adhikari"><strong>(Adhikari et al.)</strong> Adhikari, R., Stratford, K., Cates, M. E., and Wagner, A. J., Fluctuating lattice Boltzmann, Europhys. Lett. 71 (2005) 473-479.</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>.
<p>This fix is based on the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command, and was
created to be used in place of that fix, to integrate the equations of
motion of spherical rigid bodies when a lattice-Boltzmann fluid is
present with a user-specified value of the force-coupling constant.
-The fix uses the integration algorithm described in <a class="reference internal" href="fix_lb_viscous.html#mackay"><span class="std std-ref">Mackay et al.</span></a> to update the positions, velocities, and orientations of
+The fix uses the integration algorithm described in <a class="reference internal" href="#mackay"><span class="std std-ref">Mackay et al.</span></a> to update the positions, velocities, and orientations of
a set of spherical rigid bodies experiencing velocity dependent
hydrodynamic forces. The spherical bodies are assumed to rotate as
solid, uniform density spheres, with moments of inertia calculated
using the combined sum of the masses of all the constituent particles
(which are assumed to be point particles).</p>
<hr class="docutils" />
<p>By default, all of the atoms that this fix acts on experience a
hydrodynamic force due to the presence of the lattice-Boltzmann fluid.
However, the <em>innerNodes</em> keyword allows the user to specify atoms
belonging to a rigid object which do not interact with the
lattice-Boltzmann fluid (i.e. these atoms do not feel a hydrodynamic
force from the lattice-Boltzmann fluid). This can be used to
distinguish between atoms on the surface of a non-porous object, and
those on the inside.</p>
<p>This feature can be used, for example, when implementing a hard sphere
interaction between two spherical objects. Instead of interactions
occurring between the particles on the surfaces of the two spheres, it
is desirable simply to place an atom at the center of each sphere,
which does not contribute to the hydrodynamic force, and have these
central atoms interact with one another.</p>
<hr class="docutils" />
<p>Apart from the features described above, this fix is very similar to
the rigid fix (although it includes fewer optional arguments, and
assumes the constituent atoms are point particles); see
<a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> for a complete documentation.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about the <em>rigid</em> and <em>rigid/nve</em> fixes are written to
<p>Similar to the <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command: The rigid
fix computes a global scalar which can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar value calculated by
these fixes is “intensive”. The scalar is the current temperature of
the collection of rigid bodies. This is averaged over all rigid
bodies and their translational and rotational degrees of freedom. The
translational energy of a rigid body is 1/2 m v^2, where m = total
mass of the body and v = the velocity of its center of mass. The
rotational energy of a rigid body is 1/2 I w^2, where I = the moment
of inertia tensor of the body and w = its angular velocity. Degrees
of freedom constrained by the <em>force</em> and <em>torque</em> keywords are
removed from this calculation.</p>
<p>All of these fixes compute a global array of values which can be
accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>.
The number of rows in the array is equal to the number of rigid
bodies. The number of columns is 15. Thus for each rigid body, 15
values are stored: the xyz coords of the center of mass (COM), the xyz
components of the COM velocity, the xyz components of the force acting
on the COM, the xyz components of the torque acting on the COM, and
the xyz image flags of the COM, which have the same meaning as image
flags for atom positions (see the “dump” command). The force and
torque values in the array are not affected by the <em>force</em> and
<em>torque</em> keywords in the fix rigid command; they reflect values before
any changes are made by those keywords.</p>
<p>The ordering of the rigid bodies (by row in the array) is as follows.
For the <em>single</em> keyword there is just one rigid body. For the
<em>molecule</em> keyword, the bodies are ordered by ascending molecule ID.
For the <em>group</em> keyword, the list of group IDs determines the ordering
of bodies.</p>
<p>The array values calculated by these fixes are “intensive”, meaning
they are independent of the number of atoms in the simulation.</p>
<p>No parameter of these fixes can be used with the <em>start/stop</em> keywords
of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. These fixes are not invoked during
<p>This fix is part of the USER-LB package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>Can only be used if a lattice-Boltzmann fluid has been created via the
<a class="reference internal" href="fix_lb_fluid.html"><span class="doc">fix lb/fluid</span></a> command, and must come after this
command. Should only be used if the force coupling constant used in
<a class="reference internal" href="fix_lb_fluid.html"><span class="doc">fix lb/fluid</span></a> has been set by the user; this
integration fix cannot be used if the force coupling constant is set
<p>The defaults are force * on on on, and torque * on on on.</p>
<hr class="docutils" />
<p id="mackay"><strong>(Mackay et al.)</strong> Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.</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>.
<p>The inter-replica forces for the other replicas are unchanged from the
first equation.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
as invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command via the
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nph/asphere = style name of this fix command</li>
<li>additional barostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command can be appended</li>
<p>Perform constant NPH integration to update position, velocity,
orientation, and angular velocity each timestep for aspherical or
ellipsoidal particles in the group using a Nose/Hoover pressure
barostat. P is pressure; H is enthalpy. This creates a system
trajectory consistent with the isenthalpic ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command, which assumes
point particles and only updates their position and velocity.</p>
<p>Additional parameters affecting the barostat are specified by keywords
and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command. See,
for example, discussion of the <em>aniso</em>, and <em>dilate</em> keywords.</p>
<p>The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
NPH integration.</p>
<p>Regardless of what particles are in the fix group, a global pressure is
computed for all particles. Similarly, when the size of the simulation
box is changed, all particles are re-scaled to new positions, unless the
keyword <em>dilate</em> is specified with a value of <em>partial</em>, in which case
only the particles in the fix group are re-scaled. The latter can be
useful for leaving the coordinates of particles in a solid substrate
unchanged and controlling the pressure of a surrounding fluid.</p>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. To do
this, the fix creates its own computes of style “temp/asphere” and
“pressure”, as if these commands had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp all temp/asphere
compute fix-ID_press all pressure fix-ID_temp
</pre>
<p>See the <a class="reference internal" href="compute_temp_asphere.html"><span class="doc">compute temp/asphere</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is “all”
since pressure is computed for the entire system.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover barostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its thermostatting or barostatting procedure. If you do this, note
that the kinetic energy derived from the compute temperature should be
consistent with the virial term computed using all atoms for the
pressure. LAMMPS will warn you if you choose to compute temperature
on a subset of atoms.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover barostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command.</p>
<p>This fix can ramp its target pressure over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the ASPHERE package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style ellipsoid</span></a>
command.</p>
<p>All particles in the group must be finite-size. They cannot be point
particles, but they can be aspherical or spherical as defined by their
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nph/body = style name of this fix command</li>
<li>additional barostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command can be appended</li>
<p>Perform constant NPH integration to update position, velocity,
orientation, and angular velocity each timestep for body
particles in the group using a Nose/Hoover pressure
barostat. P is pressure; H is enthalpy. This creates a system
trajectory consistent with the isenthalpic ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command, which assumes
point particles and only updates their position and velocity.</p>
<p>Additional parameters affecting the barostat are specified by keywords
and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command. See,
for example, discussion of the <em>aniso</em>, and <em>dilate</em> keywords.</p>
<p>The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
NPH integration.</p>
<p>Regardless of what particles are in the fix group, a global pressure is
computed for all particles. Similarly, when the size of the simulation
box is changed, all particles are re-scaled to new positions, unless the
keyword <em>dilate</em> is specified with a value of <em>partial</em>, in which case
only the particles in the fix group are re-scaled. The latter can be
useful for leaving the coordinates of particles in a solid substrate
unchanged and controlling the pressure of a surrounding fluid.</p>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. To do
this, the fix creates its own computes of style “temp/body” and
“pressure”, as if these commands had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp all temp/body
compute fix-ID_press all pressure fix-ID_temp
</pre>
<p>See the <a class="reference internal" href="compute_temp_body.html"><span class="doc">compute temp/body</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is “all”
since pressure is computed for the entire system.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover barostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its thermostatting or barostatting procedure. If you do this, note
that the kinetic energy derived from the compute temperature should be
consistent with the virial term computed using all atoms for the
pressure. LAMMPS will warn you if you choose to compute temperature
on a subset of atoms.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover barostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command.</p>
<p>This fix can ramp its target pressure over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the BODY package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a>
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nph/sphere = style name of this fix command</li>
<li>additional barostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command can be appended</li>
<p>Perform constant NPH integration to update position, velocity, and
angular velocity each timestep for finite-size spherical particles in
the group using a Nose/Hoover pressure barostat. P is pressure; H is
enthalpy. This creates a system trajectory consistent with the
isenthalpic ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command, which assumes
point particles and only updates their position and velocity.</p>
<p>Additional parameters affecting the barostat are specified by keywords
and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command. See,
for example, discussion of the <em>aniso</em>, and <em>dilate</em> keywords.</p>
<p>The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
NPH integration.</p>
<p>Regardless of what particles are in the fix group, a global pressure is
computed for all particles. Similarly, when the size of the simulation
box is changed, all particles are re-scaled to new positions, unless the
keyword <em>dilate</em> is specified with a value of <em>partial</em>, in which case
only the particles in the fix group are re-scaled. The latter can be
useful for leaving the coordinates of particles in a solid substrate
unchanged and controlling the pressure of a surrounding fluid.</p>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. To do
this, the fix creates its own computes of style “temp/sphere” and
“pressure”, as if these commands had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp all temp/sphere
compute fix-ID_press all pressure fix-ID_temp
</pre>
<p>See the <a class="reference internal" href="compute_temp_sphere.html"><span class="doc">compute temp/sphere</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is “all”
since pressure is computed for the entire system.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover barostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its thermostatting or barostatting procedure. If you do this, note
that the kinetic energy derived from the compute temperature should be
consistent with the virial term computed using all atoms for the
pressure. LAMMPS will warn you if you choose to compute temperature
on a subset of atoms.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover barostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a> command.</p>
<p>This fix can ramp its target pressure over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix requires that atoms store torque and angular velocity (omega)
and a radius as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style sphere</span></a>
command.</p>
<p>All particles in the group must be finite-size spheres. They cannot
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>npt/asphere = style name of this fix command</li>
<li>additional thermostat and barostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command can be appended</li>
<p>Perform constant NPT integration to update position, velocity,
orientation, and angular velocity each timestep for aspherical or
ellipsoidal particles in the group using a Nose/Hoover temperature
thermostat and Nose/Hoover pressure barostat. P is pressure; T is
temperature. This creates a system trajectory consistent with the
isothermal-isobaric ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>The thermostat is applied to both the translational and rotational
degrees of freedom for the aspherical particles, assuming a compute is
used which calculates a temperature that includes the rotational
degrees of freedom (see below). The translational degrees of freedom
can also have a bias velocity removed from them before thermostatting
takes place; see the description below.</p>
<p>Additional parameters affecting the thermostat and barostat are
specified by keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command. See, for example, discussion of the <em>temp</em>,
<em>iso</em>, <em>aniso</em>, and <em>dilate</em> keywords.</p>
<p>The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
NPT integration.</p>
<p>Regardless of what particles are in the fix group, a global pressure is
computed for all particles. Similarly, when the size of the simulation
box is changed, all particles are re-scaled to new positions, unless the
keyword <em>dilate</em> is specified with a value of <em>partial</em>, in which case
only the particles in the fix group are re-scaled. The latter can be
useful for leaving the coordinates of particles in a solid substrate
unchanged and controlling the pressure of a surrounding fluid.</p>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. To do
this, the fix creates its own computes of style “temp/asphere” and
“pressure”, as if these commands had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp all temp/asphere
compute fix-ID_press all pressure fix-ID_temp
</pre>
<p>See the <a class="reference internal" href="compute_temp_asphere.html"><span class="doc">compute temp/asphere</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is “all”
since pressure is computed for the entire system.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat and barostat
to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its thermostatting or barostatting procedure. If you do this, note
that the kinetic energy derived from the compute temperature should be
consistent with the virial term computed using all atoms for the
pressure. LAMMPS will warn you if you choose to compute temperature
on a subset of atoms.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting and
barostatting to the system’s potential energy as part of
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command.</p>
<p>This fix can ramp its target temperature and pressure over multiple
runs, using the <em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a>
command. See the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do
this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the ASPHERE package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style ellipsoid</span></a>
command.</p>
<p>All particles in the group must be finite-size. They cannot be point
particles, but they can be aspherical or spherical as defined by their
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>npt/body = style name of this fix command</li>
<li>additional thermostat and barostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command can be appended</li>
<p>Perform constant NPT integration to update position, velocity,
orientation, and angular velocity each timestep for body
particles in the group using a Nose/Hoover temperature
thermostat and Nose/Hoover pressure barostat. P is pressure; T is
temperature. This creates a system trajectory consistent with the
isothermal-isobaric ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>The thermostat is applied to both the translational and rotational
degrees of freedom for the body particles, assuming a compute is
used which calculates a temperature that includes the rotational
degrees of freedom (see below). The translational degrees of freedom
can also have a bias velocity removed from them before thermostatting
takes place; see the description below.</p>
<p>Additional parameters affecting the thermostat and barostat are
specified by keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command. See, for example, discussion of the <em>temp</em>,
<em>iso</em>, <em>aniso</em>, and <em>dilate</em> keywords.</p>
<p>The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
NPT integration.</p>
<p>Regardless of what particles are in the fix group, a global pressure is
computed for all particles. Similarly, when the size of the simulation
box is changed, all particles are re-scaled to new positions, unless the
keyword <em>dilate</em> is specified with a value of <em>partial</em>, in which case
only the particles in the fix group are re-scaled. The latter can be
useful for leaving the coordinates of particles in a solid substrate
unchanged and controlling the pressure of a surrounding fluid.</p>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. To do
this, the fix creates its own computes of style “temp/body” and
“pressure”, as if these commands had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp all temp/body
compute fix-ID_press all pressure fix-ID_temp
</pre>
<p>See the <a class="reference internal" href="compute_temp_body.html"><span class="doc">compute temp/body</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is “all”
since pressure is computed for the entire system.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat and barostat
to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its thermostatting or barostatting procedure. If you do this, note
that the kinetic energy derived from the compute temperature should be
consistent with the virial term computed using all atoms for the
pressure. LAMMPS will warn you if you choose to compute temperature
on a subset of atoms.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting and
barostatting to the system’s potential energy as part of
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command.</p>
<p>This fix can ramp its target temperature and pressure over multiple
runs, using the <em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a>
command. See the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do
this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the BODY package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a>
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>npt/sphere = style name of this fix command</li>
<li>additional thermostat and barostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command can be appended</li>
<p>Perform constant NPT integration to update position, velocity, and
angular velocity each timestep for finite-sizex spherical particles in
the group using a Nose/Hoover temperature thermostat and Nose/Hoover
pressure barostat. P is pressure; T is temperature. This creates a
system trajectory consistent with the isothermal-isobaric ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>The thermostat is applied to both the translational and rotational
degrees of freedom for the spherical particles, assuming a compute is
used which calculates a temperature that includes the rotational
degrees of freedom (see below). The translational degrees of freedom
can also have a bias velocity removed from them before thermostatting
takes place; see the description below.</p>
<p>Additional parameters affecting the thermostat and barostat are
specified by keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> command. See, for example, discussion of the <em>temp</em>,
<em>iso</em>, <em>aniso</em>, and <em>dilate</em> keywords.</p>
<p>The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
NPT integration.</p>
<p>Regardless of what particles are in the fix group, a global pressure is
computed for all particles. Similarly, when the size of the simulation
box is changed, all particles are re-scaled to new positions, unless the
keyword <em>dilate</em> is specified with a value of <em>partial</em>, in which case
only the particles in the fix group are re-scaled. The latter can be
useful for leaving the coordinates of particles in a solid substrate
unchanged and controlling the pressure of a surrounding fluid.</p>
<hr class="docutils" />
<p>This fix computes a temperature and pressure each timestep. To do
this, the fix creates its own computes of style “temp/sphere” and
“pressure”, as if these commands had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp all temp/sphere
compute fix-ID_press all pressure fix-ID_temp
</pre>
<p>See the <a class="reference internal" href="compute_temp_sphere.html"><span class="doc">compute temp/sphere</span></a> and <a class="reference internal" href="compute_pressure.html"><span class="doc">compute pressure</span></a> commands for details. Note that the
IDs of the new computes are the fix-ID + underscore + “temp” or fix_ID
+ underscore + “press”, and the group for the new computes is “all”
since pressure is computed for the entire system.</p>
<p>Note that these are NOT the computes used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>
and <em>thermo_press</em>. This means you can change the attributes of this
fix’s temperature or pressure via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
or pressure during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> or
<em>thermo_press</em> will have no effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat and barostat
to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by this fix. You can use them to assign a
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have defined to this fix which will be used
in its thermostatting or barostatting procedure. If you do this, note
that the kinetic energy derived from the compute temperature should be
consistent with the virial term computed using all atoms for the
pressure. LAMMPS will warn you if you choose to compute temperature
on a subset of atoms.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting and
barostatting to the system’s potential energy as part of
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>.
<p>Perform constant NVE integration to update position and velocity for
atoms in the group each timestep. V is volume; E is energy. This
creates a system trajectory consistent with the microcanonical
ensemble.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</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>.
<p>Perform constant NVE integration to update position, velocity,
orientation, and angular velocity for aspherical particles in the
group each timestep. V is volume; E is energy. This creates a system
trajectory consistent with the microcanonical ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the ASPHERE package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style ellipsoid</span></a>
command.</p>
<p>All particles in the group must be finite-size. They cannot be point
particles, but they can be aspherical or spherical as defined by their
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>.
<p>Perform constant NVE integration to update position, velocity,
orientation, and angular velocity for body particles in the group each
timestep. V is volume; E is energy. This creates a system trajectory
consistent with the microcanonical ensemble. See <a class="reference internal" href="Section_howto.html#howto-14"><span class="std std-ref">Section 6.14</span></a> of the manual and the <a class="reference internal" href="body.html"><span class="doc">body</span></a>
doc page for more details on using body particles.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the BODY package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a>
command.</p>
<p>All particles in the group must be body particles. They cannot be
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>.
<p>Perform constant NVE integration to update position, velocity,
orientation, and angular velocity for line segment particles in the
group each timestep. V is volume; E is energy. This creates a system
trajectory consistent with the microcanonical ensemble. See
<a class="reference internal" href="Section_howto.html#howto-14"><span class="std std-ref">Section 6.14</span></a> of the manual for an
overview of using line segment particles.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the ASPHERE package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that particles be line segments as defined by the
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>.
<p>Perform constant NVE integration to update position and velocity for
atoms constrained to a curved surface (manifold) in the group each
timestep. The constraint is handled by RATTLE <a class="reference internal" href="fix_shake.html#andersen"><span class="std std-ref">(Andersen)</span></a>
written out for the special case of single-particle constraints as
explained in <a class="reference internal" href="#paquay2"><span class="std std-ref">(Paquay)</span></a>. V is volume; E is energy. This way,
the dynamics of particles constrained to curved surfaces can be
studied. If combined with <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>, this
generates Brownian motion of particles constrained to a curved
surface. For a list of currently supported manifolds and their
parameters, see <a class="reference internal" href="manifolds.html"><span class="doc">manifolds</span></a>.</p>
<p>Note that the particles must initially be close to the manifold in
question. If not, RATTLE will not be able to iterate until the
constraint is satisfied, and an error is generated. For simple
manifolds this can be achieved with <em>region</em> and <em>create_atoms</em>
commands, but for more complex surfaces it might be more useful to
write a script.</p>
<p>The manifold args may be equal-style variables, like so:</p>
<pre class="literal-block">
variable R equal "ramp(5.0,3.0)"
fix shrink_sphere all nve/manifold/rattle 1e-4 10 sphere v_R
</pre>
<p>In this case, the manifold parameter will change in time according to
the variable. This is not a problem for the time integrator as long
as the change of the manifold is slow with respect to the dynamics of
the particles. Note that if the manifold has to exert work on the
particles because of these changes, the total energy might not be
conserved.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the USER-MANIFOLD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<p>Perform constant NVE integration to update position, velocity, and
angular velocity for finite-size spherical particles in the group each
timestep. V is volume; E is energy. This creates a system trajectory
consistent with the microcanonical ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>If the <em>update</em> keyword is used with the <em>dipole</em> value, then the
orientation of the dipole moment of each particle is also updated
during the time integration. This option should be used for models
where a dipole moment is assigned to finite-size particles,
e.g. spheroids via use of the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style hybrid sphere dipole</span></a> command.</p>
<p>The default dipole orientation integrator can be changed to the
Dullweber-Leimkuhler-McLachlan integration scheme
<a class="reference internal" href="fix_nh.html#nh-dullweber"><span class="std std-ref">(Dullweber)</span></a> when using <em>update</em> with the value
<em>dipole/dlm</em>. This integrator is symplectic and time-reversible,
giving better energy conservation and allows slightly longer timesteps
at only a small additional computational cost.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix requires that atoms store torque and angular velocity (omega)
and a radius as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style sphere</span></a>
command. If the <em>dipole</em> keyword is used, then they must also store a
dipole moment as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style dipole</span></a>
command.</p>
<p>All particles in the group must be finite-size spheres. They cannot
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>.
<p>Perform constant NVE integration to update position, velocity,
orientation, and angular momentum for triangular particles in the
group each timestep. V is volume; E is energy. This creates a
system trajectory consistent with the microcanonical ensemble. See
<a class="reference internal" href="Section_howto.html#howto-14"><span class="std std-ref">Section 6.14</span></a> of the manual for an
overview of using triangular particles.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the ASPHERE package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that particles be triangles as defined by the
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nvt/asphere = style name of this fix command</li>
<li>additional thermostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command can be appended</li>
<p>Perform constant NVT integration to update position, velocity,
orientation, and angular velocity each timestep for aspherical or
ellipsoidal particles in the group using a Nose/Hoover temperature
thermostat. V is volume; T is temperature. This creates a system
trajectory consistent with the canonical ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>The thermostat is applied to both the translational and rotational
degrees of freedom for the aspherical particles, assuming a compute is
used which calculates a temperature that includes the rotational
degrees of freedom (see below). The translational degrees of freedom
can also have a bias velocity removed from them before thermostatting
takes place; see the description below.</p>
<p>Additional parameters affecting the thermostat are specified by
keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>
command. See, for example, discussion of the <em>temp</em> and <em>drag</em>
keywords.</p>
<p>This fix computes a temperature each timestep. To do this, the fix
creates its own compute of style “temp/asphere”, as if this command
had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp group-ID temp/asphere
</pre>
<p>See the <a class="reference internal" href="compute_temp_asphere.html"><span class="doc">compute temp/asphere</span></a> command for
details. Note that the ID of the new compute is the fix-ID +
underscore + “temp”, and the group for the new compute is the same as
the fix group.</p>
<p>Note that this is NOT the compute used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>.
This means you can change the attributes of this fix’s temperature
(e.g. its degrees-of-freedom) via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> will have no
effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> option is supported by this
fix. You can use it to assign a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have
defined to this fix which will be used in its thermostatting
procedure.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the ASPHERE package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style ellipsoid</span></a>
command.</p>
<p>All particles in the group must be finite-size. They cannot be point
particles, but they can be aspherical or spherical as defined by their
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nvt/body = style name of this fix command</li>
<li>additional thermostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command can be appended</li>
<p>Perform constant NVT integration to update position, velocity,
orientation, and angular velocity each timestep for body
particles in the group using a Nose/Hoover temperature
thermostat. V is volume; T is temperature. This creates a system
trajectory consistent with the canonical ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>The thermostat is applied to both the translational and rotational
degrees of freedom for the body particles, assuming a compute is
used which calculates a temperature that includes the rotational
degrees of freedom (see below). The translational degrees of freedom
can also have a bias velocity removed from them before thermostatting
takes place; see the description below.</p>
<p>Additional parameters affecting the thermostat are specified by
keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>
command. See, for example, discussion of the <em>temp</em> and <em>drag</em>
keywords.</p>
<p>This fix computes a temperature each timestep. To do this, the fix
creates its own compute of style “temp/body”, as if this command
had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp group-ID temp/body
</pre>
<p>See the <a class="reference internal" href="compute_temp_body.html"><span class="doc">compute temp/body</span></a> command for
details. Note that the ID of the new compute is the fix-ID +
underscore + “temp”, and the group for the new compute is the same as
the fix group.</p>
<p>Note that this is NOT the compute used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>.
This means you can change the attributes of this fix’s temperature
(e.g. its degrees-of-freedom) via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> will have no
effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> option is supported by this
fix. You can use it to assign a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have
defined to this fix which will be used in its thermostatting
procedure.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the BODY package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix requires that atoms store torque and angular momementum and a
quaternion as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style body</span></a>
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>.
<p>This fix combines the RATTLE-based <a class="reference internal" href="fix_shake.html#andersen"><span class="std std-ref">(Andersen)</span></a> time integrator of <a class="reference internal" href="fix_nve_manifold_rattle.html"><span class="doc">fix nve/manifold/rattle</span></a> <a class="reference internal" href="#paquay3"><span class="std std-ref">(Paquay)</span></a> with a Nose-Hoover-chain thermostat to sample the
canonical ensemble of particles constrained to a curved surface (manifold). This sampling does suffer from discretization bias of O(dt).
For a list of currently supported manifolds and their parameters, see <a class="reference internal" href="manifolds.html"><span class="doc">manifolds</span></a></p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the USER-MANIFOLD package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a>
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nvt/sllod = style name of this fix command</li>
<li>additional thermostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command can be appended</li>
<p>Perform constant NVT integration to update positions and velocities
each timestep for atoms in the group using a Nose/Hoover temperature
thermostat. V is volume; T is temperature. This creates a system
trajectory consistent with the canonical ensemble.</p>
<p>This thermostat is used for a simulation box that is changing size
and/or shape, for example in a non-equilibrium MD (NEMD) simulation.
The size/shape change is induced by use of the <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> command, so each point in the simulation box
can be thought of as having a “streaming” velocity. This
position-dependent streaming velocity is subtracted from each atom’s
actual velocity to yield a thermal velocity which is used for
temperature computation and thermostatting. For example, if the box
is being sheared in x, relative to y, then points at the bottom of the
box (low y) have a small x velocity, while points at the top of the
box (hi y) have a large x velocity. These velocities do not
contribute to the thermal “temperature” of the atom.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="fix_deform.html"><span class="doc">Fix deform</span></a> has an option for remapping either
atom coordinates or velocities to the changing simulation box. To use
fix nvt/sllod, fix deform should NOT remap atom positions, because fix
nvt/sllod adjusts the atom positions and velocities to create a
velocity profile that matches the changing box size/shape. Fix deform
SHOULD remap atom velocities when atoms cross periodic boundaries
since that is consistent with maintaining the velocity profile created
by fix nvt/sllod. LAMMPS will give an error if this setting is not
consistent.</p>
</div>
<p>The SLLOD equations of motion, originally proposed by Hoover and Ladd
(see <a class="reference internal" href="#evans"><span class="std std-ref">(Evans and Morriss)</span></a>), were proven to be equivalent to
Newton’s equations of motion for shear flow by <a class="reference internal" href="#evans"><span class="std std-ref">(Evans and Morriss)</span></a>. They were later shown to generate the desired
velocity gradient and the correct production of work by stresses for
all forms of homogeneous flow by <a class="reference internal" href="#daivis"><span class="std std-ref">(Daivis and Todd)</span></a>. As
implemented in LAMMPS, they are coupled to a Nose/Hoover chain
thermostat in a velocity Verlet formulation, closely following the
implementation used for the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command.</p>
<p>Additional parameters affecting the thermostat are specified by
keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>
command. See, for example, discussion of the <em>temp</em> and <em>drag</em>
keywords.</p>
<p>This fix computes a temperature each timestep. To do this, the fix
creates its own compute of style “temp/deform”, as if this command had
been issued:</p>
<pre class="literal-block">
compute fix-ID_temp group-ID temp/deform
</pre>
<p>See the <a class="reference internal" href="compute_temp_deform.html"><span class="doc">compute temp/deform</span></a> command for
details. Note that the ID of the new compute is the fix-ID +
underscore + “temp”, and the group for the new compute is the same as
the fix group.</p>
<p>Note that this is NOT the compute used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>.
This means you can change the attributes of this fix’s temperature
(e.g. its degrees-of-freedom) via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> will have no
effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> option is supported by this
fix. You can use it to assign a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have
defined to this fix which will be used in its thermostatting
procedure.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix works best without Nose-Hoover chain thermostats, i.e. using
tchain = 1. Setting tchain to larger values can result in poor
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>.
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>nvt/sphere = style name of this fix command</li>
<li>additional thermostat related keyword/value pairs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command can be appended</li>
<p>Perform constant NVT integration to update position, velocity, and
angular velocity each timestep for finite-size spherical particles in
the group using a Nose/Hoover temperature thermostat. V is volume; T
is temperature. This creates a system trajectory consistent with the
canonical ensemble.</p>
<p>This fix differs from the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command, which
assumes point particles and only updates their position and velocity.</p>
<p>The thermostat is applied to both the translational and rotational
degrees of freedom for the spherical particles, assuming a compute is
used which calculates a temperature that includes the rotational
degrees of freedom (see below). The translational degrees of freedom
can also have a bias velocity removed from them before thermostatting
takes place; see the description below.</p>
<p>Additional parameters affecting the thermostat are specified by
keywords and values documented with the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>
command. See, for example, discussion of the <em>temp</em> and <em>drag</em>
keywords.</p>
<p>This fix computes a temperature each timestep. To do this, the fix
creates its own compute of style “temp/sphere”, as if this command
had been issued:</p>
<pre class="literal-block">
compute fix-ID_temp group-ID temp/sphere
</pre>
<p>See the <a class="reference internal" href="compute_temp_sphere.html"><span class="doc">compute temp/sphere</span></a> command for
details. Note that the ID of the new compute is the fix-ID +
underscore + “temp”, and the group for the new compute is the same as
the fix group.</p>
<p>Note that this is NOT the compute used by thermodynamic output (see
the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command) with ID = <em>thermo_temp</em>.
This means you can change the attributes of this fix’s temperature
(e.g. its degrees-of-freedom) via the
<a class="reference internal" href="compute_modify.html"><span class="doc">compute_modify</span></a> command or print this temperature
during thermodynamic output via the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> command using the appropriate compute-ID.
It also means that changing attributes of <em>thermo_temp</em> will have no
effect on this fix.</p>
<p>Like other fixes that perform thermostatting, this fix can be used
with <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> that calculate a temperature
after removing a “bias” from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the state of the Nose/Hoover thermostat to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a>
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> option is supported by this
fix. You can use it to assign a <a class="reference internal" href="compute.html"><span class="doc">compute</span></a> you have
defined to this fix which will be used in its thermostatting
procedure.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy change induced by Nose/Hoover thermostatting to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>This fix computes the same global scalar and global vector of
quantities as does the <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> command.</p>
<p>This fix can ramp its target temperature over multiple runs, using the
<em>start</em> and <em>stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. See the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command for details of how to do this.</p>
<p>This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix requires that atoms store torque and angular velocity (omega)
and a radius as defined by the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style sphere</span></a>
command.</p>
<p>All particles in the group must be finite-size spheres. They cannot
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>.
<p>This fix is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>A PIMD simulation can be initialized with a single data file read via
the <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command. However, this means all
quasi-beads in a ring polymer will have identical positions and
velocities, resulting in identical trajectories for all quasi-beads.
To avoid this, users can simply initialize velocities with different
random number seeds assigned to each partition, as defined by the
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>.
-<li><p class="first">zero or more keyword/value pairs may be appended</p>
-</li>
-<li><p class="first">keyword = <em>q</em> or <em>mu</em> or <em>p0</em> or <em>v0</em> or <em>e0</em> or <em>tscale</em> or <em>damp</em> or <em>seed</em>or <em>f_max</em> or <em>N_f</em> or <em>eta</em> or <em>beta</em> or <em>T_init</em></p>
+<ul class="simple">
+<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
+<li>qbmsst = style name of this fix</li>
+<li>dir = <em>x</em> or <em>y</em> or <em>z</em></li>
+<li>zero or more keyword/value pairs may be appended</li>
+<li>keyword = <em>q</em> or <em>mu</em> or <em>p0</em> or <em>v0</em> or <em>e0</em> or <em>tscale</em> or <em>damp</em> or <em>seed</em>or <em>f_max</em> or <em>N_f</em> or <em>eta</em> or <em>beta</em> or <em>T_init</em></li>
+</ul>
<pre class="literal-block">
<em>q</em> value = cell mass-like parameter (mass^2/distance^4 units)
<em>mu</em> value = artificial viscosity (mass/distance/time units)
<em>p0</em> value = initial pressure in the shock equations (pressure units)
<em>v0</em> value = initial simulation cell volume in the shock equations (distance^3 units)
<em>e0</em> value = initial total energy (energy units)
<em>tscale</em> value = reduction in initial temperature (unitless fraction between 0.0 and 1.0)
<em>damp</em> value = damping parameter (time units) inverse of friction <i>&gamma;</i>
<em>seed</em> value = random number seed (positive integer)
<em>f_max</em> value = upper cutoff frequency of the vibration spectrum (1/time units)
<em>N_f</em> value = number of frequency bins (positive integer)
<em>eta</em> value = coupling constant between the shock system and the quantum thermal bath (positive unitless)
<em>beta</em> value = the quantum temperature is updated every beta time steps (positive integer)
<em>T_init</em> value = quantum temperature for the initial state (temperature units)
</pre>
-</li>
-</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix 1 all qbmsst z 0.122 q 25 mu 0.9 tscale 0.01 damp 200 seed 35082 f_max 0.3 N_f 100 eta 1 beta 400 T_init 110 (liquid methane modeled with the REAX force field, real units)
fix 2 all qbmsst z 72 q 40 tscale 0.05 damp 1 seed 47508 f_max 120.0 N_f 100 eta 1.0 beta 500 T_init 300 (quartz modeled with the BKS force field, metal units)
</pre>
<p>Two example input scripts are given, including shocked alpha quartz
and shocked liquid methane. The input script first equilibrate an
initial state with the quantum thermal bath at the target temperature
and then apply the qbmsst to simulate shock compression with quantum
nuclear correction. The following two figures plot related quantities
<p>The fix qbmsst command couples the shock system to a quantum thermal
bath with a rate that is proportional to the change of the total
energy of the shock system, <i>etot</i> - <i>etot</i><sub>0</sub>.
Here <i>etot</i> consists of both the system energy and a thermal
term, see <a class="reference internal" href="#qi"><span class="std std-ref">(Qi)</span></a>, and <i>etot</i><sub>0</sub> = <em>e0</em> is the
initial total energy.</p>
<p>The <em>eta</em> (<i>&eta;</i>) parameter is a unitless coupling constant
between the shock system and the quantum thermal bath. A small <em>eta</em>
value cannot adjust the quantum temperature fast enough during the
temperature ramping period of shock compression while large <em>eta</em>
leads to big temperature oscillation. A value of <em>eta</em> between 0.3 and
1 is usually appropriate for simulating most systems under shock
compression. We observe that different values of <em>eta</em> lead to almost
the same final thermodynamic state behind the shock, as expected.</p>
<p>The quantum temperature is updated every <em>beta</em> (<i>&beta;</i>) steps
with an integration time interval <em>beta</em> times longer than the
simulation time step. In that case, <i>etot</i> is taken as its
average over the past <em>beta</em> steps. The temperature of the quantum
thermal bath <i>T</i><sup>qm</sup> changes dynamically according to
the following equation where &Delta;<i>t</i> is the MD time step and
<i>&gamma;</i> is the friction constant which is equal to the inverse
<li><em>dhugoniot</em> is the departure from the Hugoniot (temperature units).</li>
<li><em>drayleigh</em> is the departure from the Rayleigh line (pressure units).</li>
<li><em>lagrangian_speed</em> is the laboratory-frame Lagrangian speed (particle velocity) of the computational cell (velocity units).</li>
<li><em>lagrangian_position</em> is the computational cell position in the reference frame moving at the shock speed. This is the distance of the computational cell behind the shock front.</li>
<li><em>quantum_temperature</em> is the temperature of the quantum thermal bath <i>T</i><sup>qm</sup>.</li>
</ol>
<p>To print these quantities to the log file with descriptive column
headers, the following LAMMPS commands are suggested. Here the
<a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> energy command is also enabled to allow
the thermo keyword <em>etotal</em> to print the quantity <i>etot</i>. See
also the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command.</p>
<pre class="literal-block">
fix fix_id all msst z
fix_modify fix_id energy yes
variable dhug equal f_fix_id[1]
variable dray equal f_fix_id[2]
variable lgr_vel equal f_fix_id[3]
variable lgr_pos equal f_fix_id[4]
variable T_qm equal f_fix_id[5]
thermo_style custom step temp ke pe lz pzz etotal v_dhug v_dray v_lgr_vel v_lgr_pos v_T_qm f_fix_id
</pre>
<p>The global scalar under the entry f_fix_id is the quantity of thermo
energy as an extra part of <i>etot</i>. This global scalar and the
vector of 5 quantities can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. It is worth noting that the
temp keyword under the <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command print
the instantaneous classical temperature <i>T</i><sup>cl</sup> as
described in the command <a class="reference internal" href="fix_qtb.html"><span class="doc">fix qtb</span></a>.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix style is part of the USER-QTB package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>All cell dimensions must be periodic. This fix can not be used with a
triclinic cell. The QBMSST fix has been tested only for the group-ID
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>.
<p>Perform charge equilibration (QeQ) in conjunction with the COMB
(Charge-Optimized Many-Body) potential as described in
<a class="reference internal" href="#comb-1"><span class="std std-ref">(COMB_1)</span></a> and <a class="reference internal" href="#comb-2"><span class="std std-ref">(COMB_2)</span></a>. It performs the charge
equilibration portion of the calculation using the so-called QEq
method, whereby the charge on each atom is adjusted to minimize the
energy of the system. This fix can only be used with the COMB
potential; see the <a class="reference internal" href="fix_qeq_reax.html"><span class="doc">fix qeq/reax</span></a> command for a QeQ
calculation that can be used with any potential.</p>
<p>Only charges on the atoms in the specified group are equilibrated.
The fix relies on the pair style (COMB in this case) to calculate the
per-atom electronegativity (effective force on the charges). An
electronegativity equalization calculation (or QEq) is performed in an
interative fashion, which in parallel requires communication at each
iteration for processors to exchange charge information about nearby
atoms with each other. See <a class="reference internal" href="#rappe-and-goddard"><span class="std std-ref">Rappe_and_Goddard</span></a> and
<a class="reference internal" href="#rick-and-stuart"><span class="std std-ref">Rick_and_Stuart</span></a> for details.</p>
<p>During a run, charge equilibration is peformed every <em>Nevery</em> time
steps. Charge equilibration is also always enforced on the first step
of each run. The <em>precision</em> argument controls the tolerance for the
difference in electronegativity for all atoms during charge
equilibration. <em>Precision</em> is a trade-off between the cost of
performing charge equilibration (more iterations) and accuracy.</p>
<p>If the <em>file</em> keyword is used, then information about each
equilibration calculation is written to the specifed file.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is performing charge equilibration. Default is
the outermost level.</p>
<p>This fix produces a per-atom vector which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The vector stores the
gradient of the charge on each atom. The per-atom values be accessed
on any timestep.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>This fix can be invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix command currently only supports <a class="reference internal" href="pair_comb.html"><span class="doc">pair style *comb*</span></a>.</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>.
<p>Perform the charge equilibration (QEq) method as described in <a class="reference internal" href="#rappe"><span class="std std-ref">(Rappe and Goddard)</span></a> and formulated in <a class="reference internal" href="neb.html#nakano"><span class="std std-ref">(Nakano)</span></a>. It is
typically used in conjunction with the ReaxFF force field model as
implemented in the <a class="reference internal" href="pair_reax_c.html"><span class="doc">pair_style reax/c</span></a> command, but
it can be used with any potential in LAMMPS, so long as it defines and
uses charges on each atom. The <a class="reference internal" href="fix_qeq_comb.html"><span class="doc">fix qeq/comb</span></a>
command should be used to perform charge equliibration with the <a class="reference internal" href="pair_comb.html"><span class="doc">COMB potential</span></a>. For more technical details about the
charge equilibration performed by fix qeq/reax, see the
<p>where <em>itype</em> is the atom type from 1 to Ntypes, <em>chi</em> denotes the
electronegativity in eV, <em>eta</em> denotes the self-Coulomb
potential in eV, and <em>gamma</em> denotes the valence orbital
exponent. Note that these 3 quantities are also in the ReaxFF
potential file, except that eta is defined here as twice the eta value
in the ReaxFF file. Note that unlike the rest of LAMMPS, the units
of this fix are hard-coded to be A, eV, and electronic charge.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. No global scalar or vector or per-atom
quantities are stored by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>This fix is invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the USER-REAXC package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix does not correctly handle interactions
involving multiple periodic images of the same atom. Hence, it should not
be used for periodic cell dimensions less than 10 angstroms.</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>.
<p>The <em>bond</em> keyword applies a bond restraint to the specified atoms
using the same functional form used by the <a class="reference internal" href="bond_harmonic.html"><span class="doc">bond_style harmonic</span></a> command. The potential associated with
<p>K and r0 are specified with the fix. Note that the usual 1/2 factor
is included in K.</p>
<hr class="docutils" />
<p>The <em>angle</em> keyword applies an angle restraint to the specified atoms
using the same functional form used by the <a class="reference internal" href="angle_harmonic.html"><span class="doc">angle_style harmonic</span></a> command. The potential associated with
<p>K and phi0 are specified with the fix. Note that the value of n is
hard-wired to 1. Also note that the energy will be a minimum when the
current dihedral angle phi is equal to phi0.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the potential energy associated with this fix to the
system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is adding its forces. Default is the outermost level.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the fictitious potential energy associated with the
added forces to be included in the total potential energy of the
system (the quantity being minimized), you MUST enable the
<a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option for this fix.</p>
</div>
<p>This fix computes a global scalar, which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is the
potential energy for all the restraints as discussed above. The scalar
value calculated by this fix is “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</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>.
<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</p>
</li>
<li><p class="first">style = <em>rigid</em> or <em>rigid/nve</em> or <em>rigid/nvt</em> or <em>rigid/npt</em> or <em>rigid/nph</em> or <em>rigid/small</em> or <em>rigid/nve/small</em> or <em>rigid/nvt/small</em> or <em>rigid/npt/small</em> or <em>rigid/nph/small</em></p>
</li>
<li><p class="first">bodystyle = <em>single</em> or <em>molecule</em> or <em>group</em></p>
<pre class="literal-block">
<em>single</em> args = none
<em>molecule</em> args = none
<em>group</em> args = N groupID1 groupID2 ...
N = # of groups
groupID1, groupID2, ... = list of N group IDs
</pre>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>langevin</em> or <em>temp</em> or <em>iso</em> or <em>aniso</em> or <em>x</em> or <em>y</em> or <em>z</em> or <em>couple</em> or <em>tparam</em> or <em>pchain</em> or <em>dilate</em> or <em>force</em> or <em>torque</em> or <em>infile</em></p>
Tstart,Tstop = desired temperature at start/stop of run (temperature units)
Tdamp = temperature damping parameter (time units)
seed = random number seed to use for white noise (positive integer)
<em>temp</em> values = Tstart Tstop Tdamp
Tstart,Tstop = desired temperature at start/stop of run (temperature units)
Tdamp = temperature damping parameter (time units)
<em>iso</em> or <em>aniso</em> values = Pstart Pstop Pdamp
Pstart,Pstop = scalar external pressure at start/end of run (pressure units)
Pdamp = pressure damping parameter (time units)
<em>x</em> or <em>y</em> or <em>z</em> values = Pstart Pstop Pdamp
Pstart,Pstop = external stress tensor component at start/end of run (pressure units)
Pdamp = stress damping parameter (time units)
<em>couple</em> = <em>none</em> or <em>xyz</em> or <em>xy</em> or <em>yz</em> or <em>xz</em>
<em>tparam</em> values = Tchain Titer Torder
Tchain = length of Nose/Hoover thermostat chain
Titer = number of thermostat iterations performed
Torder = 3 or 5 = Yoshida-Suzuki integration parameters
<em>pchain</em> values = Pchain
Pchain = length of the Nose/Hoover thermostat chain coupled with the barostat
<em>dilate</em> value = dilate-group-ID
dilate-group-ID = only dilate atoms in this group due to barostat volume changes
<em>force</em> values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass force is active
<em>torque</em> values = M xflag yflag zflag
M = which rigid body from 1-Nbody (see asterisk form below)
xflag,yflag,zflag = off/on if component of center-of-mass torque is active
<em>infile</em> filename
filename = file with per-body values of mass, center-of-mass, moments of inertia
<em>mol</em> value = template-ID
template-ID = ID of molecule template specified in a separate <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix 1 clump rigid single
fix 1 clump rigid/small molecule
fix 1 clump rigid single force 1 off off on langevin 1.0 1.0 1.0 428984
<p>Treat one or more sets of atoms as independent rigid bodies. This
means that each timestep the total force and torque on each rigid body
is computed as the sum of the forces and torques on its constituent
particles. The coordinates, velocities, and orientations of the atoms
in each body are then updated so that the body moves and rotates as a
single entity.</p>
<p>Examples of large rigid bodies are a colloidal particle, or portions
of a biomolecule such as a protein.</p>
<p>Example of small rigid bodies are patchy nanoparticles, such as those
modeled in <a class="reference internal" href="pair_gran.html#zhang"><span class="std std-ref">this paper</span></a> by Sharon Glotzer’s group, clumps of
granular particles, lipid molecules consiting of one or more point
dipoles connected to other spheroids or ellipsoids, irregular
particles built from line segments (2d) or triangles (3d), and
coarse-grain models of nano or colloidal particles consisting of a
small number of constituent particles. Note that the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> command can also be used to rigidify small
molecules of 2, 3, or 4 atoms, e.g. water molecules. That fix treats
the constituent atoms as point masses.</p>
<p>These fixes also update the positions and velocities of the atoms in
each rigid body via time integration, in the NVE, NVT, NPT, or NPH
ensemble, as described below.</p>
<p>There are two main variants of this fix, fix rigid and fix
rigid/small. The NVE/NVT/NPT/NHT versions belong to one of the two
variants, as their style names indicate.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Not all of the <em>bodystyle</em> options and keyword/value options are
available for both the <em>rigid</em> and <em>rigid/small</em> variants. See
details below.</p>
</div>
<p>The <em>rigid</em> styles are typically the best choice for a system with a
small number of large rigid bodies, each of which can extend across
the domain of many processors. It operates by creating a single
global list of rigid bodies, which all processors contribute to.
MPI_Allreduce operations are performed each timestep to sum the
contributions from each processor to the force and torque on all the
bodies. This operation will not scale well in parallel if large
numbers of rigid bodies are simulated.</p>
<p>The <em>rigid/small</em> styles are typically best for a system with a large
number of small rigid bodies. Each body is assigned to the atom
closest to the geometrical center of the body. The fix operates using
local lists of rigid bodies owned by each processor and information is
exchanged and summed via local communication between neighboring
processors when ghost atom info is accumlated.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To use the <em>rigid/small</em> styles the ghost atom cutoff must be
large enough to span the distance between the atom that owns the body
and every other atom in the body. This distance value is printed out
when the rigid bodies are defined. If the
<a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> cutoff plus neighbor skin does not span
this distance, then you should use the <a class="reference internal" href="comm_modify.html"><span class="doc">comm_modify cutoff</span></a> command with a setting epsilon larger than
the distance.</p>
</div>
<p>Which of the two variants is faster for a particular problem is hard
to predict. The best way to decide is to perform a short test run.
Both variants should give identical numerical answers for short runs.
Long runs should give statistically similar results, but round-off
differences may accumulate to produce divergent trajectories.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You should not update the atoms in rigid bodies via other
time-integration fixes (e.g. <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>, <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>, <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a>), or you will be integrating
their motion more than once each timestep. When performing a hybrid
simulation with some atoms in rigid bodies, and some not, a separate
time integration fix like <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> or <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> should be used for the non-rigid particles.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">These fixes are overkill if you simply want to hold a collection
of atoms stationary or have them move with a constant velocity. A
simpler way to hold atoms stationary is to not include those atoms in
your time integration fix. E.g. use “fix 1 mobile nve” instead of
“fix 1 all nve”, where “mobile” is the group of atoms that you want to
move. You can move atoms with a constant velocity by assigning them
an initial velocity (via the <a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> command),
setting the force on them to 0.0 (via the <a class="reference internal" href="fix_setforce.html"><span class="doc">fix setforce</span></a> command), and integrating them as usual
(e.g. via the <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> command).</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The aggregate properties of each rigid body are calculated one
time at the start of the first simulation run after these fixes are
specified. The properties include the position and velocity of the
center-of-mass of the body, its moments of inertia, and its angular
momentum. This is done using the properties of the constituent atoms
of the body at that point in time (or see the <em>infile</em> keyword
option). Thereafter, changing properties of individual atoms in the
body will have no effect on a rigid body’s dynamics, unless they
affect the <a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> interactions that individual
particles are part of. For example, you might think you could
displace the atoms in a body or add a large velocity to each atom in a
body to make it move in a desired direction before a 2nd run is
performed, using the <a class="reference internal" href="set.html"><span class="doc">set</span></a> or
command. But these commands will not affect the internal attributes
of the body, and the position and velocity of individual atoms in the
body will be reset when time integration starts.</p>
</div>
<hr class="docutils" />
<p>Each rigid body must have two or more atoms. An atom can belong to at
most one rigid body. Which atoms are in which bodies can be defined
via several options.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">With the <em>rigid/small</em> styles, which require that <em>bodystyle</em> be
specified as <em>molecule</em>, you can define a system that has no rigid
bodies initially. This is useful when you are using the <em>mol</em> keyword
in conjunction with another fix that is adding rigid bodies on-the-fly
as molecules, such as <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a> or <a class="reference internal" href="fix_pour.html"><span class="doc">fix pour</span></a>.</p>
</div>
<p>For bodystyle <em>single</em> the entire fix group of atoms is treated as one
rigid body. This option is only allowed for the <em>rigid</em> styles.</p>
<p>For bodystyle <em>molecule</em>, each set of atoms in the fix group with a
different molecule ID is treated as a rigid body. This option is
allowed for both the <em>rigid</em> and <em>rigid/small</em> styles. Note that
atoms with a molecule ID = 0 will be treated as a single rigid body.
For a system with atomic solvent (typically this is atoms with
molecule ID = 0) surrounding rigid bodies, this may not be what you
want. Thus you should be careful to use a fix group that only
includes atoms you want to be part of rigid bodies.</p>
<p>For bodystyle <em>group</em>, each of the listed groups is treated as a
separate rigid body. Only atoms that are also in the fix group are
included in each rigid body. This option is only allowed for the
<em>rigid</em> styles.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To compute the initial center-of-mass position and other
properties of each rigid body, the image flags for each atom in the
body are used to “unwrap” the atom coordinates. Thus you must insure
that these image flags are consistent so that the unwrapping creates a
valid rigid body (one where the atoms are close together),
particularly if the atoms in a single rigid body straddle a periodic
boundary. This means the input data file or restart file must define
the image flags for each atom consistently or that you have used the
<a class="reference internal" href="set.html"><span class="doc">set</span></a> command to specify them correctly. If a dimension is
non-periodic then the image flag of each atom must be 0 in that
dimension, else an error is generated.</p>
</div>
<p>The <em>force</em> and <em>torque</em> keywords discussed next are only allowed for
the <em>rigid</em> styles.</p>
<p>By default, each rigid body is acted on by other atoms which induce an
external force and torque on its center of mass, causing it to
translate and rotate. Components of the external center-of-mass force
and torque can be turned off by the <em>force</em> and <em>torque</em> keywords.
This may be useful if you wish a body to rotate but not translate, or
vice versa, or if you wish it to rotate or translate continuously
unaffected by interactions with other particles. Note that if you
expect a rigid body not to move or rotate by using these keywords, you
must insure its initial center-of-mass translational or angular
velocity is 0.0. Otherwise the initial translational or angular
momentum the body has will persist.</p>
<p>An xflag, yflag, or zflag set to <em>off</em> means turn off the component of
force of torque in that dimension. A setting of <em>on</em> means turn on
the component, which is the default. Which rigid body(s) the settings
apply to is determined by the first argument of the <em>force</em> and
<em>torque</em> keywords. It can be an integer M from 1 to Nbody, where
Nbody is the number of rigid bodies defined. A wild-card asterisk can
be used in place of, or in conjunction with, the M argument to set the
flags for multiple rigid bodies. This takes the form “*” or “*n” or
“n*” or “m*n”. If N = the number of rigid bodies, then an asterisk
with no numeric values means all bodies from 1 to N. A leading
asterisk means all bodies from 1 to n (inclusive). A trailing
asterisk means all bodies from n to N (inclusive). A middle asterisk
means all types from m to n (inclusive). Note that you can use the
<em>force</em> or <em>torque</em> keywords as many times as you like. If a
particular rigid body has its component flags set multiple times, the
settings from the final keyword are used.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For computational efficiency, you may wish to turn off pairwise
and bond interactions within each rigid body, as they no longer
contribute to the motion. The <a class="reference internal" href="neigh_modify.html"><span class="doc">neigh_modify exclude</span></a> and <a class="reference internal" href="delete_bonds.html"><span class="doc">delete_bonds</span></a>
commands are used to do this. If the rigid bodies have strongly
overalapping atoms, you may need to turn off these interactions to
avoid numerical problems due to large equal/opposite intra-body forces
swamping the contribution of small inter-body forces.</p>
</div>
<p>For computational efficiency, you should typically define one fix
rigid or fix rigid/small command which includes all the desired rigid
bodies. LAMMPS will allow multiple rigid fixes to be defined, but it
is more expensive.</p>
<hr class="docutils" />
<p>The constituent particles within a rigid body can be point particles
(the default in LAMMPS) or finite-size particles, such as spheres or
ellipsoids or line segments or triangles. See the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style sphere and ellipsoid and line and tri</span></a> commands for more
details on these kinds of particles. Finite-size particles contribute
differently to the moment of inertia of a rigid body than do point
particles. Finite-size particles can also experience torque (e.g. due
to <a class="reference internal" href="pair_gran.html"><span class="doc">frictional granular interactions</span></a>) and have an
orientation. These contributions are accounted for by these fixes.</p>
<p>Forces between particles within a body do not contribute to the
external force or torque on the body. Thus for computational
efficiency, you may wish to turn off pairwise and bond interactions
between particles within each rigid body. The <a class="reference internal" href="neigh_modify.html"><span class="doc">neigh_modify exclude</span></a> and <a class="reference internal" href="delete_bonds.html"><span class="doc">delete_bonds</span></a>
commands are used to do this. For finite-size particles this also
means the particles can be highly overlapped when creating the rigid
body.</p>
<hr class="docutils" />
<p>The <em>rigid</em>, <em>rigid/nve</em>, <em>rigid/small</em>, and <em>rigid/small/nve</em> styles
perform constant NVE time integration. They are referred to below as
the 4 NVE rigid styles. The only difference is that the <em>rigid</em> and
<em>rigid/small</em> styles use an integration technique based on Richardson
iterations. The <em>rigid/nve</em> and <em>rigid/small/nve</em> styles uses the
methods described in the paper by <a class="reference internal" href="#miller"><span class="std std-ref">Miller</span></a>, which are thought
to provide better energy conservation than an iterative approach.</p>
<p>The <em>rigid/nvt</em> and <em>rigid/nvt/small</em> styles performs constant NVT
integration using a Nose/Hoover thermostat with chains as described
originally in <a class="reference internal" href="#hoover"><span class="std std-ref">(Hoover)</span></a> and <a class="reference internal" href="#martyna"><span class="std std-ref">(Martyna)</span></a>, which
thermostats both the translational and rotational degrees of freedom
of the rigid bodies. They are referred to below as the 2 NVT rigid
styles. The rigid-body algorithm used by <em>rigid/nvt</em> is described in
the paper by <a class="reference internal" href="#kamberaj"><span class="std std-ref">Kamberaj</span></a>.</p>
<p>The <em>rigid/npt</em>, <em>rigid/nph</em>, <em>rigid/npt/small</em>, and <em>rigid/nph/small</em>
styles perform constant NPT or NPH integration using a Nose/Hoover
barostat with chains. They are referred to below as the 4 NPT and NPH
rigid styles. For the NPT case, the same Nose/Hoover thermostat is
also used as with <em>rigid/nvt</em> and <em>rigid/nvt/small</em>.</p>
<p>The barostat parameters are specified using one or more of the <em>iso</em>,
<em>aniso</em>, <em>x</em>, <em>y</em>, <em>z</em> and <em>couple</em> keywords. These keywords give you
the ability to specify 3 diagonal components of the external stress
tensor, and to couple these components together so that the dimensions
they represent are varied together during a constant-pressure
simulation. The effects of these keywords are similar to those
defined in <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt/nph</span></a></p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Currently the <em>rigid/npt</em>, <em>rigid/nph</em>, <em>rigid/npt/small</em>, and
<em>rigid/nph/small</em> styles do not support triclinic (non-orthongonal)
boxes.</p>
</div>
<p>The target pressures for each of the 6 components of the stress tensor
can be specified independently via the <em>x</em>, <em>y</em>, <em>z</em> keywords, which
correspond to the 3 simulation box dimensions. For each component,
the external pressure or tensor component at each timestep is a ramped
value during the run from <em>Pstart</em> to <em>Pstop</em>. If a target pressure is
specified for a component, then the corresponding box dimension will
change during a simulation. For example, if the <em>y</em> keyword is used,
the y-box length will change. A box dimension will not change if that
component is not specified, although you have the option to change
that dimension via the <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> command.</p>
<p>For all barostat keywords, the <em>Pdamp</em> parameter operates like the
<em>Tdamp</em> parameter, determining the time scale on which pressure is
relaxed. For example, a value of 10.0 means to relax the pressure in
a timespan of (roughly) 10 time units (e.g. tau or fmsec or psec - see
the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command).</p>
<p>Regardless of what atoms are in the fix group (the only atoms which
are time integrated), a global pressure or stress tensor is computed
for all atoms. Similarly, when the size of the simulation box is
changed, all atoms are re-scaled to new positions, unless the keyword
<em>dilate</em> is specified with a <em>dilate-group-ID</em> for a group that
represents a subset of the atoms. This can be useful, for example, to
leave the coordinates of atoms in a solid substrate unchanged and
controlling the pressure of a surrounding fluid. Another example is a
system consisting of rigid bodies and point particles where the
barostat is only coupled with the rigid bodies. This option should be
used with care, since it can be unphysical to dilate some atoms and
not others, because it can introduce large, instantaneous
displacements between a pair of atoms (one dilated, one not) that are
far from the dilation origin.</p>
<p>The <em>couple</em> keyword allows two or three of the diagonal components of
the pressure tensor to be “coupled” together. The value specified
with the keyword determines which are coupled. For example, <em>xz</em>
means the <em>Pxx</em> and <em>Pzz</em> components of the stress tensor are coupled.
<em>Xyz</em> means all 3 diagonal components are coupled. Coupling means two
things: the instantaneous stress will be computed as an average of the
corresponding diagonal components, and the coupled box dimensions will
be changed together in lockstep, meaning coupled dimensions will be
dilated or contracted by the same percentage every timestep. The
<em>Pstart</em>, <em>Pstop</em>, <em>Pdamp</em> parameters for any coupled dimensions must
be identical. <em>Couple xyz</em> can be used for a 2d simulation; the <em>z</em>
dimension is simply ignored.</p>
<p>The <em>iso</em> and <em>aniso</em> keywords are simply shortcuts that are
equivalent to specifying several other keywords together.</p>
<p>The keyword <em>iso</em> means couple all 3 diagonal components together when
pressure is computed (hydrostatic pressure), and dilate/contract the
dimensions together. Using “iso Pstart Pstop Pdamp” is the same as
<p>The keyword/value option pairs are used in the following ways.</p>
<p>The <em>langevin</em> and <em>temp</em> and <em>tparam</em> keywords perform thermostatting
of the rigid bodies, altering both their translational and rotational
degrees of freedom. What is meant by “temperature” of a collection of
rigid bodies and how it can be monitored via the fix output is
discussed below.</p>
<p>The <em>langevin</em> keyword applies a Langevin thermostat to the constant
NVE time integration performed by any of the 4 NVE rigid styles:
<em>rigid</em>, <em>rigid/nve</em>, <em>rigid/small</em>, <em>rigid/small/nve</em>. It cannot be
used with the 2 NVT rigid styles: <em>rigid/nvt</em>, <em>rigid/small/nvt</em>. The
desired temperature at each timestep is a ramped value during the run
from <em>Tstart</em> to <em>Tstop</em>. The <em>Tdamp</em> parameter is specified in time
units and determines how rapidly the temperature is relaxed. For
example, a value of 100.0 means to relax the temperature in a timespan
of (roughly) 100 time units (tau or fmsec or psec - see the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command). The random # <em>seed</em> must be a positive
integer.</p>
<p>The way that Langevin thermostatting operates is explained on the <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> doc page. If you wish to simply viscously
damp the rotational motion without thermostatting, you can set
<em>Tstart</em> and <em>Tstop</em> to 0.0, which means only the viscous drag term in
the Langevin thermostat will be applied. See the discussion on the
<a class="reference internal" href="fix_viscous.html"><span class="doc">fix viscous</span></a> doc page for details.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When the <em>langevin</em> keyword is used with fix rigid versus fix
rigid/small, different dynamics will result for parallel runs. This
is because of the way random numbers are used in the two cases. The
dynamics for the two cases should be statistically similar, but will
not be identical, even for a single timestep.</p>
</div>
<p>The <em>temp</em> and <em>tparam</em> keywords apply a Nose/Hoover thermostat to the
NVT time integration performed by the 2 NVT rigid styles. They cannot
be used with the 4 NVE rigid styles. The desired temperature at each
timestep is a ramped value during the run from <em>Tstart</em> to <em>Tstop</em>.
The <em>Tdamp</em> parameter is specified in time units and determines how
rapidly the temperature is relaxed. For example, a value of 100.0
means to relax the temperature in a timespan of (roughly) 100 time
units (tau or fmsec or psec - see the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command).</p>
<p>Nose/Hoover chains are used in conjunction with this thermostat. The
<em>tparam</em> keyword can optionally be used to change the chain settings
used. <em>Tchain</em> is the number of thermostats in the Nose Hoover chain.
This value, along with <em>Tdamp</em> can be varied to dampen undesirable
oscillations in temperature that can occur in a simulation. As a rule
of thumb, increasing the chain length should lead to smaller
oscillations. The keyword <em>pchain</em> specifies the number of
thermostats in the chain thermostatting the barostat degrees of
freedom.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">There are alternate ways to thermostat a system of rigid bodies.
You can use <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> to treat the individual
particles in the rigid bodies as effectively immersed in an implicit
solvent, e.g. a Brownian dynamics model. For hybrid systems with both
rigid bodies and solvent particles, you can thermostat only the
solvent particles that surround one or more rigid bodies by
appropriate choice of groups in the compute and fix commands for
temperature and thermostatting. The solvent interactions with the
rigid bodies should then effectively thermostat the rigid body
temperature as well without use of the Langevin or Nose/Hoover options
associated with the fix rigid commands.</p>
</div>
<hr class="docutils" />
<p>The <em>mol</em> keyword can only be used with the <em>rigid/small</em> styles. It
must be used when other commands, such as <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a> or <a class="reference internal" href="fix_pour.html"><span class="doc">fix pour</span></a>, add rigid
bodies on-the-fly during a simulation. You specify a <em>template-ID</em>
previously defined using the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command, which
reads a file that defines the molecule. You must use the same
<em>template-ID</em> that the other fix which is adding rigid bodies uses.
The coordinates, atom types, atom diameters, center-of-mass, and
moments of inertia can be specified in the molecule file. See the
<a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command for details. The only settings
required to be in this file are the coordinates and types of atoms in
the molecule, in which case the molecule command calculates the other
quantities itself.</p>
<p>Note that these other fixes create new rigid bodies, in addition to
those defined initially by this fix via the <em>bodystyle</em> setting.</p>
<p>Also note that when using the <em>mol</em> keyword, extra restart information
about all rigid bodies is written out whenever a restart file is
written out. See the NOTE in the next section for details.</p>
<hr class="docutils" />
<p>The <em>infile</em> keyword allows a file of rigid body attributes to be read
in from a file, rather then having LAMMPS compute them. There are 5
such attributes: the total mass of the rigid body, its center-of-mass
position, its 6 moments of inertia, its center-of-mass velocity, and
the 3 image flags of the center-of-mass position. For rigid bodies
consisting of point particles or non-overlapping finite-size
particles, LAMMPS can compute these values accurately. However, for
rigid bodies consisting of finite-size particles which overlap each
other, LAMMPS will ignore the overlaps when computing these 4
attributes. The amount of error this induces depends on the amount of
overlap. To avoid this issue, the values can be pre-computed
(e.g. using Monte Carlo integration).</p>
<p>The format of the file is as follows. Note that the file does not
have to list attributes for every rigid body integrated by fix rigid.
Only bodies which the file specifies will have their computed
attributes overridden. The file can contain initial blank lines or
comment lines starting with “#” which are ignored. The first
non-blank, non-comment line should list N = the number of lines to
follow. The N successive lines contain the following information:</p>
<p>The rigid body IDs are all positive integers. For the <em>single</em>
bodystyle, only an ID of 1 can be used. For the <em>group</em> bodystyle,
IDs from 1 to Ng can be used where Ng is the number of specified
groups. For the <em>molecule</em> bodystyle, use the molecule ID for the
atoms in a specific rigid body as the rigid body ID.</p>
<p>The masstotal and center-of-mass coordinates (xcm,ycm,zcm) are
self-explanatory. The center-of-mass should be consistent with what
is calculated for the position of the rigid body with all its atoms
unwrapped by their respective image flags. If this produces a
center-of-mass that is outside the simulation box, LAMMPS wraps it
back into the box.</p>
<p>The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
values consistent with the current orientation of the rigid body
around its center of mass. The values are with respect to the
simulation box XYZ axes, not with respect to the prinicpal axes of the
rigid body itself. LAMMPS performs the latter calculation internally.</p>
<p>The (vxcm,vycm,vzcm) values are the velocity of the center of mass.
The (lx,ly,lz) values are the angular momentum of the body. The
(vxcm,vycm,vzcm) and (lx,ly,lz) values can simply be set to 0 if you
wish the body to have no initial motion.</p>
<p>The (ixcm,iycm,izcm) values are the image flags of the center of mass
of the body. For periodic dimensions, they specify which image of the
simulation box the body is considered to be in. An image of 0 means
it is inside the box as defined. A value of 2 means add 2 box lengths
to get the true value. A value of -1 means subtract 1 box length to
get the true value. LAMMPS updates these flags as the rigid bodies
cross periodic boundaries during the simulation.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you use the <em>infile</em> or <em>mol</em> keywords and write restart
files during a simulation, then each time a restart file is written,
the fix also write an auxiliary restart file with the name
rfile.rigid, where “rfile” is the name of the restart file,
e.g. tmp.restart.10000 and tmp.restart.10000.rigid. This auxiliary
file is in the same format described above. Thus it can be used in a
new input script that restarts the run and re-specifies a rigid fix
using an <em>infile</em> keyword and the appropriate filename. Note that the
auxiliary file will contain one line for every rigid body, even if the
original file only listed a subset of the rigid bodies.</p>
</div>
<hr class="docutils" />
<p>If you use a <a class="reference internal" href="compute.html"><span class="doc">temperature compute</span></a> with a group that
includes particles in rigid bodies, the degrees-of-freedom removed by
each rigid body are accounted for in the temperature (and pressure)
computation, but only if the temperature group includes all the
particles in a particular rigid body.</p>
<p>A 3d rigid body has 6 degrees of freedom (3 translational, 3
rotational), except for a collection of point particles lying on a
straight line, which has only 5, e.g a dimer. A 2d rigid body has 3
degrees of freedom (2 translational, 1 rotational).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You may wish to explicitly subtract additional
degrees-of-freedom if you use the <em>force</em> and <em>torque</em> keywords to
eliminate certain motions of one or more rigid bodies. LAMMPS does
not do this automatically.</p>
</div>
<p>The rigid body contribution to the pressure of the system (virial) is
also accounted for by this fix.</p>
<hr class="docutils" />
<p>If your simlulation is a hybrid model with a mixture of rigid bodies
and non-rigid particles (e.g. solvent) there are several ways these
rigid fixes can be used in tandem with <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>, <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>, <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a>, and <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a>.</p>
<p>If you wish to perform NVE dynamics (no thermostatting or
barostatting), use one of 4 NVE rigid styles to integrate the rigid
bodies, and <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> to integrate the non-rigid
particles.</p>
<p>If you wish to perform NVT dynamics (thermostatting, but no
barostatting), you can use one of the 2 NVT rigid styles for the rigid
bodies, and any thermostatting fix for the non-rigid particles (<a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a>, <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>, <a class="reference internal" href="fix_temp_berendsen.html"><span class="doc">fix temp/berendsen</span></a>). You can also use one of the
4 NVE rigid styles for the rigid bodies and thermostat them using <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> on the group that contains all the
particles in the rigid bodies. The net force added by <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> to each rigid body effectively thermostats
its translational center-of-mass motion. Not sure how well it does at
thermostatting its rotational motion.</p>
<p>If you with to perform NPT or NPH dynamics (barostatting), you cannot
use both <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> and the NPT or NPH rigid styles. This
is because there can only be one fix which monitors the global
pressure and changes the simulation box dimensions. So you have 3
choices:</p>
<ul class="simple">
<li>Use one of the 4 NPT or NPH styles for the rigid bodies. Use the
<em>dilate</em> all option so that it will dilate the positions of the
non-rigid particles as well. Use <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> (or any other
thermostat) for the non-rigid particles.</li>
<li>Use <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> for the group of non-rigid particles. Use
the <em>dilate</em> all option so that it will dilate the center-of-mass
positions of the rigid bodies as well. Use one of the 4 NVE or 2 NVT
rigid styles for the rigid bodies.</li>
<li>Use <a class="reference internal" href="fix_press_berendsen.html"><span class="doc">fix press/berendsen</span></a> to compute the
pressure and change the box dimensions. Use one of the 4 NVE or 2 NVT
rigid styles for the rigid bodies. Use <a class="reference external" href="fix_nh.thml">fix nvt</a> (or any
other thermostat) for the non-rigid particles.</li>
</ul>
<p>In all case, the rigid bodies and non-rigid particles both contribute
to the global pressure and the box is scaled the same by any of the
barostatting fixes.</p>
<p>You could even use the 2nd and 3rd options for a non-hybrid simulation
consisting of only rigid bodies, assuming you give <a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> an empty group, though it’s an odd thing to do. The
barostatting fixes (<a class="reference internal" href="fix_nh.html"><span class="doc">fix npt</span></a> and <a class="reference internal" href="fix_press_berendsen.html"><span class="doc">fix press/berensen</span></a>) will monitor the pressure
and change the box dimensions, but not time integrate any particles.
The integration of the rigid bodies will be performed by fix
rigid/nvt.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about the 4 NVE rigid styles is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. The exception is if the <em>infile</em> or
<em>mol</em> keyword is used, in which case an auxiliary file is written out
with rigid body information each time a restart file is written, as
explained above for the <em>infile</em> keyword. For the 2 NVT rigid styles,
the state of the Nose/Hoover thermostat is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. Ditto for the 4 NPT and NPH rigid styles, and
the state of the Nose/Hoover barostat. See the
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by the 6
NVT, NPT, NPH rigid styles to add the energy change induced by the
thermostatting to the system’s potential energy as part of
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>temp</em> and <em>press</em> options are
supported by the 4 NPT and NPH rigid styles to change the computes
used to calculate the instantaneous pressure tensor. Note that the 2
NVT rigid fixes do not use any external compute to compute
instantaneous temperature.</p>
<p>The 2 NVE rigid fixes compute a global scalar which can be accessed by
various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar
value calculated by these fixes is “intensive”. The scalar is the
current temperature of the collection of rigid bodies. This is
averaged over all rigid bodies and their translational and rotational
degrees of freedom. The translational energy of a rigid body is 1/2 m
v^2, where m = total mass of the body and v = the velocity of its
center of mass. The rotational energy of a rigid body is 1/2 I w^2,
where I = the moment of inertia tensor of the body and w = its angular
velocity. Degrees of freedom constrained by the <em>force</em> and <em>torque</em>
keywords are removed from this calculation, but only for the <em>rigid</em>
and <em>rigid/nve</em> fixes.</p>
<p>The 6 NVT, NPT, NPH rigid fixes compute a global scalar which can be
accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>.
The scalar value calculated by these fixes is “extensive”. The scalar
is the cumulative energy change due to the thermostatting and
barostatting the fix performs.</p>
<p>All of the <em>rigid</em> styles (not the <em>rigid/small</em> styles) compute a
global array of values which can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. Similar information about the
bodies defined by the <em>rigid/small</em> styles can be accessed via the
<p>These fixes are all part of the RIGID package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>Assigning a temperature via the <a class="reference internal" href="velocity.html"><span class="doc">velocity create</span></a>
command to a system with <a class="reference internal" href="#"><span class="doc">rigid bodies</span></a> may not have
the desired outcome for two reasons. First, the velocity command can
be invoked before the rigid-body fix is invoked or initialized and the
number of adjusted degrees of freedom (DOFs) is known. Thus it is not
possible to compute the target temperature correctly. Second, the
assigned velocities may be partially canceled when constraints are
first enforced, leading to a different temperature than desired. A
workaround for this is to perform a <a class="reference internal" href="run.html"><span class="doc">run 0</span></a> command, which
insures all DOFs are accounted for properly, and then rescale the
temperature to the desired value before performing a simulation. For
<span class="n">run</span> <span class="mi">0</span> <span class="c1"># temperature may not be 300K</span>
<span class="n">velocity</span> <span class="nb">all</span> <span class="n">scale</span> <span class="mf">300.0</span> <span class="c1"># now it should be</span>
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>.
region-ID = ID of region atoms must be in to have added force
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix freeze indenter setforce 0.0 0.0 0.0
fix 2 edge setforce NULL 0.0 0.0
fix 2 edge setforce NULL 0.0 v_oscillate
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Set each component of force on each atom in the group to the specified
values fx,fy,fz. This erases all previously computed forces on the
atom, though additional fixes could add new forces. This command can
be used to freeze certain atoms in the simulation by zeroing their
force, either for running dynamics or performing an energy
minimization. For dynamics, this assumes their initial velocity is
also zero.</p>
<p>Any of the fx,fy,fz values can be specified as NULL which means do not
alter the force component in that dimension.</p>
<p>Any of the 3 quantities defining the force components can be specified
as an equal-style or atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, namely <em>fx</em>,
<em>fy</em>, <em>fz</em>. If the value is a variable, it should be specified as
v_name, where name is the variable name. In this case, the variable
will be evaluated each timestep, and its value used to determine the
force component.</p>
<p>Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent force field.</p>
<p>Atom-style variables can specify the same formulas as equal-style
variables but can also include per-atom values, such as atom
coordinates. Thus it is easy to specify a spatially-dependent force
field with optional time-dependence as well.</p>
<p>If the <em>region</em> keyword is used, the atom must also be in the
specified geometric <a class="reference internal" href="region.html"><span class="doc">region</span></a> in order to have force added
to it.</p>
<hr class="docutils" />
<p>Styles with a r <em>kk</em> suffix are functionally the same as the
corresponding style without the suffix. They have been optimized to
run faster, depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>The region keyword is also supported by Kokkos, but a Kokkos-enabled
region must be used. See the region <a class="reference internal" href="region.html"><span class="doc">region</span></a> command for
more information.</p>
<p>These accelerated styles are part of the r Kokkos package. They are
only enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by
this fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is setting the forces to the desired values; on all
other levels, the force is set to 0.0 for the atoms in the fix group,
so that setforce values are not counted multiple times. Default is to
to override forces at the outermost level.</p>
<p>This fix computes a global 3-vector of forces, which can be accessed
by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. This is the
total force on the group of atoms before the forces on individual
atoms are changed by the fix. The vector values calculated by this
fix are “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command, but you cannot set
forces to any value besides zero when performing a minimization. Use
the <a class="reference internal" href="fix_addforce.html"><span class="doc">fix addforce</span></a> command if you want to apply a
non-zero force to atoms during a minimization.</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>.
<p>Specifies that the Shardlow splitting algorithm (SSA) is to be used to
integrate the DPD equations of motion. The SSA splits the integration
into a stochastic and deterministic integration step. The fix
<em>shardlow</em> performs the stochastic integration step and must be used
in conjunction with a deterministic integrator (e.g. <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> or <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a>). The stochastic
integration of the dissipative and random forces is performed prior to
the deterministic integration of the conservative force. Further
details regarding the method are provided in <a class="reference internal" href="pair_dpd_fdt.html#lisal"><span class="std std-ref">(Lisal)</span></a> and
<p>The fix <em>shardlow</em> must be used with the <a class="reference internal" href="pair_style.html"><span class="doc">pair_style dpd/fdt</span></a> or <a class="reference internal" href="pair_style.html"><span class="doc">pair_style dpd/fdt/energy</span></a> command to properly initialize the
fluctuation-dissipation theorem parameter(s) sigma (and kappa, if
necessary).</p>
<p>Note that numerous variants of DPD can be specified by choosing an
appropriate combination of the integrator and <a class="reference internal" href="pair_style.html"><span class="doc">pair_style dpd/fdt</span></a> command. DPD under isothermal conditions can
be specified by using fix <em>shardlow</em>, fix <em>nve</em> and pair_style
<em>dpd/fdt</em>. DPD under isoenergetic conditions can be specified by
using fix <em>shardlow</em>, fix <em>nve</em> and pair_style <em>dpd/fdt/energy</em>. DPD
under isobaric conditions can be specified by using fix shardlow, fix
<em>nph</em> and pair_style <em>dpd/fdt</em>. DPD under isoenthalpic conditions can
be specified by using fix shardlow, fix <em>nph</em> and pair_style
<em>dpd/fdt/energy</em>. Examples of each DPD variant are provided in the
examples/USER/dpd directory.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command is part of the USER-DPD package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This fix is currently limited to orthogonal simulation cell
geometries.</p>
<p>This fix must be used with an additional fix that specifies time
integration, e.g. <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> or <a class="reference internal" href="fix_nh.html"><span class="doc">fix nph</span></a>.</p>
<p>The Shardlow splitting algorithm requires the sizes of the sub-domain
lengths to be larger than twice the cutoff+skin. Generally, the
domain decomposition is dependent on the number of processors
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>.
<p>This switching function has the characteristic that the temperature
scaling is faster at temperatures closer to the initial temperature of
the procedure.</p>
<p>An example script using this command is provided in the
examples/USER/misc/ti directory.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>This fix computes a global vector quantitie which can be accessed by
various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The vector has
2 positions, the first one is the coupling parameter lambda and the
second one is the time derivative of lambda. The scalar and vector
values calculated by this fix are “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command.</p>
<p>This command is part of the USER-MISC package. It is only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
</div>
<div class="section" id="default">
<h2>Default</h2>
<p>The keyword default is function = 1.</p>
<hr class="docutils" />
<p id="dekoning99"><strong>(de Koning 99)</strong> M. de Koning, A. Antonelli and S. Yip, Phys Rev Lett, 83, 3973 (1999).</p>
<p id="watanabe"><strong>(Watanabe)</strong> M. Watanabe and W. P. Reinhardt, Phys Rev Lett, 65, 3301 (1990).</p>
<p id="dekoning96"><strong>(de Koning 96)</strong> M. de Koning and A. Antonelli, Phys Rev E, 53, 465 (1996).</p>
<p id="dekoning00a"><strong>(de Koning 00a)</strong> M. de Koning, A. Antonelli and S. Yip, J Chem Phys, 115, 11025 (2000).</p>
<p id="dekoning00b"><strong>(de Koning 00b)</strong> M. de Koning et al., Computing in Science & Engineering, 2, 88 (2000).</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>.
<p>Use a two-temperature model (TTM) to represent heat transfer through
and between electronic and atomic subsystems. LAMMPS models the
atomic subsystem as usual with a molecular dynamics model and the
classical force field specified by the user, but the electronic
subsystem is modeled as a continuum, or a background “gas”, on a
regular grid. Energy can be transferred spatially within the grid
representing the electrons. Energy can also be transferred between
the electronic and the atomic subsystems. The algorithm underlying
this fix was derived by D. M. Duffy and A. M. Rutherford and is
discussed in two J Physics: Condensed Matter papers: <a class="reference internal" href="#duffy"><span class="std std-ref">(Duffy)</span></a>
and <a class="reference internal" href="#rutherford"><span class="std std-ref">(Rutherford)</span></a>. They used this algorithm in cascade
simulations where a primary knock-on atom (PKA) was initialized with a
high velocity to simulate a radiation event.</p>
<p>The description in this sub-section applies to both fix ttm and fix
ttm/mod. Fix ttm/mod adds options to account for external heat
sources (e.g. at a surface) and for specifying parameters that allow
the electronic heat capacity to depend strongly on electronic
temperature. It is more expensive computationally than fix ttm
because it treats the thermal diffusion equation as non-linear. More
details on fix ttm/mod are given below.</p>
<p>Heat transfer between the electronic and atomic subsystems is carried
out via an inhomogeneous Langevin thermostat. This thermostat differs
from the regular Langevin thermostat (<a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>) in three important ways. First, the
Langevin thermostat is applied uniformly to all atoms in the
user-specified group for a single target temperature, whereas the TTM
fix applies Langevin thermostatting locally to atoms within the
volumes represented by the user-specified grid points with a target
temperature specific to that grid point. Second, the Langevin
thermostat couples the temperature of the atoms to an infinite heat
reservoir, whereas the heat reservoir for fix TTM is finite and
represents the local electrons. Third, the TTM fix allows users to
specify not just one friction coefficient, but rather two independent
friction coefficients: one for the electron-ion interactions
(<em>gamma_p</em>), and one for electron stopping (<em>gamma_s</em>).</p>
<p>When the friction coefficient due to electron stopping, <em>gamma_s</em>, is
non-zero, electron stopping effects are included for atoms moving
faster than the electron stopping critical velocity, <em>v_0</em>. For
further details about this algorithm, see <a class="reference internal" href="#duffy"><span class="std std-ref">(Duffy)</span></a> and
<p>where the electronic temperatures along the y=0 plane have been set to
1.0, and the electronic temperatures along the y=1 plane have been set
to 2.0. The order of lines in this file is no important. If all the
nodal values are not specified, LAMMPS will generate an error.</p>
<p>The temperature output file, <em>T_oufile</em>, is created and written by
this fix. Temperatures for both the electronic and atomic subsystems
at every node and every N timesteps are output. If N is specified as
zero, no output is generated, and no output filename is needed. The
format of the output is as follows. One long line is written every
output timestep. The timestep itself is given in the first column.
The next Nx*Ny*Nz columns contain the temperatures for the atomic
subsystem, and the final Nx*Ny*Nz columns contain the temperatures for
the electronic subsystem. The ordering of the Nx*Ny*Nz columns is
with the z index varing fastest, y the next fastest, and x the
slowest.</p>
<p>These fixes do not change the coordinates of their atoms; they only
scales their velocities. Thus a time integration fix (e.g. <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>) should still be used to time integrate the affected
atoms. The fixes should not normally be used on atoms that have their
temperature controlled by another fix - e.g. <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> or
<p>where <em>X</em> = T_e/1000, and the thermal conductivity is defined as
kappa_e = D_e*rho_e*C_e, where D_e is the thermal diffusion
coefficient.</p>
<p>Electronic pressure effects are included in the TTM model to account
for the blast force acting on ions because of electronic pressure
gradient (see <a class="reference internal" href="#chen"><span class="std std-ref">(Chen)</span></a>, <a class="reference internal" href="#norman"><span class="std std-ref">(Norman)</span></a>). The total force
<p>The fix ttm/mod parameter file <em>init_file</em> has the following syntax/
Every line with the odd number is considered as a comment and
ignored. The lines with the even numbers are treated as follows:</p>
<pre class="literal-block">
a_0, energy/(temperature*electron) units
a_1, energy/(temperature^2*electron) units
a_2, energy/(temperature^3*electron) units
a_3, energy/(temperature^4*electron) units
a_4, energy/(temperature^5*electron) units
C_0, energy/(temperature*electron) units
A, 1/temperature units
rho_e, electrons/volume units
D_e, length^2/time units
gamma_p, mass/time units
gamma_s, mass/time units
v_0, length/time units
I_0, energy/(time*length^2) units
lsurface, electron grid units (positive integer)
rsurface, electron grid units (positive integer)
l_skin, length units
tau, time units
B, dimensionless
lambda, length units
n_ion, ions/volume units
surface_movement: 0 to disable tracking of surface motion, 1 to enable
T_e_min, temperature units
</pre>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>These fixes write the state of the electronic subsystem and the energy
exchange between the subsystems to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command
for info on how to re-specify a fix in an input script that reads a
restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>Because the state of the random number generator is not saved in the
restart files, this means you cannot do “exact” restarts with this
fix, where the simulation continues on the same as if no restart had
taken place. However, in a statistical sense, a restarted simulation
should produce the same behavior.</p>
<p>None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options are relevant to these
fixes.</p>
<p>Both fixes compute 2 output quantities stored in a vector of length 2,
which can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The first quantity is the
total energy of the electronic subsystem. The second quantity is the
energy transferred from the electronic to the atomic subsystem on that
timestep. Note that the velocity verlet integrator applies the fix ttm
forces to the atomic subsystem as two half-step velocity updates: one
on the current timestep and one on the subsequent timestep.
Consequently, the change in the atomic subsystem energy is lagged by
half a timestep relative to the change in the electronic subsystem
energy. As a result of this, users may notice slight fluctuations in
the sum of the atomic and electronic subsystem energies reported at
the end of the timestep.</p>
<p>The vector values calculated are “extensive”.</p>
<p>No parameter of the fixes can be used with the <em>start/stop</em> keywords
of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. The fixes are not invoked during
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>.
commands. The prescribed accuracy will be maintained by this fix throughout
the simulation.</p>
<p>None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options are relevant to this
fix.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the KSPACE package. It is only enabled if LAMMPS was
built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>Do not set “neigh_modify once yes” or else this fix will never be
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>.
<p>Use the Muller-Plathe algorithm described in <a class="reference internal" href="#muller-plathe"><span class="std std-ref">this paper</span></a> to exchange momenta between two particles in
different regions of the simulation box every N steps. This induces a
shear velocity profile in the system. As described below this enables
a viscosity of the fluid to be calculated. This algorithm is
sometimes called a reverse non-equilibrium MD (reverse NEMD) approach
to computing viscosity. This is because the usual NEMD approach is to
impose a shear velocity profile on the system and measure the response
via an off-diagonal component of the stress tensor, which is
proportional to the momentum flux. In the Muller-Plathe method, the
momentum flux is imposed, and the shear velocity profile is the
system’s response.</p>
<p>The simulation box is divided into <em>Nbin</em> layers in the <em>pdim</em>
direction, where the layer 1 is at the low end of that dimension and
the layer <em>Nbin</em> is at the high end. Every N steps, Nswap pairs of
atoms are chosen in the following manner. Only atoms in the fix group
are considered. Nswap atoms in layer 1 with positive velocity
components in the <em>vdim</em> direction closest to the target value <em>V</em> are
selected. Similarly, Nswap atoms in the “middle” layer (see below) with
negative velocity components in the <em>vdim</em> direction closest to the
negative of the target value <em>V</em> are selected. The two sets of Nswap
atoms are paired up and their <em>vdim</em> momenta components are swapped
within each pair. This resets their velocities, typically in opposite
directions. Over time, this induces a shear velocity profile in the
system which can be measured using commands such as the following,
which writes the profile to the file tmp.profile:</p>
<p>Note that by default, Nswap = 1 and vtarget = INF, though this can be
changed by the optional <em>swap</em> and <em>vtarget</em> keywords. When vtarget =
INF, one or more atoms with the most positive and negative velocity
components are selected. Setting these parameters appropriately, in
conjunction with the swap rate N, allows the momentum flux rate to be
adjusted across a wide range of values, and the momenta to be
exchanged in large chunks or more smoothly.</p>
<p>The “middle” layer for momenta swapping is defined as the <em>Nbin</em>/2 + 1
layer. Thus if <em>Nbin</em> = 20, the two swapping layers are 1 and 11.
This should lead to a symmetric velocity profile since the two layers
are separated by the same distance in both directions in a periodic
sense. This is why <em>Nbin</em> is restricted to being an even number.</p>
<p>As described below, the total momentum transferred by these velocity
swaps is computed by the fix and can be output. Dividing this
quantity by time and the cross-sectional area of the simulation box
yields a momentum flux. The ratio of momentum flux to the slope of
the shear velocity profile is proportional to the viscosity of the
fluid, in appropriate units. See the <a class="reference internal" href="#muller-plathe"><span class="std std-ref">Muller-Plathe paper</span></a> for details.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If your system is periodic in the direction of the momentum
flux, then the flux is going in 2 directions. This means the
effective momentum flux in one direction is reduced by a factor of 2.
You will see this in the equations for viscosity in the Muller-Plathe
paper. LAMMPS is simply tallying momentum which does not account for
whether or not your system is periodic; you must use the value
appropriately to yield a viscosity for your system.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">After equilibration, if the velocity profile you observe is not
linear, then you are likely swapping momentum too frequently and are
not in a regime of linear response. In this case you cannot
accurately infer a viscosity and should try increasing the Nevery
parameter.</p>
</div>
<p>An alternative method for calculating a viscosity is to run a NEMD
simulation, as described in <a class="reference internal" href="Section_howto.html#howto-13"><span class="std std-ref">Section 6.13</span></a> of the manual. NEMD simulations
deform the simmulation box via the <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a>
command. Thus they cannot be run on a charged system using a <a class="reference internal" href="kspace_style.html"><span class="doc">PPPM solver</span></a> since PPPM does not currently support
non-orthogonal boxes. Using fix viscosity keeps the box orthogonal;
thus it does not suffer from this limitation.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>This fix computes a global scalar which can be accessed by various
<a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar is the
cummulative momentum transferred between the bottom and middle of the
simulation box (in the <em>pdim</em> direction) is stored as a scalar
quantity by this fix. This quantity is zeroed when the fix is defined
and accumlates thereafter, once every N steps. The units of the
quantity are momentum = mass*velocity. The scalar value calculated by
this fix is “intensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the MISC package. It is only enabled if LAMMPS
was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>Swaps conserve both momentum and kinetic energy, even if the masses of
the swapped atoms are not equal. Thus you should not need to
thermostat the system. If you do use a thermostat, you may want to
apply it only to the non-swapped dimensions (other than <em>vdim</em>).</p>
<p>LAMMPS does not check, but you should not use this fix to swap
velocities of atoms that are in constrained molecules, e.g. via <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> or <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>. This is because
application of the constraints will alter the amount of transferred
momentum. You should, however, be able to use flexible molecules.
See the <a class="reference internal" href="#maginn"><span class="std std-ref">Maginn paper</span></a> for an example of using this algorithm
in a computation of alcohol molecule properties.</p>
<p>When running a simulation with large, massive particles or molecules
in a background solvent, you may want to only exchange momenta bewteen
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>.
and sigma are the LJ parameters for the constituent LJ
particles. Rho_wall and rho_colloid are the number density of the
constituent particles, in the wall and colloid respectively, in units
of 1/volume.</p>
<p>The <em>wall/colloid</em> interaction is derived by integrating over
constituent LJ particles of size <em>sigma</em> within the colloid particle
and a 3d half-lattice of Lennard-Jones 12/6 particles of size <em>sigma</em>
in the wall. As mentioned in the preceeding paragraph, the density of
particles in the wall and colloid can be different, as specified by
the <em>epsilon</em> pre-factor.</p>
<p>For the <em>wall/harmonic</em> style, <em>epsilon</em> is effectively the spring
constant K, and has units (energy/distance^2). The input parameter
<em>sigma</em> is ignored. The minimum energy position of the harmonic
spring is at the <em>cutoff</em>. This is a repulsive-only spring since the
interaction is truncated at the <em>cutoff</em></p>
<p>For any wall, the <em>epsilon</em> and/or <em>sigma</em> parameter can be specified
as an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a>, in which case it should be
specified as v_name, where name is the variable name. As with a
variable wall position, the variable is evaluated each timestep and
the result becomes the current epsilon or sigma of the wall.
Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent wall interaction.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For all of the styles, you must insure that r is always > 0 for
all particles in the group, or LAMMPS will generate an error. This
means you cannot start your simulation with particles at the wall
position <em>coord</em> (r = 0) or with particles on the wrong side of the
wall (r < 0). For the <em>wall/lj93</em> and <em>wall/lj126</em> styles, the energy
of the wall/particle interaction (and hence the force on the particle)
blows up as r -> 0. The <em>wall/colloid</em> style is even more
restrictive, since the energy blows up as D = r-R -> 0. This means
the finite-size particles of radius R must be a distance larger than R
from the wall position <em>coord</em>. The <em>harmonic</em> style is a softer
potential and does not blow up as r -> 0, but you must use a large
enough <em>epsilon</em> that particles always reamin on the correct side of
the wall (r > 0).</p>
</div>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to define a wall position, but only when a numeric constant or
variable is used. It is not relevant when EDGE is used to specify a
face position. In the variable case, the variable is assumed to
produce a value compatible with the <em>units</em> setting you specify.</p>
<p>A <em>box</em> value selects standard distance units as defined by the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or metal.
A <em>lattice</em> value means the distance units are in lattice spacings.
The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have been previously used to
define the lattice spacings.</p>
<p>The <em>fld</em> keyword can be used with a <em>yes</em> setting to invoke the wall
constraint before pairwise interactions are computed. This allows an
implicit FLD model using <a class="reference internal" href="pair_lubricateU.html"><span class="doc">pair_style lubricateU</span></a>
to include the wall force in its calculations. If the setting is
<em>no</em>, wall forces are imposed after pairwise interactions, in the
usual manner.</p>
<p>The <em>pbc</em> keyword can be used with a <em>yes</em> setting to allow walls to
be specified in a periodic dimension. See the
<a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command for options on simulation box
boundaries. The default for <em>pbc</em> is <em>no</em>, which means the system
must be non-periodic when using a wall. But you may wish to use a
periodic box. E.g. to allow some particles to interact with the wall
via the fix group-ID, and others to pass through it and wrap around a
periodic box. In this case you should insure that the wall if
sufficiently far enough away from the box boundary. If you do not,
then particles may interact with both the wall and with periodic
images on the other side of the box, which is probably not what you
want.</p>
<hr class="docutils" />
<p>Here are examples of variable definitions that move the wall position
in a time-dependent fashion using equal-style
<a class="reference internal" href="variable.html"><span class="doc">variables</span></a>. The wall interaction parameters (epsilon,
sigma) could be varied with additional variable definitions.</p>
<pre class="literal-block">
variable ramp equal ramp(0,10)
fix 1 all wall xlo v_ramp 1.0 1.0 2.5
</pre>
<pre class="literal-block">
variable linear equal vdisplace(0,20)
fix 1 all wall xlo v_linear 1.0 1.0 2.5
</pre>
<pre class="literal-block">
variable wiggle equal swiggle(0.0,5.0,3.0)
fix 1 all wall xlo v_wiggle 1.0 1.0 2.5
</pre>
<pre class="literal-block">
variable wiggle equal cwiggle(0.0,5.0,3.0)
fix 1 all wall xlo v_wiggle 1.0 1.0 2.5
</pre>
<p>The ramp(lo,hi) function adjusts the wall position linearly from lo to
hi over the course of a run. The vdisplace(c0,velocity) function does
something similar using the equation position = c0 + velocity*delta,
where delta is the elapsed time.</p>
<p>The swiggle(c0,A,period) function causes the wall position to
oscillate sinusoidally according to this equation, where omega = 2 PI
/ period:</p>
<pre class="literal-block">
position = c0 + A sin(omega*delta)
</pre>
<p>The cwiggle(c0,A,period) function causes the wall position to
oscillate sinusoidally according to this equation, which will have an
initial wall velocity of 0.0, and thus may impose a gentler
perturbation on the particles:</p>
<pre class="literal-block">
position = c0 + A (1 - cos(omega*delta))
</pre>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy of interaction between atoms and each wall to
the system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is adding its forces. Default is the outermost level.</p>
<p>This fix computes a global scalar energy and a global vector of
forces, which can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. Note that the scalar energy is
the sum of interactions with all defined walls. If you want the
energy on a per-wall basis, you need to use multiple fix wall
commands. The length of the vector is equal to the number of walls
defined by the fix. Each vector value is the normal force on a
specific wall. Note that an outward force on a wall will be a
negative value for <em>lo</em> walls and a positive value for <em>hi</em> walls.
The scalar and vector values calculated by this fix are “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the atom/wall interaction energy to be included in
the total potential energy of the system (the quantity being
minimized), you MUST enable the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em>
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>.
<li><p class="first">Kn = elastic constant for normal particle repulsion (force/distance units or pressure units - see discussion below)</p>
</li>
<li><p class="first">Kt = elastic constant for tangential contact (force/distance units or pressure units - see discussion below)</p>
</li>
<li><p class="first">gamma_n = damping coefficient for collisions in normal direction (1/time units or 1/time-distance units - see discussion below)</p>
</li>
<li><p class="first">gamma_t = damping coefficient for collisions in tangential direction (1/time units or 1/time-distance units - see discussion below)</p>
</li>
<li><p class="first">xmu = static yield criterion (unitless value between 0.0 and 1.0e4)</p>
</li>
<li><p class="first">dampflag = 0 or 1 if tangential damping force is excluded or included</p>
</li>
<li><p class="first">wallstyle = <em>xplane</em> or <em>yplane</em> or <em>zplane</em> or <em>zcylinder</em></p>
</li>
<li><p class="first">args = list of arguments for a particular style</p>
<pre class="literal-block">
<em>xplane</em> or <em>yplane</em> or <em>zplane</em> args = lo hi
lo,hi = position of lower and upper plane (distance units), either can be NULL)
<em>zcylinder</em> args = radius
radius = cylinder radius (distance units)
</pre>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended to args</p>
</li>
<li><p class="first">keyword = <em>wiggle</em> or <em>shear</em></p>
<pre class="literal-block">
<em>wiggle</em> values = dim amplitude period
dim = <em>x</em> or <em>y</em> or <em>z</em>
amplitude = size of oscillation (distance units)
period = time of oscillation (time units)
<em>shear</em> values = dim vshear
dim = <em>x</em> or <em>y</em> or <em>z</em>
vshear = magnitude of shear velocity (velocity units)
<p>Bound the simulation domain of a granular system with a frictional
wall. All particles in the group interact with the wall when they are
close enough to touch it.</p>
<p>The nature of the wall/particle interactions are determined by the
<em>fstyle</em> setting. It can be any of the styles defined by the
<a class="reference internal" href="pair_gran.html"><span class="doc">pair_style granular</span></a> commands. Currently this is
<em>hooke</em>, <em>hooke/history</em>, or <em>hertz/history</em>. The equation for the
force between the wall and particles touching it is the same as the
corresponding equation on the <a class="reference internal" href="pair_gran.html"><span class="doc">pair_style granular</span></a> doc
page, in the limit of one of the two particles going to infinite
-radius and mass (flat wall). I.e. delta = radius - r = overlap of
-particle with wall, m_eff = mass of particle, and sqrt(RiRj/Ri+Rj)
-becomes sqrt(radius of particle). The units for Kn, Kt, gamma_n, and
-gamma_t are as described on that doc page. The meaning of xmu and
-dampflag are also as described on that page. Note that you can choose
-a different force styles and/or different values for the 6
-wall/particle coefficients than for particle/particle interactions.
-E.g. if you wish to model the wall as a different material.</p>
+radius and mass (flat wall). Specifically, delta = radius - r =
+overlap of particle with wall, m_eff = mass of particle, and the
+effective radius of contact = RiRj/Ri+Rj is just the radius of the
+particle.</p>
<p>The parameters <em>Kn</em>, <em>Kt</em>, <em>gamma_n</em>, <em>gamma_t</em>, <em>xmu</em> and <em>dampflag</em>
-have the same meaning as those specified with the <a class="reference internal" href="pair_gran.html"><span class="doc">pair_style granular</span></a> commands. This means a NULL can be used for
-either <em>Kt</em> or <em>gamma_t</em> as described on that page. If a NULL is used
-for <em>Kt</em>, then a default value is used where <em>Kt</em> = 2/7 <em>Kn</em>. If a
-NULL is used for <em>gamma_t</em>, then a default value is used where
-<em>gamma_t</em> = 1/2 <em>gamma_n</em>.</p>
+have the same meaning and units as those specified with the
+<a class="reference internal" href="pair_gran.html"><span class="doc">pair_style granular</span></a> commands. This means a NULL can
+be used for either <em>Kt</em> or <em>gamma_t</em> as described on that page. If a
+NULL is used for <em>Kt</em>, then a default value is used where <em>Kt</em> = 2/7
+<em>Kn</em>. If a NULL is used for <em>gamma_t</em>, then a default value is used
+<p>Note that you can choose a different force styles and/or different
+values for the 6 wall/particle coefficients than for particle/particle
+interactions. E.g. if you wish to model the wall as a different
+material.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">As discussed on the doc page for <a class="reference internal" href="pair_gran.html"><span class="doc">pair_style granular</span></a>, versions of LAMMPS before 9Jan09 used a
different equation for Hertzian interactions. This means Hertizian
wall/particle interactions have also changed. They now include a
sqrt(radius) term which was not present before. Also the previous
versions used Kn and Kt from the pairwise interaction and hardwired
dampflag to 1, rather than letting them be specified directly. This
means you can set the values of the wall/particle coefficients
appropriately in the current code to reproduce the results of a
prevoius Hertzian monodisperse calculation. For example, for the
common case of a monodisperse system with particles of diameter 1, Kn,
Kt, gamma_n, and gamma_s should be set sqrt(2.0) larger than they were
previously.</p>
</div>
<p>The effective mass <em>m_eff</em> in the formulas listed on the <a class="reference internal" href="pair_gran.html"><span class="doc">pair_style granular</span></a> doc page is the mass of the particle for
particle/wall interactions (mass of wall is infinite). If the
particle is part of a rigid body, its mass is replaced by the mass of
the rigid body in those formulas. This is determined by searching for
a <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a> command (or its variants).</p>
<p>The <em>wallstyle</em> can be planar or cylindrical. The 3 planar options
specify a pair of walls in a dimension. Wall positions are given by
<em>lo</em> and <em>hi</em>. Either of the values can be specified as NULL if a
single wall is desired. For a <em>zcylinder</em> wallstyle, the cylinder’s
axis is at x = y = 0.0, and the radius of the cylinder is specified.</p>
<p>Optionally, the wall can be moving, if the <em>wiggle</em> or <em>shear</em>
keywords are appended. Both keywords cannot be used together.</p>
<p>For the <em>wiggle</em> keyword, the wall oscillates sinusoidally, similar to
the oscillations of particles which can be specified by the
<a class="reference internal" href="fix_move.html"><span class="doc">fix move</span></a> command. This is useful in packing
simulations of granular particles. The arguments to the <em>wiggle</em>
keyword specify a dimension for the motion, as well as it’s
<em>amplitude</em> and <em>period</em>. Note that if the dimension is in the plane
of the wall, this is effectively a shearing motion. If the dimension
is perpendicular to the wall, it is more of a shaking motion. A
<em>zcylinder</em> wall can only be wiggled in the z dimension.</p>
<p>Each timestep, the position of a wiggled wall in the appropriate <em>dim</em>
is set according to this equation:</p>
<pre class="literal-block">
position = coord + A - A cos (omega * delta)
</pre>
<p>where <em>coord</em> is the specified initial position of the wall, <em>A</em> is
the <em>amplitude</em>, <em>omega</em> is 2 PI / <em>period</em>, and <em>delta</em> is the time
elapsed since the fix was specified. The velocity of the wall is set
to the derivative of this expression.</p>
<p>For the <em>shear</em> keyword, the wall moves continuously in the specified
dimension with velocity <em>vshear</em>. The dimension must be tangential to
walls with a planar <em>wallstyle</em>, e.g. in the <em>y</em> or <em>z</em> directions for
an <em>xplane</em> wall. For <em>zcylinder</em> walls, a dimension of <em>z</em> means the
cylinder is moving in the z-direction along it’s axis. A dimension of
<em>x</em> or <em>y</em> means the cylinder is spinning around the z-axis, either in
the clockwise direction for <em>vshear</em> > 0 or counter-clockwise for
<em>vshear</em> < 0. In this case, <em>vshear</em> is the tangential velocity of
the wall at whatever <em>radius</em> has been defined.</p>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>This fix writes the shear friction state of atoms interacting with the
wall to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, so that a simulation can
continue correctly if granular potentials with shear “history” effects
are being used. See the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> command for
info on how to re-specify a fix in an input script that reads a
restart file, so that the operation of the fix continues in an
uninterrupted fashion.</p>
<p>None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options are relevant to this
fix. No global or per-atom quantities are stored by this fix for
access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No
parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This fix is part of the GRANULAR package. It is only enabled if
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>Any dimension (xyz) that has a granular wall must be non-periodic.</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>.
<li><p class="first">ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</p>
</li>
<li><p class="first">wall/reflect = style name of this fix command</p>
</li>
<li><p class="first">one or more face/arg pairs may be appended</p>
</li>
<li><p class="first">face = <em>xlo</em> or <em>xhi</em> or <em>ylo</em> or <em>yhi</em> or <em>zlo</em> or <em>zhi</em></p>
<pre class="literal-block">
<em>xlo</em>,<em>ylo</em>,<em>zlo</em> arg = EDGE or constant or variable
EDGE = current lo edge of simulation box
constant = number like 0.0 or -30.0 (distance units)
variable = <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> like v_x or v_wiggle
<em>xhi</em>,<em>yhi</em>,<em>zhi</em> arg = EDGE or constant or variable
EDGE = current hi edge of simulation box
constant = number like 50.0 or 100.3 (distance units)
variable = <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> like v_x or v_wiggle
</pre>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>units</em></p>
<pre class="literal-block">
<em>units</em> value = <em>lattice</em> or <em>box</em>
<em>lattice</em> = the wall position is defined in lattice units
<em>box</em> = the wall position is defined in simulation box units
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
fix xwalls all wall/reflect xlo EDGE xhi EDGE
fix walls all wall/reflect xlo 0.0 ylo 10.0 units box
fix top all wall/reflect zhi v_pressdown
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Bound the simulation with one or more walls which reflect particles
in the specified group when they attempt to move thru them.</p>
<p>Reflection means that if an atom moves outside the wall on a timestep
by a distance delta (e.g. due to <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a>), then it is
put back inside the face by the same delta, and the sign of the
corresponding component of its velocity is flipped.</p>
<p>When used in conjunction with <a class="reference internal" href="fix_nve.html"><span class="doc">fix nve</span></a> and <a class="reference internal" href="run_style.html"><span class="doc">run_style verlet</span></a>, the resultant time-integration algorithm is
equivalent to the primitive splitting algorithm (PSA) described by
<a class="reference internal" href="#bond"><span class="std std-ref">Bond</span></a>. Because each reflection event divides
the corresponding timestep asymmetrically, energy conservation is only
satisfied to O(dt), rather than to O(dt^2) as it would be for
velocity-Verlet integration without reflective walls.</p>
<p>Up to 6 walls or faces can be specified in a single command: <em>xlo</em>,
<em>xhi</em>, <em>ylo</em>, <em>yhi</em>, <em>zlo</em>, <em>zhi</em>. A <em>lo</em> face reflects particles
that move to a coordinate less than the wall position, back in the
<em>hi</em> direction. A <em>hi</em> face reflects particles that move to a
coordinate higher than the wall position, back in the <em>lo</em> direction.</p>
<p>The position of each wall can be specified in one of 3 ways: as the
EDGE of the simulation box, as a constant value, or as a variable. If
EDGE is used, then the corresponding boundary of the current
simulation box is used. If a numeric constant is specified then the
wall is placed at that position in the appropriate dimension (x, y, or
z). In both the EDGE and constant cases, the wall will never move.
If the wall position is a variable, it should be specified as v_name,
where name is an <a class="reference internal" href="variable.html"><span class="doc">equal-style variable</span></a> name. In this
case the variable is evaluated each timestep and the result becomes
the current position of the reflecting wall. Equal-style variables
can specify formulas with various mathematical functions, and include
<a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command keywords for the simulation
box parameters and timestep and elapsed time. Thus it is easy to
specify a time-dependent wall position.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to define a wall position, but only when a numeric constant or
variable is used. It is not relevant when EDGE is used to specify a
face position. In the variable case, the variable is assumed to
produce a value compatible with the <em>units</em> setting you specify.</p>
<p>A <em>box</em> value selects standard distance units as defined by the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or metal.
A <em>lattice</em> value means the distance units are in lattice spacings.
The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have been previously used to
define the lattice spacings.</p>
<hr class="docutils" />
<p>Here are examples of variable definitions that move the wall position
<p>The ramp(lo,hi) function adjusts the wall position linearly from lo to
hi over the course of a run. The vdisplace(c0,velocity) function does
something similar using the equation position = c0 + velocity*delta,
where delta is the elapsed time.</p>
<p>The swiggle(c0,A,period) function causes the wall position to
oscillate sinusoidally according to this equation, where omega = 2 PI
/ period:</p>
<pre class="literal-block">
position = c0 + A sin(omega*delta)
</pre>
<p>The cwiggle(c0,A,period) function causes the wall position to
oscillate sinusoidally according to this equation, which will have an
initial wall velocity of 0.0, and thus may impose a gentler
perturbation on the particles:</p>
<pre class="literal-block">
position = c0 + A (1 - cos(omega*delta))
</pre>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<hr class="docutils" />
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. No parameter of this fix can
be used with the <em>start/stop</em> keywords of the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.
This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>Any dimension (xyz) that has a reflecting wall must be non-periodic.</p>
<p>A reflecting wall should not be used with rigid bodies such as those
defined by a “fix rigid” command. This is because the wall/reflect
displaces atoms directly rather than exerts a force on them. For
rigid bodies, use a soft wall instead, such as <a class="reference internal" href="fix_wall.html"><span class="doc">fix wall/lj93</span></a>. LAMMPS will flag the use of a rigid
fix with fix wall/reflect with a warning, but will not generate an
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>.
<p>In all cases, <em>r</em> is the distance from the particle to the region
surface, and Rc is the <em>cutoff</em> distance at which the particle and
surface no longer interact. The energy of the wall potential is
shifted so that the wall-particle interaction energy is 0.0 at the
cutoff distance.</p>
<p>For the <em>lj93</em> and <em>lj126</em> styles, <em>epsilon</em> and <em>sigma</em> are the usual
Lennard-Jones parameters, which determine the strength and size of the
particle as it interacts with the wall. Epsilon has energy units.
Note that this <em>epsilon</em> and <em>sigma</em> may be different than any
<em>epsilon</em> or <em>sigma</em> values defined for a pair style that computes
particle-particle interactions.</p>
<p>The <em>lj93</em> interaction is derived by integrating over a 3d
half-lattice of Lennard-Jones 12/6 particles. The <em>lj126</em> interaction
is effectively a harder, more repulsive wall interaction.</p>
<p>For the <em>colloid</em> style, <em>epsilon</em> is effectively a Hamaker constant
with energy units for the colloid-wall interaction, <em>R</em> is the radius
of the colloid particle, <em>D</em> is the distance from the surface of the
colloid particle to the wall (r-R), and <em>sigma</em> is the size of a
constituent LJ particle inside the colloid particle. Note that the
cutoff distance Rc in this case is the distance from the colloid
particle center to the wall.</p>
<p>The <em>colloid</em> interaction is derived by integrating over constituent
LJ particles of size <em>sigma</em> within the colloid particle and a 3d
half-lattice of Lennard-Jones 12/6 particles of size <em>sigma</em> in the
wall.</p>
<p>For the <em>wall/harmonic</em> style, <em>epsilon</em> is effectively the spring
constant K, and has units (energy/distance^2). The input parameter
<em>sigma</em> is ignored. The minimum energy position of the harmonic
spring is at the <em>cutoff</em>. This is a repulsive-only spring since the
interaction is truncated at the <em>cutoff</em></p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For all of the styles, you must insure that r is always > 0 for
all particles in the group, or LAMMPS will generate an error. This
means you cannot start your simulation with particles on the region
surface (r = 0) or with particles on the wrong side of the region
surface (r < 0). For the <em>wall/lj93</em> and <em>wall/lj126</em> styles, the
energy of the wall/particle interaction (and hence the force on the
particle) blows up as r -> 0. The <em>wall/colloid</em> style is even more
restrictive, since the energy blows up as D = r-R -> 0. This means
the finite-size particles of radius R must be a distance larger than R
from the region surface. The <em>harmonic</em> style is a softer potential
and does not blow up as r -> 0, but you must use a large enough
<em>epsilon</em> that particles always reamin on the correct side of the
region surface (r > 0).</p>
</div>
<p><strong>Restart, fix_modify, output, run start/stop, minimize info:</strong></p>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em> option is supported by this
fix to add the energy of interaction between atoms and the wall to the
system’s potential energy as part of <a class="reference internal" href="thermo_style.html"><span class="doc">thermodynamic output</span></a>.</p>
<p>The <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>respa</em> option is supported by this
fix. This allows to set at which level of the <a class="reference internal" href="run_style.html"><span class="doc">r-RESPA</span></a>
integrator the fix is adding its forces. Default is the outermost level.</p>
<p>This fix computes a global scalar energy and a global 3-length vector
of forces, which can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The scalar energy is the sum
of energy interactions for all particles interacting with the wall
represented by the region surface. The 3 vector quantities are the
x,y,z components of the total force acting on the wall due to the
particles. The scalar and vector values calculated by this fix are
“extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want the atom/wall interaction energy to be included in
the total potential energy of the system (the quantity being
minimized), you MUST enable the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> <em>energy</em>
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>.
<li><p class="first">ID = user-defined name of the group</p>
</li>
<li><p class="first">style = <em>delete</em> or <em>region</em> or <em>type</em> or <em>id</em> or <em>molecule</em> or <em>variable</em> or <em>include</em> or <em>subtract</em> or <em>union</em> or <em>intersect</em> or <em>dynamic</em> or <em>static</em></p>
<pre class="literal-block">
<em>delete</em> = no args
<em>clear</em> = no args
<em>region</em> args = region-ID
<em>type</em> or <em>id</em> or <em>molecule</em>
args = list of one or more atom types, atom IDs, or molecule IDs
any entry in list can be a sequence formatted as A:B or A:B:C where
A = starting index, B = ending index,
C = increment between indices, 1 if not specified
args = logical value
logical = "<" or "<=" or ">" or ">=" or "==" or "!="
value = an atom type or atom ID or molecule ID (depending on <em>style</em>)
args = logical value1 value2
logical = "<>"
value1,value2 = atom types or atom IDs or molecule IDs (depending on <em>style</em>)
<em>variable</em> args = variable-name
<em>include</em> args = molecule
molecule = add atoms to group with same molecule ID as atoms already in group
<em>subtract</em> args = two or more group IDs
<em>union</em> args = one or more group IDs
<em>intersect</em> args = two or more group IDs
<em>dynamic</em> args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = <em>region</em> or <em>var</em> or <em>every</em>
<em>region</em> value = region-ID
<em>var</em> value = name of variable
<em>every</em> value = N = update group every this many timesteps
<p>If the group ID already exists, the group command adds the specified
atoms to the group.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">By default groups are static, meaning the atoms are permanently
assigned to the group. For example, if the <em>region</em> style is used to
assign atoms to a group, the atoms will remain in the group even if
they later move out of the region. As explained below, the <em>dynamic</em>
style can be used to make a group dynamic so that a periodic
determination is made as to which atoms are in the group. Since many
LAMMPS commands operate on groups of atoms, you should think carefully
about whether making a group dynamic makes sense for your model.</p>
</div>
<p>A group with the ID <em>all</em> is predefined. All atoms belong to this
group. This group cannot be deleted, or made dynamic.</p>
<p>The <em>delete</em> style removes the named group and un-assigns all atoms
that were assigned to that group. Since there is a restriction (see
below) that no more than 32 groups can be defined at any time, the
<em>delete</em> style allows you to remove groups that are no longer needed,
so that more can be specified. You cannot delete a group if it has
been used to define a current <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or <a class="reference internal" href="compute.html"><span class="doc">compute</span></a>
or <a class="reference internal" href="dump.html"><span class="doc">dump</span></a>.</p>
<p>The <em>clear</em> style un-assigns all atoms that were assigned to that
group. This may be dangerous to do during a simulation run,
e.g. using the <a class="reference internal" href="run.html"><span class="doc">run every</span></a> command if a fix or compute or
other operation expects the atoms in the group to remain constant, but
LAMMPS does not check for this.</p>
<p>The <em>region</em> style puts all atoms in the region volume into the group.
Note that this is a static one-time assignment. The atoms remain
assigned (or not assigned) to the group even in they later move out of
the region volume.</p>
<p>The <em>type</em>, <em>id</em>, and <em>molecule</em> styles put all atoms with the
specified atom types, atom IDs, or molecule IDs into the group. These
3 styles can use arguments specified in one of two formats.</p>
<p>The first format is a list of values (types or IDs). For example, the
2nd command in the examples above puts all atoms of type 3 or 4 into
the group named <em>water</em>. Each entry in the list can be a
colon-separated sequence A:B or A:B:C, as in two of the examples
above. A “sequence” generates a sequence of values (types or IDs),
with an optional increment. The first example with 500:1000 has the
default increment of 1 and would add all atom IDs from 500 to 1000
(inclusive) to the group sub, along with 10,25,50 since they also
appear in the list of values. The second example with 100:10000:10
uses an increment of 10 and would thus would add atoms IDs
100,110,120, ... 9990,10000 to the group sub.</p>
<p>The second format is a <em>logical</em> followed by one or two values (type
or ID). The 7 valid logicals are listed above. All the logicals
except <> take a single argument. The 3rd example above adds all
atoms with IDs from 1 to 150 to the group named <em>sub</em>. The logical <>
means “between” and takes 2 arguments. The 4th example above adds all
atoms belonging to molecules with IDs from 50 to 250 (inclusive) to
the group named polyA.</p>
<p>The <em>variable</em> style evaluates a variable to determine which atoms to
add to the group. It must be an <a class="reference internal" href="variable.html"><span class="doc">atom-style variable</span></a>
previously defined in the input script. If the variable evaluates
to a non-zero value for a particular atom, then that atom is added
to the specified group.</p>
<p>Atom-style variables can specify formulas that include thermodynamic
quantities, per-atom values such as atom coordinates, or per-atom
quantities calculated by computes, fixes, or other variables. They
can also include Boolean logic where 2 numeric values are compared to
yield a 1 or 0 (effectively a true or false). Thus using the
<em>variable</em> style, is a general way to flag specific atoms to include
or exclude from a group.</p>
<p>For example, these lines define a variable “eatom” that calculates the
potential energy of each atom and includes it in the group if its
potential energy is above the threshhold value -3.0.</p>
<pre class="literal-block">
compute 1 all pe/atom
compute 2 all reduce sum c_1
thermo_style custom step temp pe c_2
run 0
</pre>
<pre class="literal-block">
variable eatom atom "c_1 > -3.0"
group hienergy variable eatom
</pre>
<p>Note that these lines</p>
<pre class="literal-block">
compute 2 all reduce sum c_1
thermo_style custom step temp pe c_2
run 0
</pre>
<p>are necessary to insure that the “eatom” variable is current when the
group command invokes it. Because the eatom variable computes the
per-atom energy via the pe/atom compute, it will only be current if a
run has been performed which evaluated pairwise energies, and the
pe/atom compute was actually invoked during the run. Printing the
thermodyanmic info for compute 2 insures that this is the case, since
it sums the pe/atom compute values (in the reduce compute) to output
them to the screen. See the “Variable Accuracy” section of the
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a> doc page for more details on insuring that
variables are current when they are evaluated between runs.</p>
<p>The <em>include</em> style with its arg <em>molecule</em> adds atoms to a group that
have the same molecule ID as atoms already in the group. The molecule
ID = 0 is ignored in this operation, since it is assumed to flag
isolated atoms that are not part of molecules. An example of where
this operation is useful is if the <em>region</em> style has been used
previously to add atoms to a group that are within a geometric region.
If molecules straddle the region boundary, then atoms outside the
region that are part of molecules with atoms inside the region will
not be in the group. Using the group command a 2nd time with <em>include
molecule</em> will add those atoms that are outside the region to the
group.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <em>include molecule</em> operation is relatively expensive in a
parallel sense. This is because it requires communication of relevant
molecule IDs between all the processors and each processor to loop
over its atoms once per processor, to compare its atoms to the list of
molecule IDs from every other processor. Hence it scales as N, rather
than N/P as most of the group operations do, where N is the number of
atoms, and P is the number of processors.</p>
</div>
<p>The <em>subtract</em> style takes a list of two or more existing group names
as arguments. All atoms that belong to the 1st group, but not to any
of the other groups are added to the specified group.</p>
<p>The <em>union</em> style takes a list of one or more existing group names as
arguments. All atoms that belong to any of the listed groups are
added to the specified group.</p>
<p>The <em>intersect</em> style takes a list of two or more existing group names
as arguments. Atoms that belong to every one of the listed groups are
added to the specified group.</p>
<hr class="docutils" />
<p>The <em>dynamic</em> style flags an existing or new group as dynamic. This
means atoms will be (re)assigned to the group periodically as a
simulation runs. This is in contrast to static groups where atoms are
permanently assigned to the group. The way the assignment occurs is
as follows. Only atoms in the group specified as the parent group via
the parent-ID are assigned to the dynamic group before the following
conditions are applied. If the <em>region</em> keyword is used, atoms not in
the specified region are removed from the dynamic group. If the <em>var</em>
keyword is used, the variable name must be an atom-style or
atomfile-style variable. The variable is evaluated and atoms whose
per-atom values are 0.0, are removed from the dynamic group.</p>
<p>The assignment of atoms to a dynamic group is done at the beginning of
each run and on every timestep that is a multiple of <em>N</em>, which is the
argument for the <em>every</em> keyword (N = 1 is the default). For an
energy minimization, via the <a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command, an
assignment is made at the beginning of the minimization, but not
during the iterations of the minimizer.</p>
<p>The point in the timestep at which atoms are assigned to a dynamic
group is after the initial stage of velocity Verlet time integration
has been performed, and before neighbor lists or forces are computed.
This is the point in the timestep where atom positions have just
changed due to the time integration, so the region criterion should be
accurate, if applied.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the <em>region</em> keyword is used to determine what atoms are in
the dynamic group, atoms can move outside of the simulation box
between reneighboring events. Thus if you want to include all atoms
on the left side of the simulation box, you probably want to set the
left boundary of the region to be outside the simulation box by some
reasonable amount (e.g. up to the cutoff of the potential), else they
may be excluded from the dynamic region.</p>
</div>
<p>Here is an example of using a dynamic group to shrink the set of atoms
being integrated by using a spherical region with a variable radius
(shrinking from 18 to 5 over the course of the run). This could be
used to model a quench of the system, freezing atoms outside the
shrinking sphere, then converting the remaining atoms to a static
group and running further.</p>
<pre class="literal-block">
variable nsteps equal 5000
variable rad equal 18-(step/v_nsteps)*(18-5)
region ss sphere 20 20 0 v_rad
group mobile dynamic all region ss
fix 1 mobile nve
run ${nsteps}
group mobile static
run ${nsteps}
</pre>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">All fixes and computes take a group ID as an argument, but they
do not all allow for use of a dynamic group. If you get an error
message that this is not allowed, but feel that it should be for the
fix or compute in question, then please post your reasoning to the
LAMMPS mail list and we can change it.</p>
</div>
<p>The <em>static</em> style removes the setting for a dynamic group, converting
it to a static group (the default). The atoms in the static group are
those currently in the dynamic group.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>There can be no more than 32 groups defined at one time, including
“all”.</p>
<p>The parent group of a dynamic group cannot itself be a dynamic group.</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>.
<p>Note that if one of the commands to execute is <a class="reference internal" href="quit.html"><span class="doc">quit</span></a>, as in
the first example above, then executing the command will cause LAMMPS
to halt.</p>
<p>Note that by jumping to a label in the same input script, the if
command can be used to break out of a loop. See the <a class="reference internal" href="variable.html"><span class="doc">variable delete</span></a> command for info on how to delete the associated
loop variable, so that it can be re-used later in the input script.</p>
<p>Here is an example of a loop which checks every 1000 steps if the
system temperature has reached a certain value, and if so, breaks out
of the loop to finish the run. Note that any variable could be
checked, so long as it is current on the timestep when the run
completes. As explained on the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> doc page,
this can be insured by includig the variable in thermodynamic output.</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>.
<li><p class="first">style = <em>none</em> or <em>ewald</em> or <em>ewald/disp</em> or <em>ewald/omp</em> or <em>pppm</em> or <em>pppm/cg</em> or <em>pppm/disp</em> or <em>pppm/tip4p</em> or <em>pppm/stagger</em> or <em>pppm/disp/tip4p</em> or <em>pppm/gpu</em> or <em>pppm/kk</em> or <em>pppm/omp</em> or <em>pppm/cg/omp</em> or <em>pppm/tip4p/omp</em> or <em>msm</em> or <em>msm/cg</em> or <em>msm/omp</em> or <em>msm/cg/omp</em></p>
<pre class="literal-block">
<em>none</em> value = none
<em>ewald</em> value = accuracy
accuracy = desired relative error in forces
<em>ewald/disp</em> value = accuracy
accuracy = desired relative error in forces
<em>ewald/omp</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/cg</em> value = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
<em>pppm/disp</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/tip4p</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/disp/tip4p</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/gpu</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/kk</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/omp</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/cg/omp</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/tip4p/omp</em> value = accuracy
accuracy = desired relative error in forces
<em>pppm/stagger</em> value = accuracy
accuracy = desired relative error in forces
<em>msm</em> value = accuracy
accuracy = desired relative error in forces
<em>msm/cg</em> value = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
<em>msm/omp</em> value = accuracy
accuracy = desired relative error in forces
<em>msm/cg/omp</em> value = accuracy (smallq)
accuracy = desired relative error in forces
smallq = cutoff for charges to be considered (optional) (charge units)
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
kspace_style pppm 1.0e-4
kspace_style pppm/cg 1.0e-5 1.0e-6
kspace style msm 1.0e-4
kspace_style none
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Define a long-range solver for LAMMPS to use each timestep to compute
long-range Coulombic interactions or long-range 1/r^6 interactions.
Most of the long-range solvers perform their computation in K-space,
hence the name of this command.</p>
<p>When such a solver is used in conjunction with an appropriate pair
style, the cutoff for Coulombic or 1/r^N interactions is effectively
infinite. If the Coulombic case, this means each charge in the system
interacts with charges in an infinite array of periodic images of the
simulation domain.</p>
<p>Note that using a long-range solver requires use of a matching <a class="reference internal" href="pair_style.html"><span class="doc">pair style</span></a> to perform consistent short-range pairwise
calculations. This means that the name of the pair style contains a
matching keyword to the name of the KSpace style, as in this table:</p>
<table border="1" class="docutils">
<colgroup>
<col width="49%" />
<col width="51%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Pair style</td>
<td>KSpace style</td>
</tr>
<tr class="row-even"><td>coul/long</td>
<td>ewald or pppm</td>
</tr>
<tr class="row-odd"><td>coul/msm</td>
<td>msm</td>
</tr>
<tr class="row-even"><td>lj/long or buck/long</td>
<td>disp (for dispersion)</td>
</tr>
<tr class="row-odd"><td>tip4p/long</td>
<td>tip4p</td>
</tr>
</tbody>
</table>
<hr class="docutils" />
<p>The <em>ewald</em> style performs a standard Ewald summation as described in
any solid-state physics text.</p>
<p>The <em>ewald/disp</em> style adds a long-range dispersion sum option for
1/r^6 potentials and is useful for simulation of interfaces
<a class="reference internal" href="pair_lj_long.html#veld"><span class="std std-ref">(Veld)</span></a>. It also performs standard Coulombic Ewald summations,
but in a more efficient manner than the <em>ewald</em> style. The 1/r^6
capability means that Lennard-Jones or Buckingham potentials can be
used without a cutoff, i.e. they become full long-range potentials.
The <em>ewald/disp</em> style can also be used with point-dipoles
<a class="reference internal" href="pair_dipole.html#toukmaji"><span class="std std-ref">(Toukmaji)</span></a> and is currently the only kspace solver in
LAMMPS with this capability.</p>
<hr class="docutils" />
<p>The <em>pppm</em> style invokes a particle-particle particle-mesh solver
<a class="reference internal" href="#hockney"><span class="std std-ref">(Hockney)</span></a> which maps atom charge to a 3d mesh, uses 3d FFTs
to solve Poisson’s equation on the mesh, then interpolates electric
fields on the mesh points back to the atoms. It is closely related to
the particle-mesh Ewald technique (PME) <a class="reference internal" href="#darden"><span class="std std-ref">(Darden)</span></a> used in
AMBER and CHARMM. The cost of traditional Ewald summation scales as
N^(3/2) where N is the number of atoms in the system. The PPPM solver
scales as Nlog(N) due to the FFTs, so it is almost always a faster
<p class="last">All of the PPPM styles can be used with single-precision FFTs by
using the compiler switch -DFFT_SINGLE for the FFT_INC setting in your
lo-level Makefile. This setting also changes some of the PPPM
operations (e.g. mapping charge to mesh and interpolating electric
fields to particles) to be performed in single precision. This option
can speed-up long-range calulations, particularly in parallel or on
GPUs. The use of the -DFFT_SINGLE flag is discussed in <a class="reference internal" href="Section_start.html#start-2-4"><span class="std std-ref">this section</span></a> of the manual. MSM does not
currently support the -DFFT_SINGLE compiler switch.</p>
</div>
<hr class="docutils" />
<p>The <em>msm</em> style invokes a multi-level summation method MSM solver,
<a class="reference internal" href="#hardy"><span class="std std-ref">(Hardy)</span></a> or <a class="reference internal" href="#hardy2"><span class="std std-ref">(Hardy2)</span></a>, which maps atom charge to a 3d
mesh, and uses a multi-level hierarchy of coarser and coarser meshes
on which direct coulomb solves are done. This method does not use
FFTs and scales as N. It may therefore be faster than the other
K-space solvers for relatively large problems when running on large
core counts. MSM can also be used for non-periodic boundary conditions and
for mixed periodic and non-periodic boundaries.</p>
<p>MSM is most competitive versus Ewald and PPPM when only relatively
low accuracy forces, about 1e-4 relative error or less accurate,
are needed. Note that use of a larger coulomb cutoff (i.e. 15
angstroms instead of 10 angstroms) provides better MSM accuracy for
both the real space and grid computed forces.</p>
<p>Currently calculation of the full pressure tensor in MSM is expensive.
Using the <a class="reference internal" href="kspace_modify.html"><span class="doc">kspace_modify</span></a> <em>pressure/scalar yes</em>
command provides a less expensive way to compute the scalar pressure
(Pxx + Pyy + Pzz)/3.0. The scalar pressure can be used, for example,
to run an isotropic barostat. If the full pressure tensor is needed,
then calculating the pressure at every timestep or using a fixed
pressure simulation with MSM will cause the code to run slower.</p>
<hr class="docutils" />
<p>The specified <em>accuracy</em> determines the relative RMS error in per-atom
forces calculated by the long-range solver. It is set as a
dimensionless number, relative to the force that two unit point
charges (e.g. 2 monovalent ions) exert on each other at a distance of
1 Angstrom. This reference value was chosen as representative of the
magnitude of electrostatic forces in atomic systems. Thus an accuracy
value of 1.0e-4 means that the RMS error will be a factor of 10000
smaller than the reference force.</p>
<p>The accuracy setting is used in conjunction with the pairwise cutoff
to determine the number of K-space vectors for style <em>ewald</em> or the
grid size for style <em>pppm</em> or <em>msm</em>.</p>
<p>Note that style <em>pppm</em> only computes the grid size at the beginning of
a simulation, so if the length or triclinic tilt of the simulation
cell increases dramatically during the course of the simulation, the
accuracy of the simulation may degrade. Likewise, if the
<a class="reference internal" href="kspace_modify.html"><span class="doc">kspace_modify slab</span></a> option is used with
shrink-wrap boundaries in the z-dimension, and the box size changes
dramatically in z. For example, for a triclinic system with all three
tilt factors set to the maximum limit, the PPPM grid should be
increased roughly by a factor of 1.5 in the y direction and 2.0 in the
z direction as compared to the same system using a cubic orthogonal
simulation cell. One way to ensure the accuracy requirement is being
met is to run a short simulation at the maximum expected tilt or
length, note the required grid size, and then use the
<a class="reference internal" href="kspace_modify.html"><span class="doc">kspace_modify</span></a> <em>mesh</em> command to manually set the
PPPM grid size to this value.</p>
<p>RMS force errors in real space for <em>ewald</em> and <em>pppm</em> are estimated
using equation 18 of <a class="reference internal" href="#kolafa"><span class="std std-ref">(Kolafa)</span></a>, which is also referenced as
equation 9 of <a class="reference internal" href="#petersen"><span class="std std-ref">(Petersen)</span></a>. RMS force errors in K-space for
<em>ewald</em> are estimated using equation 11 of <a class="reference internal" href="#petersen"><span class="std std-ref">(Petersen)</span></a>,
which is similar to equation 32 of <a class="reference internal" href="#kolafa"><span class="std std-ref">(Kolafa)</span></a>. RMS force
errors in K-space for <em>pppm</em> are estimated using equation 38 of
<a class="reference internal" href="#deserno"><span class="std std-ref">(Deserno)</span></a>. RMS force errors for <em>msm</em> are estimated
using ideas from chapter 3 of <a class="reference internal" href="#hardy"><span class="std std-ref">(Hardy)</span></a>, with equation 3.197
of particular note. When using <em>msm</em> with non-periodic boundary
conditions, it is expected that the error estimation will be too
pessimistic. RMS force errors for dipoles when using <em>ewald/disp</em>
are estimated using equations 33 and 46 of <a class="reference internal" href="pair_polymorphic.html#wang"><span class="std std-ref">(Wang)</span></a>.</p>
<p>See the <a class="reference internal" href="kspace_modify.html"><span class="doc">kspace_modify</span></a> command for additional
options of the K-space solvers that can be set, including a <em>force</em>
option for setting an absoulte RMS error in forces, as opposed to a
relative RMS error.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>More specifically, the <em>pppm/gpu</em> style performs charge assignment and
force interpolation calculations on the GPU. These processes are
performed either in single or double precision, depending on whether
the -DFFT_SINGLE setting was specified in your lo-level Makefile, as
discussed above. The FFTs themselves are still calculated on the CPU.
If <em>pppm/gpu</em> is used with a GPU-enabled pair style, part of the PPPM
calculation can be performed concurrently on the GPU while other
calculations for non-bonded and bonded force calculation are performed
on the CPU.</p>
<p>The <em>pppm/kk</em> style also performs charge assignment and force
interpolation calculations on the GPU while the FFTs themselves are
calculated on the CPU in non-threaded mode.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL,
KOKKOS, USER-OMP, and OPT packages respectively. They are only
enabled if LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>Note that the long-range electrostatic solvers in LAMMPS assume conducting
metal (tinfoil) boundary conditions for both charge and dipole
interactions. Vacuum boundary conditions are not currently supported.</p>
<p>The <em>ewald/disp</em>, <em>ewald</em>, <em>pppm</em>, and <em>msm</em> styles support
non-orthogonal (triclinic symmetry) simulation boxes. However,
triclinic simulation cells may not yet be supported by suffix versions
of these styles.</p>
<p>All of the kspace styles are part of the KSPACE package. They are
only enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info. Note that
the KSPACE package is installed by default.</p>
<p>For MSM, a simulation must be 3d and one can use any combination of
periodic, non-periodic, or shrink-wrapped boundaries (specified using
the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command).</p>
<p>For Ewald and PPPM, a simulation must be 3d and periodic in all
dimensions. The only exception is if the slab option is set with
<a class="reference internal" href="kspace_modify.html"><span class="doc">kspace_modify</span></a>, in which case the xy dimensions
must be periodic and the z dimension must be non-periodic.</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>.
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>.
<li><p class="first">ID = user-assigned name for the molecule template</p>
</li>
<li><p class="first">file1,file2,... = names of files containing molecule descriptions</p>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended after each file</p>
</li>
<li><p class="first">keyword = <em>offset</em> or <em>toff</em> or <em>boff</em> or <em>aoff</em> or <em>doff</em> or <em>ioff</em> or <em>scale</em></p>
<pre class="literal-block">
<em>offset</em> values = Toff Boff Aoff Doff Ioff
Toff = offset to add to atom types
Boff = offset to add to bond types
Aoff = offset to add to angle types
Doff = offset to add to dihedral types
Ioff = offset to add to improper types
<em>toff</em> value = Toff
Toff = offset to add to atom types
<em>boff</em> value = Boff
Boff = offset to add to bond types
<em>aoff</em> value = Aoff
Aoff = offset to add to angle types
<em>doff</em> value = Doff
Doff = offset to add to dihedral types
<em>ioff</em> value = Ioff
Ioff = offset to add to improper types
<em>scale</em> value = sfactor
sfactor = scale factor to apply to the size and mass of the molecule
<li><em>Special Bond Counts, Special Bonds</em> = special neighbor info</li>
<li><em>Shake Flags, Shake Atoms, Shake Bond Types</em> = SHAKE info</li>
</ul>
<p>If a Bonds section is specified then the Special Bond Counts and
Special Bonds sections can also be used, if desired, to explicitly
list the 1-2, 1-3, 1-4 neighbors within the molecule topology (see
details below). This is optional since if these sections are not
included, LAMMPS will auto-generate this information. Note that
LAMMPS uses this info to properly exclude or weight bonded pairwise
interactions between bonded atoms. See the
<a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> command for more details. One
reason to list the special bond info explicitly is for the
<a class="reference internal" href="tutorial_drude.html"><span class="doc">thermalized Drude oscillator model</span></a> which treats
the bonds between nuclear cores and Drude electrons in a different
manner.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Whether a section is required depends on how the molecule
template is used by other LAMMPS commands. For example, to add a
molecule via the <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a> command, the Coords
and Types sections are required. To add a rigid body via the <a class="reference internal" href="fix_pour.html"><span class="doc">fix pour</span></a> command, the Bonds (Angles, etc) sections are not
required, since the molecule will be treated as a rigid body. Some
sections are optional. For example, the <a class="reference internal" href="fix_pour.html"><span class="doc">fix pour</span></a>
command can be used to add “molecules” which are clusters of
finite-size granular particles. If the Diameters section is not
specified, each particle in the molecule will have a default diameter
of 1.0. See the doc pages for LAMMPS commands that use molecule
templates for more details.</p>
</div>
<p>Each section is listed below in alphabetic order. The format of each
section is described including the number of lines it must contain and
rules (if any) for whether it can appear in the data file. In each
case the ID is ignored; it is simply included for readability, and
should be a number from 1 to Nlines for the section, indicating which
atom (or bond, etc) the entry applies to. The lines are assumed to be
listed in order from 1 to Nlines, but LAMMPS does not check for this.</p>
<hr class="docutils" />
<p><em>Coords</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID x y z</li>
<li>x,y,z = coordinate of atom</li>
</ul>
<hr class="docutils" />
<p><em>Types</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID type</li>
<li>type = atom type of atom</li>
</ul>
<hr class="docutils" />
<p><em>Charges</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID q</li>
<li>q = charge on atom</li>
</ul>
<p>This section is only allowed for <a class="reference internal" href="atom_style.html"><span class="doc">atom styles</span></a> that
support charge. If this section is not included, the default charge
on each atom in the molecule is 0.0.</p>
<hr class="docutils" />
<p><em>Diameters</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID diam</li>
<li>diam = diameter of atom</li>
</ul>
<p>This section is only allowed for <a class="reference internal" href="atom_style.html"><span class="doc">atom styles</span></a> that
support finite-size spherical particles, e.g. atom_style sphere. If
not listed, the default diameter of each atom in the molecule is 1.0.</p>
<hr class="docutils" />
<p><em>Masses</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID mass</li>
<li>mass = mass of atom</li>
</ul>
<p>This section is only allowed for <a class="reference internal" href="atom_style.html"><span class="doc">atom styles</span></a> that
support per-atom mass, as opposed to per-type mass. See the
<a class="reference internal" href="mass.html"><span class="doc">mass</span></a> command for details. If this section is not
included, the default mass for each atom is derived from its volume
(see Diameters section) and a default density of 1.0, in
<a class="reference internal" href="units.html"><span class="doc">units</span></a> of mass/volume.</p>
<hr class="docutils" />
<p><em>Bonds</em> section:</p>
<ul class="simple">
<li>one line per bond</li>
<li>line syntax: ID type atom1 atom2</li>
<li>type = bond type (1-Nbondtype)</li>
<li>atom1,atom2 = IDs of atoms in bond</li>
</ul>
<p>The IDs for the two atoms in each bond should be values
from 1 to Natoms, where Natoms = # of atoms in the molecule.</p>
<hr class="docutils" />
<p><em>Angles</em> section:</p>
<ul class="simple">
<li>one line per angle</li>
<li>line syntax: ID type atom1 atom2 atom3</li>
<li>type = angle type (1-Nangletype)</li>
<li>atom1,atom2,atom3 = IDs of atoms in angle</li>
</ul>
<p>The IDs for the three atoms in each angle should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule. The 3 atoms are
ordered linearly within the angle. Thus the central atom (around
which the angle is computed) is the atom2 in the list.</p>
<hr class="docutils" />
<p><em>Dihedrals</em> section:</p>
<ul class="simple">
<li>one line per dihedral</li>
<li>line syntax: ID type atom1 atom2 atom3 atom4</li>
<li>type = dihedral type (1-Ndihedraltype)</li>
<li>atom1,atom2,atom3,atom4 = IDs of atoms in dihedral</li>
</ul>
<p>The IDs for the four atoms in each dihedral should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule. The 4 atoms are
ordered linearly within the dihedral.</p>
<hr class="docutils" />
<p><em>Impropers</em> section:</p>
<ul class="simple">
<li>one line per improper</li>
<li>line syntax: ID type atom1 atom2 atom3 atom4</li>
<li>type = improper type (1-Nimpropertype)</li>
<li>atom1,atom2,atom3,atom4 = IDs of atoms in improper</li>
</ul>
<p>The IDs for the four atoms in each improper should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule. The ordering of
the 4 atoms determines the definition of the improper angle used in
the formula for the defined <a class="reference internal" href="improper_style.html"><span class="doc">improper style</span></a>. See
the doc pages for individual styles for details.</p>
<hr class="docutils" />
<p><em>Special Bond Counts</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID N1 N2 N3</li>
<li>N1 = # of 1-2 bonds</li>
<li>N2 = # of 1-3 bonds</li>
<li>N3 = # of 1-4 bonds</li>
</ul>
<p>N1, N2, N3 are the number of 1-2, 1-3, 1-4 neighbors respectively of
this atom within the topology of the molecule. See the
<a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> doc page for more discussion of
1-2, 1-3, 1-4 neighbors. If this section appears, the Special Bonds
section must also appear.</p>
<p>As explained above, LAMMPS will auto-generate this information if this
section is not specified. If specified, this section will
override what would be auto-generated.</p>
<hr class="docutils" />
<p><em>Special Bonds</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID a b c d ...</li>
<li>a,b,c,d,... = IDs of atoms in N1+N2+N3 special bonds</li>
</ul>
<p>A, b, c, d, etc are the IDs of the n1+n2+n3 atoms that are 1-2, 1-3,
1-4 neighbors of this atom. The IDs should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule. The first N1
values should be the 1-2 neighbors, the next N2 should be the 1-3
neighbors, the last N3 should be the 1-4 neighbors. No atom ID should
appear more than once. See the <a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> doc
page for more discussion of 1-2, 1-3, 1-4 neighbors. If this section
appears, the Special Bond Counts section must also appear.</p>
<p>As explained above, LAMMPS will auto-generate this information if this
section is not specified. If specified, this section will override
what would be auto-generated.</p>
<hr class="docutils" />
<p><em>Shake Flags</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID flag</li>
<li>flag = 0,1,2,3,4</li>
</ul>
<p>This section is only needed when molecules created using the template
will be constrained by SHAKE via the “fix shake” command. The other
two Shake sections must also appear in the file, following this one.</p>
<p>The meaning of the flag for each atom is as follows. See the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> doc page for a further description of SHAKE
clusters.</p>
<ul class="simple">
<li>0 = not part of a SHAKE cluster</li>
<li>1 = part of a SHAKE angle cluster (two bonds and the angle they form)</li>
<li>2 = part of a 2-atom SHAKE cluster with a single bond</li>
<li>3 = part of a 3-atom SHAKE cluster with two bonds</li>
<li>4 = part of a 4-atom SHAKE cluster with three bonds</li>
</ul>
<hr class="docutils" />
<p><em>Shake Atoms</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID a b c d</li>
<li>a,b,c,d = IDs of atoms in cluster</li>
</ul>
<p>This section is only needed when molecules created using the template
will be constrained by SHAKE via the “fix shake” command. The other
two Shake sections must also appear in the file.</p>
<p>The a,b,c,d values are atom IDs (from 1 to Natoms) for all the atoms
in the SHAKE cluster that this atom belongs to. The number of values
that must appear is determined by the shake flag for the atom (see the
Shake Flags section above). All atoms in a particular cluster should
list their a,b,c,d values identically.</p>
<p>If flag = 0, no a,b,c,d values are listed on the line, just the
(ignored) ID.</p>
<p>If flag = 1, a,b,c are listed, where a = ID of central atom in the
angle, and b,c the other two atoms in the angle.</p>
<p>If flag = 2, a,b are listed, where a = ID of atom in bond with the the
lowest ID, and b = ID of atom in bond with the highest ID.</p>
<p>If flag = 3, a,b,c are listed, where a = ID of central atom,
and b,c = IDs of other two atoms bonded to the central atom.</p>
<p>If flag = 4, a,b,c,d are listed, where a = ID of central atom,
and b,c,d = IDs of other three atoms bonded to the central atom.</p>
<p>See the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> doc page for a further description
of SHAKE clusters.</p>
<hr class="docutils" />
<p><em>Shake Bond Types</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: ID a b c</li>
<li>a,b,c = bond types (or angle type) of bonds (or angle) in cluster</li>
</ul>
<p>This section is only needed when molecules created using the template
will be constrained by SHAKE via the “fix shake” command. The other
two Shake sections must also appear in the file.</p>
<p>The a,b,c values are bond types (from 1 to Nbondtypes) for all bonds
in the SHAKE cluster that this atom belongs to. The number of values
that must appear is determined by the shake flag for the atom (see the
Shake Flags section above). All atoms in a particular cluster should
list their a,b,c values identically.</p>
<p>If flag = 0, no a,b,c values are listed on the line, just the
(ignored) ID.</p>
<p>If flag = 1, a,b,c are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), b = bondtype of the bond between the central atom and
the 2nd non-central atom (value c in the Shake Atoms section), and c =
the angle type (1 to Nangletypes) of the angle between the 3 atoms.</p>
<p>If flag = 2, only a is listed, where a = bondtype of the bond between
the 2 atoms in the cluster.</p>
<p>If flag = 3, a,b are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), and b = bondtype of the bond between the central atom
and the 2nd non-central atom (value c in the Shake Atoms section).</p>
<p>If flag = 4, a,b,c are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), b = bondtype of the bond between the central atom and
the 2nd non-central atom (value c in the Shake Atoms section), and c =
bondtype of the bond between the central atom and the 3rd non-central
atom (value d in the Shake Atoms section).</p>
<p>See the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> doc page for a further description
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>.
<p>The overall electrostatics energy is given in Hartree units of energy
by default and can be modified by an energy-conversion constant,
according to the units chosen (see <a class="reference internal" href="units.html"><span class="doc">electron_units</span></a>). The
cutoff Rc, given in Bohrs (by default), truncates the interaction
distance. The recommended cutoff for this pair style should follow
the minimum image criterion, i.e. half of the minimum unit cell
length.</p>
<p>Style <em>eff/long</em> (not yet available) computes the same interactions as
style <em>eff/cut</em> except that an additional damping factor is applied so
it can be used in conjunction with the
<a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style</span></a> command and its <em>ewald</em> or <em>pppm</em>
option. The Coulombic cutoff specified for this style means that
pairwise interactions within this distance are computed directly;
interactions outside that distance are computed in reciprocal space.</p>
<p>This potential is designed to be used with <a class="reference internal" href="atom_style.html"><span class="doc">atom_style electron</span></a> definitions, in order to handle the
description of systems with interacting nuclei and explicit electrons.</p>
<p>The following coefficients must be defined for each pair of atoms
types via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command as in the examples
above, or in the data file or restart files read by the
<p>For atom type pairs I,J and I != J, the cutoff distance for the
<em>eff/cut</em> style can be mixed. The default mix value is <em>geometric</em>.
See the “pair_modify” command for details.</p>
<p>The <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> shift option is not relevant for
these pair styles.</p>
<p>The <em>eff/long</em> (not yet available) style supports the
<a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> table option for tabulation of the
short-range portion of the long-range Coulombic interaction.</p>
<p>These pair styles do not support the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a>
tail option for adding long-range tail corrections to energy and
pressure.</p>
<p>These pair styles write their information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, so pair_style and pair_coeff commands do not need
to be specified in an input script that reads a restart file.</p>
<p>These pair styles can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command. They do not support the
<p>These pair styles will only be enabled if LAMMPS is built with the
USER-EFF package. It will only be enabled if LAMMPS was built with
that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a>
section for more info.</p>
<p>These pair styles require that particles store electron attributes
such as radius, radial velocity, and radital force, as defined by the
<a class="reference internal" href="atom_style.html"><span class="doc">atom_style</span></a>. The <em>electron</em> atom style does all of
this.</p>
<p>Thes pair styles require you to use the <a class="reference internal" href="comm_modify.html"><span class="doc">comm_modify vel yes</span></a> command so that velocites are stored by ghost
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>.
<p>If an assignment to <em>none</em> is made in a simulation with the
<em>hybrid/overlay</em> pair style, it wipes out all previous assignments of
that atom type pair to sub-styles.</p>
<p>Note that you may need to use an <a class="reference internal" href="atom_style.html"><span class="doc">atom_style</span></a> hybrid
command in your input script, if atoms in the simulation will need
attributes from several atom styles, due to using multiple pair
potentials.</p>
<hr class="docutils" />
<p>Different force fields (e.g. CHARMM vs AMBER) may have different rules
for applying weightings that change the strength of pairwise
interactions bewteen pairs of atoms that are also 1-2, 1-3, and 1-4
neighbors in the molecular bond topology, as normally set by the
<a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> command. Different weights can be
assigned to different pair hybrid sub-styles via the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify special</span></a> command. This allows multiple force fields
to be used in a model of a hybrid system, however, there is no consistent
approach to determine parameters automatically for the interactions
between the two force fields, this is only recommended when particles
described by the different force fields do not mix.</p>
<p>Here is an example for mixing CHARMM and AMBER: The global <em>amber</em>
setting sets the 1-4 interactions to non-zero scaling factors and
pair_modify pair lj/cut/coul/long special lj 0.0 0.0 0.5
pair_modify pair lj/cut/coul/long special coul 0.0 0.0 0.83333333
pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
</pre>
<p>Here is an example for mixing Tersoff with OPLS/AA based on
a data file that defines bonds for all atoms where for the
Tersoff part of the system the force constants for the bonded
interactions have been set to 0. Note the global settings are
effectively <em>lj/coul 0.0 0.0 0.5</em> as required for OPLS/AA:</p>
<pre class="literal-block">
special_bonds lj/coul 1e-20 1e-20 0.5
pair_hybrid tersoff lj/cut/coul/long 12.0
pair_modify pair tersoff special lj/coul 1.0 1.0 1.0
</pre>
<p>See the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> doc page for details on
the specific syntax, requirements and restrictions.</p>
<hr class="docutils" />
<p>The potential energy contribution to the overall system due to an
individual sub-style can be accessed and output via the <a class="reference internal" href="compute_pair.html"><span class="doc">compute pair</span></a> command.</p>
<hr class="docutils" />
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Several of the potentials defined via the pair_style command in
LAMMPS are really many-body potentials, such as Tersoff, AIREBO, MEAM,
ReaxFF, etc. The way to think about using these potentials in a
hybrid setting is as follows.</p>
</div>
<p>A subset of atom types is assigned to the many-body potential with a
single <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command, using “* *” to include
all types and the NULL keywords described above to exclude specific
types not assigned to that potential. If types 1,3,4 were assigned in
that way (but not type 2), this means that all many-body interactions
between all atoms of types 1,3,4 will be computed by that potential.
Pair_style hybrid allows interactions between type pairs 2-2, 1-2,
2-3, 2-4 to be specified for computation by other pair styles. You
could even add a second interaction for 1-1 to be computed by another
pair style, assuming pair_style hybrid/overlay is used.</p>
<p>But you should not, as a general rule, attempt to exclude the
many-body interactions for some subset of the type pairs within the
set of 1,3,4 interactions, e.g. exclude 1-1 or 1-3 interactions. That
is not conceptually well-defined for many-body interactions, since the
potential will typically calculate energies and foces for small groups
of atoms, e.g. 3 or 4 atoms, using the neighbor lists of the atoms to
find the additional atoms in the group. It is typically non-physical
to think of excluding an interaction between a particular pair of
atoms when the potential computes 3-body or 4-body interactions.</p>
<p>However, you can still use the pair_coeff none setting or the
<a class="reference internal" href="neigh_modify.html"><span class="doc">neigh_modify exclude</span></a> command to exclude certain
type pairs from the neighbor list that will be passed to a manybody
sub-style. This will alter the calculations made by a many-body
potential, since it builds its list of 3-body, 4-body, etc
interactions from the pair list. You will need to think carefully as
to whether it produces a physically meaningful result for your model.</p>
<p>For example, imagine you have two atom types in your model, type 1 for
atoms in one surface, and type 2 for atoms in the other, and you wish
to use a Tersoff potential to compute interactions within each
surface, but not between surfaces. Then either of these two command
sequences would implement that model:</p>
<pre class="literal-block">
pair_style hybrid tersoff
pair_coeff * * tersoff SiC.tersoff C C
pair_coeff 1 2 none
</pre>
<pre class="literal-block">
pair_style tersoff
pair_coeff * * SiC.tersoff C C
neigh_modify exclude type 1 2
</pre>
<p>Either way, only neighbor lists with 1-1 or 2-2 interactions would be
passed to the Tersoff potential, which means it would compute no
3-body interactions containing both type 1 and 2 atoms.</p>
<p>Here is another example, using hybrid/overlay, to use 2 many-body
potentials together, in an overlapping manner. Imagine you have CNT
(C atoms) on a Si surface. You want to use Tersoff for Si/Si and Si/C
interactions, and AIREBO for C/C interactions. Si atoms are type 1; C
atoms are type 2. Something like this will work:</p>
<pre class="literal-block">
pair_style hybrid/overlay tersoff airebo 3.0
pair_coeff * * tersoff SiC.tersoff.custom Si C
pair_coeff * * airebo CH.airebo NULL C
</pre>
<p>Note that to prevent the Tersoff potential from computing C/C
interactions, you would need to modify the SiC.tersoff file to turn
off C/C interaction, i.e. by setting the appropriate coefficients to
0.0.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual.</p>
<p>Since the <em>hybrid</em> and <em>hybrid/overlay</em> styles delegate computation to
the individual sub-styles, the suffix versions of the <em>hybrid</em> and
<em>hybrid/overlay</em> styles are used to propagate the corresponding suffix
to all sub-styles, if those versions exist. Otherwise the
non-accelerated version will be used.</p>
<p>The individual accelerated sub-styles are part of the GPU,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the
<a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
shift, table, and tail options for an I,J pair interaction, if the
associated sub-style supports it.</p>
<p>For the hybrid pair styles, the list of sub-styles and their
respective settings are written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, so a <a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> command does
not need to specified in an input script that reads a restart file.
However, the coefficient information is not stored in the restart
file. Thus, pair_coeff commands need to be re-specified in the
restart input script.</p>
<p>These pair styles support the use of the <em>inner</em>, <em>middle</em>, and
<em>outer</em> keywords of the <a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command, if
their sub-styles do.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>When using a long-range Coulombic solver (via the
<a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style</span></a> command) with a hybrid pair_style,
one or more sub-styles will be of the “long” variety,
e.g. <em>lj/cut/coul/long</em> or <em>buck/coul/long</em>. You must insure that the
short-range Coulombic cutoff used by each of these long pair styles is
the same or else LAMMPS will generate an error.</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>.
<p>This pair style does not support mixing since all parameters are
explicit for each pair.</p>
<p>The <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> shift option is supported by this
pair style.</p>
<p>The <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> table and tail options are not
relevant for this pair style.</p>
<p>This pair style does not write its information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, so pair_style and pair_coeff commands need
to be specified in an input script that reads a restart file.</p>
<p>This pair style can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command. It does not support the
<p>This pair style does not use a neighbor list and instead identifies
atoms by their IDs. This has two consequences: 1) The cutoff has to be
chosen sufficiently large, so that the second atom of a pair has to be
a ghost atom on the same node on which the first atom is local;
otherwise the interaction will be skipped. You can use the <em>check</em>
option to detect, if interactions are missing. 2) Unlike other pair
styles in LAMMPS, an atom I will not interact with multiple images of
atom J (assuming the images are within the cutoff distance), but only
with the nearest image.</p>
<p>This style is part of the USER-MISC package. It is only enabled if
LAMMPS is build with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making of LAMMPS</span></a> section for more info.</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>.
<p>For atom type pairs I,J and I != J, the epsilon and sigma coefficients
and cutoff distance for all of the lj/cut pair styles can be mixed.
The default mix value is <em>geometric</em>. See the “pair_modify” command
for details.</p>
<p>All of the <em>lj/cut</em> pair styles support the
<a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> shift option for the energy of the
Lennard-Jones portion of the pair interaction.</p>
<p>The <em>lj/cut/coul/long</em> and <em>lj/cut/tip4p/long</em> pair styles support the
<a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> table option since they can tabulate
the short-range portion of the long-range Coulombic interaction.</p>
<p>All of the <em>lj/cut</em> pair styles support the
<a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> tail option for adding a long-range
tail correction to the energy and pressure for the Lennard-Jones
portion of the pair interaction.</p>
<p>All of the <em>lj/cut</em> pair styles write their information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, so pair_style and pair_coeff commands do
not need to be specified in an input script that reads a restart file.</p>
<p>The <em>lj/cut</em> and <em>lj/cut/coul/long</em> pair styles support the use of the
<em>inner</em>, <em>middle</em>, and <em>outer</em> keywords of the <a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command, meaning the pairwise forces can be
partitioned by distance at different levels of the rRESPA hierarchy.
The other styles only support the <em>pair</em> keyword of run_style respa.
See the <a class="reference internal" href="run_style.html"><span class="doc">run_style</span></a> command for details.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>These pair styles can only be used if LAMMPS was built with the
USER-MISC package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a>
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>.
<p>The peridynamic pair styles implement material models that can be used
at the mescscopic and macroscopic scales. See <a class="reference external" href="PDF/PDLammps_overview.pdf">this document</a> for an overview of LAMMPS commands
for Peridynamics modeling.</p>
<p>Style <em>peri/pmb</em> implements the Peridynamic bond-based prototype
microelastic brittle (PMB) model.</p>
<p>Style <em>peri/lps</em> implements the Peridynamic state-based linear
peridynamic solid (LPS) model.</p>
<p>Style <em>peri/ves</em> implements the Peridynamic state-based linear
peridynamic viscoelastic solid (VES) model.</p>
<p>Style <em>peri/eps</em> implements the Peridynamic state-based elastic-plastic
solid (EPS) model.</p>
<p>The canonical papers on Peridynamics are <a class="reference internal" href="#silling2000"><span class="std std-ref">(Silling 2000)</span></a>
and <a class="reference internal" href="#silling2007"><span class="std std-ref">(Silling 2007)</span></a>. The implementation of Peridynamics
in LAMMPS is described in <a class="reference internal" href="#parks"><span class="std std-ref">(Parks)</span></a>. Also see the <a class="reference external" href="http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf">PDLAMMPS user guide</a> for
more details about its implementation.</p>
<p>The peridynamic VES and EPS models in PDLAMMPS were implemented by
R. Rahman and J. T. Foster at University of Texas at San Antonio. The
original VES formulation is described in “(Mitchell2011)” and the
original EPS formulation is in “(Mitchell2011a)”. Additional PDF docs
that describe the VES and EPS implementations are include in the
LAMMPS distro in <a class="reference external" href="PDF/PDLammps_VES.pdf">doc/PDF/PDLammps_VES.pdf</a> and
<a class="reference external" href="PDF/PDLammps_EPS.pdf">doc/PDF/PDLammps_EPS.pdf</a>. For questions
regarding the VES and EPS models in LAMMPS you can contact R. Rahman
(rezwanur.rahman at utsa.edu).</p>
<p>The following coefficients must be defined for each pair of atom types
via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command as in the examples above,
<p>C is the effectively a spring constant for Peridynamic bonds, the
horizon is a cutoff distance for truncating interactions, and s00 and
alpha are used as a bond breaking criteria. The units of c are such
that c/distance = stiffness/volume^2, where stiffness is
energy/distance^2 and volume is distance^3. See the users guide for
more details.</p>
<p>For the <em>peri/lps</em> style:</p>
<ul class="simple">
<li>K (force/area units)</li>
<li>G (force/area units)</li>
<li>horizon (distance units)</li>
<li>s00 (unitless)</li>
<li>alpha (unitless)</li>
</ul>
<p>K is the bulk modulus and G is the shear modulus. The horizon is a
cutoff distance for truncating interactions, and s00 and alpha are
used as a bond breaking criteria. See the users guide for more
details.</p>
<p>For the <em>peri/ves</em> style:</p>
<ul class="simple">
<li>K (force/area units)</li>
<li>G (force/area units)</li>
<li>horizon (distance units)</li>
<li>s00 (unitless)</li>
<li>alpha (unitless)</li>
<li>m_lambdai (unitless)</li>
<li>m_taubi (unitless)</li>
</ul>
<p>K is the bulk modulus and G is the shear modulus. The horizon is a
cutoff distance for truncating interactions, and s00 and alpha are
used as a bond breaking criteria. m_lambdai and m_taubi are the
viscoelastic relaxation parameter and time constant,
respectively. m_lambdai varies within zero to one. For very small
values of m_lambdai the viscoelsatic model responds very similar to a
linear elastic model. For details please see the description in
“(Mtchell2011)”.</p>
<p>For the <em>peri/eps</em> style:</p>
<p>K (force/area units)
G (force/area units)
horizon (distance units)
s00 (unitless)
alpha (unitless)
m_yield_stress (force/area units)</p>
<p>K is the bulk modulus and G is the shear modulus. The horizon is a
cutoff distance and s00 and alpha are used as a bond breaking
criteria. m_yield_stress is the yield stress of the material. For
details please see the description in “(Mtchell2011a)”.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p>These pair styles do not support mixing. Thus, coefficients for all
I,J pairs must be specified explicitly.</p>
<p>These pair styles do not support the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a>
shift option.</p>
<p>The <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> table and tail options are not
relevant for these pair styles.</p>
<p>These pair styles write their information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, so pair_style and pair_coeff commands do not need
to be specified in an input script that reads a restart file.</p>
<p>These pair styles can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command. They do not support the
<p>All of these styles are part of the PERI package. They are only
enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</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>.
<li><p class="first">cfile = NULL or name of a control file</p>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
<pre class="literal-block">
keyword = <em>checkqeq</em> or <em>lgvdw</em> or <em>safezone</em> or <em>mincap</em>
<em>checkqeq</em> value = <em>yes</em> or <em>no</em> = whether or not to require qeq/reax fix
<em>lgvdw</em> value = <em>yes</em> or <em>no</em> = whether or not to use a low gradient vdW correction
<em>safezone</em> = factor used for array allocation
<em>mincap</em> = minimum size for array allocation
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
pair_style reax/c NULL
pair_style reax/c controlfile checkqeq no
pair_style reax/c NULL lgvdw yes
pair_style reax/c NULL safezone 1.6 mincap 100
pair_coeff * * ffield.reax C H O N
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Style <em>reax/c</em> computes the ReaxFF potential of van Duin, Goddard and
co-workers. ReaxFF uses distance-dependent bond-order functions to
represent the contributions of chemical bonding to the potential
energy. There is more than one version of ReaxFF. The version
implemented in LAMMPS uses the functional forms documented in the
supplemental information of the following paper: <a class="reference internal" href="#chenoweth-2008"><span class="std std-ref">(Chenoweth et al., 2008)</span></a>. The version integrated into LAMMPS matches
the most up-to-date version of ReaxFF as of summer 2010. For more
technical details about the pair reax/c implementation of ReaxFF, see
the <a class="reference internal" href="#aktulga"><span class="std std-ref">(Aktulga)</span></a> paper.</p>
<p>The <em>reax/c/kk</em> style is a Kokkos version of the ReaxFF potential that is
derived from the <em>reax/c</em> style. The Kokkos version can run on GPUs and
can also use OpenMP multithreading. For more information about the Kokkos package,
see <a class="reference internal" href="Section_packages.html#kokkos"><span class="std std-ref">Section 4</span></a> and <a class="reference internal" href="accelerate_kokkos.html"><span class="doc">Section 5.3.3</span></a>.
One important consideration when using the <em>reax/c/kk</em> style is the choice of either
half or full neighbor lists. This setting can be changed using the Kokkos <a class="reference internal" href="package.html"><span class="doc">package</span></a>
command.</p>
<p>The <em>reax/c</em> style differs from the <a class="reference internal" href="pair_reax.html"><span class="doc">pair_style reax</span></a>
command in the lo-level implementation details. The <em>reax</em> style is a
Fortran library, linked to LAMMPS. The <em>reax/c</em> style was initially
implemented as stand-alone C code and is now integrated into LAMMPS as
a package.</p>
<p>LAMMPS provides several different versions of ffield.reax in its
potentials dir, each called potentials/ffield.reax.label. These are
documented in potentials/README.reax. The default ffield.reax
contains parameterizations for the following elements: C, H, O, N.</p>
<p>The format of these files is identical to that used originally by van
Duin. We have tested the accuracy of <em>pair_style reax/c</em> potential
against the original ReaxFF code for the systems mentioned above. You
can use other ffield files for specific chemical systems that may be
available elsewhere (but note that their accuracy may not have been
tested).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">We do not distribute a wide variety of ReaxFF force field files
with LAMMPS. Adri van Duin’s group at PSU is the central repository
for this kind of data as they are continuously deriving and updating
parameterizations for different classes of materials. You can submit
a contact request at the Materials Computation Center (MCC) website
<p>Use of this pair style requires that a charge be defined for every
atom. See the <a class="reference internal" href="atom_style.html"><span class="doc">atom_style</span></a> and
<a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> commands for details on how to specify
charges.</p>
<p>The ReaxFF parameter files provided were created using a charge
equilibration (QEq) model for handling the electrostatic interactions.
Therefore, by default, LAMMPS requires that the <a class="reference internal" href="fix_qeq_reax.html"><span class="doc">fix qeq/reax</span></a> command be used with <em>pair_style reax/c</em>
when simulating a ReaxFF model, to equilibrate charge each timestep.
Using the keyword <em>checkqeq</em> with the value <em>no</em>
turns off the check for <em>fix qeq/reax</em>,
allowing a simulation to be run without charge equilibration.
In this case, the static charges you
assign to each atom will be used for computing the electrostatic
interactions in the system.
See the <a class="reference internal" href="fix_qeq_reax.html"><span class="doc">fix qeq/reax</span></a> command for details.</p>
<p>Using the optional keyword <em>lgvdw</em> with the value <em>yes</em> turns on
the low-gradient correction of the ReaxFF/C for long-range
London Dispersion, as described in the <a class="reference internal" href="#liu-2011"><span class="std std-ref">(Liu)</span></a> paper. Force field
file <em>ffield.reax.lg</em> is designed for this correction, and is trained
for several energetic materials (see “Liu”). When using lg-correction,
recommended value for parameter <em>thb</em> is 0.01, which can be set in the
control file. Note: Force field files are different for the original
or lg corrected pair styles, using wrong ffield file generates an error message.</p>
<p>Optional keywords <em>safezone</em> and <em>mincap</em> are used for allocating
reax/c arrays. Increasing these values can avoid memory problems, such
as segmentation faults and bondchk failed errors, that could occur under
certain conditions. These keywords aren’t used by the Kokkos version, which
instead uses a more robust memory allocation scheme that checks if the sizes of
the arrays have been exceeded and automatically allocates more memory.</p>
<p>The thermo variable <em>evdwl</em> stores the sum of all the ReaxFF potential
energy contributions, with the exception of the Coulombic and charge
equilibration contributions which are stored in the thermo variable
<em>ecoul</em>. The output of these quantities is controlled by the
<p>This pair style tallies a breakdown of the total ReaxFF potential
energy into sub-categories, which can be accessed via the <a class="reference internal" href="compute_pair.html"><span class="doc">compute pair</span></a> command as a vector of values of length 14.
The 14 values correspond to the following sub-categories (the variable
names in italics match those used in the original FORTRAN ReaxFF code):</p>
<ol class="arabic simple">
<li><em>eb</em> = bond energy</li>
<li><em>ea</em> = atom energy</li>
<li><em>elp</em> = lone-pair energy</li>
<li><em>emol</em> = molecule energy (always 0.0)</li>
<p>This pair style does not support the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a>
mix, shift, table, and tail options.</p>
<p>This pair style does not write its information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, since it is stored in potential files. Thus, you
need to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.</p>
<p>This pair style can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command. It does not support the
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This pair style is part of the USER-REAXC package. It is only enabled
if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>The ReaxFF potential files provided with LAMMPS in the potentials
directory are parameterized for real <a class="reference internal" href="units.html"><span class="doc">units</span></a>. You can use
the ReaxFF potential with any LAMMPS units, but you would need to
create your own potential file with coefficients listed in the
appropriate units if your simulation doesn’t use “real” units.</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>.
<p>where <em>E<sub>tot</sub></em> is the total potential energy of the system,
<em>E<sub>ES</sub></em> is the electrostatic part of the total energy,
<em>E<sub>OO</sub></em> is the interaction between oxygens and
<em>E<sub>MO</sub></em> is a short-range interaction between metal and oxygen
atoms. This interactions depend on interatomic distance
<em>r<sub>ij</sub></em> and/or the charge <em>Q<sub>i</sub></em> of atoms
<em>i</em>. Cut-off function enables smooth convergence to zero interaction.</p>
<p>The parameters appearing in the upper expressions are set in the
ffield.SMTBQ.Syst file where Syst corresponds to the selected system
(e.g. field.SMTBQ.Al2O3). Exemples for TiO<sub>2</sub>,
Al<sub>2</sub>O<sub>3</sub> are provided. A single pair_coeff command
is used with the SMTBQ styles which provides the path to the potential
file with parameters for needed elements. These are mapped to LAMMPS
atom types by specifying additional arguments after the potential
filename in the pair_coeff command. Note that atom type 1 must always
correspond to oxygen atoms. As an example, to simulate a TiO2 system,
atom type 1 has to be oxygen and atom type 2 Ti. The following
pair_coeff command should then be used:</p>
<pre class="literal-block">
pair_coeff * * PathToLammps/potentials/ffield.smtbq.TiO2 O Ti
</pre>
<p>The electrostatic part of the energy consists of two components</p>
<p>self-energy of atom <em>i</em> in the form of a second order charge dependent
polynomial and a long-range Coulombic electrostatic interaction. The
latter uses the wolf summation method described in <a class="reference internal" href="#wolf"><span class="std std-ref">Wolf</span></a>,
spherically truncated at a longer cutoff, <em>R<sub>coul</sub></em>. The
charge of each ion is modeled by an orbital Slater which depends on
the principal quantum number (<em>n</em>) of the outer orbital shared by the
ion.</p>
<p>Interaction between oxygen, <em>E<sub>OO</sub></em>, consists of two parts,
an attractive and a repulsive part. The attractive part is effective
only at short range (< r<sub>2</sub><sup>OO</sup>). The attractive
contribution was optimized to study surfaces reconstruction
(e.g. <a class="reference internal" href="#smtb-q-2"><span class="std std-ref">SMTB-Q_2</span></a> in TiO<sub>2</sub>) and is not necessary
for oxide bulk modeling. The repulsive part is the Pauli interaction
between the electron clouds of oxygen. The Pauli repulsion and the
coulombic electrostatic interaction have same cut off value. In the
ffield.SMTBQ.Syst, the keyword <em>‘buck’</em> allows to consider only the
repulsive O-O interactions. The keyword <em>‘buckPlusAttr’</em> allows to
consider the repulsive and the attractive O-O interactions.</p>
<p>The short-range interaction between metal-oxygen, <em>E<sub>MO</sub></em> is
based on the second moment approximation of the density of states with
a N-body potential for the band energy term,
<em>E<sup>i</sup><sub>cov</sub></em>, and a Born-Mayer type repulsive terms
as indicated by the keyword <em>‘second_moment’</em> in the
ffield.SMTBQ.Syst. The energy band term is given by:</p>
<p>Thus parameter &#956, indicated above, is given by : &#956 = (&#8730n
+ &#8730m) &#8260 2</p>
<p>The potential offers the possibility to consider the polarizability of
the electron clouds of oxygen by changing the slater radius of the
charge density around the oxygens through the parameters <em>rBB, rB and
rS</em> in the ffield.SMTBQ.Syst. This change in radius is performed
according to the method developed by E. Maras
<a class="reference internal" href="#smtb-q-2"><span class="std std-ref">SMTB-Q_2</span></a>. This method needs to determine the number of
nearest neighbors around the oxygen. This calculation is based on
first (<em>r<sub>1n</sub></em>) and second (<em>r<sub>2n</sub></em>) distances
neighbors.</p>
<p>The SMTB-Q potential is a variable charge potential. The equilibrium
charge on each atom is calculated by the electronegativity
equalization (QEq) method. See <a class="reference internal" href="#rick"><span class="std std-ref">Rick</span></a> for further detail. One
can adjust the frequency, the maximum number of iterative loop and the
convergence of the equilibrium charge calculation. To obtain the
energy conservation in NVE thermodynamic ensemble, we recommend to use
a convergence parameter in the interval 10<sup>-5</sup> -
10<sup>-6</sup> eV.</p>
<p>The ffield.SMTBQ.Syst files are provided for few systems. They consist
of nine parts and the lines beginning with ‘#’ are comments (note that
the number of comment lines matter). The first sections are on the
potential parameters and others are on the simulation options and
might be modified. Keywords are character type and must be enclosed in
quotation marks (‘’).</p>
<ol class="arabic simple">
<li>Number of different element in the oxide:</li>
</ol>
<ul class="simple">
<li>N<sub>elem</sub>= 2 or 3</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="2">
<li>Atomic parameters</li>
</ol>
<p>For the anion (oxygen)</p>
<ul class="simple">
<li>Name of element (char) and stoichiometry in oxide</li>
<li>Formal charge and mass of element</li>
<li>Principal quantic number of outer orbital (<em>n</em>), electronegativity (<em>&#967<sup>0</sup><sub>i</simulationub></em>) and hardness (<em>J<sup>0</sup><sub>i</sub></em>)</li>
<li>Ionic radius parameters : max coordination number (<em>coordBB</em> = 6 by default), bulk coordination number <em>(coordB)</em>, surface coordination number <em>(coordS)</em> and <em>rBB, rB and rS</em> the slater radius for each coordination number. (<b>note : If you don’t want to change the slater radius, use three identical radius values</b>)</li>
<li>Number of orbital shared by the element in the oxide (<em>d<sub>i</sub></em>)</li>
<li>Divided line</li>
</ul>
<p>For each cations (metal):</p>
<ul class="simple">
<li>Name of element (char) and stoichiometry in oxide</li>
<li>Formal charge and mass of element</li>
<li>Number of electron in outer orbital <em>(ne)</em>, electronegativity (<em>&#967<sup>0</sup><sub>i</simulationub></em>), hardness (<em>J<sup>0</sup><sub>i</sub></em>) and <em>r<sub>Salter</sub></em> the slater radius for the cation.</li>
<li>Number of orbitals shared by the elements in the oxide (<em>d<sub>i</sub></em>)</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="3">
<li>Potential parameters:</li>
</ol>
<ul class="simple">
<li>Keyword for element1, element2 and interaction potential (‘second_moment’ or ‘buck’ or ‘buckPlusAttr’) between element 1 and 2. If the potential is ‘second_moment’, specify ‘oxide’ or ‘metal’ for metal-oxygen or metal-metal interactions respectively.</li>
<li>Potential parameter: <pre><br/> If type of potential is ‘second_moment’ : <em>A (eV)</em>, <em>p</em>, <em>&#958<sup>0</sup></em> (eV) and <em>q</em> <br/> <em>r<sub>c1</sub></em> (&#197), <em>r<sub>c2</sub></em> (&#197) and <em>r<sub>0</sub></em> (&#197) <br/> If type of potential is ‘buck’ : <em>C</em> (eV) and <em>&#961</em> (&#197) <br/> If type of potential is ‘buckPlusAttr’ : <em>C</em> (eV) and <em>&#961</em> (&#197) <br/> <em>D</em> (eV), <em>B</em> (&#197<sup>-1</sup>), <em>r<sub>1</sub><sup>OO</sup></em> (&#197) and <em>r<sub>2</sub><sup>OO</sup></em> (&#197) </pre></li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="4">
<li>Tables parameters:</li>
</ol>
<ul class="simple">
<li>Cutoff radius for the Coulomb interaction (<em>R<sub>coul</sub></em>)</li>
<li>Starting radius (<em>r<sub>min</sub></em> = 1,18845 &#197) and increments (<em>dr</em> = 0,001 &#197) for creating the potential table.</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="5">
<li>Rick model parameter:</li>
</ol>
<ul class="simple">
<li><em>Nevery</em> : parameter to set the frequency (<em>1/Nevery</em>) of the charge resolution. The charges are evaluated each <em>Nevery</em> time steps.</li>
<li>Max number of iterative loop (<em>loopmax</em>) and precision criterion (<em>prec</em>) in eV of the charge resolution</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="6">
<li>Coordination parameter:</li>
</ol>
<ul class="simple">
<li>First (<em>r<sub>1n</sub></em>) and second (<em>r<sub>2n</sub></em>) neighbor distances in &#197</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="7">
<li>Charge initialization mode:</li>
</ol>
<ul class="simple">
<li>Keyword (<em>QInitMode</em>) and initial oxygen charge (<em>Q<sub>init</sub></em>). If keyword = ‘true’, all oxygen charges are initially set equal to <em>Q<sub>init</sub></em>. The charges on the cations are initially set in order to respect the neutrality of the box. If keyword = ‘false’, all atom charges are initially set equal to 0 if you use “create_atom”#create_atom command or the charge specified in the file structure using <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> command.</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="8">
<li>Mode for the electronegativity equalization (Qeq)</li>
</ol>
<ul class="simple">
-<li>Keyword mode: <pre> <br/> QEqAll (one QEq group) | no parameters <br/> QEqAllParallel (several QEq groups) | no parameters <br/> Surface | zlim (QEq only for z>zlim) </pre></li>
+<li>Keyword mode: <pre> <br/> QEqAll (one QEq group) | no parameters <br/> QEqAllParallel (several QEq groups) | no parameters <br/> Surface | zlim (QEq only for z>zlim) </pre></li>
<li>Parameter if necessary</li>
<li>Divided line</li>
</ul>
<ol class="arabic simple" start="9">
<li>Verbose</li>
</ol>
<ul class="simple">
<li>If you want the code to work in verbose mode or not : ‘true’ or ‘false’</li>
<li>If you want to print or not in file ‘Energy_component.txt’ the three main contributions to the energy of the system according to the description presented above : ‘true’ or ‘false’ and <em>N<sub>Energy</sub></em>. This option writes in file every <em>N<sub>Energy</sub></em> time step. If the value is ‘false’ then <em>N<sub>Energy</sub></em> = 0. The file take into account the possibility to have several QEq group <em>g</em> then it writes: time step, number of atoms in group <em>g</em>, electrostatic part of energy, <em>E<sub>ES</sub></em>, the interaction between oxygen, <em>E<sub>OO</sub></em>, and short range metal-oxygen interaction, <em>E<sub>MO</sub></em>.</li>
<li>If you want to print in file ‘Electroneg_component.txt’ the electronegativity component (<em>&#8706E<sub>tot</sub> &#8260&#8706Q<sub>i</sub></em>) or not: ‘true’ or ‘false’ and <em>N<sub>Electroneg</sub></em>.This option writes in file every <em>N<sub>Electroneg</sub></em> time step. If the value is ‘false’ then <em>N<sub>Electroneg</sub></em> = 0. The file consist in atom number <em>i</em>, atom type (1 for oxygen and # higher than 1 for metal), atom position: <em>x</em>, <em>y</em> and <em>z</em>, atomic charge of atom <em>i</em>, electrostatic part of atom <em>i</em> electronegativity, covalent part of atom <em>i</em> electronegativity, the hopping integral of atom <em>i</em> <em>(Z&#946<sup>2</sup>)<sub>i<sub></em> and box electronegativity.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This last option slows down the calculation dramatically. Use
<p>This pair style does not support the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a>
mix, shift, table, and tail options.</p>
<p>This pair style does not write its information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>, since it is stored in potential files. Thus, you
needs to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.</p>
<p>This pair style can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command. It does not support the
<p>This pair style is part of the USER-SMTBQ package and is only enabled
if LAMMPS is built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This potential requires using atom type 1 for oxygen and atom type
higher than 1 for metal atoms.</p>
<p>This pair style requires the <a class="reference internal" href="newton.html"><span class="doc">newton</span></a> setting to be “on”
for pair interactions.</p>
<p>The SMTB-Q potential files provided with LAMMPS (see the potentials
directory) are parameterized for metal <a class="reference internal" href="units.html"><span class="doc">units</span></a>.</p>
<hr class="docutils" />
<p><strong>Citing this work:</strong></p>
<p>Please cite related publication: N. Salles, O. Politano, E. Amzallag
and R. Tetot, Comput. Mater. Sci. 111 (2016) 181-189</p>
<hr class="docutils" />
<p id="smtb-q-1"><strong>(SMTB-Q_1)</strong> N. Salles, O. Politano, E. Amzallag, R. Tetot,
Comput. Mater. Sci. 111 (2016) 181-189</p>
<p id="smtb-q-2"><strong>(SMTB-Q_2)</strong> E. Maras, N. Salles, R. Tetot, T. Ala-Nissila,
H. Jonsson, J. Phys. Chem. C 2015, 119, 10391-10399</p>
<p id="smtb-q-3"><strong>(SMTB-Q_3)</strong> R. Tetot, N. Salles, S. Landron, E. Amzallag, Surface
Science 616, 19-8722 28 (2013)</p>
<p id="wolf"><strong>(Wolf)</strong> D. Wolf, P. Keblinski, S. R. Phillpot, J. Eggebrecht, J Chem
Phys, 110, 8254 (1999).</p>
<p id="rick"><strong>(Rick)</strong> S. W. Rick, S. J. Stuart, B. J. Berne, J Chem Phys 101, 6141
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>.
<p>where <em>L</em> is the normalized distance from the atom to the point of
closest approach of bond <em>i</em> and <em>j</em>. The <em>mid</em> option takes <em>L</em> as
0.5 for each interaction as described in <a class="reference internal" href="#sirk"><span class="std std-ref">(Sirk)</span></a>.</p>
<p>The following coefficients must be defined via the
<a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command as in the examples above, or in
the data file or restart file read by the <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a>
or <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> commands:</p>
<ul class="simple">
<li><em>C</em> (force units)</li>
<li><em>rc</em> (distance units)</li>
</ul>
<p>The last coefficient is optional. If not specified, the global cutoff
is used.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Pair style srp considers each bond of type <em>btype</em> to be a
fictitious “particle” of type <em>bptype</em>, where <em>bptype</em> is either the
largest atom type in the system, or the type set by the <em>bptype</em> flag.
Any actual existing particles with this atom type will be deleted at
the beginning of a run. This means you must specify the number of
types in your system accordingly; usually to be one larger than what
would normally be the case, e.g. via the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a>
or by changing the header in your <a class="reference internal" href="read_data.html"><span class="doc">data file</span></a>. The
ficitious “bond particles” are inserted at the beginning of the run,
and serve as placeholders that define the position of the bonds. This
allows neighbor lists to be constructed and pairwise interactions to
be computed in almost the same way as is done for actual particles.
Because bonds interact only with other bonds, <a class="reference internal" href="pair_hybrid.html"><span class="doc">pair_style hybrid</span></a> should be used to turn off interactions
between atom type <em>bptype</em> and all other types of atoms. An error
will be flagged if <a class="reference internal" href="pair_hybrid.html"><span class="doc">pair_style hybrid</span></a> is not used.</p>
</div>
<p>The optional <em>exclude</em> keyword determines if forces are computed
between first neighbor (directly connected) bonds. For a setting of
<em>no</em>, first neighbor forces are computed; for <em>yes</em> they are not
computed. A setting of <em>no</em> cannot be used with the <em>min</em> option for
distance calculation because the the minimum distance between directly
connected bonds is zero.</p>
<p>Pair style <em>srp</em> turns off normalization of thermodynamic properties
by particle number, as if the command <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify norm no</span></a> had been issued.</p>
<p>The pairwise energy associated with style <em>srp</em> is shifted to be zero
<p>This pair style does not support the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a>
shift option for the energy of the pair interaction. Note that as
discussed above, the energy term is already shifted to be 0.0 at the
cutoff distance <em>rc</em>.</p>
<p>The <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a> table option is not relevant for
this pair style.</p>
<p>This pair style does not support the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify</span></a>
tail option for adding long-range tail corrections to energy and
pressure.</p>
<p>This pair style writes global and per-atom information to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. Pair srp should be used with <a class="reference internal" href="pair_hybrid.html"><span class="doc">pair_style hybrid</span></a>, thus the pair_coeff commands need to be
specified in the input script when reading a restart file.</p>
<p>This pair style can only be used via the <em>pair</em> keyword of the
<a class="reference internal" href="run_style.html"><span class="doc">run_style respa</span></a> command. It does not support the
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>.
<li>style = <em>lookup</em> or <em>linear</em> or <em>spline</em> or <em>bitmap</em> = method of interpolation</li>
<li>N = use N values in <em>lookup</em>, <em>linear</em>, <em>spline</em> tables</li>
<li>N = use 2^N values in <em>bitmap</em> tables</li>
<li>zero or more keywords may be appended</li>
<li>keyword = <em>ewald</em> or <em>pppm</em> or <em>msm</em> or <em>dispersion</em> or <em>tip4p</em></li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
pair_style table linear 1000
pair_style table linear 1000 pppm
pair_style table bitmap 12
pair_coeff * 3 morse.table ENTRY1
pair_coeff * 3 morse.table ENTRY1 7.0
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Style <em>table</em> creates interpolation tables from potential energy and
force values listed in a file(s) as a function of distance. When
performing dynamics or minimation, the interpolation tables are used
to evaluate energy and forces for pairwise interactions between
particles, similar to how analytic formulas are used for other pair
styles.</p>
<p>The interpolation tables are created as a pre-computation by fitting
cubic splines to the file values and interpolating energy and force
values at each of <em>N</em> distances. During a simulation, the tables are
used to interpolate energy and force values as needed for each pair of
particles separated by a distance <em>R</em>. The interpolation is done in
one of 4 styles: <em>lookup</em>, <em>linear</em>, <em>spline</em>, or <em>bitmap</em>.</p>
<p>For the <em>lookup</em> style, the distance <em>R</em> is used to find the nearest
table entry, which is the energy or force.</p>
<p>For the <em>linear</em> style, the distance <em>R</em> is used to find the 2
surrounding table values from which an energy or force is computed by
linear interpolation.</p>
<p>For the <em>spline</em> style, a cubic spline coefficients are computed and
stored for each of the <em>N</em> values in the table, one set of splines for
energy, another for force. Note that these splines are different than
the ones used to pre-compute the <em>N</em> values. Those splines were fit
to the <em>Nfile</em> values in the tabulated file, where often <em>Nfile</em> <
<em>N</em>. The distance <em>R</em> is used to find the appropriate set of spline
coefficients which are used to evaluate a cubic polynomial which
computes the energy or force.</p>
<p>For the <em>bitmap</em> style, the specified <em>N</em> is used to create
interpolation tables that are 2^N in length. The distance <em>R</em> is used
to index into the table via a fast bit-mapping technique due to
-<a class="reference internal" href="pair_table_rx.html#wolff"><span class="std std-ref">(Wolff)</span></a>, and a linear interpolation is performed between
+<a class="reference internal" href="#wolff"><span class="std std-ref">(Wolff)</span></a>, and a linear interpolation is performed between
adjacent table values.</p>
<p>The following coefficients must be defined for each pair of atoms
types via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command as in the examples
above.</p>
<ul class="simple">
<li>filename</li>
<li>keyword</li>
<li>cutoff (distance units)</li>
</ul>
<p>The filename specifies a file containing tabulated energy and force
values. The keyword specifies a section of the file. The cutoff is
an optional coefficient. If not specified, the outer cutoff in the
table itself (see below) will be used to build an interpolation table
that extend to the largest tabulated distance. If specified, only
file values up to the cutoff are used to create the interpolation
table. The format of this file is described below.</p>
<p>If your tabulated potential(s) are designed to be used as the
short-range part of one of the long-range solvers specified by the
<a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style</span></a> command, then you must use one or
more of the optional keywords listed above for the pair_style command.
These are <em>ewald</em> or <em>pppm</em> or <em>msm</em> or <em>dispersion</em> or <em>tip4p</em>. This
is so LAMMPS can insure the short-range potential and long-range
solver are compatible with each other, as it does for other
short-range pair styles, such as <a class="reference internal" href="pair_lj.html"><span class="doc">pair_style lj/cut/coul/long</span></a>. Note that it is up to you to insure
the tabulated values for each pair of atom types has the correct
functional form to be compatible with the matching long-range solver.</p>
<hr class="docutils" />
<p>Here are some guidelines for using the pair_style table command to
best effect:</p>
<ul class="simple">
<li>Vary the number of table points; you may need to use more than you think
to get good resolution.</li>
<li>Always use the <a class="reference internal" href="pair_write.html"><span class="doc">pair_write</span></a> command to produce a plot
of what the final interpolated potential looks like. This can show up
interpolation “features” you may not like.</li>
<li>Start with the linear style; it’s the style least likely to have problems.</li>
<li>Use <em>N</em> in the pair_style command equal to the “N” in the tabulation
file, and use the “RSQ” or “BITMAP” parameter, so additional interpolation
is not needed. See discussion below.</li>
<li>Make sure that your tabulated forces and tabulated energies are
consistent (dE/dr = -F) over the entire range of r values. LAMMPS
will warn if this is not the case.</li>
<li>Use as large an inner cutoff as possible. This avoids fitting splines
to very steep parts of the potential.</li>
</ul>
<hr class="docutils" />
<p>The format of a tabulated file is a series of one or more sections,
defined as follows (without the parenthesized comments):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Morse potential for Fe (one or more comment or blank lines)</span>
</pre></div>
</div>
<pre class="literal-block">
MORSE_FE (keyword is first text on line)
N 500 R 1.0 10.0 (N, R, RSQ, BITMAP, FPRIME parameters)
(blank)
1 1.0 25.5 102.34 (index, r, energy, force)
2 1.02 23.4 98.5
...
500 10.0 0.001 0.003
</pre>
<p>A section begins with a non-blank line whose 1st character is not a
“#”; blank lines or lines starting with “#” can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The line can contain additional text, but the
initial text must match the argument specified in the pair_coeff
command. The next line lists (in any order) one or more parameters
for the table. Each parameter is a keyword followed by one or more
numeric values.</p>
<p>The parameter “N” is required and its value is the number of table
entries that follow. Note that this may be different than the <em>N</em>
specified in the <a class="reference internal" href="pair_style.html"><span class="doc">pair_style table</span></a> command. Let
Ntable = <em>N</em> in the pair_style command, and Nfile = “N” in the
tabulated file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate energy and force values at Ntable different
points. The resulting tables of length Ntable are then used as
described above, when computing energy and force for individual pair
distances. This means that if you want the interpolation tables of
length Ntable to match exactly what is in the tabulated file (with
effectively no preliminary interpolation), you should set Ntable =
Nfile, and use the “RSQ” or “BITMAP” parameter. This is because the
internal table abscissa is always RSQ (separation distance squared),
for efficient lookup.</p>
<p>All other parameters are optional. If “R” or “RSQ” or “BITMAP” does
not appear, then the distances in each line of the table are used
as-is to perform spline interpolation. In this case, the table values
can be spaced in <em>r</em> uniformly or however you wish to position table
values in regions of large gradients.</p>
<p>If used, the parameters “R” or “RSQ” are followed by 2 values <em>rlo</em>
and <em>rhi</em>. If specified, the distance associated with each energy and
force value is computed from these 2 values (at high accuracy), rather
than using the (low-accuracy) value listed in each line of the table.
The distance values in the table file are ignored in this case.
For “R”, distances uniformly spaced between <em>rlo</em> and <em>rhi</em> are
computed; for “RSQ”, squared distances uniformly spaced between
<em>rlo*rlo</em> and <em>rhi*rhi</em> are computed.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you use “R” or “RSQ”, the tabulated distance values in the
file are effectively ignored, and replaced by new values as described
in the previous paragraph. If the distance value in the table is not
very close to the new value (i.e. round-off difference), then you will
be assingning energy/force values to a different distance, which is
probably not what you want. LAMMPS will warn if this is occurring.</p>
</div>
<p>If used, the parameter “BITMAP” is also followed by 2 values <em>rlo</em> and
<em>rhi</em>. These values, along with the “N” value determine the ordering
of the N lines that follow and what distance is associated with each.
This ordering is complex, so it is not documented here, since this
file is typically produced by the <a class="reference internal" href="pair_write.html"><span class="doc">pair_write</span></a> command
with its <em>bitmap</em> option. When the table is in BITMAP format, the “N”
parameter in the file must be equal to 2^M where M is the value
specified in the pair_style command. Also, a cutoff parameter cannot
be used as an optional 3rd argument in the pair_coeff command; the
entire table extent as specified in the file must be used.</p>
<p>If used, the parameter “FPRIME” is followed by 2 values <em>fplo</em> and
<em>fphi</em> which are the derivative of the force at the innermost and
outermost distances listed in the table. These values are needed by
the spline construction routines. If not specified by the “FPRIME”
parameter, they are estimated (less accurately) by the first 2 and
last 2 force values in the table. This parameter is not used by
BITMAP tables.</p>
<p>Following a blank line, the next N lines list the tabulated values.
On each line, the 1st value is the index from 1 to N, the 2nd value is
r (in distance units), the 3rd value is the energy (in energy units),
and the 4th is the force (in force units). The r values must increase
from one line to the next (unless the BITMAP parameter is specified).</p>
<p>Note that one file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified keyword.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</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>.
<li>style = <em>thole</em> or <em>lj/cut/thole/long</em> or <em>lj/cut/thole/long/omp</em></li>
<li>args = list of arguments for a particular style</li>
</ul>
<pre class="literal-block">
<em>thole</em> args = damp cutoff
damp = global damping parameter
cutoff = global cutoff (distance units)
<em>lj/cut/thole/long</em> or <em>lj/cut/thole/long/omp</em> args = damp cutoff (cutoff2)
damp = global damping parameter
cutoff = global cutoff for LJ (and Thole if only 1 arg) (distance units)
cutoff2 = global cutoff for Thole (optional) (distance units)
</pre>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
pair_style hybrid/overlay ... thole 2.6 12.0
pair_coeff 1 1 thole 1.0
pair_coeff 1 2 thole 1.0 2.6 10.0
pair_coeff * 2 thole 1.0 2.6
</pre>
<pre class="literal-block">
pair_style lj/cut/thole/long 2.6 12.0
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>The <em>thole</em> pair styles are meant to be used with force fields that
include explicit polarization through Drude dipoles. This link
describes how to use the <a class="reference internal" href="tutorial_drude.html"><span class="doc">thermalized Drude oscillator model</span></a> in LAMMPS and polarizable models in LAMMPS
are discussed in <a class="reference internal" href="Section_howto.html#howto-25"><span class="std std-ref">this Section</span></a>.</p>
<p>The <em>thole</em> pair style should be used as a sub-style within in the
<a class="reference internal" href="pair_hybrid.html"><span class="doc">pair_hybrid/overlay</span></a> command, in conjunction with a
main pair style including Coulomb interactions, i.e. any pair style
containing <em>coul/cut</em> or <em>coul/long</em> in its style name.</p>
<p>The <em>lj/cut/thole/long</em> pair style is equivalent to, but more convenient that
the frequent combination <em>hybrid/overlay lj/cut/coul/long cutoff thole damp
cutoff2</em>. It is not only a shorthand for this pair_style combination, but
it also allows for mixing pair coefficients instead of listing them all.
The <em>lj/cut/thole/long</em> pair style is also a bit faster because it avoids an
overlay and can benefit from OMP acceleration. Moreover, it uses a more
precise approximation of the direct Coulomb interaction at short range similar
to <a class="reference internal" href="pair_cs.html"><span class="doc">coul/long/cs</span></a>, which stabilizes the temperature of
Drude particles.</p>
<p>The <em>thole</em> pair styles compute the Coulomb interaction damped at
<p>This function results from an adaptation to point charges
-<a class="reference internal" href="tutorial_drude.html#noskov"><span class="std std-ref">(Noskov)</span></a> of the dipole screening scheme originally proposed
-by <a class="reference internal" href="tutorial_drude.html#thole"><span class="std std-ref">Thole</span></a>. The scaling coefficient <span class="math">\(s_{ij}\)</span> is determined
+<a class="reference internal" href="#noskov"><span class="std std-ref">(Noskov)</span></a> of the dipole screening scheme originally proposed
+by <a class="reference internal" href="#thole"><span class="std std-ref">Thole</span></a>. The scaling coefficient <span class="math">\(s_{ij}\)</span> is determined
by the polarizability of the atoms, <span class="math">\(\alpha_i\)</span>, and by a Thole
damping parameter <span class="math">\(a\)</span>. This Thole damping parameter usually takes
a value of 2.6, but in certain force fields the value can depend upon
the atom types. The mixing rule for Thole damping parameters is the
arithmetic average, and for polarizabilities the geometric average
<p>The damping function is only applied to the interactions between the
point charges representing the induced dipoles on polarizable sites,
that is, charges on Drude particles, <span class="math">\(q_{D,i}\)</span>, and opposite
charges, <span class="math">\(-q_{D,i}\)</span>, located on the respective core particles
(to which each Drude particle is bonded). Therefore, Thole screening
is not applied to the full charge of the core particle <span class="math">\(q_i\)</span>, but
only to the <span class="math">\(-q_{D,i}\)</span> part of it.</p>
<p>The interactions between core charges are subject to the weighting
factors set by the <a class="reference internal" href="special_bonds.html"><span class="doc">special_bonds</span></a> command. The
interactions between Drude particles and core charges or
non-polarizable atoms are also subject to these weighting factors. The
Drude particles inherit the 1-2, 1-3 and 1-4 neighbor relations from
their respective cores.</p>
<p>For pair_style <em>thole</em>, the following coefficients must be defined for
each pair of atoms types via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command
as in the example above.</p>
<ul class="simple">
<li>alpha (distance units^3)</li>
<li>damp</li>
<li>cutoff (distance units)</li>
</ul>
<p>The last two coefficients are optional. If not specified the global
Thole damping parameter or global cutoff specified in the pair_style
command are used. In order to specify a cutoff (third argument) a damp
parameter (second argument) must also be specified.</p>
<p>For pair style <em>lj/cut/thole/long</em>, the following coefficients must be
defined for each pair of atoms types via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a>
command.</p>
<ul class="simple">
<li>epsilon (energy units)</li>
<li>sigma (length units)</li>
<li>alpha (distance units^3)</li>
<li>damps</li>
<li>LJ cutoff (distance units)</li>
</ul>
<p>The last two coefficients are optional and default to the global values from
the <em>pair_style</em> command line.</p>
<hr class="docutils" />
<p>Styles with a <em>gpu</em>, <em>intel</em>, <em>kk</em>, <em>omp</em>, or <em>opt</em> suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed in <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a>
of the manual. The accelerated styles take the same arguments and
should produce the same results, except for round-off and precision
issues.</p>
<p>These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
USER-OMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
<p><strong>Mixing</strong>:</p>
<p>The <em>thole</em> pair style does not support mixing. Thus, coefficients
for all I,J pairs must be specified explicitly.</p>
<p>The <em>lj/cut/thole/long</em> pair style does support mixing. Mixed coefficients
<p>These pair styles are part of the USER-DRUDE package. They are only
enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>This pair_style should currently not be used with the <a class="reference internal" href="dihedral_charmm.html"><span class="doc">charmm dihedral style</span></a> if the latter has non-zero 1-4 weighting
factors. This is because the <em>thole</em> pair style does not know which
pairs are 1-4 partners of which dihedrals.</p>
<p>The <em>lj/cut/thole/long</em> pair style should be used with a <a class="reference internal" href="kspace_style.html"><span class="doc">Kspace solver</span></a>
like PPPM or Ewald, which is only enabled if LAMMPS was built with the kspace
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>.
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>.
<p>Run a parallel replica dynamics (PRD) simulation using multiple
replicas of a system. One or more replicas can be used. The total
number of steps <em>N</em> to run can be interpreted in one of two ways; see
discussion of the <em>time</em> keyword below.</p>
<p>PRD is described in <a class="reference internal" href="tad.html#voter"><span class="std std-ref">this paper</span></a> by Art Voter. It is a method
for performing accelerated dynamics that is suitable for
infrequent-event systems that obey first-order kinetics. A good
overview of accelerated dynamics methods for such systems in given in
<a class="reference internal" href="tad.html#voter2"><span class="std std-ref">this review paper</span></a> from the same group. To quote from the
paper: “The dynamical evolution is characterized by vibrational
excursions within a potential basin, punctuated by occasional
transitions between basins.” The transition probability is
characterized by p(t) = k*exp(-kt) where k is the rate constant.
Running multiple replicas gives an effective enhancement in the
timescale spanned by the multiple simulations, while waiting for an
event to occur.</p>
<p>Each replica runs on a partition of one or more processors. Processor
partitions are defined at run-time using the -partition command-line
switch; see <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">Section 2.7</span></a> of the
manual. Note that if you have MPI installed, you can run a
multi-replica simulation with more replicas (partitions) than you have
physical processors, e.g you can run a 10-replica simulation on one or
two processors. For PRD, this makes little sense, since this offers
no effective parallel speed-up in searching for infrequent events. See
<a class="reference internal" href="Section_howto.html#howto-5"><span class="std std-ref">Section 6.5</span></a> of the manual for further
discussion.</p>
<p>When a PRD simulation is performed, it is assumed that each replica is
running the same model, though LAMMPS does not check for this.
I.e. the simulation domain, the number of atoms, the interaction
potentials, etc should be the same for every replica.</p>
<p>A PRD run has several stages, which are repeated each time an “event”
occurs in one of the replicas, as defined below. The logic for a PRD
run is as follows:</p>
<pre class="literal-block">
while (time remains):
dephase for n_dephase*t_dephase steps
until (event occurs on some replica):
run dynamics for t_event steps
quench
check for uncorrelated event on any replica
until (no correlated event occurs):
run dynamics for t_correlate steps
quench
check for correlated event on this replica
event replica shares state with all replicas
</pre>
<p>Before this loop begins, the state of the system on replica 0 is
shared with all replicas, so that all replicas begin from the same
initial state. The first potential energy basin is identified by
quenching (an energy minimization, see below) the initial state and
storing the resulting coordinates for reference.</p>
<p>In the first stage, dephasing is performed by each replica
independently to eliminate correlations between replicas. This is
done by choosing a random set of velocities, based on the
<em>random_seed</em> that is specified, and running <em>t_dephase</em> timesteps of
dynamics. This is repeated <em>n_dephase</em> times. At each of the
<em>n_dephase</em> stages, if an event occurs during the <em>t_dephase</em> steps of
dynamics for a particular replica, the replica repeats the stage until
no event occurs.</p>
<p>If the <em>temp</em> keyword is not specified, the target temperature for
velocity randomization for each replica is the current temperature of
that replica. Otherwise, it is the specified <em>Tdephase</em> temperature.
The style of velocity randomization is controlled using the keyword
<em>vel</em> with arguments that have the same meaning as their counterparts
in the <a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> command.</p>
<p>In the second stage, each replica runs dynamics continuously, stopping
every <em>t_event</em> steps to check if a transition event has occurred.
This check is performed by quenching the system and comparing the
resulting atom coordinates to the coordinates from the previous basin.
The first time through the PRD loop, the “previous basin” is the set
of quenched coordinates from the initial state of the system.</p>
<p>A quench is an energy minimization and is performed by whichever
algorithm has been defined by the <a class="reference internal" href="min_style.html"><span class="doc">min_style</span></a> command.
Minimization parameters may be set via the
<a class="reference internal" href="min_modify.html"><span class="doc">min_modify</span></a> command and by the <em>min</em> keyword of the
PRD command. The latter are the settings that would be used with the
<a class="reference internal" href="minimize.html"><span class="doc">minimize</span></a> command. Note that typically, you do not
need to perform a highly-converged minimization to detect a transition
event.</p>
<p>The event check is performed by a compute with the specified
<em>compute-ID</em>. Currently there is only one compute that works with the
PRD commmand, which is the <a class="reference internal" href="compute_event_displace.html"><span class="doc">compute event/displace</span></a> command. Other
event-checking computes may be added. <a class="reference internal" href="compute_event_displace.html"><span class="doc">Compute event/displace</span></a> checks whether any atom in
the compute group has moved further than a specified threshold
distance. If so, an “event” has occurred.</p>
<p>In the third stage, the replica on which the event occurred (event
replica) continues to run dynamics to search for correlated events.
This is done by running dynamics for <em>t_correlate</em> steps, quenching
every <em>t_event</em> steps, and checking if another event has occurred.</p>
<p>The first time no correlated event occurs, the final state of the
event replica is shared with all replicas, the new basin reference
coordinates are updated with the quenched state, and the outer loop
begins again. While the replica event is searching for correlated
events, all the other replicas also run dynamics and event checking
with the same schedule, but the final states are always overwritten by
the state of the event replica.</p>
<p>The outer loop of the pseudo-code above continues until <em>N</em> steps of
dynamics have been performed. Note that <em>N</em> only includes the
dynamics of stages 2 and 3, not the steps taken during dephasing or
the minimization iterations of quenching. The specified <em>N</em> is
interpreted in one of two ways, depending on the <em>time</em> keyword. If
the <em>time</em> value is <em>steps</em>, which is the default, then each replica
runs for <em>N</em> timesteps. If the <em>time</em> value is <em>clock</em>, then the
simulation runs until <em>N</em> aggregate timesteps across all replicas have
elapsed. This aggregate time is the “clock” time defined below, which
typically advances nearly M times faster than the timestepping on a
single replica.</p>
<hr class="docutils" />
<p>Four kinds of output can be generated during a PRD run: event
statistics, thermodynamic output by each replica, dump files, and
restart files.</p>
<p>When running with multiple partitions (each of which is a replica in
this case), the print-out to the screen and master log.lammps file is
limited to event statistics. Note that if a PRD run is performed on
only a single replica then the event statistics will be intermixed
with the usual thermodynamic output discussed below.</p>
<p>The quantities printed each time an event occurs are the timestep, CPU
time, clock, event number, a correlation flag, the number of
coincident events, and the replica number of the chosen event.</p>
<p>The timestep is the usual LAMMPS timestep, except that time does not
advance during dephasing or quenches, but only during dynamics. Note
that are two kinds of dynamics in the PRD loop listed above. The
first is when all replicas are performing independent dynamics,
waiting for an event to occur. The second is when correlated events
are being searched for and only one replica is running dynamics.</p>
<p>The CPU time is the total processor time since the start of the PRD
run.</p>
<p>The clock is the same as the timestep except that it advances by M
steps every timestep during the first kind of dynamics when the M
replicas are running independently. The clock advances by only 1 step
per timestep during the second kind of dynamics, since only a single
replica is checking for a correlated event. Thus “clock” time
represents the aggregate time (in steps) that effectively elapses
during a PRD simulation on M replicas. If most of the PRD run is
spent in the second stage of the loop above, searching for infrequent
events, then the clock will advance nearly M times faster than it
would if a single replica was running. Note the clock time between
events will be drawn from p(t).</p>
<p>The event number is a counter that increments with each event, whether
it is uncorrelated or correlated.</p>
<p>The correlation flag will be 0 when an uncorrelated event occurs
during the second stage of the loop listed above, i.e. when all
replicas are running independently. The correlation flag will be 1
when a correlated event occurs during the third stage of the loop
listed above, i.e. when only one replica is running dynamics.</p>
<p>When more than one replica detects an event at the end of the second
stage, then one of them is chosen at random. The number of coincident
events is the number of replicas that detected an event. Normally, we
expect this value to be 1. If it is often greater than 1, then either
the number of replicas is too large, or <em>t_event</em> is too large.</p>
<p>The replica number is the ID of the replica (from 0 to M-1) that
found the event.</p>
<hr class="docutils" />
<p>When running on multiple partitions, LAMMPS produces additional log
files for each partition, e.g. log.lammps.0, log.lammps.1, etc. For
the PRD command, these contain the thermodynamic output for each
replica. You will see short runs and minimizations corresponding to
the dynamics and quench operations of the loop listed above. The
timestep will be reset aprpopriately depending on whether the
operation advances time or not.</p>
<p>After the PRD command completes, timing statistics for the PRD run are
printed in each replica’s log file, giving a breakdown of how much CPU
time was spent in each stage (dephasing, dynamics, quenching, etc).</p>
<hr class="docutils" />
<p>Any <a class="reference internal" href="dump.html"><span class="doc">dump files</span></a> defined in the input script, will be
written to during a PRD run at timesteps corresponding to both
uncorrelated and correlated events. This means the the requested dump
frequency in the <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> command is ignored. There will be
one dump file (per dump command) created for all partitions.</p>
<p>The atom coordinates of the dump snapshot are those of the minimum
energy configuration resulting from quenching following a transition
event. The timesteps written into the dump files correspond to the
timestep at which the event occurred and NOT the clock. A dump
snapshot corresponding to the initial minimum state used for event
detection is written to the dump file at the beginning of each PRD
run.</p>
<hr class="docutils" />
<p>If the <a class="reference internal" href="restart.html"><span class="doc">restart</span></a> command is used, a single restart file
for all the partitions is generated, which allows a PRD run to be
continued by a new input script in the usual manner.</p>
<p>The restart file is generated at the end of the loop listed above. If
no correlated events are found, this means it contains a snapshot of
the system at time T + <em>t_correlate</em>, where T is the time at which the
uncorrelated event occurred. If correlated events were found, then it
contains a snapshot of the system at time T + <em>t_correlate</em>, where T
is the time of the last correlated event.</p>
<p>The restart frequency specified in the <a class="reference internal" href="restart.html"><span class="doc">restart</span></a> command
is interpreted differently when performing a PRD run. It does not
mean the timestep interval between restart files. Instead it means an
event interval for uncorrelated events. Thus a frequency of 1 means
write a restart file every time an uncorrelated event occurs. A
frequency of 10 means write a restart file every 10th uncorrelated
event.</p>
<p>When an input script reads a restart file from a previous PRD run, the
new script can be run on a different number of replicas or processors.
However, it is assumed that <em>t_correlate</em> in the new PRD command is
the same as it was previously. If not, the calculation of the “clock”
value for the first event in the new run will be slightly off.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command can only be used if LAMMPS was built with the REPLICA
package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section
for more info on packages.</p>
<p><em>N</em> and <em>t_correlate</em> settings must be integer multiples of
<em>t_event</em>.</p>
<p>Runs restarted from restart file written during a PRD run will not
produce identical results due to changes in the random numbers used
for dephasing.</p>
<p>This command cannot be used when any fixes are defined that keep track
of elapsed time to perform time-dependent operations. Examples
include the “ave” fixes such as <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a>.
Also <a class="reference internal" href="fix_dt_reset.html"><span class="doc">fix dt/reset</span></a> and <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a>.</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>.
<li><p class="first">file = name of data file to read in</p>
</li>
<li><p class="first">zero or more keyword/arg pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>add</em> or <em>offset</em> or <em>shift</em> or <em>extra/atom/types</em> or <em>extra/bond/types</em> or <em>extra/angle/types</em> or <em>extra/dihedral/types</em> or <em>extra/improper/types</em> or <em>group</em> or <em>nocoeff</em> or <em>fix</em></p>
<pre class="literal-block">
<em>add</em> arg = <em>append</em> or <em>Nstart</em> or <em>merge</em>
append = add new atoms with IDs appended to current IDs
Nstart = add new atoms with IDs starting with Nstart
merge = add new atoms with their IDs unchanged
<em>offset</em> args = toff boff aoff doff ioff
toff = offset to add to atom types
boff = offset to add to bond types
aoff = offset to add to angle types
doff = offset to add to dihedral types
ioff = offset to add to improper types
<em>shift</em> args = Sx Sy Sz
Sx,Sy,Sz = distance to shift atoms when adding to system (distance units)
<em>extra/atom/types</em> arg = # of extra atom types
<em>extra/bond/types</em> arg = # of extra bond types
<em>extra/angle/types</em> arg = # of extra angle types
<em>extra/dihedral/types</em> arg = # of extra dihedral types
<em>extra/improper/types</em> arg = # of extra improper types
<p>Read in a data file containing information LAMMPS needs to run a
simulation. The file can be ASCII text or a gzipped text file
(detected by a .gz suffix). This is one of 3 ways to specify initial
atom coordinates; see the <a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> and
<a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> commands for alternative methods.
Also see the explanation of the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-restart command-line switch</span></a> which can convert a restart file to
a data file.</p>
<p>This command can be used multiple times to add new atoms and their
properties to an existing system by using the <em>add</em>, <em>offset</em>, and
<em>shift</em> keywords. See more details below, which includes the use case
for the <em>extra</em> keywords.</p>
<p>The <em>group</em> keyword adds all the atoms in the data file to the
specified group-ID. The group will be created if it does not already
exist. This is useful if you are reading multiple data files and wish
to put sets of atoms into different groups so they can be operated on
later. E.g. a group of added atoms can be moved to new positions via
the <a class="reference internal" href="displace_atoms.html"><span class="doc">displace_atoms</span></a> command. Note that atoms
read from the data file are also always added to the “all” group. The
<a class="reference internal" href="group.html"><span class="doc">group</span></a> command discusses atom groups, as used in LAMMPS.</p>
<p>The <em>nocoeff</em> keyword tells read_data to ignore force field parameters.
The various Coeff sections are still read and have to have the correct
number of lines, but they are not applied. This also allows to read a
data file without having any pair, bond, angle, dihedral or improper
styles defined, or to read a data file for a different force field.</p>
<p>The use of the <em>fix</em> keyword is discussed below.</p>
<hr class="docutils" />
<p><strong>Reading multiple data files</strong></p>
<p>The read_data command can be used multiple times with the same or
different data files to build up a complex system from components
contained in individual data files. For example one data file could
contain fluid in a confined domain; a second could contain wall atoms,
and the second file could be read a third time to create a wall on the
other side of the fluid. The third set of atoms could be rotated to
an opposing direction using the <a class="reference internal" href="displace_atoms.html"><span class="doc">displace_atoms</span></a>
command, after the third read_data command is used.</p>
<p>The <em>add</em>, <em>offset</em>, <em>shift</em>, <em>extra</em>, and <em>group</em> keywords are
useful in this context.</p>
<p>If a simulation box does not yet exist, the <em>add</em> keyword
cannot be used; the read_data command is being used for the first
time. If a simulation box does exist, due to using the
<a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command, or a previous read_data command,
then the <em>add</em> keyword must be used.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The simulation box size (xlo to xhi, ylo to yhi, zlo to zhi) in
the new data file will be merged with the existing simulation box to
create a large enough box in each dimension to contain both the
existing and new atoms. Each box dimension never shrinks due to this
merge operation, it only stays the same or grows. Care must be used if
you are growing the existing simulation box in a periodic dimension.
If there are existing atoms with bonds that straddle that periodic
boundary, then the atoms may become far apart if the box size grows.
This will separate the atoms in the bond, which can lead to “lost”
bond atoms or bad dynamics.</p>
</div>
<p>The three choices for the <em>add</em> argument affect how the IDs of atoms
in the data file are treated. If <em>append</em> is specified, atoms in the
data file are added to the current system, with their atom IDs reset
so that an atomID = M in the data file becomes atomID = N+M, where N
is the largest atom ID in the current system. This rule is applied to
all occurrences of atom IDs in the data file, e.g. in the Velocity or
Bonds section. If <em>Nstart</em> is specified, then <em>Nstart</em> is a numeric
value is given, e.g. 1000, so that an atomID = M in the data file
becomes atomID = 1000+M. If <em>merge</em> is specified, the data file atoms
are added to the current system without changing their IDs. They are
assumed to merge (without duplication) with the currently defined
atoms. It is up to you to insure there are no multiply defined atom
IDs, as LAMMPS only performs an incomplete check that this is the case
by insuring the resulting max atomID >= the number of atoms.</p>
<p>The <em>offset</em> and <em>shift</em> keywords can only be used if the <em>add</em>
keyword is also specified.</p>
<p>The <em>offset</em> keyword adds the specified offset values to the atom
types, bond types, angle types, dihedral types, and improper types as
they are read from the data file. E.g. if <em>toff</em> = 2, and the file
uses atom types 1,2,3, then the added atoms will have atom types
3,4,5. These offsets apply to all occurrences of types in the data
file, e.g. for the Atoms or Masses or Pair Coeffs or Bond Coeffs
sections. This makes it easy to use atoms and molecules and their
attributes from a data file in different simulations, where you want
their types (atom, bond, angle, etc) to be different depending on what
other types already exist. All five offset values must be specified,
but individual values will be ignored if the data file does not use
that attribute (e.g. no bonds).</p>
<p>The <em>shift</em> keyword can be used to specify an (Sx, Sy, Sz)
displacement applied to the coordinates of each atom. Sz must be 0.0
for a 2d simulation. This is a mechanism for adding structured
collections of atoms at different locations within the simulation box,
to build up a complex geometry. It is up to you to insure atoms do
not end up overlapping unphysically which would lead to bad dynamics.
Note that the <a class="reference internal" href="displace_atoms.html"><span class="doc">displace_atoms</span></a> command can be used
to move a subset of atoms after they have been read from a data file.
Likewise, the <a class="reference internal" href="delete_atoms.html"><span class="doc">delete_atoms</span></a> command can be used to
remove overlapping atoms. Note that the shift values (Sx, Sy, Sz) are
also added to the simulation box information (xlo, xhi, ylo, yhi, zlo,
zhi) in the data file to shift its boundaries. E.g. xlo_new = xlo +
Sx, xhi_new = xhi + Sx.</p>
<p>The <em>extra</em> keywords can only be used the first time the read_data
command is used. They are useful if you intend to add new atom, bond,
angle, etc types later with additional read_data commands. This is
because the maximum number of allowed atom, bond, angle, etc types is
set by LAMMPS when the system is first initialized. If you do not use
the <em>extra</em> keywords, then the number of these types will be limited
to what appears in the first data file you read. For example, if the
first data file is a solid substrate of Si, it will likely specify a
single atom type. If you read a second data file with a different
material (water molecules) that sit on top of the substrate, you will
want to use different atom types for those atoms. You can only do
this if you set the <em>extra/atom/types</em> keyword to a sufficiently large
value when reading the substrate data file. Note that use of the
<em>extra</em> keywords also allows each data file to contain sections like
Masses or Pair Coeffs or Bond Coeffs which are sized appropriately for
the number of types in that data file. If the <em>offset</em> keyword is
used appropriately when each data file is read, the values in those
sections will be stored correctly in the larger data structures
allocated by the use of the <em>extra</em> keywords. E.g. the substrate file
can list mass and pair coefficients for type 1 silicon atoms. The
water file can list mass and pair coeffcients for type 1 and type 2
hydrogen and oxygen atoms. Use of the <em>extra</em> and <em>offset</em> keywords
will store those mass and pair coefficient values appropriately in
data structures that allow for 3 atom types (Si, H, O). Of course,
you would still need to specify coefficients for H/Si and O/Si
interactions in your input script to have a complete pairwise
interaction model.</p>
<p>An alternative to using the <em>extra</em> keywords with the read_data
command, is to use the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command to
initialize the simulation box and all the various type limits you need
via its <em>extra</em> keywords. Then use the read_data command one or more
times to populate the system with atoms, bonds, angles, etc, using the
<em>offset</em> keyword if desired to alter types used in the various data
files you read.</p>
<hr class="docutils" />
<p><strong>Format of a data file</strong></p>
<p>The structure of the data file is important, though many settings and
sections are optional or can come in any order. See the examples
directory for sample data files for different problems.</p>
<p>A data file has a header and a body. The header appears first. The
first line of the header is always skipped; it typically contains a
description of the file. Then lines are read one at a time. Lines
can have a trailing comment starting with ‘#’ that is ignored. If the
line is blank (only whitespace after comment is deleted), it is
skipped. If the line contains a header keyword, the corresponding
value(s) is read from the line. If it doesn’t contain a header
keyword, the line begins the body of the file.</p>
<p>The body of the file contains zero or more sections. The first line
of a section has only a keyword. This line can have a trailing
comment starting with ‘#’ that is either ignored or can be used to
check for a style match, as described below. The next line is
skipped. The remaining lines of the section contain values. The
number of lines depends on the section keyword as described below.
Zero or more blank lines can be used between sections. Sections can
appear in any order, with a few exceptions as noted below.</p>
<p>The keyword <em>fix</em> can be used one or more times. Each usage specifies
a fix that will be used to process a specific portion of the data
file. Any header line containing <em>header-string</em> and any section with
a name containing <em>section-string</em> will be passed to the specified
fix. See the <a class="reference internal" href="fix_property_atom.html"><span class="doc">fix property/atom</span></a> command for
an example of a fix that operates in this manner. The doc page for
the fix defines the syntax of the header line(s) and section(s) that
it reads from the data file. Note that the <em>header-string</em> can be
specified as NULL, in which case no header lines are passed to the
fix. This means that it can infer the length of its Section from
standard header settings, such as the number of atoms.</p>
<p>The formatting of individual lines in the data file (indentation,
spacing between words and numbers) is not important except that header
and section keywords (e.g. atoms, xlo xhi, Masses, Bond Coeffs) must
be capitalized as shown and can’t have extra white space between their
words - e.g. two spaces or a tab between the 2 words in “xlo xhi” or
the 2 words in “Bond Coeffs”, is not valid.</p>
<hr class="docutils" />
<p><strong>Format of the header of a data file</strong></p>
<p>These are the recognized header keywords. Header lines can come in
any order. The value(s) are read from the beginning of the line.
Thus the keyword <em>atoms</em> should be in a line like “1000 atoms”; the
keyword <em>ylo yhi</em> should be in a line like “-10.0 10.0 ylo yhi”; the
keyword <em>xy xz yz</em> should be in a line like “0.0 5.0 6.0 xy xz yz”.
All these settings have a default value of 0, except the lo/hi box
size defaults are -0.5 and 0.5. A line need only appear if the value
is different than the default.</p>
<ul class="simple">
<li><em>atoms</em> = # of atoms in system</li>
<li><em>bonds</em> = # of bonds in system</li>
<li><em>angles</em> = # of angles in system</li>
<li><em>dihedrals</em> = # of dihedrals in system</li>
<li><em>impropers</em> = # of impropers in system</li>
<li><em>atom types</em> = # of atom types in system</li>
<li><em>bond types</em> = # of bond types in system</li>
<li><em>angle types</em> = # of angle types in system</li>
<li><em>dihedral types</em> = # of dihedral types in system</li>
<li><em>improper types</em> = # of improper types in system</li>
<li><em>extra bond per atom</em> = leave space for this many new bonds per atom</li>
<li><em>extra angle per atom</em> = leave space for this many new angles per atom</li>
<li><em>extra dihedral per atom</em> = leave space for this many new dihedrals per atom</li>
<li><em>extra improper per atom</em> = leave space for this many new impropers per atom</li>
<li><em>extra special per atom</em> = leave space for this many new special bonds per atom</li>
<li><em>ellipsoids</em> = # of ellipsoids in system</li>
<li><em>lines</em> = # of line segments in system</li>
<li><em>triangles</em> = # of triangles in system</li>
<li><em>bodies</em> = # of bodies in system</li>
<li><em>xlo xhi</em> = simulation box boundaries in x dimension</li>
<li><em>ylo yhi</em> = simulation box boundaries in y dimension</li>
<li><em>zlo zhi</em> = simulation box boundaries in z dimension</li>
<p>If the <em>xy xz yz</em> line does not appear, LAMMPS will set up an
axis-aligned (orthogonal) simulation box. If the line does appear,
LAMMPS creates a non-orthogonal simulation domain shaped as a
parallelepiped with triclinic symmetry. The parallelepiped has its
“origin” at (xlo,ylo,zlo) and is defined by 3 edge vectors starting
from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C =
(xz,yz,zhi-zlo). <em>Xy,xz,yz</em> can be 0.0 or positive or negative values
and are called “tilt factors” because they are the amount of
displacement applied to faces of an originally orthogonal box to
transform it into the parallelepiped.</p>
<p>By default, the tilt factors (xy,xz,yz) can not skew the box more than
half the distance of the corresponding parallel box length. For
example, if xlo = 2 and xhi = 12, then the x box length is 10 and the
xy tilt factor must be between -5 and 5. Similarly, both xz and yz
must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not
a limitation, since if the maximum tilt factor is 5 (as in this
example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
... are all geometrically equivalent. If you wish to define a box
with tilt factors that exceed these limits, you can use the <a class="reference internal" href="box.html"><span class="doc">box tilt</span></a> command, with a setting of <em>large</em>; a setting of
<em>small</em> is the default.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">Section 6.12</span></a> of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.</p>
<p>When a triclinic system is used, the simulation domain should normally
be periodic in the dimension that the tilt is applied to, which is
given by the second dimension of the tilt factor (e.g. y for xy tilt).
This is so that pairs of atoms interacting across that boundary will
have one of them shifted by the tilt factor. Periodicity is set by
the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command. For example, if the xy tilt
factor is non-zero, then the y dimension should be periodic.
Similarly, the z dimension should be periodic if xz or yz is non-zero.
LAMMPS does not require this periodicity, but you may lose atoms if
this is not the case.</p>
<p>Also note that if your simulation will tilt the box, e.g. via the <a class="reference internal" href="fix_deform.html"><span class="doc">fix deform</span></a> command, the simulation box must be setup to
be triclinic, even if the tilt factors are initially 0.0. You can
also change an orthogonal box to a triclinic box or vice versa by
using the <a class="reference internal" href="change_box.html"><span class="doc">change box</span></a> command with its <em>ortho</em> and
<em>triclinic</em> options.</p>
<p>For 2d simulations, the <em>zlo zhi</em> values should be set to bound the z
coords for atoms that appear in the file; the default of -0.5 0.5 is
valid if all z coords are 0.0. For 2d triclinic simulations, the xz
and yz tilt factors must be 0.0.</p>
<p>If the system is periodic (in a dimension), then atom coordinates can
be outside the bounds (in that dimension); they will be remapped (in a
periodic sense) back inside the box. Note that if the <em>add</em> option is
being used to add atoms to a simulation box that already exists, this
periodic remapping will be performed using simulation box bounds that
are the union of the existing box and the box boundaries in the new
data file.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If the system is non-periodic (in a dimension), then all atoms
in the data file must have coordinates (in that dimension) that are
“greater than or equal to” the lo value and “less than or equal to”
the hi value. If the non-periodic dimension is of style “fixed” (see
the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command), then the atom coords must be
strictly “less than” the hi value, due to the way LAMMPS assign atoms
to processors. Note that you should not make the lo/hi values
radically smaller/larger than the extent of the atoms. For example,
if your atoms extend from 0 to 50, you should not specify the box
bounds as -10000 and 10000. This is because LAMMPS uses the specified
box size to layout the 3d grid of processors. A huge (mostly empty)
box will be sub-optimal for performance when using “fixed” boundary
conditions (see the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command). When using
“shrink-wrap” boundary conditions (see the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a>
command), a huge (mostly empty) box may cause a parallel simulation to
lose atoms when LAMMPS shrink-wraps the box around the atoms. The
read_data command will generate an error in this case.</p>
</div>
<p>The “extra bond per atom” setting (angle, dihedral, improper) is only
needed if new bonds (angles, dihedrals, impropers) will be added to
the system when a simulation runs, e.g. by using the <a class="reference internal" href="fix_bond_create.html"><span class="doc">fix bond/create</span></a> command. This will pre-allocate
space in LAMMPS data structures for storing the new bonds (angles,
dihedrals, impropers).</p>
<p>The “extra special per atom” setting is typically only needed if new
bonds/angles/etc will be added to the system, e.g. by using the <a class="reference internal" href="fix_bond_create.html"><span class="doc">fix bond/create</span></a> command. Or if entire new molecules
will be added to the system, e.g. by using the <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a> or <a class="reference internal" href="fix_pour.html"><span class="doc">fix pour</span></a> commands, which
will have more special 1-2,1-3,1-4 neighbors than any other molecules
defined in the data file. Using this setting will pre-allocate space
in the LAMMPS data structures for storing these neighbors. See the
pages for more discussion of 1-2,1-3,1-4 neighbors.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">All of the “extra” settings are only used if they appear in the
first data file read; see the description of the <em>add</em> keyword above
for reading multiple data files. If they appear in later data files,
they are ignored.</p>
</div>
<p>The “ellipsoids” and “lines” and “triangles” and “bodies” settings are
only used with <a class="reference internal" href="atom_style.html"><span class="doc">atom_style ellipsoid or line or tri or body</span></a> and specify how many of the atoms are
finite-size ellipsoids or lines or triangles or bodies; the remainder
are point particles. See the discussion of ellipsoidflag and the
<em>Ellipsoids</em> section below. See the discussion of lineflag and the
<em>Lines</em> section below. See the discussion of triangleflag and the
<em>Triangles</em> section below. See the discussion of bodyflag and the
<em>Bodies</em> section below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For <a class="reference internal" href="atom_style.html"><span class="doc">atom_style template</span></a>, the molecular
topology (bonds,angles,etc) is contained in the molecule templates
read-in by the <a class="reference internal" href="molecule.html"><span class="doc">molecule</span></a> command. This means you
cannot set the <em>bonds</em>, <em>angles</em>, etc header keywords in the data
file, nor can you define <em>Bonds</em>, <em>Angles</em>, etc sections as discussed
below. You can set the <em>bond types</em>, <em>angle types</em>, etc header
keywords, though it is not necessary. If specified, they must match
the maximum values defined in any of the template molecules.</p>
</div>
<hr class="docutils" />
<p><strong>Format of the body of a data file</strong></p>
<p>These are the section keywords for the body of the file.</p>
<p>Atom lines specify the (x,y,z) coordinates of atoms. These can be
inside or outside the simulation box. When the data file is read,
LAMMPS wraps coordinates outside the box back into the box for
dimensions that are periodic. As discussed above, if an atom is
outside the box in a non-periodic dimension, it will be lost.</p>
<p>LAMMPS always stores atom coordinates as values which are inside the
simulation box. It also stores 3 flags which indicate which image of
the simulation box (in each dimension) the atom would be in if its
coordinates were unwrapped across periodic boundaries. An image flag
of 0 means the atom is still inside the box when unwrapped. A value
of 2 means add 2 box lengths to get the unwrapped coordinate. A value
of -1 means subtract 1 box length to get the unwrapped coordinate.
LAMMPS updates these flags as atoms cross periodic boundaries during
the simulation. The <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> command can output atom atom
coordinates in wrapped or unwrapped form, as well as the 3 image
flags.</p>
<p>In the data file, atom lines (all lines or none of them) can
optionally list 3 trailing integer values (nx,ny,nz), which are used
to initialize the atom’s image flags. If nx,ny,nz values are not
listed in the data file, LAMMPS initializes them to 0. Note that the
image flags are immediately updated if an atom’s coordinates need to
wrapped back into the simulation box.</p>
<p>It is only important to set image flags correctly in a data file if a
simulation model relies on unwrapped coordinates for some calculation;
otherwise they can be left unspecified. Examples of LAMMPS commands
that use unwrapped coordinates internally are as follows:</p>
<ul class="simple">
<li>Atoms in a rigid body (see <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid</span></a>, <a class="reference internal" href="fix_rigid.html"><span class="doc">fix rigid/small</span></a>) must have consistent image flags, so that
when the atoms are unwrapped, they are near each other, i.e. as a
single body.</li>
<li>If the <a class="reference internal" href="replicate.html"><span class="doc">replicate</span></a> command is used to generate a larger
system, image flags must be consistent for bonded atoms when the bond
crosses a periodic boundary. I.e. the values of the image flags
should be different by 1 (in the appropriate dimension) for the two
atoms in such a bond.</li>
<li>If you plan to <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> image flags and perform post-analysis
that will unwrap atom coordinates, it may be important that a
continued run (restarted from a data file) begins with image flags
that are consistent with the previous run.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If your system is an infinite periodic crystal with bonds then
it is impossible to have fully consistent image flags. This is because
some bonds will cross periodic boundaries and connect two atoms with the
same image flag.</p>
</div>
<p>Atom velocities and other atom quantities not defined above are set to
0.0 when the <em>Atoms</em> section is read. Velocities can be set later by
a <em>Velocities</em> section in the data file or by a
<a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> or <a class="reference internal" href="set.html"><span class="doc">set</span></a> command in the input
script.</p>
<hr class="docutils" />
<p><em>Bodies</em> section:</p>
<ul>
<li><p class="first">one or more lines per body</p>
</li>
<li><p class="first">first line syntax: atom-ID Ninteger Ndouble</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Ninteger</span> <span class="o">=</span> <span class="c1"># of integer quantities for this particle</span>
<span class="n">Ndouble</span> <span class="o">=</span> <span class="c1"># of floating-point quantities for this particle</span>
</pre></div>
</div>
</li>
<li><p class="first">0 or more integer lines with total of Ninteger values</p>
</li>
<li><p class="first">0 or more double lines with total of Ndouble values</p>
<p>The <em>Ellipsoids</em> section must appear if <a class="reference internal" href="atom_style.html"><span class="doc">atom_style ellipsoid</span></a> is used and any atoms are listed in the
<em>Atoms</em> section with an ellipsoidflag = 1. The number of ellipsoids
should be specified in the header section via the “ellipsoids”
keyword.</p>
<p>The 3 shape values specify the 3 diameters or aspect ratios of a
finite-size ellipsoidal particle, when it is oriented along the 3
coordinate axes. They must all be non-zero values.</p>
<p>The values <em>quatw</em>, <em>quati</em>, <em>quatj</em>, and <em>quatk</em> set the orientation
of the atom as a quaternion (4-vector). Note that the shape
attributes specify the aspect ratios of an ellipsoidal particle, which
is oriented by default with its x-axis along the simulation box’s
x-axis, and similarly for y and z. If this body is rotated (via the
right-hand rule) by an angle theta around a unit vector (a,b,c), then
the quaternion that represents its new orientation is given by
(cos(theta/2), a*sin(theta/2), b*sin(theta/2), c*sin(theta/2)). These
4 components are quatw, quati, quatj, and quatk as specified above.
LAMMPS normalizes each atom’s quaternion in case (a,b,c) is not
specified as a unit vector.</p>
<p>The <em>Ellipsoids</em> section must appear after the <em>Atoms</em> section.</p>
<hr class="docutils" />
<p><em>EndBondTorsion Coeffs</em> section:</p>
<ul>
<li><p class="first">one line per dihedral type</p>
</li>
<li><p class="first">line syntax: ID coeffs</p>
<pre class="literal-block">
ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of <a class="reference internal" href="dihedral_coeff.html"><span class="doc">dihedral_coeff</span></a>)
</pre>
</li>
</ul>
<hr class="docutils" />
<p><em>Improper Coeffs</em> section:</p>
<ul>
<li><p class="first">one line per improper type</p>
<p>The ordering of the 4 atoms determines the definition of the improper
angle used in the formula for each <a class="reference internal" href="improper_style.html"><span class="doc">improper style</span></a>. See the doc pages for individual styles
for details.</p>
<p>The <em>Impropers</em> section must appear after the <em>Atoms</em> section. All
values in this section must be integers (1, not 1.0).</p>
<hr class="docutils" />
<p><em>Lines</em> section:</p>
<ul>
<li><p class="first">one line per line segment</p>
<p>The number and meaning of the coefficients are specific to the defined
pair style. See the <a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> and
<a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> commands for details. Since pair
coefficients for types I != J are not specified, these will be
generated automatically by the pair style’s mixing rule. See the
individual pair_style doc pages and the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify mix</span></a> command for details. Pair coefficients can also
be set via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command in the input
script.</p>
<hr class="docutils" />
<p><em>PairIJ Coeffs</em> section:</p>
<ul>
<li><p class="first">one line per pair of atom types for all I,J with I <= J</p>
<p>This section must have N*(N+1)/2 lines where N = # of atom types. The
number and meaning of the coefficients are specific to the defined
pair style. See the <a class="reference internal" href="pair_style.html"><span class="doc">pair_style</span></a> and
<a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> commands for details. Since pair
coefficients for types I != J are all specified, these values will
turn off the default mixing rule defined by the pair style. See the
individual pair_style doc pages and the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify mix</span></a> command for details. Pair coefficients can also
be set via the <a class="reference internal" href="pair_coeff.html"><span class="doc">pair_coeff</span></a> command in the input
<p>The <em>Triangles</em> section must appear if <a class="reference internal" href="atom_style.html"><span class="doc">atom_style tri</span></a> is used and any atoms are listed in the <em>Atoms</em>
section with a triangleflag = 1. The number of lines should be
specified in the header section via the “triangles” keyword.</p>
<p>The 3 corner points are the corner points of the triangle. The
ordering of the 3 points should be such that using a right-hand rule
to go from point1 to point2 to point3 gives an “outward” normal vector
to the face of the triangle. I.e. normal = (c2-c1) x (c3-c1). This
orientation may be important for defining some interactions.</p>
<p>The <em>Triangles</em> section must appear after the <em>Atoms</em> section.</p>
<hr class="docutils" />
<p><em>Velocities</em> section:</p>
<ul class="simple">
<li>one line per atom</li>
<li>line syntax: depends on atom style</li>
</ul>
<table border="1" class="docutils">
<colgroup>
<col width="42%" />
<col width="58%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>all styles except those listed</td>
<p>Translational velocities can also be set by the
<a class="reference internal" href="velocity.html"><span class="doc">velocity</span></a> command in the input script.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>To read gzipped data files, you must compile LAMMPS with the
-DLAMMPS_GZIP option - see the <a class="reference internal" href="Section_start.html#start-2"><span class="std std-ref">Making LAMMPS</span></a> section of the documentation.</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>.
so that all atoms in the restart file are inside the simulation box.
If this is not the case, the read_restart command will print an error
that atoms were “lost” when the file is read. This error should be
reported to the LAMMPS developers so the invalid writing of the
restart file can be fixed. If you still wish to use the restart file,
the optional <em>remap</em> flag can be appended to the read_restart command.
This should avoid the error, by explicitly remapping each atom back
into the simulation box, updating image flags for the atom
appropriately.</p>
</div>
<p>Restart files are saved in binary format to enable exact restarts,
meaning that the trajectories of a restarted run will precisely match
those produced by the original run had it continued on.</p>
<p>Several things can prevent exact restarts due to round-off effects, in
which case the trajectories in the 2 runs will slowly diverge. These
include running on a different number of processors or changing
certain settings such as those set by the <a class="reference internal" href="newton.html"><span class="doc">newton</span></a> or
<a class="reference internal" href="processors.html"><span class="doc">processors</span></a> commands. LAMMPS will issue a warning in
these cases.</p>
<p>Certain fixes will not restart exactly, though they should provide
statistically similar results. These include <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> and <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a>.</p>
<p>Certain pair styles will not restart exactly, though they should
provide statistically similar results. This is because the forces
they compute depend on atom velocities, which are used at half-step
values every timestep when forces are computed. When a run restarts,
forces are initially evaluated with a full-step velocity, which is
different than if the run had continued. These pair styles include
<p>If a restarted run is immediately different than the run which
produced the restart file, it could be a LAMMPS bug, so consider
<a class="reference internal" href="Section_errors.html#err-2"><span class="std std-ref">reporting it</span></a> if you think the behavior is
wrong.</p>
<p>Because restart files are binary, they may not be portable to other
machines. In this case, you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-restart command-line switch</span></a> to convert a restart file to a data
file.</p>
<p>Similar to how restart files are written (see the
<p>As indicated in the above list, the <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a> used for a
simulation are not stored in the restart file. This means the new
input script should specify all fixes it will use. However, note that
some fixes store an internal “state” which is written to the restart
file. This allows the fix to continue on with its calculations in a
restarted simulation. To re-enable such a fix, the fix command in the
new input script must use the same fix-ID and group-ID as was used in
the input script that wrote the restart file. If a match is found,
LAMMPS prints a message indicating that the fix is being re-enabled.
If no match is found before the first run or minimization is performed
by the new script, the “state” information for the saved fix is
discarded. See the doc pages for individual fixes for info on which
ones can be restarted in this manner.</p>
<p>Likewise, the <a class="reference internal" href="fix.html"><span class="doc">computes</span></a> used for a simulation are not stored
in the restart file. This means the new input script should specify
all computes it will use. However, some computes create a fix
internally to store “state” information that persists from timestep to
timestep. An example is the <a class="reference internal" href="compute_msd.html"><span class="doc">compute msd</span></a> command
which uses a fix to store a reference coordinate for each atom, so
that a displacement can be calculated at any later time. If the
compute command in the new input script uses the same compute-ID and
group-ID as was used in the input script that wrote the restart file,
then it will create the same fix in the restarted run. This means the
re-created fix will be re-enabled with the stored state information as
described in the previous paragraph, so that the compute can continue
its calculations in a consistent manner.</p>
<p>Some pair styles, like the <a class="reference internal" href="pair_gran.html"><span class="doc">granular pair styles</span></a>, also
use a fix to store “state” information that persists from timestep to
timestep. In the case of granular potentials, it is contact
information between pairs of touching particles. This info will also
be re-enabled in the restart script, assuming you re-use the same
granular pair style.</p>
<p>LAMMPS allows bond interactions (angle, etc) to be turned off or
deleted in various ways, which can affect how their info is stored in
a restart file.</p>
<p>If bonds (angles, etc) have been turned off by the <a class="reference internal" href="fix_shake.html"><span class="doc">fix shake</span></a> or <a class="reference internal" href="delete_bonds.html"><span class="doc">delete_bonds</span></a> command,
their info will be written to a restart file as if they are turned on.
This means they will need to be turned off again in a new run after
the restart file is read.</p>
<p>Bonds that are broken (e.g. by a bond-breaking potential) are written
to the restart file as broken bonds with a type of 0. Thus these
bonds will still be broken when the restart file is read.</p>
<p>Bonds that have been broken by the <a class="reference internal" href="fix_bond_break.html"><span class="doc">fix bond/break</span></a> command have disappeared from the
system. No information about these bonds is written to the restart
file.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>To write and read restart files in parallel with MPI-IO, the MPIIO
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>.
<li><p class="first">ID = user-assigned name for the region</p>
</li>
<li><p class="first">style = <em>delete</em> or <em>block</em> or <em>cone</em> or <em>cylinder</em> or <em>plane</em> or <em>prism</em> or <em>sphere</em> or <em>union</em> or <em>intersect</em></p>
<pre class="literal-block">
<em>delete</em> = no args
<em>block</em> args = xlo xhi ylo yhi zlo zhi
xlo,xhi,ylo,yhi,zlo,zhi = bounds of block in all dimensions (distance units)
<em>cone</em> args = dim c1 c2 radlo radhi lo hi
dim = <em>x</em> or <em>y</em> or <em>z</em> = axis of cone
c1,c2 = coords of cone axis in other 2 dimensions (distance units)
radlo,radhi = cone radii at lo and hi end (distance units)
lo,hi = bounds of cone in dim (distance units)
<em>cylinder</em> args = dim c1 c2 radius lo hi
dim = <em>x</em> or <em>y</em> or <em>z</em> = axis of cylinder
c1,c2 = coords of cylinder axis in other 2 dimensions (distance units)
radius = cylinder radius (distance units)
radius can be a variable (see below)
lo,hi = bounds of cylinder in dim (distance units)
<em>plane</em> args = px py pz nx ny nz
px,py,pz = point on the plane (distance units)
nx,ny,nz = direction normal to plane (distance units)
xlo,xhi,ylo,yhi,zlo,zhi = bounds of untilted prism (distance units)
xy = distance to tilt y in x direction (distance units)
xz = distance to tilt z in x direction (distance units)
yz = distance to tilt z in y direction (distance units)
<em>sphere</em> args = x y z radius
x,y,z = center of sphere (distance units)
radius = radius of sphere (distance units)
radius can be a variable (see below)
<em>union</em> args = N reg-ID1 reg-ID2 ...
N = # of regions to follow, must be 2 or greater
reg-ID1,reg-ID2, ... = IDs of regions to join together
<em>intersect</em> args = N reg-ID1 reg-ID2 ...
N = # of regions to follow, must be 2 or greater
reg-ID1,reg-ID2, ... = IDs of regions to intersect
</pre>
</li>
<li><p class="first">zero or more keyword/arg pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>side</em> or <em>units</em> or <em>move</em> or <em>rotate</em></p>
<pre class="literal-block">
<em>side</em> value = <em>in</em> or <em>out</em>
<em>in</em> = the region is inside the specified geometry
<em>out</em> = the region is outside the specified geometry
<em>units</em> value = <em>lattice</em> or <em>box</em>
<em>lattice</em> = the geometry is defined in lattice units
<em>box</em> = the geometry is defined in simulation box units
<em>move</em> args = v_x v_y v_z
v_x,v_y,v_z = equal-style variables for x,y,z displacement of region over time
<em>rotate</em> args = v_theta Px Py Pz Rx Ry Rz
v_theta = equal-style variable for rotaton of region over time (in radians)
Px,Py,Pz = origin for axis of rotation (distance units)
Rx,Ry,Rz = axis of rotation vector
</pre>
</li>
<li><p class="first">accelerated styles (with same args) = <em>block/kk</em></p>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
region 1 block -3.0 5.0 INF 10.0 INF INF
region 2 sphere 0.0 0.0 0.0 5 side out
region void cylinder y 2 3 5 -5.0 EDGE units box
region 1 prism 0 10 0 10 0 10 2 0 0
region outside union 4 side1 side2 side3 side4
region 2 sphere 0.0 0.0 0.0 5 side out move v_left v_up NULL
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>This command defines a geometric region of space. Various other
commands use regions. For example, the region can be filled with
atoms via the <a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> command. Or a bounding
box around the region, can be used to define the simulation box via
the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> command. Or the atoms in the region
can be identified as a group via the <a class="reference internal" href="group.html"><span class="doc">group</span></a> command, or
deleted via the <a class="reference internal" href="delete_atoms.html"><span class="doc">delete_atoms</span></a> command. Or the
surface of the region can be used as a boundary wall via the <a class="reference internal" href="fix_wall_region.html"><span class="doc">fix wall/region</span></a> command.</p>
<p>Commands which use regions typically test whether an atom’s position
is contained in the region or not. For this purpose, coordinates
exactly on the region boundary are considered to be interior to the
region. This means, for example, for a spherical region, an atom on
the sphere surface would be part of the region if the sphere were
defined with the <em>side in</em> keyword, but would not be part of the
region if it were defined using the <em>side out</em> keyword. See more
details on the <em>side</em> keyword below.</p>
<p>Normally, regions in LAMMPS are “static”, meaning their geometric
extent does not change with time. If the <em>move</em> or <em>rotate</em> keyword
is used, as described below, the region becomes “dynamic”, meaning
it’s location or orientation changes with time. This may be useful,
for example, when thermostatting a region, via the compute temp/region
command, or when the fix wall/region command uses a region surface as
a bounding wall on particle motion, i.e. a rotating container.</p>
<p>The <em>delete</em> style removes the named region. Since there is little
overhead to defining extra regions, there is normally no need to do
this, unless you are defining and discarding large numbers of regions
in your input script.</p>
<p>The lo/hi values for <em>block</em> or <em>cone</em> or <em>cylinder</em> or <em>prism</em> styles
can be specified as EDGE or INF. EDGE means they extend all the way
to the global simulation box boundary. Note that this is the current
box boundary; if the box changes size during a simulation, the region
does not. INF means a large negative or positive number (1.0e20), so
it should encompass the simulation box even if it changes size. If a
region is defined before the simulation box has been created (via
<a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a> or <a class="reference internal" href="read_data.html"><span class="doc">read_data</span></a> or
<a class="reference internal" href="read_restart.html"><span class="doc">read_restart</span></a> commands), then an EDGE or INF
parameter cannot be used. For a <em>prism</em> region, a non-zero tilt
factor in any pair of dimensions cannot be used if both the lo/hi
values in either of those dimensions are INF. E.g. if the xy tilt is
non-zero, then xlo and xhi cannot both be INF, nor can ylo and yhi.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Regions in LAMMPS do not get wrapped across periodic boundaries,
as specified by the <a class="reference internal" href="boundary.html"><span class="doc">boundary</span></a> command. For example, a
spherical region that is defined so that it overlaps a periodic
boundary is not treated as 2 half-spheres, one on either side of the
simulation box.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Regions in LAMMPS are always 3d geometric objects, regardless of
whether the <a class="reference internal" href="dimension.html"><span class="doc">dimension</span></a> of a simulation is 2d or 3d.
Thus when using regions in a 2d simulation, you should be careful to
define the region so that its intersection with the 2d x-y plane of
the simulation has the 2d geometric extent you want.</p>
</div>
<p>For style <em>cone</em>, an axis-aligned cone is defined which is like a
<em>cylinder</em> except that two different radii (one at each end) can be
defined. Either of the radii (but not both) can be 0.0.</p>
<p>For style <em>cone</em> and <em>cylinder</em>, the c1,c2 params are coordinates in
the 2 other dimensions besides the cylinder axis dimension. For dim =
x, c1/c2 = y/z; for dim = y, c1/c2 = x/z; for dim = z, c1/c2 = x/y.
Thus the third example above specifies a cylinder with its axis in the
y-direction located at x = 2.0 and z = 3.0, with a radius of 5.0, and
extending in the y-direction from -5.0 to the upper box boundary.</p>
<p>For style <em>plane</em>, a plane is defined which contain the point
(px,py,pz) and has a normal vector (nx,ny,nz). The normal vector does
not have to be of unit length. The “inside” of the plane is the
half-space in the direction of the normal vector; see the discussion
of the <em>side</em> option below.</p>
<p>For style <em>prism</em>, a parallelepiped is defined (it’s too hard to spell
parallelepiped in an input script!). The parallelepiped has its
“origin” at (xlo,ylo,zlo) and is defined by 3 edge vectors starting
from the origin given by A = (xhi-xlo,0,0); B = (xy,yhi-ylo,0); C =
(xz,yz,zhi-zlo). <em>Xy,xz,yz</em> can be 0.0 or positive or negative values
and are called “tilt factors” because they are the amount of
displacement applied to faces of an originally orthogonal box to
transform it into the parallelepiped.</p>
<p>A prism region that will be used with the <a class="reference internal" href="create_box.html"><span class="doc">create_box</span></a>
command to define a triclinic simulation box must have tilt factors
(xy,xz,yz) that do not skew the box more than half the distance of
corresponding the parallel box length. For example, if xlo = 2 and
xhi = 12, then the x box length is 10 and the xy tilt factor must be
between -5 and 5. Similarly, both xz and yz must be between
-(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation,
since if the maximum tilt factor is 5 (as in this example), then
configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all
geometrically equivalent.</p>
<p>The <em>radius</em> value for style <em>sphere</em> and <em>cylinder</em> can be specified
as an equal-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. If the value is a
variable, it should be specified as v_name, where name is the variable
name. In this case, the variable will be evaluated each timestep, and
its value used to determine the radius of the region.</p>
<p>Equal-style variables can specify formulas with various mathematical
functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a> command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent radius.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">Section 6.12</span></a> of the doc pages
for a geometric description of triclinic boxes, as defined by LAMMPS,
and how to transform these parameters to and from other commonly used
triclinic representations.</p>
<p>The <em>union</em> style creates a region consisting of the volume of all the
listed regions combined. The <em>intersect</em> style creates a region
consisting of the volume that is common to all the listed regions.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <em>union</em> and <em>intersect</em> regions operate by invoking methods
from their list of sub-regions. Thus you cannot delete the
sub-regions after defining the <em>union</em> or <em>intersection</em> region.</p>
</div>
<hr class="docutils" />
<p>The <em>side</em> keyword determines whether the region is considered to be
inside or outside of the specified geometry. Using this keyword in
conjunction with <em>union</em> and <em>intersect</em> regions, complex geometries
can be built up. For example, if the interior of two spheres were
each defined as regions, and a <em>union</em> style with <em>side</em> = out was
constructed listing the region-IDs of the 2 spheres, the resulting
region would be all the volume in the simulation box that was outside
both of the spheres.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to define the region for any argument above listed as having distance
units. It also affects the scaling of the velocity vector specfied
with the <em>vel</em> keyword, the amplitude vector specified with the
<em>wiggle</em> keyword, and the rotation point specified with the <em>rotate</em>
keyword, since they each involve a distance metric.</p>
<p>A <em>box</em> value selects standard distance units as defined by the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or metal.
A <em>lattice</em> value means the distance units are in lattice spacings.
The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have been previously used to
define the lattice spacings which are used as follows:</p>
<ul class="simple">
<li>For style <em>block</em>, the lattice spacing in dimension x is applied to
xlo and xhi, similarly the spacings in dimensions y,z are applied to
ylo/yhi and zlo/zhi.</li>
<li>For style <em>cone</em>, the lattice spacing in argument <em>dim</em> is applied to
lo and hi. The spacings in the two radial dimensions are applied to
c1 and c2. The two cone radii are scaled by the lattice
spacing in the dimension corresponding to c1.</li>
<li>For style <em>cylinder</em>, the lattice spacing in argument <em>dim</em> is applied
to lo and hi. The spacings in the two radial dimensions are applied
to c1 and c2. The cylinder radius is scaled by the lattice
spacing in the dimension corresponding to c1.</li>
<li>For style <em>plane</em>, the lattice spacing in dimension x is applied to
px and nx, similarly the spacings in dimensions y,z are applied to
py/ny and pz/nz.</li>
<li>For style <em>prism</em>, the lattice spacing in dimension x is applied to
xlo and xhi, similarly for ylo/yhi and zlo/zhi. The lattice spacing
in dimension x is applied to xy and xz, and the spacing in dimension y
to yz.</li>
<li>For style <em>sphere</em>, the lattice spacing in dimensions x,y,z are
applied to the sphere center x,y,z. The spacing in dimension x is
applied to the sphere radius.</li>
</ul>
<hr class="docutils" />
<p>If the <em>move</em> or <em>rotate</em> keywords are used, the region is “dynamic”,
meaning its location or orientation changes with time. These keywords
cannot be used with a <em>union</em> or <em>intersect</em> style region. Instead,
the keywords should be used to make the individual sub-regions of the
<em>union</em> or <em>intersect</em> region dynamic. Normally, each sub-region
should be “dynamic” in the same manner (e.g. rotate around the same
point), though this is not a requirement.</p>
<p>The <em>move</em> keyword allows one or more <a class="reference internal" href="variable.html"><span class="doc">equal-style variables</span></a> to be used to specify the x,y,z displacement
of the region, typically as a function of time. A variable is
specified as v_name, where name is the variable name. Any of the
three variables can be specified as NULL, in which case no
displacement is calculated in that dimension.</p>
<p>Note that equal-style variables can specify formulas with various
mathematical functions, and include <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style</span></a>
command keywords for the simulation box parameters and timestep and
elapsed time. Thus it is easy to specify a region displacement that
change as a function of time or spans consecutive runs in a continuous
fashion. For the latter, see the <em>start</em> and <em>stop</em> keywords of the
<a class="reference internal" href="run.html"><span class="doc">run</span></a> command and the <em>elaplong</em> keyword of <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></a> for details.</p>
<p>For example, these commands would displace a region from its initial
position, in the positive x direction, effectively at a constant
<p>The <em>rotate</em> keyword rotates the region around a rotation axis <em>R</em> =
(Rx,Ry,Rz) that goes thru a point <em>P</em> = (Px,Py,Pz). The rotation
angle is calculated, presumably as a function of time, by a variable
specified as v_theta, where theta is the variable name. The variable
should generate its result in radians. The direction of rotation for
the region around the rotation axis is consistent with the right-hand
rule: if your right-hand thumb points along <em>R</em>, then your fingers
wrap around the axis in the direction of rotation.</p>
<p>The <em>move</em> and <em>rotate</em> keywords can be used together. In this case,
the displacement specified by the <em>move</em> keyword is applied to the <em>P</em>
point of the <em>rotate</em> keyword.</p>
<hr class="docutils" />
<p>Styles with a <em>kk</em> suffix are functionally the same as the
corresponding style without the suffix. They have been optimized to
run faster, depending on your available hardware, as discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual. The
accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>The code using the region (such as a fix or compute) must also be supported
by Kokkos or no acceleration will occur. Currently, only <em>block</em> style
regions are supported by Kokkos.</p>
<p>These accelerated styles are part of the Kokkos package. They are
only enabled if LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
<p>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a> when you invoke LAMMPS, or you can
use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a> command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>A prism cannot be of 0.0 thickness in any dimension; use a small z
thickness for 2d simulations. For 2d simulations, the xz and yz
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>.
<p>When you run in 2-partition mode with the <em>verlet/split</em> style, the
thermodyanmic data for the entire simulation will be output to the log
and screen file of the 1st partition, which are log.lammps.0 and
screen.0 by default; see the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-plog and -pscreen command-line switches</span></a> to change this. The log and
screen file for the 2nd partition will not contain thermodynamic
output beyone the 1st timestep of the run.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
performance details of the speed-up offered by the <em>verlet/split</em>
style. One important performance consideration is the assignemnt of
logical processors in the 2 partitions to the physical cores of a
parallel machine. The <a class="reference internal" href="processors.html"><span class="doc">processors</span></a> command has
options to support this, and strategies are discussed in
<a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual.</p>
<hr class="docutils" />
<p>The <em>respa</em> style implements the rRESPA multi-timescale integrator
<a class="reference internal" href="#tuckerman"><span class="std std-ref">(Tuckerman)</span></a> with N hierarchical levels, where level 1 is
the innermost loop (shortest timestep) and level N is the outermost
loop (largest timestep). The loop factor arguments specify what the
looping factor is between levels. N1 specifies the number of
iterations of level 1 for a single iteration of level 2, N2 is the
iterations of level 2 per iteration of level 3, etc. N-1 looping
parameters must be specified.</p>
<p>The <a class="reference internal" href="timestep.html"><span class="doc">timestep</span></a> command sets the timestep for the
outermost rRESPA level. Thus if the example command above for a
4-level rRESPA had an outer timestep of 4.0 fmsec, the inner timestep
would be 8x smaller or 0.5 fmsec. All other LAMMPS commands that
specify number of timesteps (e.g. <a class="reference internal" href="neigh_modify.html"><span class="doc">neigh_modify</span></a>
parameters, <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> every N timesteps, etc) refer to the
outermost timesteps.</p>
<p>The rRESPA keywords enable you to specify at what level of the
hierarchy various forces will be computed. If not specified, the
defaults are that bond forces are computed at level 1 (innermost
loop), angle forces are computed where bond forces are, dihedral
forces are computed where angle forces are, improper forces are
computed where dihedral forces are, pair forces are computed at the
outermost level, and kspace forces are computed where pair forces are.
The inner, middle, outer forces have no defaults.</p>
<p>For fixes that support it, the rRESPA level at which a given fix is
active, can be selected through the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> command.</p>
<p>The <em>inner</em> and <em>middle</em> keywords take additional arguments for
cutoffs that are used by the pairwise force computations. If the 2
cutoffs for <em>inner</em> are 5.0 and 6.0, this means that all pairs up to
6.0 apart are computed by the inner force. Those between 5.0 and 6.0
have their force go ramped to 0.0 so the overlap with the next regime
(middle or outer) is smooth. The next regime (middle or outer) will
compute forces for all pairs from 5.0 outward, with those from 5.0 to
6.0 having their value ramped in an inverse manner.</p>
<p>Only some pair potentials support the use of the <em>inner</em> and <em>middle</em>
and <em>outer</em> keywords. If not, only the <em>pair</em> keyword can be used
with that pair style, meaning all pairwise forces are computed at the
same rRESPA level. See the doc pages for individual pair styles for
details.i</p>
<p>Another option for using pair potentials with rRESPA is with the
<em>hybrid</em> keyword, which requires the use of the <a class="reference internal" href="pair_hybrid.html"><span class="doc">pair_style hybrid or hybrid/overlay</span></a> command. In this scenario, different
sub-styles of the hybrid pair style are evaluated at different rRESPA
levels. This can be useful, for example, to set different timesteps
for hybrid coarse-grained/all-atom models. The <em>hybrid</em> keyword
requires as many level assignments as there are hybrid substyles,
which assigns each sub-style to a rRESPA level, following their order
of definition in the pair_style command. Since the <em>hybrid</em> keyword
operates on pair style computations, it is mututally exclusive with
either the <em>pair</em> or the <em>inner</em>/<em>middle</em>/<em>outer</em> keywords.</p>
<p>When using rRESPA (or for any MD simulation) care must be taken to
choose a timestep size(s) that insures the Hamiltonian for the chosen
ensemble is conserved. For the constant NVE ensemble, total energy
must be conserved. Unfortunately, it is difficult to know <em>a priori</em>
how well energy will be conserved, and a fairly long test simulation
(~10 ps) is usually necessary in order to verify that no long-term
drift in energy occurs with the trial set of parameters.</p>
<p>With that caveat, a few rules-of-thumb may be useful in selecting
<em>respa</em> settings. The following applies mostly to biomolecular
simulations using the CHARMM or a similar all-atom force field, but
the concepts are adaptable to other problems. Without SHAKE, bonds
involving hydrogen atoms exhibit high-frequency vibrations and require
a timestep on the order of 0.5 fmsec in order to conserve energy. The
relatively inexpensive force computations for the bonds, angles,
impropers, and dihedrals can be computed on this innermost 0.5 fmsec
step. The outermost timestep cannot be greater than 4.0 fmsec without
risking energy drift. Smooth switching of forces between the levels
of the rRESPA hierarchy is also necessary to avoid drift, and a 1-2
angstrom “healing distance” (the distance between the outer and inner
cutoffs) works reasonably well. We thus recommend the following
settings for use of the <em>respa</em> style without SHAKE in biomolecular
<p>The <em>respa/omp</em> styles is a variant of <em>respa</em> adapted for use with
pair, bond, angle, dihedral, improper, or kspace styles with an <em>omp</em>
suffix. It is functionally equivalent to <em>respa</em> but performs additional
operations required for managing <em>omp</em> styles. For more on <em>omp</em> styles
see the <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual.
Accelerated styles take the same arguments and should produce the same
results, except for round-off and precision issues.</p>
<p>You can specify <em>respa/omp</em> explicitly in your input script, or
you can use the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">-suffix command-line switch</span></a>
when you invoke LAMMPS, or you can use the <a class="reference internal" href="suffix.html"><span class="doc">suffix</span></a>
command in your input script.</p>
<p>See <a class="reference internal" href="Section_accelerate.html"><span class="doc">Section 5</span></a> of the manual for
more instructions on how to use the accelerated styles effectively.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>The <em>verlet/split</em> style can only be used if LAMMPS was built with the
REPLICA package. Correspondingly the <em>respa/omp</em> style is available only
if the USER-OMP package was included. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a>
section for more info on packages.</p>
<p>Whenever using rRESPA, the user should experiment with trade-offs in
speed and accuracy for their system, and verify that they are
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>.
<li><p class="first">compute-ID = ID of the compute used for event detection</p>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>min</em> or <em>neb</em> or <em>min_style</em> or <em>neb_style</em> or <em>neb_log</em></p>
<pre class="literal-block">
<em>min</em> values = etol ftol maxiter maxeval
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
maxiter = max iterations of minimize
maxeval = max number of force/energy evaluations
<em>neb</em> values = ftol N1 N2 Nevery
etol = stopping tolerance for energy (energy units)
ftol = stopping tolerance for force (force units)
N1 = max # of iterations (timesteps) to run initial NEB
N2 = max # of iterations (timesteps) to run barrier-climbing NEB
Nevery = print NEB statistics every this many timesteps
<em>neb_style</em> value = <em>quickmin</em> or <em>fire</em>
<em>neb_step</em> value = dtneb
dtneb = timestep for NEB damped dynamics minimization
<em>neb_log</em> value = file where NEB statistics are printed
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<pre class="literal-block">
tad 2000 50 1800 2300 0.01 0.01 event
tad 2000 50 1800 2300 0.01 0.01 event &
min 1e-05 1e-05 100 100 &
neb 0.0 0.01 200 200 20 &
min_style cg &
neb_style fire &
neb_log log.neb
</pre>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Run a temperature accelerated dynamics (TAD) simulation. This method
requires two or more partitions to perform NEB transition state
searches.</p>
<p>TAD is described in <a class="reference internal" href="#voter"><span class="std std-ref">this paper</span></a> by Art Voter. It is a method
that uses accelerated dynamics at an elevated temperature to generate
results at a specified lower temperature. A good overview of
accelerated dynamics methods for such systems is given in <a class="reference internal" href="#voter2"><span class="std std-ref">this review paper</span></a> from the same group. In general, these methods assume
that the long-time dynamics is dominated by infrequent events i.e. the
system is is confined to low energy basins for long periods,
punctuated by brief, randomly-occurring transitions to adjacent
basins. TAD is suitable for infrequent-event systems, where in
addition, the transition kinetics are well-approximated by harmonic
transition state theory (hTST). In hTST, the temperature dependence of
transition rates follows the Arrhenius relation. As a consequence a
set of event times generated in a high-temperature simulation can be
mapped to a set of much longer estimated times in the low-temperature
system. However, because this mapping involves the energy barrier of
the transition event, which is different for each event, the first
event at the high temperature may not be the earliest event at the low
temperature. TAD handles this by first generating a set of possible
events from the current basin. After each event, the simulation is
reflected backwards into the current basin. This is repeated until
the stopping criterion is satisfied, at which point the event with the
earliest low-temperature occurrence time is selected. The stopping
criterion is that the confidence measure be greater than
1-<em>delta</em>. The confidence measure is the probability that no earlier
low-temperature event will occur at some later time in the
high-temperature simulation. hTST provides an lower bound for this
probability, based on the user-specified minimum pre-exponential
factor (reciprocal of <em>tmax</em>).</p>
<p>In order to estimate the energy barrier for each event, the TAD method
invokes the <a class="reference internal" href="neb.html"><span class="doc">NEB</span></a> method. Each NEB replica runs on a
partition of processors. The current NEB implementation in LAMMPS
restricts you to having exactly one processor per replica. For more
information, see the documentation for the <a class="reference internal" href="neb.html"><span class="doc">neb</span></a> command. In
the current LAMMPS implementation of TAD, all the non-NEB TAD
operations are performed on the first partition, while the other
partitions remain idle. See <a class="reference internal" href="Section_howto.html#howto-5"><span class="std std-ref">Section 6.5</span></a> of the manual for further discussion of
multi-replica simulations.</p>
<p>A TAD run has several stages, which are repeated each time an event is
performed. The logic for a TAD run is as follows:</p>
<pre class="literal-block">
while (time remains):
while (time < tstop):
until (event occurs):
run dynamics for t_event steps
quench
run neb calculation using all replicas
compute tlo from energy barrier
update earliest event
update tstop
reflect back into current basin
execute earliest event
</pre>
<p>Before this outer loop begins, the initial potential energy basin is
identified by quenching (an energy minimization, see below) the
initial state and storing the resulting coordinates for reference.</p>
<p>Inside the inner loop, dynamics is run continuously according to
whatever integrator has been specified by the user, stopping every
<em>t_event</em> steps to check if a transition event has occurred. This
check is performed by quenching the system and comparing the resulting
atom coordinates to the coordinates from the previous basin.</p>
<p>A quench is an energy minimization and is performed by whichever
algorithm has been defined by the <a class="reference internal" href="min_style.html"><span class="doc">min_style</span></a> command;
its default is the CG minimizer. The tolerances and limits for each
quench can be set by the <em>min</em> keyword. Note that typically, you do
not need to perform a highly-converged minimization to detect a
transition event.</p>
<p>The event check is performed by a compute with the specified
<em>compute-ID</em>. Currently there is only one compute that works with the
TAD commmand, which is the <a class="reference internal" href="compute_event_displace.html"><span class="doc">compute event/displace</span></a> command. Other
event-checking computes may be added. <a class="reference internal" href="compute_event_displace.html"><span class="doc">Compute event/displace</span></a> checks whether any atom in
the compute group has moved further than a specified threshold
distance. If so, an “event” has occurred.</p>
<p>The NEB calculation is similar to that invoked by the <a class="reference internal" href="neb.html"><span class="doc">neb</span></a>
command, except that the final state is generated internally, instead
of being read in from a file. The style of minimization performed by
NEB is determined by the <em>neb_style</em> keyword and must be a damped
dynamics minimizer. The tolerances and limits for each NEB
calculation can be set by the <em>neb</em> keyword. As discussed on the
<a class="reference internal" href="neb.html"><span class="doc">neb</span></a>, it is often advantageous to use a larger timestep for
NEB than for normal dyanmics. Since the size of the timestep set by
the <a class="reference internal" href="timestep.html"><span class="doc">timestep</span></a> command is used by TAD for performing
dynamics, there is a <em>neb_step</em> keyword which can be used to set a
larger timestep for each NEB calculation if desired.</p>
<hr class="docutils" />
<p>A key aspect of the TAD method is setting the stopping criterion
appropriately. If this criterion is too conservative, then many
events must be generated before one is finally executed. Conversely,
if this criterion is too aggressive, high-entropy high-barrier events
will be over-sampled, while low-entropy low-barrier events will be
under-sampled. If the lowest pre-exponential factor is known fairly
accurately, then it can be used to estimate <em>tmax</em>, and the value of
<em>delta</em> can be set to the desired confidence level e.g. <em>delta</em> = 0.05
corresponds to 95% confidence. However, for systems where the dynamics
are not well characterized (the most common case), it will be
necessary to experiment with the values of <em>delta</em> and <em>tmax</em> to get a
good trade-off between accuracy and performance.</p>
<p>A second key aspect is the choice of <em>t_hi</em>. A larger value greatly
increases the rate at which new events are generated. However, too
large a value introduces errors due to anharmonicity (not accounted
for within hTST). Once again, for any given system, experimentation is
necessary to determine the best value of <em>t_hi</em>.</p>
<hr class="docutils" />
<p>Five kinds of output can be generated during a TAD run: event
statistics, NEB statistics, thermodynamic output by each replica, dump
files, and restart files.</p>
<p>Event statistics are printed to the screen and master log.lammps file
each time an event is executed. The quantities are the timestep, CPU
time, global event number <em>N</em>, local event number <em>M</em>, event status,
energy barrier, time margin, <em>t_lo</em> and <em>delt_lo</em>. The timestep is
the usual LAMMPS timestep, which corresponds to the high-temperature
time at which the event was detected, in units of timestep. The CPU
time is the total processor time since the start of the TAD run. The
global event number <em>N</em> is a counter that increments with each
executed event. The local event number <em>M</em> is a counter that resets to
zero upon entering each new basin. The event status is <em>E</em> when an
event is executed, and is <em>D</em> for an event that is detected, while
<em>DF</em> is for a detected event that is also the earliest (first) event
at the low temperature.</p>
<p>The time margin is the ratio of the high temperature time in the
current basin to the stopping time. This last number can be used to
judge whether the stopping time is too short or too long (see above).</p>
<p><em>t_lo</em> is the low-temperature event time when the current basin was
entered, in units of timestep. del*t_lo* is the time of each detected
event, measured relative to <em>t_lo</em>. <em>delt_lo</em> is equal to the
high-temperature time since entering the current basin, scaled by an
exponential factor that depends on the hi/lo temperature ratio and the
energy barrier for that event.</p>
<p>On lines for executed events, with status <em>E</em>, the global event number
is incremented by one,
the local event number and time margin are reset to zero,
while the global event number, energy barrier, and
<em>delt_lo</em> match the last event with status <em>DF</em>
in the immediately preceding block of detected events.
The low-temperature event time <em>t_lo</em> is incremented by <em>delt_lo</em>.</p>
<p>NEB statistics are written to the file specified by the <em>neb_log</em>
keyword. If the keyword value is “none”, then no NEB statistics are
printed out. The statistics are written every <em>Nevery</em> timesteps. See
the <a class="reference internal" href="neb.html"><span class="doc">neb</span></a> command for a full description of the NEB
statistics. When invoked from TAD, NEB statistics are never printed to
the screen.</p>
<p>Because the NEB calculation must run on multiple partitions, LAMMPS
produces additional screen and log files for each partition,
e.g. log.lammps.0, log.lammps.1, etc. For the TAD command, these
contain the thermodynamic output of each NEB replica. In addition, the
log file for the first partition, log.lammps.0, will contain
thermodynamic output from short runs and minimizations corresponding
to the dynamics and quench operations, as well as a line for each new
detected event, as described above.</p>
<p>After the TAD command completes, timing statistics for the TAD run are
printed in each replica’s log file, giving a breakdown of how much CPU
time was spent in each stage (NEB, dynamics, quenching, etc).</p>
<p>Any <a class="reference internal" href="dump.html"><span class="doc">dump files</span></a> defined in the input script will be written
to during a TAD run at timesteps when an event is executed. This
means the the requested dump frequency in the <a class="reference internal" href="dump.html"><span class="doc">dump</span></a> command
is ignored. There will be one dump file (per dump command) created
for all partitions. The atom coordinates of the dump snapshot are
those of the minimum energy configuration resulting from quenching
following the executed event. The timesteps written into the dump
files correspond to the timestep at which the event occurred and NOT
the clock. A dump snapshot corresponding to the initial minimum state
used for event detection is written to the dump file at the beginning
of each TAD run.</p>
<p>If the <a class="reference internal" href="restart.html"><span class="doc">restart</span></a> command is used, a single restart file
for all the partitions is generated, which allows a TAD run to be
continued by a new input script in the usual manner. The restart file
is generated after an event is executed. The restart file contains a
snapshot of the system in the new quenched state, including the event
number and the low-temperature time. The restart frequency specified
in the <a class="reference internal" href="restart.html"><span class="doc">restart</span></a> command is interpreted differently when
performing a TAD run. It does not mean the timestep interval between
restart files. Instead it means an event interval for executed
events. Thus a frequency of 1 means write a restart file every time
an event is executed. A frequency of 10 means write a restart file
every 10th executed event. When an input script reads a restart file
from a previous TAD run, the new script can be run on a different
number of replicas or processors.</p>
<p>Note that within a single state, the dynamics will typically
temporarily continue beyond the event that is ultimately chosen, until
the stopping criterionis satisfied. When the event is eventually
executed, the timestep counter is reset to the value when the event
was detected. Similarly, after each quench and NEB minimization, the
timestep counter is reset to the value at the start of the
minimization. This means that the timesteps listed in the replica log
files do not always increase monotonically. However, the timestep
values printed to the master log file, dump files, and restart files
are always monotonically increasing.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command can only be used if LAMMPS was built with the REPLICA
package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section
for more info on packages.</p>
<p><em>N</em> setting must be integer multiple of <em>t_event</em>.</p>
<p>Runs restarted from restart files written during a TAD run will only
produce identical results if the user-specified integrator supports
exact restarts. So <a class="reference internal" href="fix_nh.html"><span class="doc">fix nvt</span></a> will produce an exact
restart, but <a class="reference internal" href="fix_langevin.html"><span class="doc">fix langevin</span></a> will not.</p>
<p>This command cannot be used when any fixes are defined that keep track
of elapsed time to perform time-dependent operations. Examples
include the “ave” fixes such as <a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a>.
Also <a class="reference internal" href="fix_dt_reset.html"><span class="doc">fix dt/reset</span></a> and <a class="reference internal" href="fix_deposit.html"><span class="doc">fix deposit</span></a>.</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>.
<p>Run a parallel tempering or replica exchange simulation using multiple
replicas (ensembles) of a system. Two or more replicas must be used.</p>
<p>Each replica runs on a partition of one or more processors. Processor
partitions are defined at run-time using the -partition command-line
switch; see <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">Section 2.7</span></a> of the
manual. Note that if you have MPI installed, you can run a
multi-replica simulation with more replicas (partitions) than you have
physical processors, e.g you can run a 10-replica simulation on one or
two processors. You will simply not get the performance speed-up you
would see with one or more physical processors per replica. See <a class="reference internal" href="Section_howto.html#howto-5"><span class="std std-ref">this section</span></a> of the manual for further
discussion.</p>
<p>Each replica’s temperature is controlled at a different value by a fix
with <em>fix-ID</em> that controls temperature. Most thermostat fix styles
(with and without included time integration) are supported. The command
will print an error message and abort, if the chosen fix is unsupported.
The desired temperature is specified by <em>temp</em>, which is typically a
variable previously set in the input script, so that each partition is
assigned a different temperature. See the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>
command for more details. For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>variable t world 300.0 310.0 320.0 330.0
fix myfix all nvt temp $t $t 100.0
temper 100000 100 $t myfix 3847 58382
</pre></div>
</div>
<p>would define 4 temperatures, and assign one of them to the thermostat
used by each replica, and to the temper command.</p>
<p>As the tempering simulation runs for <em>N</em> timesteps, a temperature swap
between adjacent ensembles will be attempted every <em>M</em> timesteps. If
<em>seed1</em> is 0, then the swap attempts will alternate between odd and
even pairings. If <em>seed1</em> is non-zero then it is used as a seed in a
random number generator to randomly choose an odd or even pairing each
time. Each attempted swap of temperatures is either accepted or
rejected based on a Boltzmann-weighted Metropolis criterion which uses
<em>seed2</em> in the random number generator.</p>
<p>As a tempering run proceeds, multiple log files and screen output
files are created, one per replica. By default these files are named
log.lammps.M and screen.M where M is the replica number from 0 to N-1,
with N = # of replicas. See the <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">section on command-line switches</span></a> for info on how to change these
names.</p>
<p>The main screen and log file (log.lammps) will list information about
which temperature is assigned to each replica at each thermodynamic
output timestep. E.g. for a simulation with 16 replicas:</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>.
<p>The kinetic energy of the system <em>ke</em> is inferred from the temperature
of the system with 1/2 Kb T of energy for each degree of freedom.
Thus, using different <a class="reference internal" href="compute.html"><span class="doc">compute commands</span></a> for calculating
temperature, via the <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify temp</span></a> command,
may yield different kinetic energies, since different computes that
calculate temperature can subtract out different non-thermal
components of velocity and/or include different degrees of freedom
(translational, rotational, etc).</p>
<p>The potential energy of the system <em>pe</em> will include contributions
from fixes if the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify thermo</span></a> option is set
for a fix that calculates such a contribution. For example, the <a class="reference internal" href="fix_wall.html"><span class="doc">fix wall/lj93</span></a> fix calculates the energy of atoms
interacting with the wall. See the doc pages for “individual fixes”
to see which ones contribute.</p>
<p>A long-range tail correction <em>etail</em> for the VanderWaal pairwise
energy will be non-zero only if the <a class="reference internal" href="pair_modify.html"><span class="doc">pair_modify tail</span></a> option is turned on. The <em>etail</em> contribution
is included in <em>evdwl</em>, <em>epair</em>, <em>pe</em>, and <em>etotal</em>, and the
corresponding tail correction to the pressure is included in <em>press</em>
and <em>pxx</em>, <em>pyy</em>, etc.</p>
<hr class="docutils" />
<p>The <em>step</em>, <em>elapsed</em>, and <em>elaplong</em> keywords refer to timestep
count. <em>Step</em> is the current timestep, or iteration count when a
<a class="reference internal" href="minimize.html"><span class="doc">minimization</span></a> is being performed. <em>Elapsed</em> is the
number of timesteps elapsed since the beginning of this run.
<em>Elaplong</em> is the number of timesteps elapsed since the beginning of
an initial run in a series of runs. See the <em>start</em> and <em>stop</em>
keywords for the <a class="reference internal" href="run.html"><span class="doc">run</span></a> for info on how to invoke a series of
runs that keep track of an initial starting time. If these keywords
are not used, then <em>elapsed</em> and <em>elaplong</em> are the same value.</p>
<p>The <em>dt</em> keyword is the current timestep size in time
<a class="reference internal" href="units.html"><span class="doc">units</span></a>. The <em>time</em> keyword is the current elapsed
simulation time, also in time <a class="reference internal" href="units.html"><span class="doc">units</span></a>, which is simply
(step*dt) if the timestep size has not changed and the timestep has
not been reset. If the timestep has changed (e.g. via <a class="reference internal" href="fix_dt_reset.html"><span class="doc">fix dt/reset</span></a>) or the timestep has been reset (e.g. via
the “reset_timestep” command), then the simulation time is effectively
a cummulative value up to the current point.</p>
<p>The <em>cpu</em> keyword is elapsed CPU seconds since the beginning of this
run. The <em>tpcpu</em> and <em>spcpu</em> keywords are measures of how fast your
simulation is currently running. The <em>tpcpu</em> keyword is simulation
time per CPU second, where simulation time is in time
<a class="reference internal" href="units.html"><span class="doc">units</span></a>. E.g. for metal units, the <em>tpcpu</em> value would be
picoseconds per CPU second. The <em>spcpu</em> keyword is the number of
timesteps per CPU second. Both quantities are on-the-fly metrics,
measured relative to the last time they were invoked. Thus if you are
printing out thermodyamic output every 100 timesteps, the two keywords
will continually output the time and timestep rate for the last 100
steps. The <em>tpcpu</em> keyword does not attempt to track any changes in
timestep size, e.g. due to using the <a class="reference internal" href="fix_dt_reset.html"><span class="doc">fix dt/reset</span></a>
command.</p>
<p>The <em>cpuremain</em> keyword estimates the CPU time remaining in the
current run, based on the time elapsed thus far. It will only be a
good estimate if the CPU time/timestep for the rest of the run is
similar to the preceding timesteps. On the initial timestep the value
will be 0.0 since there is no history to estimate from. For a
minimization run performed by the “minimize” command, the estimate is
based on the <em>maxiter</em> parameter, assuming the minimization will
proceed for the maximum number of allowed iterations.</p>
<p>The <em>part</em> keyword is useful for multi-replica or multi-partition
simulations to indicate which partition this output and this file
corresponds to, or for use in a <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> to append to
a filename for output specific to this partition. See <a class="reference internal" href="Section_start.html#start-7"><span class="std std-ref">Section 2.7</span></a> of the manual for details on running
in multi-partition mode.</p>
<p>The <em>timeremain</em> keyword returns the remaining seconds when a
timeout has been configured via the <a class="reference internal" href="timer.html"><span class="doc">timer timeout</span></a> command.
If the timeout timer is inactive, the value of this keyword is 0.0 and
if the timer is expired, it is negative. This allows for example to exit
loops cleanly, if the timeout is expired with:</p>
<em>cellgamma</em>, correspond to the usual crystallographic quantities that
define the periodic unit cell of a crystal. See <a class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">this section</span></a> of the doc pages for a geometric
description of triclinic periodic cells, including a precise defintion
of these quantities in terms of the internal LAMMPS cell dimensions
per-atom, or local values. Only global values can be referenced by
this command. However, per-atom compute values for an individual atom
can be referenced in a <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> and the variable
referenced by thermo_style custom, as discussed below. See the
discussion above for how the I in <em>c_ID[I]</em> can be specified with a
wildcard asterisk to effectively specify multiple values from a global
compute vector.</p>
<p>The ID in the keyword should be replaced by the actual ID of a compute
that has been defined elsewhere in the input script. See the
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> command for details. If the compute calculates
a global scalar, vector, or array, then the keyword formats with 0, 1,
or 2 brackets will reference a scalar value from the compute.</p>
<p>Note that some computes calculate “intensive” global quantities like
temperature; others calculate “extensive” global quantities like
kinetic energy that are summed over all atoms in the compute group.
Intensive quantities are printed directly without normalization by
thermo_style custom. Extensive quantities may be normalized by the
total number of atoms in the simulation (NOT the number of atoms in
the compute group) when output, depending on the <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify norm</span></a> option being used.</p>
<p>The <em>f_ID</em> and <em>f_ID[I]</em> and <em>f_ID[I][J]</em> keywords allow global
values calculated by a fix to be output. As discussed on the
<a class="reference internal" href="fix.html"><span class="doc">fix</span></a> doc page, fixes can calculate global, per-atom, or
local values. Only global values can be referenced by this command.
However, per-atom fix values can be referenced for an individual atom
in a <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> and the variable referenced by
thermo_style custom, as discussed below. See the discussion above for
how the I in <em>f_ID[I]</em> can be specified with a wildcard asterisk to
effectively specify multiple values from a global fix vector.</p>
<p>The ID in the keyword should be replaced by the actual ID of a fix
that has been defined elsewhere in the input script. See the
<a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command for details. If the fix calculates a global
scalar, vector, or array, then the keyword formats with 0, 1, or 2
brackets will reference a scalar value from the fix.</p>
<p>Note that some fixes calculate “intensive” global quantities like
timestep size; others calculate “extensive” global quantities like
energy that are summed over all atoms in the fix group. Intensive
quantities are printed directly without normalization by thermo_style
custom. Extensive quantities may be normalized by the total number of
atoms in the simulation (NOT the number of atoms in the fix group)
when output, depending on the <a class="reference internal" href="thermo_modify.html"><span class="doc">thermo_modify norm</span></a>
option being used.</p>
<p>The <em>v_name</em> keyword allow the current value of a variable to be
output. The name in the keyword should be replaced by the variable
name that has been defined elsewhere in the input script. Only
equal-style and vector-style variables can be referenced; the latter
requires a bracketed term to specify the Ith element of the vector
calculated by the variable. However, an atom-style variable can be
referenced for an individual atom by an equal-style variable and that
variable referenced. See the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command for
details. Variables of style <em>equal</em> and <em>vector</em> and <em>atom</em> define a
formula which can reference per-atom properties or thermodynamic
keywords, or they can invoke other computes, fixes, or variables when
evaluated, so this is a very general means of creating thermodynamic
output.</p>
<p>Note that equal-style and vector-style variables are assumed to
produce “intensive” global quantities, which are thus printed as-is,
without normalization by thermo_style custom. You can include a
division by “natoms” in the variable formula if this is not the case.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>This command must come after the simulation box is defined by a
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>.