LIGGGHTS WWW Site - LIGGGHTS Documentation - LIGGGHTS Commands

dump command

Syntax:

dump ID group-ID style N file args 

Examples:

dump myDump all atom 100 dump.atom
dump 2 subgroup atom 50 dump.run.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 2 inner cfg 10 dump.snap.*.cfg id type xs ys zs vx vy vz
dump snap all cfg 100 dump.config.*.cfg id type xs ys zs id type c_Stress2
dump 1 all xtc 1000 file.xtc 

LIGGGHTS vs. LAMMPS Info:

Two new styles (stl and mesh/gran/VTK) are available for dumping granular mesh geometry into STL files or VTK files. The former is used for dumping only the geometry, while the latter command is used to dump the mesh IDs, stress etc- calculated on a granular mesh using the fix mesh/gran/stressanalysis command.

Description:

Dump a snapshot of atom quantities to one or more files every N timesteps in one of several styles. 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 one per processor). Only information for atoms in the specified group is dumped. The dump_modify command can also alter what atoms are included. Not all styles support all these options; see details below.

IMPORTANT NOTE: 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.

When LAMMPS is running in parallel, the atom information written to dump files (typically one line per atom) may be written in an indeterminate order. This is because data for a single snapshot is collected from multiple processors. This is always the case for the atom, local, and custom styles. It is also the case for the xyz style if the dump group is not all. It is not the case for the dcd and xtc styles which always write atoms in sorted order. So does the xyz style if the dump group is all. The cfg style supports the sort option of the dump_modify command which allows sorting to be turned on or off.


The style keyword determines what atom quantities are written to the file and in what format. Settings made via the dump_modify command can also alter the format of individual values and the file itself.

The atom, local, and custom styles create files in a simple text format that is self-explanatory when viewing a dump file. Many of the LAMMPS post-processing tools, including Pizza.py, work with this format.

For post-processing purposes the atom and custom text files are self-describing in the following sense. The simulation box bounds are included in each snapshot and if the box is triclinic (non-orthogonal), then the tilt factors are also printed; see the region prism command for a description of tilt factors. For triclinic boxes the box bounds themselves (first 2 quantities on each line) are a true "bounding box" around the simulation domain, which means they include the effect of any tilt. The "ITEM: ATOMS" line in each snapshot also lists the meaning of each column of the per-atom lines that follow. For example, this would be "id type xs ys zs" for the default atom style, and it will be the atom attributes you specify in the dump command for the custom style.

For style atom, 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 dump_modify settings. Image flags can also be added for each atom via dump_modify.

Style custom 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 q for atom style bond, 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.

For style local, local output generated by computes and fixes is used to gnerate 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 compute property/local 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 read_data command.

Style cfg has the same command syntax as style custom and writes extended CFG format files, as used by the AtomEye visualization package. Since the extended CFG format uses a single snapshot of the system per file, a wild-card "*" must be included in the filename, as discussed below. The list of atom attributes for style cfg must begin with "id type xs ys zs", since these quantities are needed to write the CFG files in the appropriate format (though the "id" and "type" fields do not appear explicitly in the file). Any remaining attributes will be stored as "auxiliary properties" in the CFG files. Note that you will typically want to use the dump_modify element command with CFG-formatted files, to associate element names with atom types, so that AtomEye can render atoms appropriately.

The dcd style writes DCD files, a standard atomic trajectory format used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD files are binary and thus may not be portable to different machines. The dump group must be all for the dcd style. The unwrap option of the dump_modify command allows DCD 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.

The xtc style writes XTC files, a compressed trajectory format used by the GROMACS molecular dynamics package, and described here. The precision used in XTC files can be adjusted via the dump_modify 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 dump group must be all for the xtc style. The unwrap option of the dump_modify 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.

The xyz style writes XYZ files, which is a simple text-based coordinate format that many codes can read.

Note that DCD, XTC, and XYZ formatted files can be read directly by VMD (a popular molecular viewing program). We are told VMD will also read LAMMPS atom style dump files since someone has added a LAMMPS format plug-in to VMD. It may require an initial snapshot from an XYZ formatted file to get started.

The stl style dumps active STL geometries defined via fix mesh/gran commands into the specified file. If you do not supply the optional list of mesh IDs, all meshes are dumped, irrespective of whether they are used in a fix wall/gran command or not. By specifying a list of mesh IDs you can explicitly choose which meshes to dump. The group-ID is ignored, because the command is not applied to particles, but to mesh geometries. This dump is especially useful if a fix move/mesh/gran is registered. If the position of the mesh is changed over time and you want to dump one file for each dump timestep for post-processing together with the particle data, you should use a filename like 'mydumpfile*.stl'. Note: This series of files can then be post-processed together with the particle dump file converted to VTK in Paraview , www.paraview.org

