forked from lijiext/lammps
343 lines
17 KiB
HTML
343 lines
17 KiB
HTML
<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
|
|
|
|
<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>
|
|
|
|
<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
|
|
<I>dcd</I> args = none
|
|
<I>xtc</I> args = none
|
|
<I>xyz</I> args = none
|
|
<I>custom</I> args = list of atom attributes
|
|
possible attributes = tag, mol, type,
|
|
x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
|
|
vx, vy, vz, fx, fy, fz,
|
|
q, mux, muy, muz,
|
|
quatw, quati, quatj, quatk, tqx, tqy, tqz,
|
|
c_ID, c_ID[N], f_ID, f_ID[N], v_name
|
|
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
|
|
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
|
|
quatw,quati,quatj,quatk = quaternion components for aspherical particles
|
|
tqx,tqy,tqz = torque on aspherical particles
|
|
c_ID = per-atom scalar value calculated by a compute with ID
|
|
c_ID[N] = Nth component of per-atom vector calculated by a compute with ID
|
|
f_ID = per-atom scalar value calculated by a fix with ID
|
|
f_ID[N] = Nth component of per-atom vector calculated by a fix with ID
|
|
v_name = per-atom value calculated by an atom-style variable with name
|
|
</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
|
|
dump 4b flow custom 100 dump.%.myforce tag type c_myF[3] v_ke
|
|
dump 1 all xtc 1000 file.xtc
|
|
</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>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.
|
|
</P>
|
|
<P>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
|
|
format that is self-explanatory when viewing a dump file. Many of the
|
|
LAMMPS <A HREF = "Section_tools.html">post-processing tools</A>, including
|
|
<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. You cannot
|
|
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
|
|
the timestep. An explanation of the dump custom quantities is given
|
|
below.
|
|
</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. The <I>unwrap</I> option
|
|
of the <A HREF = "dump_modify.html">dump_modify</A> 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.
|
|
</P>
|
|
<P>The <I>xtc</I> style writes XTC files, a compressed trajectory format used
|
|
by the GROMACS molecular dynamics package, and described
|
|
<A HREF = "http://www.gromacs.org/documentation/reference_3.3/online/xtc.html">here</A>.
|
|
The precision used in XTC files can be adjusted via the
|
|
<A HREF = "dump_modify.html">dump_modify</A> 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 <I>all</I> for the <I>xtc</I> style. The <I>unwrap</I> option of
|
|
the <A HREF = "dump_modify.html">dump_modify</A> 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.
|
|
</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
|
|
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.
|
|
</P>
|
|
<HR>
|
|
|
|
<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).
|
|
</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>
|
|
<P>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 <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>,
|
|
<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
|
|
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
|
|
<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>
|
|
<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.
|
|
</P>
|
|
<P>The <I>c_ID</I> and <I>c_ID[N]</I> keywords allow scalar or vector per-atom
|
|
quantities calculated by a <A HREF = "compute.html">compute</A> to be output. The
|
|
ID in the keyword should be replaced by the actual ID of the compute
|
|
that has been defined previously in the input script. See the
|
|
<A HREF = "compute.html">compute</A> command for details. There are per-atom
|
|
computes for calculating the energy, stress, centro-symmetry
|
|
parameter, and coordination number of individual atoms.
|
|
</P>
|
|
<P>Note that computes which calculate global scalar and vector
|
|
quantities, as opposed to per-atom quantities, cannot be output in a
|
|
dump. Instead, these quantities can be output by the <A HREF = "thermo_style.html">thermo_style
|
|
custom</A> command.
|
|
</P>
|
|
<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
|
|
must be in the range from 1-M, which will print the Nth component of
|
|
the M-length per-atom vector calculated by the compute.
|
|
</P>
|
|
<P>The <I>f_ID</I> and <I>f_ID[N]</I> keywords allow scalar or vector per-atom
|
|
quantities calculated by a <A HREF = "fix.html">fix</A> 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. The <A HREF = "fix_ave_atom.html">fix
|
|
ave/atom</A> command is one that calculates per-atom
|
|
quantities. Since it can time-average per-atom quantities produced by
|
|
any <A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or atom-style
|
|
<A HREF = "variable.html">variable</A>, this allows those time-averaged results to
|
|
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 must
|
|
be in the range from 1-M, which will print the Nth component of the
|
|
M-length per-atom vector calculated by the fix.
|
|
</P>
|
|
<P>The <I>v_name</I> keyword allows per-atom quantities calculated by a
|
|
<A HREF = "variable.html">variable</A> to be output. The name in the keyword 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 <I>atom</I> 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.
|
|
</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 to calculate
|
|
per-atom quantities which could then be output into dump files.
|
|
</P>
|
|
<HR>
|
|
|
|
<P><B>Restrictions:</B>
|
|
</P>
|
|
<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>
|
|
<P>To write gzipped dump files, you must compile LAMMPS with the
|
|
-DLAMMPS_GZIP 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
|
|
enabled if LAMMPS was built with that package. See the <A HREF = "Section_start.html#2_3">Making
|
|
LAMMPS</A> section for more info.
|
|
</P>
|
|
<P>The <I>xtc</I> style is part of the "xtc" package. It is only enabled if
|
|
LAMMPS was built with that package. See the <A HREF = "Section_start.html#2_3">Making
|
|
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.
|
|
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 compatability 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.
|
|
</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>
|