forked from lijiext/lammps
457 lines
22 KiB
Plaintext
457 lines
22 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 {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,
|
|
spin, eradius, evel, eforce,
|
|
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
|
|
spin = electron spin
|
|
eradius = electron radius
|
|
evel = electron radial velocity
|
|
eforce = electron radial force
|
|
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
|
|
dump e_data all custom 100 dump.eff id type x y z spin eradius fx fy fz eforce :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.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). See "this section"_Section_tools.html#vmd of the manual and
|
|
the tools/lmp2vmd/README.txt file for more information about support
|
|
in VMD for reading and visualizing LAMMPS dump files.
|
|
|
|
: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. 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"_dump_modify.html 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"_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 {spin}, {eradius}, {evel}, and {eforce} attributes are for
|
|
particles that represent nuclei and electrons modeled with the
|
|
electronic force field (EFF). See "atom_style
|
|
electron"_atom_style.html and "pair_style eff"_pair_eff.html for more
|
|
details.
|
|
|
|
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
|