The mesh/gran/VTK style can be used to dumps active mesh geometries defined via fix mesh/gran commands. Different keywords can be used to dump the per-triangle stress, id, velocity, wear or stress components into the specified file using a VTK file format. The list of mesh IDs is optional. As with the stl style, all active meshes are dumped if you do not supply the optional list of mesh IDs. By specifying list of mesh IDs you can explicitly choose which meshes to dump. The group-ID is ignored. Again, a series of files can be post-processed in Paraview , www.paraview.org


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 dump_modify first command, which can 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 dump_modify every command (not allowed for dcd style).

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 undump command is used or when LAMMPS exits. For the dcd and xtc styles, this is a single large binary file.

Dump filenames can contain two wild-card 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 dcd and xtc styles.

If a "%" character appears in the filename, then one file is written for each processor 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 dcd, xtc, and xyz styles.

Note that the "*" and "%" characters can be used together to produce a large number of small dump files!

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 binary2txt tool) 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 atom and custom styles.

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 dcd and xtc styles.


This section explains the local attributes that can be specified as part of the local style.

The index 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.

The c_ID and c_ID[N] attributes allow local vectors or arrays calculated by a compute 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 compute command for details. There are computes for calculating local information such as indices, types, and energies for bonds and angles.

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 thermo_style custom command, and per-atom quantities can be output by the dump custom command.

If c_ID is used as a attribute, then the local vector calculated by the compute is printed. If c_ID[N] is used, then N must be in the range from 1-M, which will print the Nth column of the M-length local array calculated by the compute.

The f_ID and f_ID[N] attributes allow local vectors or arrays calculated by a fix 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.

If f_ID is used as a attribute, then the local vector calculated by the fix is printed. If f_ID[N] is used, then N must be in the range from 1-M, which will print the Nth column of the M-length local array calculated by the fix.


This section explains the atom attributes that can be specified as part of the custom and cfg styles.

The id, mol, type, mass, vx, vy, vz, fx, fy, fz, q attributes are self-explanatory.

Id is the atom ID. Mol is the molecule ID, included in the data file for molecular systems. Type is the atom type. Mass is the atom mass. Vx, vy, vz, fx, fy, fz, and q are components of atom velocity and force and atomic charge.

There are several options for outputting atom coordinates. The x, y, z attributes write atom coordinates "unscaled", in the appropriate distance units (Angstroms, sigma, etc). Use xs, ys, zs if you want the coordinates "scaled" to the box size, so that each value is 0.0 to 1.0. If the simluation box is triclinic (tilted), then all atom coords will still be between 0.0 and 1.0. Use xu, yu, zu 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 xu, yu, zu means that the coordinate values may be far outside the box bounds printed with the snapshot. The image flags can be printed directly using the ix, iy, iz attributes. The dump_modify command describes in more detail what is meant by scaled vs unscaled coordinates and the image flags.

The mux, muy, muz attributes are specific to dipolar systems defined with an atom style of dipole. They give the orientation of the atom's point dipole moment.

The radius attribute is specific to extended spherical particles that have a finite size, such as granular particles defined with an atom style of granular.

The omegax, omegay, and omegaz attributes are specific to extended spherical or aspherical particles that have an angular velocity. Only certain atom styles, such as granular or dipole define this quantity.

The angmomx, angmomy, and angmomz attributes are specific to extended aspherical particles that have an angular momentum. Only the ellipsoid atom style defines this quantity.

The quatw, quati, quatj, quatk attributes are for aspherical particles defined with an atom style of ellipsoid. They are the components of the quaternion that defines the orientation of the particle.

The tqx, tqy, tqz attributes are for extended spherical or aspherical particles that can sustain a rotational torque due to interactions with other particles.

The c_ID and c_ID[N] attributes allow per-atom vectors or arrays calculated by a compute 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 compute command for details. There are computes for calculating the per-atom energy, stress, centro-symmetry parameter, and coordination number of individual atoms.

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 thermo_style custom command, and local quantities can be output by the dump local command.

If c_ID is used as a attribute, then the per-atom vector calculated by the compute is printed. If c_ID[N] 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.

The f_ID and f_ID[N] attributes allow vector or array per-atom quantities calculated by a fix 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 fix ave/atom command is one that calculates per-atom quantities. Since it can time-average per-atom quantities produced by any compute, fix, or atom-style variable, this allows those time-averaged results to be written to a dump file.

If f_ID is used as a attribute, then the per-atom vector calculated by the fix is printed. If f_ID[N] 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.

The v_name attribute allows per-atom vectors calculated by a variable 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 atom 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.

See this section 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.


Restrictions:

To write gzipped dump files, you must compile LAMMPS with the -DLAMMPS_GZIP option - see the Making LAMMPS section of the documentation.

The xtc style is part of the "xtc" package. It is only enabled if LAMMPS was built with that package. See the Making LAMMPS section for more info. This is because some machines may not support the lo-level XDR data format that XTC files are written with, which will result in a compile-time error when a lo-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 XTC 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 lo-level Makefile, e.g. src/MAKE/Makefile.foo. This compatibility mode has been tested successfully on Cray XT3 and IBM BlueGene/L machines and should also work on the Cray XT4, IBM BG/P, and Windows XP machines.

Related commands:

dump_modify, undump

Default: none