git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@16053 f3b2605a-c512-4ea7-a41b...

[lammps.git] / doc / src / dump_custom_vtk.txt

 "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 custom/vtk 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 = {custom/vtk} :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
  {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 :pre

      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 "dump_modify"_dump_modify.html 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 :pre
:ule

[Examples:]

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

The style {custom/vtk} is similar to the "custom"_dump.html 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),
"dump_modify binary"_dump_modify.html 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
"dump_modify every"_dump_modify.html command for details.

Only information for atoms in the specified group is dumped.  The
"dump_modify thresh and region"_dump_modify.html commands can also
alter what atoms are included; see details below.

As described below, special characters ("*", "%") in the filename
determine the kind of output.

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.

IMPORTANT NOTE: Unless the "dump_modify sort"_dump_modify.html
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 "atom_modify
sort"_atom_modify.html 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
"dump_modify"_dump_modify.html doc page for details.

:line

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.

: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 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 "dump_modify every"_dump_modify.html command.
The "dump_modify every"_dump_modify.html 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
"dump_modify first"_dump_modify.html 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 "dump_modify pad"_dump_modify.html
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 "dump_modify"_dump_modify.html 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.

:line

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 "dump_modify element"_dump_modify.html 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 "units"_units.html (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 "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/vtk
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 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 "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 "Section 10"_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:]

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 "Making
LAMMPS"_Section_start.html#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:]

"dump"_dump.html, "dump image"_dump_image.html,
"dump_modify"_dump_modify.html, "undump"_undump.html

[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.