lammps/doc/dump.txt

 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line
   
dump command :h3

[Syntax:]

dump ID group-ID style N file args :pre

ID = user-assigned name for the dump :ulb,l
group-ID = ID of the group of atoms to be dumped :l
style = {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {local} or {custom} :l
N = dump every this many timesteps :l
file = name of file to write dump info to :l
args = list of arguments for a particular style :l
  {atom} args = none
  {cfg} args = same as {custom} args, see below
  {dcd} args = none
  {xtc} args = none
  {xyz} args = none :pre

  {local} args = list of local attributes
    possible attributes = index, c_ID, c_ID\[N\], f_ID, f_ID\[N\]
      index = enumeration of local values
      c_ID = local vector calculated by a compute with ID
      c_ID\[N\] = Nth column of local array calculated by a compute with ID
      f_ID = local vector calculated by a fix with ID
      f_ID\[N\] = Nth column of local array calculated by a fix with ID :pre
      
  {custom} args = list of atom attributes
    possible attributes = id, mol, type, mass,
			  x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
			  vx, vy, vz, fx, fy, fz,
                          q, mux, muy, muz,
                          radius, omegax, omegay, omegaz,
                          angmomx, angmomy, angmomz,
			  quatw, quati, quatj, quatk, tqx, tqy, tqz,
			  c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :pre

      id = atom ID
      mol = molecule ID
      type = atom type
      mass = atom mass
      x,y,z = unscaled atom coordinates
      xs,ys,zs = scaled atom coordinates
      xu,yu,zu = unwrapped atom coordinates
      ix,iy,iz = box image that the atom is in
      vx,vy,vz = atom velocities
      fx,fy,fz = forces on atoms
      q = atom charge
      mux,muy,muz = orientation of dipolar atom
      radius = radius of extended spherical particle
      omegax,omegay,omegaz = angular velocity of extended particle
      angmomx,angmomy,angmomz = angular momentum of extended particle
      quatw,quati,quatj,quatk = quaternion components for aspherical particles
      tqx,tqy,tqz = torque on extended particles
      c_ID = per-atom vector calculated by a compute with ID
      c_ID\[N\] = Nth column of per-atom array calculated by a compute with ID
      f_ID = per-atom vector calculated by a fix with ID
      f_ID\[N\] = Nth column of per-atom array calculated by a fix with ID
      v_name = per-atom vector calculated by an atom-style variable with name :pre
:ule

[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_Stress[2]
dump 1 all xtc 1000 file.xtc :pre

[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"_dump_modify.html 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"_dump_modify.html
command which allows sorting to be turned on or off.

:line

The {style} keyword determines what atom quantities are written to the
file and in what format.  Settings made via the
"dump_modify"_dump_modify.html 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"_Section_tools.html, including
"Pizza.py"_http://www.cs.sandia.gov/~sjplimp/pizza.html, 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"_region.html 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"_dump_modify.html 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"_compute.html
and "fixes"_fix.html 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"_compute_property_local.html 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"_read_data.html command.

Style {cfg} has the same command syntax as style {custom} and writes
extended CFG format files, as used by the
"AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A 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"_dump_modify.html 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"_dump_modify.html 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"_http://www.gromacs.org/documentation/reference_3.3/online/xtc.html.
The precision used in XTC files can be adjusted via the
"dump_modify"_dump_modify.html 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"_dump_modify.html 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"_http://www.ks.uiuc.edu/Research/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.

:line

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.  A dump is also performed on the very first
timestep after the dump command is invoked.  This can be useful
following a "minimization"_minimize.html which may converge and end on
an arbitrary timestep.  N can be changed between runs by using the
"dump_modify"_dump_modify.html 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"_undump.html
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"_Section_tools.html#binary) 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.

:line

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"_compute.html 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"_compute.html 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"_thermo_style.html 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"_fix.html 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.

:line

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"_units.html (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"_dump_modify.html 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"_compute.html 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"_compute.html 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"_thermo_style.html 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"_fix.html 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"_fix_ave_atom.html command is one that calculates per-atom
quantities.  Since it can time-average per-atom quantities produced by
any "compute"_compute.html, "fix"_fix.html, or atom-style
"variable"_variable.html, 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"_variable.html 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"_Section_modify.html 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.

:line

[Restrictions:]

To write gzipped dump files, you must compile LAMMPS with the
-DLAMMPS_GZIP option - see the "Making LAMMPS"_Section_start.html#2_2
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_start.html#2_3 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"_dump_modify.html, "undump"_undump.html

[Default:] none