\(\renewcommand{\AA}{\text{Å}}\)
dump_modify command
dump_modify command for image/movie options
Syntax
dump_modify dump-ID keyword values ...
dump-ID = ID of dump to modify
one or more keyword/value pairs may be appended
these keywords apply to various dump styles
keyword = append or at or balance or buffer or colname or delay or element or every or every/time or fileper or first or flush or format or header or image or label or maxfiles or nfile or pad or pbc or precision or region or refresh or scale or sfactor or skip or sort or tfactor or thermo or thresh or time or triclinic/general or types or units or unwrap
append arg = yes or no at arg = N N = index of frame written upon first dump balance arg = yes or no buffer arg = yes or no colname values = ID string, or default string = new column header name ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output or a custom dump keyword or reference to compute, fix, property or variable. delay arg = Dstep Dstep = delay output until this timestep 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 on timesteps which are a multiple of N N can be a variable (see below) every/time arg = Delta Delta = dump once every Delta interval of simulation time (time units) Delta can be a variable (see below) fileper arg = Np Np = write one file for every this many processors first arg = yes or no flush arg = yes or no format args = line string, int string, float string, ID string, or none string = C-style format string ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output or a custom dump keyword or reference to compute, fix, property or variable. header arg = yes or no yes to write the header no to not write the header image arg = yes or no label arg = string string = character string (e.g., BONDS) to use in header of dump local file maxfiles arg = Fmax Fmax = keep only the most recent Fmax snapshots (one snapshot per file) nfile arg = Nf Nf = write this many files, one from each of Nf processors pad arg = Nchar = # of characters to convert timestep to pbc arg = yes or no = remap atoms via periodic boundary conditions precision arg = power-of-10 value from 10 to 1000000 region arg = region-ID or "none" refresh arg = c_ID = compute ID that supports a refresh operation scale arg = yes or no sfactor arg = coordinate scaling factor (> 0.0) skip arg = v_name v_name = variable with name which evaluates to non-zero (skip) or 0 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 tfactor arg = time scaling factor (> 0.0) thermo arg = yes or no thresh args = attribute operator value attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "|^" value = numeric value to compare to, or LAST these 3 args can be replaced by the word "none" to turn off thresholding time arg = yes or no triclinic/general arg = yes or no types value = numeric or labels units arg = yes or no unwrap arg = yes or nothese keywords apply only to the image and movie styles
keyword = acolor or adiam or amap or backcolor or bcolor or bdiam or boxcolor or color or bitrate or framerate
see the dump image doc page for details
these keywords apply only to the /gz and /zstd dump styles
keyword = compression_level
compression_level args = level level = integer specifying the compression level that should be used (see below for supported levels)
these keywords apply only to the /zstd dump styles
keyword = checksum
checksum args = yes or no (add checksum at end of zst file)
these keywords apply only to the vtk* dump style
keyword = binary
binary args = yes or no (select between binary and text mode VTK files)
Examples
dump_modify 1 format line "%d %d %20.15g %g %g" scale yes
dump_modify 1 format float %20.15g scale yes
dump_modify myDump image yes scale no flush yes
dump_modify 1 region mySphere thresh x < 0.0 thresh fx >= 3.2
dump_modify xtcdump precision 10000 sfactor 0.1
dump_modify 1 every 1000 nfile 20
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.
Unless otherwise noted, the following keywords apply to all the various dump styles, including the dump image and dump movie 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 or image/movie 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.
The at keyword only applies to the netcdf dump style. It can only be used if the append yes keyword is also used. The N argument is the index of which frame to append to. A negative value can be specified for N, which means a frame counted from the end of the file. The at keyword can only be used if the dump_modify command is 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 buffer keyword applies only to dump styles atom, cfg, custom, local, and xyz. It also applies only to text output files, not to binary or gzipped files. If specified as yes, 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 no, 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.
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.
Added in version 4May2022.
The colname keyword can be used to change the default header keyword for dump styles: atom, custom, cfg, and local and their compressed, ADIOS variants. The setting for ID string replaces the default text with the provided string. ID can be a positive integer when it represents the column number counting from the left, a negative integer when it represents the column number from the right (i.e. -1 is the last column/keyword), or a custom dump keyword (or compute, fix, property, or variable reference) and then it replaces the string for that specific keyword. For atom dump styles only the keywords “id”, “type”, “x”, “y”, “z”, “ix”, “iy”, “iz” can be accessed via string regardless of whether scaled or unwrapped coordinates were enabled or disabled, and it always assumes 8 columns for indexing regardless of whether image flags are enabled or not. For dump style cfg only changes to the “auxiliary” keywords (6th or later keyword) will become visible.
The colname keyword can be used multiple times. If multiple colname settings refer to the same keyword, the last setting has precedence. A setting of default clears all previous settings, reverting all values to their default names. Using the scale or image keyword will also reset all header keywords to their default values.
The delay keyword applies to all dump styles. No snapshots will be output until the specified Dstep timestep or later. Specifying Dstep < 0 is the same as turning off the delay setting. This is a way to turn off unwanted output early in a simulation, for example, during an equilibration phase.
The element keyword applies only to the dump cfg, xyz, and image 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.
In the case of dump cfg, this allows the AtomEye visualization package to read the dump file and render atoms with the appropriate size and color.
In the case of dump image, the output images will follow the same AtomEye 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.
In the case of xyz format dumps, there are no restrictions to what label can be used as an element name. Any white-space separated text will be accepted.
The every keyword can be used with any dump style except the dcd and xtc styles. It specifies that the output of dump snapshots will now be performed on timesteps which are a multiple of a new \(N\) value, This overrides the dump frequency originally specified by the dump command.
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() and stride() 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. 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 every keyword, if the file contains a list of ascending timesteps, you can output snapshots whenever you wish.
Note that when using the variable option with the every keyword, you 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 following commands would write snapshots at the timesteps listed in file tmp.times:
variable f file tmp.times
variable s equal next(f)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s
Note
When using a file-style variable with the every keyword, the file of timesteps must list a first timestep that is beyond the current timestep (e.g., it cannot be 0). And it must list one or more timesteps beyond the length of the run you perform. This is because the dump command will generate an error if the next timestep it reads from the file is not a value greater than the current timestep. Thus if you wanted output on steps 0,15,100 of a 100-timestep run, the file should contain the values 15,100,101 and you should also use the dump_modify first command. Any final value > 100 could be used in place of 101.
Added in version 7Jan2022.
The every/time keyword can be used with any dump style except the dcd and xtc styles. It changes the frequency of dump snapshots from being based on the current timestep to being determined by elapsed simulation time, i.e. in time units of the units command, and specifies Delta for the interval between snapshots. This can be useful when the timestep size varies during a simulation run, e.g. by use of the fix dt/reset command. The default is to perform output on timesteps which a multiples of specified timestep value \(N\); see the every keyword.
The every/time keyword can be used with any dump style except the dcd and xtc styles. It does two things. It specifies that the interval between dump snapshots will be set in simulation time (i.e. in time units of the units command). This can be useful when the timestep size varies during a simulation run (e.g., by use of the fix dt/reset command). The default is to specify the interval in timesteps; see the every keyword. The every/time command also sets the interval value.
Note
If you wish dump styles atom, custom, local, or xyz to include the simulation time as a field in the header portion of each snapshot, you also need to use the dump_modify time keyword with a setting of yes. See its documentation below.
Note that since snapshots are output on simulation steps, each snapshot will be written on the first timestep whose associated simulation time is >= the exact snapshot time value.
As with the every option, the Delta value can be specified in one of two ways. It can be a numeric value in which case it must be > 0.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 simulation time at which a dump snapshot will be written out. On that timestep the variable will be evaluated again to determine the next simulation time, etc. Thus the variable should return values in time units. Note the current timestep or simulation time can be used in an equal-style variables since they are both thermodynamic keywords. 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 every/time keyword, if the file contains a list of ascending simulation times, you can output snapshots whenever you wish.
Note that when using the variable option with the every/time keyword, you need to use the first option if you want an initial snapshot written to the dump file. The every/time keyword cannot be used with the dump dcd style.
For example, the following commands will write snapshots at successive simulation times which grow by a factor of 1.5 with each interval. The dt value used in the variable is to avoid a zero result when the initial simulation time is 0.0.
variable increase equal 1.5*(time+dt)
dump 1 all atom 100 tmp.dump
dump_modify 1 every/time v_increase first yes
The following commands would write snapshots at the times listed in file tmp.times:
variable f file tmp.times
variable s equal next(f)
dump 1 all atom 100 tmp.dump
dump_modify 1 every/time v_s
Note
When using a file-style variable with the every/time keyword, the file of timesteps must list a first time that is beyond the time associated with the current timestep (e.g., it cannot be 0.0). And it must list one or more times beyond the length of the run you perform. This is because the dump command will generate an error if the next time it reads from the file is not a value greater than the current time. Thus if you wanted output at times 0,15,100 of a run of length 100 in simulation time, the file should contain the values 15,100,101 and you should also use the dump_modify first command. Any final value > 100 could be used in place of 101.
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 or dump_modify every command, including timestep 0. It will also always occur if the current simulation time is a multiple of Delta, the time interval specified in the dump_modify every/time command.
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.
Note that if the argument to the dump_modify every dump_modify every/time commands is a variable and not a numeric value, then specifying first yes is the only way to write a dump snapshot on the first timestep after the dump command is invoked.
The flush keyword determines whether a flush operation is invoked after a dump snapshot is written to the dump file. A flush ensures 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 format keyword can be used to change the default numeric format output by the text-based dump styles: atom, local, custom, cfg, and xyz styles. Only the line or none options can be used with the atom and xyz styles.
All the specified format strings are C-style formats, such as used by the C/C++ printf() command. The line keyword takes a single argument which is the format string for an entire line of output for each atom (do not include a trailing “n”), with \(N\) fields, which you must enclose in quotes if there is more than one field. The int and float keywords take a single format argument and are applied to all integer or floating-point quantities output. The setting for M string also takes a single format argument which is used for the \(M\)th value output in each line (e.g., the fifth column is output in high precision by “format 5 %20.15g”).
Note
When using the line keyword for the cfg style, the first two fields (atom ID and type) are not actually written into the CFG file, however you must include formats for them in the format string.
The format keyword can be used multiple times. The precedence is that for each value in a line of output, the M format (if specified) is used, else the int or float setting (if specified) is used, else the line setting (if specified) for that value is used, else the default setting is used. A setting of none clears all previous settings, reverting all values to their default format.
Note
Atom and molecule IDs are stored internally as 4-byte or 8-byte signed integers, depending on how LAMMPS was compiled. When specifying the format int option you can use a “%d”-style format identifier in the format string and LAMMPS will convert this to the corresponding 8-byte form if it is needed when outputting those values. However, when specifying the line option or format M string option for those values, you should specify a format string appropriate for an 8-byte signed integer (e.g., one with “%ld”) if LAMMPS was compiled with the -DLAMMPS_BIGBIG option for 8-byte IDs.
Note
Any value written to a text-based dump file that is a per-atom quantity calculated by a compute or fix 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 example, these commands:
compute 1 all property/local batom1 batom2
dump 1 all local 100 tmp.bonds index c_1[1] c_1[2]
dump_modify 1 format line "%d %0.0f %0.0f"
will output the two atom IDs for atoms in each bond as integers. If the dump_modify command were omitted, they would appear as floating-point values, assuming they were large integers (more than six digits). The “index” keyword should use the “%d” format since it is not generated by a compute or fix, and is stored internally as an integer.
The fileper keyword is documented below with the nfile keyword.
The header keyword toggles whether the dump file will include a header. Excluding a header will reduce the size of the dump file for data produced by pair tracker or bpm bond styles which may not require the information typically written to the header.
The image keyword applies only to the dump atom style. If the image value is yes, three 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 through the box boundary twice and is really two 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. Using this keyword will reset all custom header names set with dump_modify colname to their respective default values.
The label keyword applies only to the dump local style. When it writes local information, such as bond or angle topology to a dump file, it will use the specified label to format the header. By default this includes two lines:
ITEM: NUMBER OF ENTRIES
ITEM: ENTRIES ...
The word “ENTRIES” will be replaced with the string specified (e.g., BONDS or ANGLES).
The maxfiles keyword can only be used when a ‘*’ wildcard is included in the dump file name (i.e., when writing a new file(s) for each snapshot). The specified Fmax is how many snapshots will be kept. Once this number is reached, the file(s) containing the oldest snapshot is deleted before a new dump file is written. If the specified \(\text{Fmax} \le 0\), then all files are retained.
This can be useful for debugging, especially if you do not know on what timestep something bad will happen (e.g., when LAMMPS will exit with an error). You can dump every time step and limit the number of dump files produced, even if you run for thousands of steps.
The nfile or fileper keywords can be used in conjunction with the “%” wildcard character in the specified dump file name, for all dump styles except the dcd, image, movie, xtc, and xyz styles (for which “%” is not allowed). As explained on the dump command doc page, the “%” character causes the dump file to be written in pieces, one piece for each of \(P\) processors. By default, \(P\) is the number of processors the simulation is running on. The nfile or fileper keyword can be used to set \(P\) to a smaller value, which can be more efficient when running on a large number of processors.
The nfile keyword sets \(P\) to the specified \(N_f\) value. For example, if \(N_f = 4\), and the simulation is running on 100 processors, four files will be written by processors 0, 25, 50, and 75. Each will collect information from itself and the next 24 processors and write it to a dump file.
For the fileper keyword, the specified value of \(N_p\) means write one file for every \(N_p\) processors. For example, if \(N_p = 4\), every fourth processor (0, 4, 8, 12, etc.) will collect information from itself and the next three processors and write it to a dump file.
The pad keyword only applies when the dump filename is specified with a wildcard “*” character which becomes the timestep. If pad is 0, which is the default, the timestep is converted into a string of unpadded length (e.g., 100 or 12000 or 2000000). When pad is specified with Nchar \(>\) 0, the string is padded with leading zeroes so they are all the same length = Nchar. For example, pad 7 would yield 0000100, 0012000, 2000000. This can be useful so that post-processing programs can easily read the files in ascending timestep order.
The pbc keyword applies to all the dump styles. As explained on the dump doc page, atom coordinates in a dump file may be slightly outside the simulation box. This is because periodic boundary conditions are enforced only on timesteps when neighbor lists are rebuilt, which will not typically coincide with the timesteps dump snapshots are written. If the setting of this keyword is set to yes, then all atoms will be remapped to the periodic box before the snapshot is written, then restored to their original position. If it is set to no they will not be. The no setting is the default because it requires no extra computation.
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 refresh keyword only applies to the dump custom, cfg, image, and movie styles. It allows an “incremental” dump file to be written, by refreshing a compute that is used as a threshold for determining which atoms are included in a dump snapshot. The specified c_ID gives the ID of the compute. It is prefixed by “c_” to indicate a compute, which is the only current option. At some point, other options may be added (e.g., fixes or variables).
Note
This keyword can only be specified once for a dump. Refreshes of multiple computes cannot yet be performed.
The definition and motivation of an incremental dump file is as follows. Instead of outputting all atoms at each snapshot (with some associated values), you may only wish to output the subset of atoms with a value that has changed in some way compared to the value the last time that atom was output. In some scenarios this can result in a dramatically smaller dump file. If desired, by post-processing the sequence of snapshots, the values for all atoms at all timesteps can be inferred.
A concrete example is a simulation of atom diffusion in a solid, represented as atoms on a lattice. Diffusive hops are rare. Imagine that when a hop occurs an atom moves more than a distance Dhop. For any snapshot we only want to output atoms that have hopped since the last snapshot. This can be accomplished with something the following commands:
variable Dhop equal 0.6
variable check atom "c_dsp[4] > v_Dhop"
compute dsp all displace/atom refresh check
dump 1 all custom 20 tmp.dump id type x y z
dump_modify 1 append yes thresh c_dsp[4] > ${Dhop} refresh c_dsp
The compute displace/atom command calculates the displacement of each atom from its reference position. The “4” index is the scalar displacement; 1, 2, and 3 are the \(xyz\) components of the displacement. The dump_modify thresh command will cause only atoms that have displaced more than \(0.6~\AA\) to be output on a given snapshot (assuming metal units). However, note that when an atom is output, we also need to update the reference position for that atom to its new coordinates. So that it will not be output in every snapshot thereafter. That reference position is stored by compute displace/atom. So the dump_modify refresh option triggers a call to compute displace/atom at the end of every dump to perform that update. The refresh check option shown as part of the compute displace/atom command enables the compute to respond to the call from the dump command, and update the appropriate reference positions. This is done be defining an atom-style variable, check in this example, which calculates a Boolean value (0 or 1) for each atom, based on the same criterion used by dump_modify thresh.
See the compute displace/atom command for more details, including an example of how to produce output that includes an initial snapshot with the reference position of all atoms.
Note that only computes with a refresh option will work with dump_modify refresh. See individual compute doc pages for details. Currently, only compute displace/atom supports this option. Others may be added at some point. If you use a compute that does not support refresh operations, LAMMPS will not complain; dump_modify refresh will simply do nothing.
The region keyword only applies to the dump custom, cfg, image, and movie 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 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 simulation 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., \(\AA\) or \(\sigma\)). Using this keyword will reset all custom header names set with dump_modify colname to their respective default values.
The sfactor and tfactor keywords only apply to the dump xtc style. They allow customization of the unit conversion factors used when writing to XTC files. By default, they are initialized for whatever units style is being used, to write out coordinates in nanometers and time in picoseconds. For example, for real units, LAMMPS defines sfactor = 0.1 and tfactor = 0.001, since the \(\AA\) and fs used by real units are 0.1 nm and 0.001 ps, respectively. If you are using a units system with distance and time units far from nm and ps, 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.
Added in version 15Sep2022.
The skip keyword can be used with all dump styles. It allows a dump snapshot to be skipped (not written to the dump file), if a condition is met. The condition is computed by an equal-style variable, which should be specified as v_name, where name is the variable name. If the variable evaluation returns a non-zero value, then the dump snapshot is skipped. If it returns zero, the dump proceeds as usual. Note that equal-style variable can contain Boolean operators which effectively evaluate as a true (non-zero) or false (zero) result.
The skip keyword can be useful for debugging purposes, e.g. to dump only on a particular timestep. Or to limit output to conditions of interest, e.g. only when the force on some atom exceeds a threshold value.
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 \(N\)th 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. If multiple processors are writing the dump file, via the “%” wildcard in the dump filename and the nfile or fileper keywords are set to non-default values (i.e., the number of dump file pieces is not equal to the number of procs), then sorting cannot be performed.
In a parallel run, the per-processor dump file pieces can have significant imbalance in number of lines of per-atom info. The balance keyword determines whether the number of lines in each processor snapshot are balanced to be nearly the same. A balance value of no means no balancing will be done, while yes means balancing will be performed. This balancing preserves dump sorting order. For a serial run, this option is ignored since the output is already balanced.
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 thermo keyword only applies the dump styles netcdf and yaml. It triggers writing of thermo information to the dump file alongside per-atom data. The values included in the dump file are cached values from the last thermo output and include the exact same the values as specified by the thermo_style command. Because these are cached values, they are only up-to-date when dump output is on a timestep that also has thermo output. Dump style yaml will skip thermo output on incompatible steps.
The thresh keyword only applies to the dump custom, cfg, image, and movie 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 dump custom command, with the exception of the element attribute, since it is not a numeric value. Note that a different attributes can be used than those output by the dump custom command. For example, you can output the coordinates and stress of atoms whose energy is above some threshold.
If an atom-style variable is used as the attribute, then it can produce continuous numeric values or effective Boolean 0/1 values, which may be useful for the comparison operator. Boolean values can be generated by variable formulas that use comparison or Boolean math operators or special functions like gmask() and rmask() and grmask(). See the variable command page for details.
The specified value must be a simple numeric value or the word LAST. If LAST is used, it refers to the value of the attribute the last time the dump command was invoked to produce a snapshot. This is a way to only dump atoms whose attribute has changed (or not changed). Three examples follow.
dump_modify ... thresh ix != LAST
This will dump atoms which have crossed the periodic \(x\) boundary of the simulation box since the last dump. (Note that atoms that crossed once and then crossed back between the two dump timesteps would not be included.)
region foo sphere 10 20 10 15
variable inregion atom rmask(foo)
dump_modify ... thresh v_inregion |^ LAST
This will dump atoms which crossed the boundary of the spherical region since the last dump.
variable charge atom "(q > 0.5) || (q < -0.5)"
dump_modify ... thresh v_charge |^ LAST
This will dump atoms whose charge has changed from an absolute value less than \(\frac12\) to greater than \(\frac12\) (or vice versa) since the last dump (e.g., due to reactions and subsequent charge equilibration in a reactive force field).
The choice of operators listed above are the usual comparison operators. The XOR operation (exclusive or) is also included as “|^”. In this context, XOR means that if either the attribute or value is 0.0 and the other is non-zero, then the result is “true” and the threshold criterion is met. Otherwise it is not met.
Note
For style custom, the triclinic/general keyword can alter dump output for general triclinic simulation boxes and their atoms. See the dump command for details of how this changes the format of dump file snapshots. The thresh keyword may access per-atom attributes either directly or indirectly through a compute or variable. If the attribute is an atom coordinate or a per-atom vector (such as velocity, force, or dipole moment), its value will NOT be a general triclinic (rotated) value. Rather it will be a restricted triclinic value.
The time keyword only applies to the dump atom, custom, local, and xyz styles (and their COMPRESS package versions atom/gz, custom/gz and local/gz). For the first three styles, if set to yes, each frame will will contain two extra lines before the “ITEM: TIMESTEP” entry:
ITEM: TIME <elapsed time>
For the xyz style, the simulation time is included on the same line as the timestep value.
This will output the current elapsed simulation time in current time units equivalent to the thermo keyword time. This is to simplify post-processing of trajectories using a variable time step (e.g., when using fix dt/reset). The default setting is no.
The types keyword applies only to the dump xyz style. If this keyword is used with a value of numeric, then numeric atom types are printed in the xyz file (default). If the value labels is specified, then type labels are printed for atom types.
The triclinic/general keyword only applies to the dump atom and custom styles. It can only be used with a value of yes if the simulation box was created as a general triclinic box. See the Howto_triclinic doc page for a detailed explanation of orthogonal, restricted triclinic, and general triclinic simulation boxes.
If this keyword is used with a value of yes, the box information at the beginning of each snapshot will include information about the 3 arbitrary edge vectors A, B, C that define the general triclinic box as well as their origin. The format is described on the dump doc page.
The coordinates of each atom will likewise be output as values in (or near) the general triclinic box. Likewise, per-atom vector quantities such as velocity, omega, dipole moment, etc will have orientations consistent with the general triclinic box, meaning they will be rotated relative to the standard xyz coordinate axes. See the dump doc page for a full list of which dump attributes this affects.
The units keyword only applies to the dump atom, custom, and local styles (and their COMPRESS package versions atom/gz, custom/gz and local/gz). If set to yes, each individual dump file will contain two extra lines at the very beginning with:
ITEM: UNITS <units style>
This will output the current selected units style to the dump file and thus allows visualization and post-processing tools to determine the choice of units of the data in the dump file. The default setting is no.
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 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 these coordinates may thus be far outside the box size stored with the snapshot.
The COMPRESS package offers both GZ and Zstd
compression variants of styles atom, custom, local, cfg, and xyz. When
using these styles the compression level can be controlled by the
compression_level keyword. File names with these styles have to
end in either .gz or .zst.
GZ supports compression levels from \(-1\) (default), 0 (no compression),
and 1 to 9, 9 being the best compression. The COMPRESS /gz styles use 9
as default compression level.
Zstd offers a wider range of compression levels, including negative levels that sacrifice compression for performance. 0 is the default, positive levels are 1 to 22, with 22 being the most expensive compression. Zstd promises higher compression/decompression speeds for similar compression ratios. For more details see https://facebook.github.io/zstd/.
In addition, Zstd compressed files can include a checksum of the
entire contents. The Zstd enabled dump styles enable this feature by
default and it can be disabled with the checksum keyword.
The VTK package offers writing dump files in VTK file formats that can be read by a variety of visualization tools based on the VTK library. These VTK files follow naming conventions that collide with the LAMMPS convention to append “.bin” to a file name in order to switch to a binary output. Thus for vtk style dumps the dump_modify command supports the keyword binary which selects between generating text mode and binary style VTK files.
Restrictions
Not all dump_modify options can be applied to all dump styles. Details are in the discussions of the individual options.
Default
The option defaults are
append = no
balance = no
buffer = yes for dump styles atom, custom, loca, and xyz
element = “C” for every atom type
every = whatever it was set to via the dump command
fileper = # of processors
first = no
flush = yes
format = %d and %g for each integer or floating point value
image = no
label = ENTRIES
maxfiles = -1
nfile = 1
pad = 0
pbc = no
precision = 1000
region = none
scale = yes
sort = off for dump styles atom, custom, cfg, and local
sort = id for dump styles dcd, xtc, and xyz
thresh = none
time = no
triclinic/general = no
types = numeric
units = no
unwrap = no
compression_level = 9 (gz variants)
compression_level = 0 (zstd variants)
checksum = yes (zstd variants)