<li>one or more keyword/value pairs may be appended</li>
<li>these keywords apply to various dump styles</li>
<li>keyword = <em>append</em> or <em>buffer</em> or <em>element</em> or <em>every</em> or <em>fileper</em> or <em>first</em> or <em>flush</em> or <em>format</em> or <em>image</em> or <em>label</em> or <em>nfile</em> or <em>pad</em> or <em>precision</em> or <em>region</em> or <em>scale</em> or <em>sort</em> or <em>thresh</em> or <em>unwrap</em></li>
</ul>
<preclass="literal-block">
<em>append</em> arg = <em>yes</em> or <em>no</em>
<em>buffer</em> arg = <em>yes</em> or <em>no</em>
<em>element</em> args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
<em>every</em> arg = N
N = dump every this many timesteps
N can be a variable (see below)
<em>fileper</em> arg = Np
Np = write one file for every this many processors
<em>tfactor</em> arg = time scaling factor (> 0.0)
<em>sort</em> arg = <em>off</em> or <em>id</em> or N or -N
off = no sorting of per-atom lines within a snapshot
id = sort per-atom lines by atom ID
N = sort per-atom lines in ascending order by the Nth column
-N = sort per-atom lines in descending order by the Nth column
<em>thresh</em> args = attribute operation value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operation = "<" or "<=" or ">" or ">=" or "==" or "!="
value = numeric value to compare to
these 3 args can be replaced by the word "none" to turn off thresholding
<em>unwrap</em> arg = <em>yes</em> or <em>no</em>
</pre>
<ulclass="simple">
<li>these keywords apply only to the <em>image</em> and <em>movie</em><aclass="reference internal"href="dump_image.html"><spanclass="doc">styles</span></a></li>
<li>keyword = <em>acolor</em> or <em>adiam</em> or <em>amap</em> or <em>backcolor</em> or <em>bcolor</em> or <em>bdiam</em> or <em>boxcolor</em> or <em>color</em> or <em>bitrate</em> or <em>framerate</em></li>
</ul>
<preclass="literal-block">
<em>acolor</em> args = type color
type = atom type or range of types (see below)
color = name of color or color1/color2/...
<em>adiam</em> args = type diam
type = atom type or range of types (see below)
diam = diameter of atoms of that type (distance units)
<em>amap</em> args = lo hi style delta N entry1 entry2 ... entryN
lo = number or <em>min</em> = lower bound of range of color map
hi = number or <em>max</em> = upper bound of range of color map
style = 2 letters = "c" or "d" or "s" plus "a" or "f"
"c" for continuous
"d" for discrete
"s" for sequential
"a" for absolute
"f" for fractional
delta = binsize (only used for style "s", otherwise ignored)
binsize = range is divided into bins of this width
N = # of subsequent entries
entry = value color (for continuous style)
value = number or <em>min</em> or <em>max</em> = single value within range
color = name of color used for that value
entry = lo hi color (for discrete style)
lo/hi = number or <em>min</em> or <em>max</em> = lower/upper bound of subset of range
color = name of color used for that subset of values
entry = color (for sequential style)
color = name of color used for a bin of values
<em>backcolor</em> arg = color
color = name of color for background
<em>bcolor</em> args = type color
type = bond type or range of types (see below)
color = name of color or color1/color2/...
<em>bdiam</em> args = type diam
type = bond type or range of types (see below)
diam = diameter of bonds of that type (distance units)
<em>boxcolor</em> arg = color
color = name of color for simulation box lines and processor sub-domain lines
<em>color</em> args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
<p>Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.</p>
<p>As explained on the <aclass="reference internal"href="dump.html"><spanclass="doc">dump</span></a> doc page, the <em>atom/mpiio</em>,
<em>custom/mpiio</em>, and <em>xyz/mpiio</em> dump 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. Thus if a
dump_modify option below is valid for the <em>atom</em> style, it is also
valid for the <em>atom/mpiio</em> style, and similarly for the other styles
which allow for use of MPI-IO.</p>
<p>These keywords apply to various dump styles, including the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump image</span></a> and <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump movie</span></a> styles. The
description gives details.</p>
<hrclass="docutils"/>
<p>The <em>append</em> keyword applies to all dump styles except <em>cfg</em> and <em>xtc</em>
and <em>dcd</em>. It also applies only to text output files, not to binary
or gzipped or image/movie files. If specified as <em>yes</em>, then dump
snapshots are appended to the end of an existing dump file. If
specified as <em>no</em>, then a new dump file will be created which will
overwrite an existing file with the same name. This keyword can only
take effect if the dump_modify command is used after the
<aclass="reference internal"href="dump.html"><spanclass="doc">dump</span></a> command, but before the first command that causes
dump snapshots to be output, e.g. a <aclass="reference internal"href="run.html"><spanclass="doc">run</span></a> or
<aclass="reference internal"href="minimize.html"><spanclass="doc">minimize</span></a> command. Once the dump file has been opened,
this keyword has no further effect.</p>
<hrclass="docutils"/>
<p>The <em>buffer</em> keyword applies only to dump styles <em>atom</em>, <em>cfg</em>,
<em>custom</em>, <em>local</em>, and <em>xyz</em>. It also applies only to text output
files, not to binary or gzipped files. If specified as <em>yes</em>, which
is the default, then each processor writes its output into an internal
text buffer, which is then sent to the processor(s) which perform file
writes, and written by those processors(s) as one large chunk of text.
If specified as <em>no</em>, each processor sends its per-atom data in binary
format to the processor(s) which perform file wirtes, and those
processor(s) format and write it line by line into the output file.</p>
<p>The buffering mode is typically faster since each processor does the
relatively expensive task of formatting the output for its own atoms.
However it requires about twice the memory (per processor) for the
extra buffering.</p>
<hrclass="docutils"/>
<p>The <em>element</em> keyword applies only to the the dump <em>cfg</em>, <em>xyz</em>, and
<em>image</em> styles. It associates element names (e.g. H, C, Fe) with
LAMMPS atom types. See the list of element names at the bottom of
this page.</p>
<p>In the case of dump <em>cfg</em>, this allows the <aclass="reference external"href="http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</a>
visualization package to read the dump file and render atoms with the
appropriate size and color.</p>
<p>In the case of dump <em>image</em>, the output images will follow the same
<aclass="reference external"href="http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</a> convention. An element name is specified for each
atom type (1 to Ntype) in the simulation. The same element name can
be given to multiple atom types.</p>
<p>In the case of <em>xyz</em> format dumps, there are no restrictions to what
label can be used as an element name. Any whitespace separated text
will be accepted.</p>
<hrclass="docutils"/>
<p>The <em>every</em> keyword changes the dump frequency originally specified by
the <aclass="reference internal"href="dump.html"><spanclass="doc">dump</span></a> command to a new value. The every keyword can be
specified in one of two ways. It can be a numeric value in which case
it must be > 0. Or it can be an <aclass="reference internal"href="variable.html"><spanclass="doc">equal-style variable</span></a>,
which should be specified as v_name, where name is the variable name.</p>
<p>In this case, the variable is evaluated at the beginning of a run to
determine the next timestep at which a dump snapshot will be written
out. On that timestep the variable will be evaluated again to
determine the next timestep, etc. Thus the variable should return
timestep values. See the stagger() and logfreq() and stride() math
functions for <aclass="reference internal"href="variable.html"><spanclass="doc">equal-style variables</span></a>, as examples of
useful functions to use in this context. Other similar math functions
could easily be added as options for <aclass="reference internal"href="variable.html"><spanclass="doc">equal-style variables</span></a>. Also see the next() function, which allows
use of a file-style variable which reads successive values from a
file, each time the variable is evaluated. Used with the <em>every</em>
keyword, if the file contains a list of ascending timesteps, you can
output snapshots whenever you wish.</p>
<p>Note that when using the variable option with the <em>every</em> keyword, you
need to use the <em>first</em> option if you want an initial snapshot written
to the dump file. The <em>every</em> keyword cannot be used with the dump
<em>dcd</em> style.</p>
<p>For example, the following commands will
write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:</p>
<pclass="last">Any value written to a text-based dump file that is a per-atom
quantity calculated by a <aclass="reference internal"href="compute.html"><spanclass="doc">compute</span></a> or <aclass="reference internal"href="fix.html"><spanclass="doc">fix</span></a> is
stored internally as a floating-point value. If the value is actually
an integer and you wish it to appear in the text dump file as a
(large) integer, then you need to use an appropriate format. For
coordinates in nanometers and time in picoseconds. I.e. for <em>real</em>
units, LAMMPS defines <em>sfactor</em> = 0.1 and <em>tfactor</em> = 0.001, since the
Angstroms and fmsec used by <em>real</em> units are 0.1 nm and 0.001 psec
respectively. If you are using a units system with distance and time
units far from nm and psec, you may wish to write XTC files with
different units, since the compression algorithm used in XTC files is
most effective when the typical magnitude of position data is between
10.0 and 0.1.</p>
<hrclass="docutils"/>
<p>The <em>region</em> keyword only applies to the dump <em>custom</em>, <em>cfg</em>,
<em>image</em>, and <em>movie</em> styles. If specified, only atoms in the region
will be written to the dump file or included in the image/movie. Only
one region can be applied as a filter (the last one specified). See
the <aclass="reference internal"href="region.html"><spanclass="doc">region</span></a> command for more details. Note that a region
can be defined as the “inside” or “outside” of a geometric shape, and
it can be the “union” or “intersection” of a series of simpler
regions.</p>
<hrclass="docutils"/>
<p>The <em>scale</em> keyword applies only to the dump <em>atom</em> style. A scale
value of <em>yes</em> means atom coords are written in normalized units from
0.0 to 1.0 in each box dimension. If the simluation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. A
value of <em>no</em> means they are written in absolute distance units
(e.g. Angstroms or sigma).</p>
<hrclass="docutils"/>
<p>The <em>sort</em> keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of <em>off</em> means they will
typically be written in indeterminate order, either in serial or
parallel. This is the case even in serial if the <aclass="reference internal"href="atom_modify.html"><spanclass="doc">atom_modify sort</span></a> option is turned on, which it is by default, to
improve performance. A sort value of <em>id</em> means sort the output by
atom ID. A sort value of N or -N means sort the output by the value
in the Nth column of per-atom info in either ascending or descending
order.</p>
<p>The dump <em>local</em> style cannot be sorted by atom ID, since there are
typically multiple lines of output per atom. Some dump styles, such
as <em>dcd</em> and <em>xtc</em>, require sorting by atom ID to format the output
file correctly. If multiple processors are writing the dump file, via
the “%” wildcard in the dump filename, then sorting cannot be
performed.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Unless it is required by the dump style, sorting dump file
output requires extra overhead in terms of CPU and communication cost,
as well as memory, versus unsorted output.</p>
</div>
<hrclass="docutils"/>
<p>The <em>thresh</em> keyword only applies to the dump <em>custom</em>, <em>cfg</em>,
<em>image</em>, and <em>movie</em> styles. Multiple thresholds can be specified.
Specifying “none” turns off all threshold criteria. If thresholds are
specified, only atoms whose attributes meet all the threshold criteria
are written to the dump file or included in the image. The possible
attributes that can be tested for are the same as those that can be
specified in the <aclass="reference internal"href="dump.html"><spanclass="doc">dump custom</span></a> command, with the exception
of the <em>element</em> attribute, since it is not a numeric value. Note
that different attributes can be output by the dump custom command
than are used as threshold criteria by the dump_modify command.
E.g. you can output the coordinates and stress of atoms whose energy
is above some threshold.</p>
<hrclass="docutils"/>
<p>The <em>unwrap</em> keyword only applies to the dump <em>dcd</em> and <em>xtc</em> styles.
If set to <em>yes</em>, coordinates will 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>These keywords apply only to the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump image</span></a> and
<aclass="reference internal"href="dump_image.html"><spanclass="doc">dump movie</span></a> styles. Any keyword that affects an
image, also affects a movie, since the movie is simply a collection of
images. Some of the keywords only affect the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump movie</span></a> style. The descriptions give details.</p>
<hrclass="docutils"/>
<p>The <em>acolor</em> keyword can be used with the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump image</span></a>
command, when its atom color setting is <em>type</em>, to set the color that
atoms of each type will be drawn in the image.</p>
<p>The specified <em>type</em> should be an integer from 1 to Ntypes = the
number of atom types. A wildcard asterisk can be used in place of or
in conjunction with the <em>type</em> argument to specify a range of atom
<p>The <em>bitrate</em> keyword can be used with the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump movie</span></a> command to define the size of the resulting
movie file and its quality via setting how many kbits per second are
to be used for the movie file. Higher bitrates require less
compression and will result in higher quality movies. The quality is
also determined by the compression format and encoder. The default
setting is 2000 kbit/s, which will result in average quality with
older compression formats.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Not all movie file formats supported by dump movie allow the
bitrate to be set. If not, the setting is silently ignored.</p>
</div>
<hrclass="docutils"/>
<p>The <em>boxcolor</em> keyword sets the color of the simulation box drawn
around the atoms in each image as well as the color of processor
sub-domain boundaries. See the “dump image box” command for how to
specify that a box be drawn via the <em>box</em> keyword, and the sub-domain
boundaries via the <em>subbox</em> keyword. The color name can be any of the
140 pre-defined colors (see below) or a color name defined by the
dump_modify color option.</p>
<hrclass="docutils"/>
<p>The <em>color</em> keyword allows definition of a new color name, in addition
to the 140-predefined colors (see below), and associates 3
red/green/blue RGB values with that color name. The color name can
then be used with any other dump_modify keyword that takes a color
name as a value. The RGB values should each be floating point values
between 0.0 and 1.0 inclusive.</p>
<p>When a color name is converted to RGB values, the user-defined color
names are searched first, then the 140 pre-defined color names. This
means you can also use the <em>color</em> keyword to overwrite one of the
pre-defined color names with new RBG values.</p>
<hrclass="docutils"/>
<p>The <em>framerate</em> keyword can be used with the <aclass="reference internal"href="dump_image.html"><spanclass="doc">dump movie</span></a> command to define the duration of the resulting
movie file. Movie files written by the dump <em>movie</em> command have a
default frame rate of 24 frames per second and the images generated
will be converted at that rate. Thus a sequence of 1000 dump images
will result in a movie of about 42 seconds. To make a movie run
longer you can either generate images more frequently or lower the
frame rate. To speed a movie up, you can do the inverse. Using a
frame rate higher than 24 is not recommended, as it will result in
simply dropping the rendered images. It is more efficient to dump
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
