forked from lijiext/lammps
352 lines
16 KiB
Plaintext
352 lines
16 KiB
Plaintext
"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 {bond} or {dcd} or {xtc} or {xyz} 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
|
|
{bond} args = none
|
|
{dcd} args = none
|
|
{xtc} args = none
|
|
{xyz} args = none
|
|
{custom} args = list of atom attributes
|
|
possible attributes = id, mol, type,
|
|
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
|
|
id = 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
|
|
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 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
|
|
: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 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}, {bond}, 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}.
|
|
|
|
: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}, {bond}, 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 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.
|
|
|
|
For style {bond}, the bond topology between atoms is written, in the
|
|
same format specified in data files read in by the
|
|
"read_data"_read_data.html 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 "bond_style"_bond_style.html command) by setting their
|
|
bond type to 0 are not written. Bonds that have been turned off (see
|
|
the "fix shake"_fix_shake.html or "delete_bonds"_delete_bonds.html
|
|
commands) by setting their bond type negative are written into the
|
|
file.
|
|
|
|
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 dump custom quantities is given
|
|
below.
|
|
|
|
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. 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 atom quantities that can be specified as
|
|
part of the {custom} style.
|
|
|
|
The {id}, {mol}, {type}, {x}, {y}, {z}, {vx}, {vy}, {vz}, {fx}, {fy},
|
|
{fz}, {q} keywords are self-explanatory. {Id} is the atom ID. {Mol}
|
|
is the molecule ID, included in the data file for molecular systems.
|
|
The {x}, {y}, {z} keywords 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. 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 size printed with the snapshot. The image flags can
|
|
be printed directly using the {ix}, {iy}, {iz} keywords. 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} keywords 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} keyword 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} keywords 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} keywords are specific to
|
|
extended aspherical particles that have an angular momentum. Only
|
|
the {ellipsoid) atom style defines this quantity.
|
|
|
|
The {quatw}, {quati}, {quatj}, {quatk} keywords 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} keywords 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\]} keywords allow scalar or vector per-atom
|
|
quantities calculated by a "compute"_compute.html 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
|
|
"compute"_compute.html command for details. There are per-atom
|
|
computes for calculating the energy, stress, centro-symmetry
|
|
parameter, and coordination number of individual atoms.
|
|
|
|
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 "thermo_style
|
|
custom"_thermo_style.html command.
|
|
|
|
If {c_ID} is used as a keyword, then the scalar per-atom quantity
|
|
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 component of
|
|
the M-length per-atom vector calculated by the compute.
|
|
|
|
The {f_ID} and {f_ID\[N\]} keywords allow scalar or vector per-atom
|
|
quantities calculated by a "fix"_fix.html 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 "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 keyword, then the scalar per-atom quantity
|
|
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 component of the
|
|
M-length per-atom vector calculated by the fix.
|
|
|
|
The {v_name} keyword allows per-atom quantities calculated by a
|
|
"variable"_variable.html 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 {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:]
|
|
|
|
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 {atom}; the "dump_modify command"_dump_modify.html must be
|
|
used to change it. The exception is DCD files which store the tilt
|
|
factors for subsequent visualization by programs like
|
|
"VMD"_http://www.ks.uiuc.edu/Research/vmd.
|
|
|
|
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 {bond} style is part of the "molecular" 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.
|
|
|
|
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
|