2006-09-22 00:22:34 +08:00
< HTML >
< CENTER > < A HREF = "http://lammps.sandia.gov" > LAMMPS WWW Site< / A > - < A HREF = "Manual.html" > LAMMPS Documentation< / A > - < A HREF = "Section_commands.html#comm" > LAMMPS Commands< / A >
< / CENTER >
< HR >
< H3 > dump_modify command
< / H3 >
< P > < B > Syntax:< / B >
< / P >
2007-07-03 03:59:56 +08:00
< PRE > dump_modify dump-ID keyword values ...
2006-09-22 00:22:34 +08:00
< / PRE >
< UL > < LI > dump-ID = ID of dump to modify
2007-07-03 03:59:56 +08:00
< LI > one or more keyword/value pairs may be appended
2006-09-22 00:22:34 +08:00
2009-12-18 07:42:38 +08:00
< LI > keyword = < I > append< / I > or < I > every< / I > or < I > flush< / I > or < I > format< / I > or < I > image< / I > or < I > label< / I > or < I > precision< / I > or < I > region< / I > or < I > scale< / I > or < I > sort< / I > or < I > thresh< / I > or < I > unwrap< / I >
2006-09-22 00:22:34 +08:00
2009-09-05 03:40:03 +08:00
< PRE > < I > append< / I > arg = < I > yes< / I > or < I > no< / I >
< I > element< / I > args = E1 E2 ... EN, where N = # of atom types
2009-09-03 00:20:52 +08:00
E1,...,EN = element name, e.g. C or Fe or Ga
2006-09-22 00:22:34 +08:00
< I > every< / I > arg = N
N = dump every this many timesteps
2010-08-06 07:19:40 +08:00
N can be a variable (see below)
2010-03-03 06:52:34 +08:00
< I > first< / I > arg = < I > yes< / I > or < I > no< / I >
2009-09-03 00:20:52 +08:00
< I > format< / I > arg = C-style format string for one line of output
< I > flush< / I > arg = < I > yes< / I > or < I > no< / I >
< I > image< / I > arg = < I > yes< / I > or < I > no< / I >
2009-12-18 07:42:38 +08:00
< I > label< / I > arg = string
string = character string (e.g. BONDS) to use in header of dump local file
2008-01-18 02:29:47 +08:00
< I > precision< / I > arg = power-of-10 value from 10 to 1000000
2006-09-22 00:22:34 +08:00
< I > region< / I > arg = region-ID or "none"
2009-09-03 00:20:52 +08:00
< I > scale< / I > arg = < I > yes< / I > or < I > no< / I >
2010-09-16 06:15:54 +08:00
< I > sort< / I > arg = < I > off< / I > or 0 or N
off = no sorting of per-atom lines within a snapshot
0 = sort per-atom lines by atom ID
N = sort per-atom lines by the Nth column
2006-09-22 00:22:34 +08:00
< I > thresh< / I > args = attribute operation value
2006-11-11 05:28:48 +08:00
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
2007-06-20 20:56:17 +08:00
operation = "< " or "< =" or ">" or ">=" or "==" or "!="
2006-09-22 00:22:34 +08:00
value = numeric value to compare to
2008-03-01 09:13:20 +08:00
these 3 args can be replaced by the word "none" to turn off thresholding
2009-09-03 00:20:52 +08:00
< I > unwrap< / I > arg = < I > yes< / I > or < I > no< / I >
2006-09-22 00:22:34 +08:00
< / PRE >
< / UL >
< P > < B > Examples:< / B >
< / P >
< PRE > dump_modify 1 format "%d %d %20.15g %g %g" scale yes
dump_modify myDump image yes scale no flush yes
2008-01-18 02:29:47 +08:00
dump_modify 1 region mySphere thresh x < 0.0 thresh epair > = 3.2
2010-08-06 07:19:40 +08:00
dump_modify xtcdump precision 10000
dump_modify 1 every 1000
dump_modify 1 every v_myVar
2006-09-22 00:22:34 +08:00
< / PRE >
< P > < B > Description:< / B >
< / P >
< P > Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.
< / P >
2009-09-05 03:40:03 +08:00
< P > The < I > append< / I > keyword applies to all dump styles except < I > cfg< / I > and < I > xtc< / I >
and < I > dcd< / I > . It also applies only to text output files, not to binary
or gzipped files. If specified as < I > yes< / I > , then dump snapshots are
appended to the end of an existing dump file. If specified as < I > no< / I > ,
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 < A HREF = "dump.html" > dump< / A > command, but
before the first command that causes dump snapshots to be output,
e.g. a < A HREF = "run.html" > run< / A > or < A HREF = "minimize.html" > minimize< / A > command. Once the
dump file has been opened, this keyword has no further effect.
< / P >
2009-09-03 00:20:52 +08:00
< P > The < I > element< / I > keyword applies only to the the dump < I > cfg< / I > style. It
associates element names (e.g. H, C, Fe) with LAMMPS atom types, so
that the < A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A" > AtomEye< / A >
visualization package can render atoms with the appropriate size and
color. 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 > The < I > every< / I > keyword changes the dump frequency originally specified by
2010-08-06 07:19:40 +08:00
the < A HREF = "dump.html" > dump< / 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 < A HREF = "variable.html" > equal-style variable< / A > ,
2010-08-13 07:10:38 +08:00
which should be specified as v_name, where name is the variable name.
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
2010-08-06 07:19:40 +08:00
timestep values. See the stagger() and logfreq() math functions for
< A HREF = "variable.html" > equal-style variables< / A > , as examples of useful functions
to use in this context. Other similar math functions could easily be
added as options for < A HREF = "variable.html" > equal-style variables< / A > . When
using the variable option with the < I > every< / I > keyword, you also need to
use the < I > first< / I > option if you want an initial snapshot written to the
dump file. The < I > every< / I > keyword cannot be used with the dump < I > dcd< / I >
style.
2009-09-03 00:20:52 +08:00
< / P >
2010-08-06 07:19:40 +08:00
< P > For example, the following commands will
write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
< / P >
< PRE > variable s equal logfreq(10,3,10)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes
< / PRE >
2010-03-03 06:52:34 +08:00
< P > The < I > first< / I > keyword determines whether a dump snapshot is written on
the very first timestep after the dump command is invoked. This will
always occur if the current timestep is a multiple of N, the frequency
specified in the < A HREF = "dump.html" > dump< / A > command, including timestep 0. But
if this is not the case, a dump snapshot will only be written if the
setting of this keyword is < I > yes< / I > . If it is < I > no< / I > , which is the
default, then it will not be written.
< / P >
2010-08-11 22:30:24 +08:00
< P > The < I > flush< / I > keyword determines whether a flush operation is invoked
2009-09-03 00:20:52 +08:00
after a dump snapshot is written to the dump file. A flush insures
the output in that file is current (no buffering by the OS), even if
LAMMPS halts before the simulation completes. Flushes cannot be
performed with dump style < I > xtc< / I > .
< / P >
2006-09-22 00:22:34 +08:00
< P > The text-based dump styles have a default C-style format string which
simply specifies %d for integers and %g for real values. The < I > format< / I >
keyword can be used to override the default with a new C-style format
string. Do not include a trailing "\n" newline character in the
format string. This option has no effect on the < I > dcd< / I > and < I > xtc< / I > dump
2009-09-03 00:20:52 +08:00
styles since they write binary files. Note that for the < I > cfg< / I > style,
the first two fields (atom id and type) are not actually written into
the CFG file, though you must include formats for them in the format
string.
< / P >
< P > The < I > image< / I > keyword applies only to the dump < I > atom< / I > style. If the
image value is < I > yes< / I > , 3 flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
example, an x image flag of -2 with a normalized coord of 0.5 means
the atom is in the center of the box, but has passed thru the box
boundary 2 times and is really 2 box lengths to the left of its
2009-01-13 23:40:11 +08:00
current coordinate. Note that for dump style < I > custom< / I > these various
values can be printed in the dump file by using the appropriate atom
2006-09-22 00:22:34 +08:00
attributes in the dump command itself.
< / P >
2009-12-18 07:42:38 +08:00
< P > The < I > label< / I > keyword applies only to the dump < I > local< / I > style. When
it writes local informatoin, such as bond or angle topology
to a dump file, it will use the specified < I > label< / I > to format
the header. By default this includes 2 lines:
< / P >
< PRE > ITEM: NUMBER OF ENTRIES
ITEM: ENTRIES ...
< / PRE >
< P > The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
< / P >
2009-09-03 00:20:52 +08:00
< P > The < I > precision< / I > keyword only applies to the dump < I > xtc< / I > style. A
2008-01-18 02:29:47 +08:00
specified value of N means that coordinates are stored to 1/N
nanometer accuracy, e.g. for N = 1000, the coordinates are written to
1/1000 nanometer accuracy.
< / P >
2009-09-03 00:20:52 +08:00
< P > The < I > region< / I > keyword only applies to the dump < I > custom< / I > and < I > cfg< / I >
styles. If specified, only atoms in the region will be written to the
dump file. Only one region can be applied as a filter (the last one
specified). See the < A HREF = "region.html" > region< / 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 >
< P > The < I > scale< / I > keyword applies only to the dump < I > atom< / I > style. A scale
value of < I > yes< / I > 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 < I > no< / I > means they are written in absolute distance units
(e.g. Angstroms or sigma).
< / P >
2010-09-16 06:15:54 +08:00
< P > The < I > sort< / I > keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of < I > off< / I > means they will
typically be written in indeterminate order, either in serial or
parallel. This is the case even in serial if the < A HREF = "atom_modify.html" > atom_modify
sort< / A > option is turned on, which it is by default, to
improve performance. A sort value of 0 means sort the output by atom
ID. A sort value of N means sort the output by the value in the Nth
column of per-atom info. The dump < I > local< / I > style cannot be sorted by
atom ID, since there are typically multiple lines of output per atom.
Some dump styles, such as < I > dcd< / I > and < I > xtc< / I > , require sorting by atom
ID to format the output file correctly.
< / P >
< P > IMPORTANT NOTE: 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.
2009-09-03 04:56:46 +08:00
< / P >
2009-09-03 00:20:52 +08:00
< P > The < I > thresh< / I > keyword only applies to the dump < I > custom< / I > and < I > cfg< / I >
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. The possible attributes that can be tested for are the
2006-09-22 00:22:34 +08:00
same as those that can be specified in the < A HREF = "dump.html" > dump custom< / A >
command. Note that different attributes can be output by the dump
2008-03-01 09:13:20 +08:00
custom command than are used as threshold criteria by the dump_modify
2006-09-22 00:22:34 +08:00
command. E.g. you can output the coordinates and stress of atoms
2008-03-01 09:13:20 +08:00
whose energy is above some threshold.
2006-09-22 00:22:34 +08:00
< / P >
2009-09-03 00:20:52 +08:00
< P > The < I > unwrap< / I > keyword only applies to the dump < I > dcd< / I > and < I > xtc< / I > styles.
If set to < I > yes< / I > , 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 >
2006-09-22 00:22:34 +08:00
< P > < B > Restrictions:< / B > none
< / P >
< P > < B > Related commands:< / B >
< / P >
< P > < A HREF = "dump.html" > dump< / A > , < A HREF = "undump.html" > undump< / A >
< / P >
< P > < B > Default:< / B >
< / P >
2009-09-03 00:20:52 +08:00
< P > The option defaults are
< / P >
2009-09-05 03:40:03 +08:00
< UL > < LI > append = no
< LI > element = "C" for every atom type
2009-09-03 00:20:52 +08:00
< LI > every = whatever it was set to via the < A HREF = "dump.html" > dump< / A > command
2010-03-03 06:52:34 +08:00
< LI > first = no
2009-09-03 00:20:52 +08:00
< LI > flush = yes (except for the dump < I > xtc< / I > style)
< LI > format = %d and %g for each integer or floating point value
< LI > image = no
2009-12-18 07:42:38 +08:00
< LI > label = ENTRIES
2009-09-03 00:20:52 +08:00
< LI > precision = 1000
< LI > region = none
< LI > scale = yes
2010-09-16 06:15:54 +08:00
< LI > sort = off for dump styles < I > atom< / I > , < I > custom< / I > , < I > cfg< / I > , and < I > local< / I >
< LI > sort = 0 for dump styles < I > dcd< / I > , < I > xtc< / I > , and < I > xyz< / I > meaning sort by atom ID
2009-09-03 00:20:52 +08:00
< LI > thresh = none
< LI > unwrap = no
< / UL >
2006-09-22 00:22:34 +08:00
< / HTML >