Syntax:
dump_modify dump-ID keyword values ...
append arg = yes or no element args = E1 E2 ... EN, where N = # of atom types E1,...,EN = element name, e.g. C or Fe or Ga every arg = N N = dump every this many timesteps N can be a variable (see below) first arg = yes or no format arg = C-style format string for one line of output flush arg = yes or no image arg = yes or no label arg = string string = character string (e.g. BONDS) to use in header of dump local file precision arg = power-of-10 value from 10 to 1000000 region arg = region-ID or "none" scale arg = yes or no sort arg = off or id 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 thresh 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 unwrap arg = yes or no
Examples:
dump_modify 1 format "%d %d %20.15g %g %g" scale yes dump_modify myDump image yes scale no flush yes dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2 dump_modify xtcdump precision 10000 dump_modify 1 every 1000 dump_modify 1 every v_myVar
Description:
Modify the parameters of a previously defined dump command. Not all parameters are relevant to all dump styles.
The append keyword applies to all dump styles except cfg and xtc and dcd. It also applies only to text output files, not to binary or gzipped files. If specified as yes, then dump snapshots are appended to the end of an existing dump file. If specified as no, 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 dump command, but before the first command that causes dump snapshots to be output, e.g. a run or minimize command. Once the dump file has been opened, this keyword has no further effect.
The element keyword applies only to the the dump cfg style. It associates element names (e.g. H, C, Fe) with LAMMPS atom types, so that the AtomEye 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.
The every keyword changes the dump frequency originally specified by the dump 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 equal-style variable, 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 timestep values. See the stagger() and logfreq() math functions for equal-style variables, as examples of useful functions to use in this context. Other similar math functions could easily be added as options for equal-style variables. When using the variable option with the every keyword, you also need to use the first option if you want an initial snapshot written to the dump file. The every keyword cannot be used with the dump dcd style.
For example, the following commands will write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
variable s equal logfreq(10,3,10) dump 1 all atom 100 tmp.dump dump_modify 1 every v_s first yes
The first 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 dump 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 yes. If it is no, which is the default, then it will not be written.
The flush keyword determines whether a flush operation is invoked 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 xtc.
The text-based dump styles have a default C-style format string which simply specifies %d for integers and %g for real values. The format 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 dcd and xtc dump styles since they write binary files. Note that for the cfg 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.
The image keyword applies only to the dump atom style. If the image value is yes, 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 current coordinate. Note that for dump style custom these various values can be printed in the dump file by using the appropriate atom attributes in the dump command itself.
The label keyword applies only to the dump local style. When it writes local informatoin, such as bond or angle topology to a dump file, it will use the specified label to format the header. By default this includes 2 lines:
ITEM: NUMBER OF ENTRIES ITEM: ENTRIES ...
The word "ENTRIES" will be replaced with the string specified, e.g. BONDS or ANGLES.
The precision keyword only applies to the dump xtc style. A 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.
The region keyword only applies to the dump custom and cfg 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 region 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.
The scale keyword applies only to the dump atom style. A scale value of yes 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 no means they are written in absolute distance units (e.g. Angstroms or sigma).
The sort keyword determines whether lines of per-atom output in a snapshot are sorted or not. A sort value of off means they will typically be written in indeterminate order, either in serial or parallel. This is the case even in serial if the atom_modify sort option is turned on, which it is by default, to improve performance. A sort value of id 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. The dump local style cannot be sorted by atom ID, since there are typically multiple lines of output per atom. Some dump styles, such as dcd and xtc, require sorting by atom ID to format the output file correctly.
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, versus unsorted output.
The thresh keyword only applies to the dump custom and cfg 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 same as those that can be specified in the dump custom command. 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.
The unwrap keyword only applies to the dump dcd and xtc styles. If set to yes, 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.
Restrictions: none
Related commands:
Default:
The option defaults are