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 command
|
|
|
|
</H3>
|
|
|
|
<P><B>Syntax:</B>
|
|
|
|
</P>
|
|
|
|
<PRE>dump ID group-ID style N file args
|
|
|
|
</PRE>
|
|
|
|
<UL><LI>ID = user-assigned name for the dump
|
|
|
|
|
|
|
|
<LI>group-ID = ID of the group of atoms to be dumped
|
|
|
|
|
2007-02-10 05:37:30 +08:00
|
|
|
<LI>style = <I>atom</I> or <I>bond</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>custom</I>
|
2006-09-22 00:22:34 +08:00
|
|
|
|
|
|
|
<LI>N = dump every this many timesteps
|
|
|
|
|
|
|
|
<LI>file = name of file to write dump info to
|
|
|
|
|
|
|
|
<LI>args = list of arguments for a particular style
|
|
|
|
|
|
|
|
<PRE> <I>atom</I> args = none
|
|
|
|
<I>bond</I> args = none
|
2007-02-10 05:37:30 +08:00
|
|
|
<I>dcd</I> args = none
|
|
|
|
<I>xtc</I> args = precision (optional)
|
|
|
|
precision = power-of-10 value from 10 to 1000000 (default = 1000)
|
|
|
|
<I>xyz</I> args = none
|
2006-09-22 00:22:34 +08:00
|
|
|
<I>custom</I> args = list of atom attributes
|
2007-02-10 05:37:30 +08:00
|
|
|
possible attributes = tag, mol, type,
|
|
|
|
x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
|
|
|
|
vx, vy, vz, fx, fy, fz,
|
2007-04-20 07:25:27 +08:00
|
|
|
q, mux, muy, muz,
|
|
|
|
quatw, quati, quatj, quatk, tqx, tqy, tqz,
|
2007-09-28 07:25:52 +08:00
|
|
|
c_ID, c_ID[N], f_ID, f_ID[N]
|
2006-09-22 00:22:34 +08:00
|
|
|
tag = atom ID
|
|
|
|
mol = molecule ID
|
|
|
|
type = atom type
|
|
|
|
x,y,z = unscaled atom coordinates
|
|
|
|
xs,ys,zs = scaled atom coordinates
|
|
|
|
xu,yu,zu = unwrapped atom coordinates
|
2006-10-03 06:11:58 +08:00
|
|
|
ix,iy,iz = box image that the atom is in
|
2006-09-22 00:22:34 +08:00
|
|
|
vx,vy,vz = atom velocities
|
|
|
|
fx,fy,fz = forces on atoms
|
|
|
|
q = atom charge
|
|
|
|
mux,muy,muz = orientation of dipolar atom
|
2007-04-20 07:25:27 +08:00
|
|
|
quatw,quati,quatj,quatk = quaternion components for aspherical particles
|
|
|
|
tqx,tqy,tqz = torque on aspherical particles
|
2007-02-10 05:37:30 +08:00
|
|
|
c_ID = scalar per-atom quantity calculated by a compute identified by its ID
|
2007-09-28 07:25:52 +08:00
|
|
|
c_ID[N] = Nth per-atom vector quantity calculated by a compute identified by its ID
|
|
|
|
f_ID = scalar per-atom quantity calculated by a fix identified by its ID
|
|
|
|
f_ID[N] = Nth per-atom vector quantity calculated by a fix identified by its ID
|
2006-09-22 00:22:34 +08:00
|
|
|
</PRE>
|
|
|
|
|
|
|
|
</UL>
|
|
|
|
<P><B>Examples:</B>
|
|
|
|
</P>
|
|
|
|
<PRE>dump myDump all atom 100 dump.atom
|
|
|
|
dump 2 subgroup atom 50 dump.run.bin
|
|
|
|
dump 4a all custom 100 dump.myforce.* tag type x y vx fx
|
2007-09-28 07:25:52 +08:00
|
|
|
dump 4b flow custom 100 dump.%.myforce tag type c_myF[3]
|
2006-09-22 00:22:34 +08:00
|
|
|
dump 1 all xtc 1000 file.xtc 100.0
|
|
|
|
</PRE>
|
|
|
|
<P><B>Description:</B>
|
|
|
|
</P>
|
|
|
|
<P>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
|
|
|
|
<A HREF = "dump_modify.html">dump_modify</A> command can also alter what atoms are
|
|
|
|
included. Not all styles support all these options; see details
|
|
|
|
below.
|
|
|
|
</P>
|
|
|
|
<P>Note that 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.
|
|
|
|
</P>
|
|
|
|
<P>Also note that 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 <I>atom</I>, <I>bond</I>, and <I>custom</I> styles. It is also the case
|
|
|
|
for the <I>xyz</I> style if the dump group is not <I>all</I>. It is not the
|
|
|
|
case for the <I>dcd</I> and <I>xtc</I> styles which always write atoms in sorted
|
|
|
|
order. So does the <I>xyz</I> style if the dump group is <I>all</I>.
|
|
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
<P>The <I>style</I> keyword determines what atom quantities are written to the
|
|
|
|
file and in what format. Settings made via the
|
|
|
|
<A HREF = "dump_modify.html">dump_modify</A> command can also alter the format of
|
|
|
|
individual values and the file itself.
|
|
|
|
</P>
|
|
|
|
<P>The <I>atom</I>, <I>bond</I>, and <I>custom</I> styles create files in a simple text
|
2007-04-13 07:23:28 +08:00
|
|
|
format that is self-explanatory when viewing a dump file. Many of the
|
|
|
|
LAMMPS <A HREF = "Section_tools.html">post-processing tools</A>, including
|
2006-09-22 00:22:34 +08:00
|
|
|
<A HREF = "http://www.cs.sandia.gov/~sjplimp/pizza.html">Pizza.py</A>, work with
|
|
|
|
this format.
|
|
|
|
</P>
|
|
|
|
<P>For style <I>atom</I>, 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
|
|
|
|
<A HREF = "dump_modify.html">dump_modify</A> settings. Image flags can also be
|
|
|
|
added for each atom via dump_modify.
|
|
|
|
</P>
|
|
|
|
<P>For style <I>bond</I>, the bond topology between atoms is written, in the
|
|
|
|
same format specified in data files read in by the
|
|
|
|
<A HREF = "read_data.html">read_data</A> command. Both atoms in the bond must be in
|
|
|
|
the dump group for the bond to be written. Any bonds that have been
|
|
|
|
broken (see the <A HREF = "bond_style.html">bond_style</A> command) by setting their
|
|
|
|
bond type to 0 are not written. Bonds that have been turned off (see
|
|
|
|
the <A HREF = "fix_shake.html">fix shake</A> or <A HREF = "delete_bonds.html">delete_bonds</A>
|
|
|
|
commands) by setting their bond type negative are written into the
|
|
|
|
file.
|
|
|
|
</P>
|
|
|
|
<P>Style <I>custom</I> 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. Be careful not
|
|
|
|
to specify a quantity that is not defined for a particular simulation
|
|
|
|
- such as <I>q</I> for atom style <I>bond</I>, 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
|
2007-09-28 07:25:52 +08:00
|
|
|
the timestep. An explanation of the dump custom quantities is given
|
|
|
|
below.
|
2006-09-22 00:22:34 +08:00
|
|
|
</P>
|
|
|
|
<P>The <I>dcd</I> 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 <I>all</I> for the <I>dcd</I> style.
|
|
|
|
</P>
|
|
|
|
<P>The <I>xtc</I> style writes XTC files, a compressed trajectory format used
|
2007-02-23 00:52:24 +08:00
|
|
|
by the GROMACS molecular dynamics package, and described
|
2006-09-22 00:22:34 +08:00
|
|
|
<A HREF = "http://www.gromacs.org/documentation/reference_3.3/online/xtc.html">here</A>.
|
|
|
|
The precision used in XTC files can be specified; for example, a value
|
|
|
|
of 100 means that coordinates are stored to 1/100 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 <I>all</I> for the <I>xtc</I> style.
|
|
|
|
</P>
|
|
|
|
<P>The <I>xyz</I> style writes XYZ files, which is a simple text-based
|
|
|
|
coordinate format that many codes can read.
|
|
|
|
</P>
|
|
|
|
<P>Note that DCD, XTC, and XYZ formatted files can be read directly by
|
|
|
|
<A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD</A> (a popular molecular viewing
|
2007-02-23 00:52:24 +08:00
|
|
|
program). We are told VMD will also read LAMMPS <I>atom</I> 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.
|
2006-09-22 00:22:34 +08:00
|
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
|
2006-12-16 06:53:57 +08:00
|
|
|
<P>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. N can be changed between runs by using the
|
|
|
|
<A HREF = "dump_modify.html">dump_modify</A> command (not allowed for <I>dcd</I> style).
|
2006-09-22 00:22:34 +08:00
|
|
|
</P>
|
|
|
|
<P>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 <A HREF = "undump.html">undump</A>
|
|
|
|
command is used or when LAMMPS exits. For the <I>dcd</I> and <I>xtc</I> styles,
|
|
|
|
this is a single large binary file.
|
|
|
|
</P>
|
2006-10-03 06:11:58 +08:00
|
|
|
<P>Dump filenames can contain two wild-card characters. If a "*"
|
2006-09-22 00:22:34 +08:00
|
|
|
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 <I>dcd</I> and
|
|
|
|
<I>xtc</I> styles.
|
|
|
|
</P>
|
|
|
|
<P>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
|
|
|
|
<I>dcd</I>, <I>xtc</I>, and <I>xyz</I> styles.
|
|
|
|
</P>
|
|
|
|
<P>Note that the "*" and "%" characters can be used together to produce a
|
|
|
|
large number of small dump files!
|
|
|
|
</P>
|
|
|
|
<P>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 <A HREF = "Section_tools.html#binary">binary2txt
|
|
|
|
tool</A>) 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 <I>atom</I> and <I>custom</I> styles.
|
|
|
|
</P>
|
|
|
|
<P>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 <I>dcd</I> and <I>xtc</I>
|
|
|
|
styles.
|
|
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
<P>This section explains the atom quantities that can be specified as
|
|
|
|
part of the <I>custom</I> style.
|
|
|
|
</P>
|
|
|
|
<P>The <I>tag</I>, <I>mol</I>, <I>type</I>, <I>x</I>, <I>y</I>, <I>z</I>, <I>vx</I>, <I>vy</I>, <I>vz</I>, <I>fx</I>, <I>fy</I>,
|
2007-02-10 05:37:30 +08:00
|
|
|
<I>fz</I>, <I>q</I> keywords are self-explanatory. <I>Tag</I> is the atom ID. <I>Mol</I>
|
|
|
|
is the molecule ID, included in the data file for molecular systems.
|
|
|
|
The <I>x</I>, <I>y</I>, <I>z</I> keywords write atom coordinates "unscaled", in the
|
2007-09-28 07:25:52 +08:00
|
|
|
appropriate distance <A HREF = "units.html">units</A> (Angstroms, sigma, etc). Use
|
|
|
|
<I>xs</I>, <I>ys</I>, <I>zs</I> if you want the coordinates "scaled" to the box size,
|
|
|
|
so that each value is 0.0 to 1.0. Use <I>xu</I>, <I>yu</I>, <I>zu</I> 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 <I>xu</I>, <I>yu</I>, <I>zu</I> means that the coordinate values may be far
|
|
|
|
outside the box size printed with the snapshot. The image flags can
|
|
|
|
be printed directly using the <I>ix</I>, <I>iy</I>, <I>iz</I> keywords. The
|
2007-02-10 05:37:30 +08:00
|
|
|
<A HREF = "dump_modify.html">dump_modify</A> command describes in more detail what
|
|
|
|
is meant by scaled vs unscaled coordinates and the image flags.
|
|
|
|
</P>
|
2007-04-20 07:25:27 +08:00
|
|
|
<P>The <I>mux</I>, <I>muy</I>, <I>muz</I> keywords are specific to dipolar systems
|
|
|
|
defined with an atom style of <I>dipole</I>. They give the orientation of
|
|
|
|
the atom's dipole.
|
|
|
|
</P>
|
|
|
|
<P>The <I>quatw</I>, <I>quati</I>, <I>quatj</I>, <I>quatk</I>, <I>tqx</I>, <I>tqy</I>, <I>tqz</I> keywords
|
|
|
|
are specific to aspherical particles defined with an atom style of
|
|
|
|
<I>ellipsoid</I>. The first 4 are the components of the quaternion that
|
|
|
|
define the orientiation of the particle. The final 3 give the
|
|
|
|
rotational torque on the particle.
|
2007-02-10 05:37:30 +08:00
|
|
|
</P>
|
|
|
|
<P>The <I>c_ID</I> and <I>c_ID[N]</I> keywords allow scalar or vector per-atom
|
|
|
|
quantities calculated by a compute to be output. The ID in the
|
|
|
|
keyword should be replaced by the actual ID of the compute that has
|
2007-09-28 07:25:52 +08:00
|
|
|
been defined previously in the input script. See the
|
|
|
|
<A HREF = "compute.html">compute</A> command for details. There are pre-defined
|
|
|
|
computes for calculating the energy, stress, centro-symmetry
|
|
|
|
parameter, and coordination number of individual atoms. The "compute
|
|
|
|
variable/atom" command will evaluate a per-atom formula you define via
|
|
|
|
the <A HREF = "variable.html">variable atom</A> command, for each atom, which can
|
|
|
|
then be dumped.
|
|
|
|
</P>
|
|
|
|
<P>Note that scalar and vector quantities that are not calculated on a
|
|
|
|
per-atom basis by a compute (e.g. global temperature or pressure)
|
|
|
|
cannot be output in a dump. Rather, these quantities can be output by
|
|
|
|
the <A HREF = "thermo_style.html">thermo_style custom</A> command.
|
2007-02-10 05:37:30 +08:00
|
|
|
</P>
|
2007-02-21 08:18:01 +08:00
|
|
|
<P>If <I>c_ID</I> is used as a keyword, then the scalar per-atom quantity
|
|
|
|
calculated by the compute is printed. If <I>c_ID[N]</I> is used, then N
|
|
|
|
in the range from 1-M will print the Nth component of the M-length
|
|
|
|
per-atom vector calculated by the compute.
|
2007-02-10 05:37:30 +08:00
|
|
|
</P>
|
2007-09-28 07:25:52 +08:00
|
|
|
<P>The <I>f_ID</I> and <I>f_ID[N]</I> keywords allow scalar or vector per-atom
|
|
|
|
quantities calculated by a fix to be output. The ID in the keyword
|
|
|
|
should be replaced by the actual ID of the fix that has been defined
|
|
|
|
previously in the input script. Currently the <A HREF = "fix_ave_atom.html">fix
|
|
|
|
ave/atom</A> command is the only fix that calculates
|
|
|
|
per-atom quantities. Since it takes a per-atom <A HREF = "compute.html">compute</A>
|
|
|
|
as an argument it effectively time-averages any of the previously
|
|
|
|
described compute quantities so the time-averaged result can be
|
|
|
|
written to a dump file.
|
|
|
|
</P>
|
|
|
|
<P>If <I>f_ID</I> is used as a keyword, then the scalar per-atom quantity
|
|
|
|
calculated by the fix is printed. If <I>f_ID[N]</I> is used, then N
|
|
|
|
in the range from 1-M will print the Nth component of the M-length
|
|
|
|
per-atom vector calculated by the fix.
|
|
|
|
</P>
|
|
|
|
<P>See <A HREF = "Section_modify.html">this section</A> of the manual for information
|
|
|
|
on how to add new compute and fix styles to LAMMPS that calculate
|
|
|
|
per-atom quantities which could then be output with these keywords.
|
2006-09-22 00:22:34 +08:00
|
|
|
</P>
|
|
|
|
<HR>
|
|
|
|
|
|
|
|
<P><B>Restrictions:</B>
|
|
|
|
</P>
|
2007-03-08 09:01:08 +08:00
|
|
|
<P>Scaled coordinates cannot be writted to dump files when the simulation
|
|
|
|
box is triclinic (non-orthogonal). Note that this is the default for
|
|
|
|
dump style <I>atom</I>; the <A HREF = "dump_modify.html">dump_modify command</A> must be
|
|
|
|
used to change it. The exception is DCD files which store the tilt
|
|
|
|
factors for subsequent visualization by programs like
|
|
|
|
<A HREF = "http://www.ks.uiuc.edu/Research/vmd">VMD</A>.
|
|
|
|
</P>
|
2006-09-22 00:22:34 +08:00
|
|
|
<P>To write gzipped dump files, you must compile LAMMPS with the -DGZIP
|
|
|
|
option - see the <A HREF = "Section_start.html#2_2">Making LAMMPS</A> section of the
|
|
|
|
documentation.
|
|
|
|
</P>
|
|
|
|
<P>The <I>bond</I> style is part of the "molecular" package. It is only
|
2007-06-25 22:36:36 +08:00
|
|
|
enabled if LAMMPS was built with that package. See the <A HREF = "Section_start.html#2_3">Making
|
2006-09-22 00:22:34 +08:00
|
|
|
LAMMPS</A> section for more info.
|
|
|
|
</P>
|
|
|
|
<P>The <I>xtc</I> style is part of the "xtc" package. It is only enabled if
|
2007-06-25 22:36:36 +08:00
|
|
|
LAMMPS was built with that package. See the <A HREF = "Section_start.html#2_3">Making
|
2006-09-22 00:22:34 +08:00
|
|
|
LAMMPS</A> 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.
|
|
|
|
</P>
|
2007-07-03 04:04:44 +08:00
|
|
|
<P>Some pair potentials do not allow the calculation of per-atom energy
|
|
|
|
and stress via the <I>epair</I>, <I>etotal</I>, <I>sxx</I>, etc keywords. One of
|
|
|
|
these are the granular pair potentials. However, for those
|
|
|
|
potentials, the <A HREF = "fix_gran_diag.html">fix gran/diag</A> command can be used
|
|
|
|
instead.
|
2006-09-22 00:22:34 +08:00
|
|
|
</P>
|
|
|
|
<P><B>Related commands:</B>
|
|
|
|
</P>
|
|
|
|
<P><A HREF = "dump_modify.html">dump_modify</A>, <A HREF = "undump.html">undump</A>
|
|
|
|
</P>
|
|
|
|
<P><B>Default:</B> none
|
|
|
|
</P>
|
|
|
|
</HTML>
|