346 lines
17 KiB
HTML
346 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 custom/vtk 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>custom/vtk</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>custom/vtk</I> args = list of atom attributes
|
|
possible attributes = id, mol, type, element, mass, density, rho, p
|
|
x, y, z, xs, ys, zs, xu, yu, zu,
|
|
xsu, ysu, zsu, ix, iy, iz,
|
|
vx, vy, vz, fx, fy, fz,
|
|
q, mux, muy, muz, mu,
|
|
radius, diameter, omegax, omegay, omegaz,
|
|
angmomx, angmomy, angmomz, tqx, tqy, tqz,
|
|
spin, eradius, ervel, erforce,
|
|
c_ID, c_ID[N], f_ID, f_ID[N], v_name
|
|
</PRE>
|
|
<PRE> id = atom ID
|
|
mol = molecule ID
|
|
type = atom type
|
|
element = name of atom element, as defined by <A HREF = "dump_modify_vtk.html">dump_modify</A> command
|
|
mass = atom mass
|
|
x,y,z = unscaled atom coordinates
|
|
xs,ys,zs = scaled atom coordinates
|
|
xu,yu,zu = unwrapped atom coordinates
|
|
xsu,ysu,zsu = scaled 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 dipole moment of atom
|
|
mu = magnitude of dipole moment of atom
|
|
radius,diameter = radius,diameter of spherical particle
|
|
omegax,omegay,omegaz = angular velocity of spherical particle
|
|
angmomx,angmomy,angmomz = angular momentum of aspherical particle
|
|
tqx,tqy,tqz = torque on finite-size particles
|
|
spin = electron spin
|
|
eradius = electron radius
|
|
ervel = electron radial velocity
|
|
erforce = 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>
|
|
|
|
</UL>
|
|
<P><B>Examples:</B>
|
|
</P>
|
|
<PRE>dump dmpvtk all custom/vtk 100 dump*.myforce.vtk id type vx fx
|
|
dump dmpvtp flow custom/vtk 100 dump*.%.displace.vtp id type c_myD[1] c_myD[2] c_myD[3] v_ke
|
|
dump e_data all custom/vtk 100 dump*.vtu id type spin eradius fx fy fz eforce
|
|
</PRE>
|
|
<P><B>LIGGGHTS vs. LAMMPS Info:</B>
|
|
</P>
|
|
<P>The new style <I>custom/vtk</I> is similar to the <A HREF = "dump.html">custom</A> style but
|
|
uses the VTK library to write data to VTK simple legacy or XML format depending
|
|
on the filename extension specified. This can be either <I>.vtk</I> for the legacy
|
|
format or <I>.vtp</I> and <I>.vtu</I>, respectively, for the XML format; see the
|
|
<A HREF = "http://www.vtk.org/VTK/img/file-formats.pdf">VTK homepage</A> for a detailed
|
|
description of these formats.
|
|
Since this naming convention conflicts with the way binary output is usually
|
|
specified (see below), <A HREF = "dump_modify_vtk.html">dump_modify binary</A> allows to set
|
|
the binary flag for this dump style explicitly.
|
|
</P>
|
|
<P><B>Description:</B>
|
|
</P>
|
|
<P>Dump a snapshot of atom quantities to one or more files every N
|
|
timesteps. The timesteps on which dump output is written can also
|
|
be controlled by a variable; see the <A HREF = "dump_modify_vtk.html">dump_modify
|
|
every</A> command for details.
|
|
</P>
|
|
<P>Only information for atoms in the specified group is dumped. The
|
|
<A HREF = "dump_modify_vtk.html">dump_modify thresh and region</A> commands can also
|
|
alter what atoms are included; see details below.
|
|
</P>
|
|
<P>As described below, special characters ("*", "%") in the filename determine the kind of output.
|
|
</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>IMPORTANT NOTE: Unless the <A HREF = "dump_modify_vtk.html">dump_modify sort</A> option
|
|
is invoked, the lines of atom information written to dump files
|
|
will be in an indeterminate order for each snapshot.
|
|
This is even true when running on a single processor,
|
|
if the <A HREF = "atom_modify.html">atom_modify sort</A> option is on, which it is
|
|
by default. In this case atoms are re-ordered periodically during a
|
|
simulation, due to spatial sorting. It is also true when running in
|
|
parallel, because data for a single snapshot is collected from
|
|
multiple processors, each of which owns a subset of the atoms.
|
|
</P>
|
|
<P>For the <I>custom/vtk</I> style, sorting is off by default. See the
|
|
<A HREF = "dump_modify_vtk.html">dump_modify</A> doc page for details.
|
|
</P>
|
|
<HR>
|
|
|
|
<P>The dimensions of the simulation box are written to a separate file
|
|
for each snapshot (either in legacy VTK or XML format depending on
|
|
the format of the main dump file) with the suffix <I>_boundingBox</I>
|
|
appended to the given dump filename.
|
|
</P>
|
|
<P>For an orthogonal simulation box this information is saved as a
|
|
rectilinear grid (legacy .vtk or .vtr XML format).
|
|
</P>
|
|
<P>Triclinic simulation boxes (non-orthogonal) are saved as
|
|
hexahedrons in either legacy .vtk or .vtu XML format.
|
|
</P>
|
|
<P>Style <I>custom/vtk</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. In contrast to the <I>custom</I> style, the attributes
|
|
are rearranged to ensure correct ordering of vector components
|
|
(except for computes and fixes - these have to be given in the right
|
|
order) and duplicate entries are removed.
|
|
</P>
|
|
<P>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 possible dump custom/vtk attributes
|
|
is given below. Since position data is required to write VTK files "x y z"
|
|
do not have to be specified explicitly.
|
|
</P>
|
|
<P>The VTK format uses a single snapshot of the system per file, thus
|
|
a wildcard "*" must be included in the filename, as discussed below.
|
|
Otherwise the dump files will get overwritten with the new snapshot
|
|
each time.
|
|
</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. 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 <A HREF = "dump_modify_vtk.html">dump_modify first</A> command, which
|
|
can also 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 <A HREF = "dump_modify_vtk.html">dump_modify every</A> command.
|
|
The <A HREF = "dump_modify_vtk.html">dump_modify every</A> command
|
|
also allows a variable to be used to determine the sequence of
|
|
timesteps on which dump files are written. In this mode a dump on the
|
|
first timestep of a run will also not be written unless the
|
|
<A HREF = "dump_modify_vtk.html">dump_modify first</A> command is used.
|
|
</P>
|
|
<P>Dump filenames can contain two wildcard 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*.vtk becomes tmp.dump0.vtk, tmp.dump10000.vtk,
|
|
tmp.dump20000.vtk, etc. Note that the <A HREF = "dump_modify_vtk.html">dump_modify pad</A>
|
|
command can be used to insure all timestep numbers are the same length
|
|
(e.g. 00010), which can make it easier to read a series of dump files
|
|
in order with some post-processing tools.
|
|
</P>
|
|
<P>If a "%" character appears in the filename, then each of P processors
|
|
writes a portion of the dump file, and the "%" character is replaced
|
|
with the processor ID from 0 to P-1 preceded by an underscore character.
|
|
For example, tmp.dump%.vtp becomes tmp.dump_0.vtp, tmp.dump_1.vtp, ...
|
|
tmp.dump_P-1.vtp, etc. This creates smaller files and can be a fast
|
|
mode of output on parallel machines that support parallel I/O for output.
|
|
</P>
|
|
<P>By default, P = the number of processors meaning one file per
|
|
processor, but P can be set to a smaller value via the <I>nfile</I> or
|
|
<I>fileper</I> keywords of the <A HREF = "dump_modify_vtk.html">dump_modify</A> command.
|
|
These options can be the most efficient way of writing out dump files
|
|
when running on large numbers of processors.
|
|
</P>
|
|
<P>For the legacy VTK format "%" is ignored and P = 1, i.e., only
|
|
processor 0 does write files.
|
|
</P>
|
|
<P>Note that using the "*" and "%" characters together can produce a
|
|
large number of small dump files!
|
|
</P>
|
|
<P>If <I>dump_modify binary</I> is used, 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.
|
|
</P>
|
|
<HR>
|
|
|
|
<P>This section explains the atom attributes that can be specified as
|
|
part of the <I>custom/vtk</I> style.
|
|
</P>
|
|
<P>The <I>id</I>, <I>mol</I>, <I>type</I>, <I>element</I>, <I>mass</I>, <I>vx</I>, <I>vy</I>, <I>vz</I>, <I>fx</I>, <I>fy</I>,
|
|
<I>fz</I>, <I>q</I> attributes are self-explanatory.
|
|
</P>
|
|
<P><I>id</I> is the atom ID. <I>mol</I> is the molecule ID, included in the data
|
|
file for molecular systems. <I>type</I> is the atom type. <I>element</I> is
|
|
typically the chemical name of an element, which you must assign to
|
|
each type via the <A HREF = "dump_modify_vtk.html">dump_modify element</A> command.
|
|
More generally, it can be any string you wish to associate with an
|
|
atom type. <I>mass</I> is the atom mass. <I>vx</I>, <I>vy</I>, <I>vz</I>, <I>fx</I>, <I>fy</I>,
|
|
<I>fz</I>, and <I>q</I> are components of atom velocity and force and atomic
|
|
charge.
|
|
</P>
|
|
<P>There are several options for outputting atom coordinates. The <I>x</I>,
|
|
<I>y</I>, <I>z</I> attributes are used to write atom coordinates "unscaled", in the
|
|
appropriate distance <A HREF = "units.html">units</A> (Angstroms, sigma, etc).
|
|
Additionaly, you can use <I>xs</I>, <I>ys</I>, <I>zs</I> if you want to also save the
|
|
coordinates "scaled" to the box size, so that each value is 0.0 to 1.0.
|
|
If the simulation box is triclinic (tilted), then all atom coords will
|
|
still be between 0.0 and 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 through 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 bounds printed with the snapshot. Using <I>xsu</I>, <I>ysu</I>, <I>zsu</I> is similar
|
|
to using <I>xu</I>, <I>yu</I>, <I>zu</I>, except that the unwrapped coordinates are
|
|
scaled by the box size. Atoms that have passed through a periodic boundary
|
|
will have the corresponding cooordinate increased or decreased by 1.0.
|
|
</P>
|
|
<P>The image flags can be printed directly using the <I>ix</I>, <I>iy</I>, <I>iz</I>
|
|
attributes. For periodic dimensions, they specify which image of the
|
|
simulation box the atom is considered to be in. An image of 0 means
|
|
it is inside the box as defined. A value of 2 means add 2 box lengths
|
|
to get the true value. A value of -1 means subtract 1 box length to
|
|
get the true value. LAMMPS updates these flags as atoms cross
|
|
periodic boundaries during the simulation.
|
|
</P>
|
|
<P>The <I>mux</I>, <I>muy</I>, <I>muz</I> attributes are specific to dipolar systems
|
|
defined with an atom style of <I>dipole</I>. They give the orientation of
|
|
the atom's point dipole moment. The <I>mu</I> attribute gives the
|
|
magnitude of the atom's dipole moment.
|
|
</P>
|
|
<P>The <I>radius</I> and <I>diameter</I> attributes are specific to spherical
|
|
particles that have a finite size, such as those defined with an atom
|
|
style of <I>sphere</I>.
|
|
</P>
|
|
<P>The <I>omegax</I>, <I>omegay</I>, and <I>omegaz</I> attributes are specific to
|
|
finite-size spherical particles that have an angular velocity. Only
|
|
certain atom styles, such as <I>sphere</I> define this quantity.
|
|
</P>
|
|
<P>The <I>angmomx</I>, <I>angmomy</I>, and <I>angmomz</I> attributes are specific to
|
|
finite-size aspherical particles that have an angular momentum. Only
|
|
the <I>ellipsoid</I> atom style defines this quantity.
|
|
</P>
|
|
<P>The <I>tqx</I>, <I>tqy</I>, <I>tqz</I> attributes are for finite-size particles that
|
|
can sustain a rotational torque due to interactions with other
|
|
particles.
|
|
</P>
|
|
<P>The <I>spin</I>, <I>eradius</I>, <I>ervel</I>, and <I>erforce</I> attributes are for
|
|
particles that represent nuclei and electrons modeled with the
|
|
electronic force field (EFF). See <A HREF = "atom_style.html">atom_style
|
|
electron</A> and <A HREF = "pair_eff.html">pair_style eff</A> for more
|
|
details.
|
|
</P>
|
|
<P>The <I>c_ID</I> and <I>c_ID[N]</I> attributes allow per-atom vectors or arrays
|
|
calculated by a <A HREF = "compute.html">compute</A> 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
|
|
<A HREF = "compute.html">compute</A> command for details. There are computes for
|
|
calculating the per-atom energy, stress, centro-symmetry parameter,
|
|
and coordination number of individual atoms.
|
|
</P>
|
|
<P>Note that computes which calculate global or local quantities, as
|
|
opposed to per-atom quantities, cannot be output in a dump custom/vtk
|
|
command. Instead, global quantities can be output by the
|
|
<A HREF = "thermo_style.html">thermo_style custom</A> command, and local quantities
|
|
can be output by the dump local command.
|
|
</P>
|
|
<P>If <I>c_ID</I> is used as an attribute, then the per-atom vector 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 column of the M-length
|
|
per-atom array calculated by the compute.
|
|
</P>
|
|
<P>The <I>f_ID</I> and <I>f_ID[N]</I> attributes allow vector or array per-atom
|
|
quantities calculated by a <A HREF = "fix.html">fix</A> 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 <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 attribute, then the per-atom vector 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 column of the M-length
|
|
per-atom array calculated by the fix.
|
|
</P>
|
|
<P>The <I>v_name</I> attribute allows per-atom vectors calculated by a
|
|
<A HREF = "variable.html">variable</A> 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 <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">Section_modify</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>The <I>custom/vtk</I> style does not support writing of gzipped dump files.
|
|
</P>
|
|
<P>To be able to use <I>custom/vtk</I>, you have to link to the VTK library,
|
|
please adapt your Makefile accordingly. You must compile LAMMPS with the
|
|
-DLAMMPS_VTK option - see the <A HREF = "Section_start.html#start_2">Making LAMMPS</A>
|
|
section of the documentation.
|
|
</P>
|
|
<P>The <I>custom/vtk</I> dump style neither supports buffering nor custom format strings.
|
|
</P>
|
|
<P><B>Related commands:</B>
|
|
</P>
|
|
<P><A HREF = "dump.html">dump</A>, <A HREF = "dump_image.html">dump image</A>, <A HREF = "dump_modify.html">dump_modify</A>,
|
|
<A HREF = "undump.html">undump</A>
|
|
</P>
|
|
<P><B>Default:</B>
|
|
</P>
|
|
<P>By default, files are written in ASCII format. If the file extension is not
|
|
one of .vtk, .vtp or .vtu, the legacy VTK file format is used.
|
|
</P>
|
|
</HTML>
|