forked from lijiext/lammps
361 lines
16 KiB
Plaintext
361 lines
16 KiB
Plaintext
.. index:: dump custom/vtk
|
|
|
|
dump custom/vtk command
|
|
=======================
|
|
|
|
Syntax
|
|
""""""
|
|
|
|
.. parsed-literal::
|
|
|
|
dump ID group-ID style N file args
|
|
|
|
* ID = user-assigned name for the dump
|
|
* group-ID = ID of the group of atoms to be dumped
|
|
* style = *custom/vtk*
|
|
* N = dump every this many timesteps
|
|
* file = name of file to write dump info to
|
|
* args = list of arguments for a particular style
|
|
.. parsed-literal::
|
|
|
|
*custom/vtk* args = list of atom attributes
|
|
possible attributes = id, mol, proc, procp1, type, element, mass,
|
|
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
|
|
|
|
.. parsed-literal::
|
|
|
|
id = atom ID
|
|
mol = molecule ID
|
|
proc = ID of processor that owns atom
|
|
procp1 = ID+1 of processor that owns atom
|
|
type = atom type
|
|
element = name of atom element, as defined by :doc:`dump_modify <dump_modify_vtk>` 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
|
|
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
|
|
|
|
|
|
|
|
Examples
|
|
""""""""
|
|
|
|
.. parsed-literal::
|
|
|
|
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
|
|
|
|
The style *custom/vtk* is similar to the :doc:`custom <dump>` 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
|
|
**.vtk* for the legacy format or **.vtp* and **.vtu*\ , respectively,
|
|
for the XML format; see the `VTK homepage <http://www.vtk.org/VTK/img/file-formats.pdf>`_ for a detailed
|
|
description of these formats. Since this naming convention conflicts
|
|
with the way binary output is usually specified (see below),
|
|
:doc:`dump_modify binary <dump_modify_vtk>` allows to set the binary
|
|
flag for this dump style explicitly.
|
|
|
|
Description
|
|
"""""""""""
|
|
|
|
Dump a snapshot of atom quantities to one or more files every N
|
|
timesteps in a format readable by the `VTK visualization toolkit <http://www.vtk.org>`_ or other visualization tools that use it,
|
|
e.g. `ParaView <http://www.paraview.org>`_. The timesteps on which dump
|
|
output is written can also be controlled by a variable; see the
|
|
:doc:`dump_modify every <dump_modify_vtk>` command for details.
|
|
|
|
Only information for atoms in the specified group is dumped. The
|
|
:doc:`dump_modify thresh and region <dump_modify_vtk>` commands can also
|
|
alter what atoms are included; see details below.
|
|
|
|
As described below, special characters ("*", "%") in the filename
|
|
determine the kind of output.
|
|
|
|
.. warning::
|
|
|
|
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.
|
|
|
|
.. warning::
|
|
|
|
Unless the :doc:`dump_modify sort <dump_modify_vtk>`
|
|
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 :doc:`atom_modify sort <atom_modify>` 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.
|
|
|
|
For the *custom/vtk* style, sorting is off by default. See the
|
|
:doc:`dump_modify <dump_modify_vtk>` doc page for details.
|
|
|
|
|
|
----------
|
|
|
|
|
|
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 *_boundingBox*
|
|
appended to the given dump filename.
|
|
|
|
For an orthogonal simulation box this information is saved as a
|
|
rectilinear grid (legacy .vtk or .vtr XML format).
|
|
|
|
Triclinic simulation boxes (non-orthogonal) are saved as
|
|
hexahedrons in either legacy .vtk or .vtu XML format.
|
|
|
|
Style *custom/vtk* 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 *custom* 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.
|
|
|
|
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/vtk attributes
|
|
is given below. Since position data is required to write VTK files "x y z"
|
|
do not have to be specified explicitly.
|
|
|
|
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.
|
|
|
|
|
|
----------
|
|
|
|
|
|
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 :doc:`dump_modify first <dump_modify_vtk>` 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 :doc:`dump_modify every <dump_modify_vtk>` command.
|
|
The :doc:`dump_modify every <dump_modify_vtk>` 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
|
|
:doc:`dump_modify first <dump_modify_vtk>` command is used.
|
|
|
|
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 :doc:`dump_modify pad <dump_modify_vtk>`
|
|
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.
|
|
|
|
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.
|
|
|
|
By default, P = the number of processors meaning one file per
|
|
processor, but P can be set to a smaller value via the *nfile* or
|
|
*fileper* keywords of the :doc:`dump_modify <dump_modify_vtk>` command.
|
|
These options can be the most efficient way of writing out dump files
|
|
when running on large numbers of processors.
|
|
|
|
For the legacy VTK format "%" is ignored and P = 1, i.e., only
|
|
processor 0 does write files.
|
|
|
|
Note that using the "*" and "%" characters together can produce a
|
|
large number of small dump files!
|
|
|
|
If *dump_modify binary* 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.
|
|
|
|
|
|
----------
|
|
|
|
|
|
This section explains the atom attributes that can be specified as
|
|
part of the *custom/vtk* style.
|
|
|
|
The *id*\ , *mol*\ , *proc*\ , *procp1*\ , *type*\ , *element*\ , *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. *element* is
|
|
typically the chemical name of an element, which you must assign to
|
|
each type via the :doc:`dump_modify element <dump_modify_vtk>` command.
|
|
More generally, it can be any string you wish to associate with an
|
|
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 are used to write atom coordinates "unscaled", in
|
|
the appropriate distance :doc:`units <units>` (Angstroms, sigma, etc).
|
|
Additionaly, you can use *xs*\ , *ys*\ , *zs* 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 *xu*\ , *yu*\ , *zu* 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 *xu*\ , *yu*\ , *zu* means that the coordinate
|
|
values may be far outside the box bounds printed with the snapshot.
|
|
Using *xsu*\ , *ysu*\ , *zsu* is similar to using *xu*\ , *yu*\ , *zu*\ , 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.
|
|
|
|
The image flags can be printed directly using the *ix*\ , *iy*\ , *iz*
|
|
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.
|
|
|
|
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 *mu* attribute gives the
|
|
magnitude of the atom's dipole moment.
|
|
|
|
The *radius* and *diameter* attributes are specific to spherical
|
|
particles that have a finite size, such as those defined with an atom
|
|
style of *sphere*\ .
|
|
|
|
The *omegax*\ , *omegay*\ , and *omegaz* attributes are specific to
|
|
finite-size spherical particles that have an angular velocity. Only
|
|
certain atom styles, such as *sphere* define this quantity.
|
|
|
|
The *angmomx*\ , *angmomy*\ , and *angmomz* attributes are specific to
|
|
finite-size aspherical particles that have an angular momentum. Only
|
|
the *ellipsoid* atom style defines this quantity.
|
|
|
|
The *tqx*\ , *tqy*\ , *tqz* attributes are for finite-size particles that
|
|
can sustain a rotational torque due to interactions with other
|
|
particles.
|
|
|
|
The *spin*\ , *eradius*\ , *ervel*\ , and *erforce* attributes are for
|
|
particles that represent nuclei and electrons modeled with the
|
|
electronic force field (EFF). See :doc:`atom_style electron <atom_style>` and :doc:`pair_style eff <pair_eff>` for more
|
|
details.
|
|
|
|
The *c_ID* and *c_ID[N]* attributes allow per-atom vectors or arrays
|
|
calculated by a :doc:`compute <compute>` 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
|
|
:doc:`compute <compute>` 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/vtk
|
|
command. Instead, global quantities can be output by the
|
|
:doc:`thermo_style custom <thermo_style>` command, and local quantities
|
|
can be output by the dump local command.
|
|
|
|
If *c_ID* is used as an 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 :doc:`fix <fix>` 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 :doc:`fix ave/atom <fix_ave_atom>` command is one that calculates per-atom
|
|
quantities. Since it can time-average per-atom quantities produced by
|
|
any :doc:`compute <compute>`, :doc:`fix <fix>`, or atom-style
|
|
:doc:`variable <variable>`, 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
|
|
:doc:`variable <variable>` 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 :doc:`Section_modify <Section_modify>` 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.
|
|
|
|
|
|
----------
|
|
|
|
|
|
Restrictions
|
|
""""""""""""
|
|
|
|
|
|
The *custom/vtk* style does not support writing of gzipped dump files.
|
|
|
|
The *custom/vtk* dump style is part of the USER-VTK package. It is
|
|
only enabled if LAMMPS was built with that package. See the :ref:`Making LAMMPS <start_3>` section for more info.
|
|
|
|
To use this dump style, you also must link to the VTK library. See
|
|
the info in lib/vtk/README and insure the Makefile.lammps file in that
|
|
directory is appropriate for your machine.
|
|
|
|
The *custom/vtk* dump style neither supports buffering nor custom
|
|
format strings.
|
|
|
|
Related commands
|
|
""""""""""""""""
|
|
|
|
:doc:`dump <dump>`, :doc:`dump image <dump_image>`,
|
|
:doc:`dump_modify <dump_modify>`, :doc:`undump <undump>`
|
|
|
|
Default
|
|
"""""""
|
|
|
|
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.
|
|
|
|
|
|
.. _lws: http://lammps.sandia.gov
|
|
.. _ld: Manual.html
|
|
.. _lc: Section_commands.html#comm
|