File: dump.html

package info (click to toggle)
liggghts 3.8.0%2Brepack1-7
links: PTS, VCS
area: main
in suites: bullseye
size: 27,240 kB
sloc: cpp: 151,239; javascript: 9,132; sh: 910; python: 676; makefile: 459; ansic: 411
file content (753 lines) | stat: -rw-r--r-- 40,273 bytes
parent folder | download | duplicates (5)


<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>dump command &mdash; LIGGGHTS v3.X documentation</title>
  

  
  
  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="LIGGGHTS v3.X documentation" href="index.html"/> 

  
  <script src="_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

   
  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search">
          

          
            <a href="Manual.html" class="icon icon-home"> LIGGGHTS
          

          
          </a>

          
            
            
              <div class="version">
                v3.X
              </div>
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">9. Modifying &amp; extending LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">10. Python interface to LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="Manual.html">LIGGGHTS</a>
        
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="Manual.html">Docs</a> &raquo;</li>
        
      <li>dump command</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/dump.txt" rel="nofollow"> View page source</a>
          
          <a href="http://www.cfdem.com"> Website</a>
          
            <a href="Section_commands.html#comm" rel="nofollow"> Commands</a>
            
          
        
      </li>
    
  </ul>

  
  <hr/>
  
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="dump-command">
<span id="index-0"></span><h1>dump command<a class="headerlink" href="#dump-command" title="Permalink to this headline">¶</a></h1>
</div>
<div class="section" id="dump-image-command">
<h1><a class="reference internal" href="dump_image.html"><em>dump image</em></a> command<a class="headerlink" href="#dump-image-command" title="Permalink to this headline">¶</a></h1>
</div>
<div class="section" id="dump-movie-command">
<h1><a class="reference internal" href="dump_image.html"><em>dump movie</em></a> command<a class="headerlink" href="#dump-movie-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>dump ID group-ID style N file args
</pre></div>
</div>
<ul class="simple">
<li>ID = user-assigned name for the dump</li>
<li>group-ID = ID of the group of atoms to be dumped</li>
<li>style = <em>atom</em> or <em>atom/vtk</em> or <em>xyz</em> or <em>image</em> or <em>local</em> or <em>custom</em> or <em>mesh/stl</em> or <em>mesh/vtk</em> or <em>mesh/vtm</em> or <em>decomposition/vtk</em></li>
<li>N = dump every this many timesteps</li>
<li>file = name of file to write dump info to</li>
<li>args = list of arguments for a particular style</li>
</ul>
<pre class="literal-block">
<em>atom</em> args = none
<em>atom/vtk</em> args = none
<em>xyz</em> args = none
</pre>
<pre class="literal-block">
<em>image</em> args = discussed on <a class="reference internal" href="dump_image.html"><em>dump image</em></a> doc page
</pre>
<pre class="literal-block">
<em>mesh/stl</em> args = 'local' or 'ghost' or 'all' or 'region' or any ID of a <a class="reference internal" href="fix_mesh_surface.html"><em>fix mesh/surface</em></a>
    <em>region</em> values = ID for region threshold
<em>mesh/vtk</em> args =  zero or more keyword/ value pairs followed by one or more dump-identifiers followed by one or more mesh ids
    keywords = <em>output</em>
    <em>output</em> values = 'face' or 'interpolate' or 'original'
    dump-identifier = 'stress' or 'id' or 'wear' or 'vel' or 'stresscomponents' or 'owner' or 'area' or 'aedges' or 'acorners' or 'nneigs'
    mesh-ids = any ID of a <a class="reference internal" href="fix_mesh_surface.html"><em>fix mesh/surface</em></a>
<em>mesh/vtm</em> args =  one or two keyword/ value(s) pairs
    keywords = <em>meshes</em> (required) or <em>mesh_properties</em>
    <em>meshes</em> value(s) = mesh-ids
    mesh-ids = either keyword 'all' or a list of IDs of <a class="reference internal" href="fix_mesh_surface.html"><em>fix mesh/surface</em></a>
    <em>mesh_properties</em> value(s) = one or more dump-identifier
    dump-identifier = 'stress' or 'id' or 'wear' or 'vel' or 'stresscomponents' or 'owner' or 'area' or 'aedges' or 'acorners' or 'nneigs'
<em>decomposition/vtk</em> args = none
</pre>
<pre class="literal-block">
<em>local</em> 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>
<pre class="literal-block">
<em>custom</em> args = list of atom attributes
  possible attributes = id, mol, id_multisphere , 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,
                     c_ID, c_ID[N], f_ID, f_ID[N], v_name
</pre>
<pre class="literal-block">
id = atom ID
mol = molecule ID
id_multisphere = ID of multisphere body
type = atom type
element = name of atom element, as defined by <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></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
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>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>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 dmpMyMesh mesh/vtk 100 mesh*.vtk vel area my_mesh_id
dump dmpAllMeshes mesh/vtk 100 mesh*.vtk stress wear
dump dmpMyMeshVTM mesh/vtm 100 mesh*.vtm meshes my_mesh_id mesh_properties vel area
dump dmpAllMeshesVTM mesh/vtm 100 mesh*.vtm meshes all mesh_properties stress wear
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Dump a snapshot of atom quantities to one or more files every N
timesteps in one of several styles.  The <em>image</em> style is the
exception; it creates a JPG or PPM image file of the atom
configuration every N timesteps, as discussed on the <a class="reference internal" href="dump_image.html"><em>dump image</em></a> doc page.  The timesteps on which dump output
is written can also be controlled by a variable; see the <a class="reference internal" href="dump_modify.html"><em>dump_modify every</em></a> command for details.</p>
<p>Only information for atoms in the specified group is dumped.  The
<a class="reference internal" href="dump_modify.html"><em>dump_modify thresh and region</em></a> commands can also
alter what atoms are included.  Not all styles support all these
options; see details below.</p>
<p>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 multiple smaller files).</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">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>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Unless the <a class="reference internal" href="dump_modify.html"><em>dump_modify sort</em></a> option
is invoked, the lines of atom information written to dump files
(typically one line per atom) will be in an indeterminate order for
each snapshot.  This is even true when running on a single processor,
if the <a class="reference internal" href="atom_modify.html"><em>atom_modify sort</em></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>
</div>
<p>For the <em>atom</em>, <em>custom</em>, and <em>local</em> styles, sorting is off by
default.  For the <em>xyz</em> style, sorting by
atom ID is on by default. See the <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> doc
page for details.</p>
<hr class="docutils" />
<p>The <em>style</em> keyword determines what atom quantities are written to the
file and in what format.  Settings made via the
<a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> command can also alter the format of
individual values and the file itself.</p>
<p>The <em>atom</em>, <em>local</em>, and <em>custom</em> styles create files in a simple text
format that is self-explanatory when viewing a dump file.</p>
<p>For post-processing purposes the <em>atom</em>, <em>local</em>, and <em>custom</em> text
files are self-describing in the following sense.</p>
<p>The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:</p>
<div class="highlight-python"><div class="highlight"><pre>ITEM: BOX BOUNDS xx yy zz
xlo xhi
ylo yhi
zlo zhi
</pre></div>
</div>
<p>where xlo,xhi are the maximum extents of the simulation box in the
x-dimension, and similarly for y and z.  The &#8220;xx yy zz&#8221; represent 6
characters that encode the style of boundary for each of the 6
simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi).  Each of
the 6 characters is either p = periodic, f = fixed, s = shrink wrap,
or m = shrink wrapped with a minimum value.  See the
<a class="reference internal" href="boundary.html"><em>boundary</em></a> command for details.</p>
<p>For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
formatted as follows:</p>
<div class="highlight-python"><div class="highlight"><pre>ITEM: BOX BOUNDS xy xz yz xx yy zz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz
</pre></div>
</div>
<p>The presence of the text &#8220;xy xz yz&#8221; in the ITEM line indicates that
the 3 tilt factors will be included on each of the 3 following lines.
This bounding box is convenient for many visualization programs.  The
meaning of the 6 character flags for &#8220;xx yy zz&#8221; is the same as above.</p>
<p>Note that the first two numbers on each line are now xlo_bound instead
of xlo, etc, since they repesent a bounding box.  See <span class="xref std std-ref">this section</span> of the doc pages for a geometric
description of triclinic boxes, as defined by LIGGGHTS(R)-PUBLIC, simple formulas
for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) are
calculated from the triclinic parameters, and how to transform those
parameters to and from other commonly used triclinic representations.</p>
<p>The &#8220;ITEM: ATOMS&#8221; line in each snapshot lists column descriptors for
the per-atom lines that follow.  For example, the descriptors would be
&#8220;id type xs ys zs&#8221; for the default <em>atom</em> style, and would be the atom
attributes you specify in the dump command for the <em>custom</em> style.</p>
<p>For style <em>atom</em>, 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
<a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> settings.  Image flags can also be
added for each atom via dump_modify.</p>
<p>For style <em>atom/vtk</em>, atom coordinates, velocity, rotational
velocity, force, atom ID, atom radius and atom type are written to
VTK files. Note that you have to link against VTK libraries to use
this functionality.</p>
<p>Style <em>custom</em> 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 <em>q</em> for atom style <em>bond</em>, since that atom style doesn&#8217;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.</p>
<p>For style <em>local</em>, local output generated by <a class="reference internal" href="compute.html"><em>computes</em></a>
and <a class="reference internal" href="fix.html"><em>fixes</em></a> is used to generate 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 <a class="reference internal" href="compute_property_local.html"><em>compute property/local</em></a> command with dump local,
it is possible to generate information on bonds that can
be cut and pasted directly into a data file read by the
<a class="reference internal" href="read_data.html"><em>read_data</em></a> command.</p>
<p>The <em>xyz</em> style writes XYZ files, which is a simple text-based
coordinate format that many codes can read. Specifically it has
a line with the number of atoms, then a comment line that is
usually ignored followed by one line per atom with the atom type
and the x-, y-, and z-coordinate of that atom. You can use the
<a class="reference internal" href="dump_modify.html"><em>dump_modify element</em></a> option to change the output
from using the (numerical) atom type to an element name (or some
other label). This will help many visualization programs to guess
bonds and colors.</p>
<p>The <em>mesh/stl</em> style dumps active STL geometries defined via
<code class="xref doc docutils literal"><span class="pre">fix</span> <span class="pre">mesh</span></code> commands into the specified file.
If you do not supply the optional list of mesh IDs, all meshes are dumped,
irrespective of whether they are used in a <a class="reference internal" href="fix_wall_gran.html"><em>fix wall/gran</em></a>
command or not. By specifying a list of mesh IDs you can explicitly
choose which meshes to dump. The group-ID is ignored, because the command
is not applied to particles, but to mesh geometries.
With keywords &#8216;local&#8217;, &#8216;owned&#8217; or &#8216;ghost&#8217; you can decide which parts
of the parallel meshes you want to dump (default is &#8216;local&#8217;). If the
multiprocessor option is not used (no &#8216;%&#8217; in filename), data is gathered
from all processors, so using the default will output the whole mesh
data across all processors.</p>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre>dump stl1 all mesh/stl 300 post/dump*.stl
dump stl2 all mesh/stl 300 post/dump_proc%_local*.stl local
dump stl3 all mesh/stl 300 post/dump_proc%_ghost*.stl ghost
dump stl4 all mesh/stl 300 post/dump_proc_all_ghost*.stl ghost
</pre></div>
</div>
<p>The first command will write one file per time-step containing the complete
mesh. The second command will output one file per time-step per processor
containing the local (owned) mesh elements of each processor.
The third command will output one file per time-step per processor
containing the ghost (corona) mesh elements of each processor.
The third command will output one file per time-step containing the
ghost (corona) mesh elements of all processors.</p>
<p>With the <em>region</em> keyword, just those mesh element where the element center
(arithmetic average of all nodes) is in the specified region, will be
dumped.</p>
<p>This dump is especially useful if a
<a class="reference internal" href="fix_move_mesh.html"><em>fix move/mesh</em></a> is registered. If the position
of the mesh is changed over time and you want to dump one file for each dump
timestep for post-processing together with the particle data, you should use
a filename like &#8216;mydumpfile*.stl&#8217;. Note: This series of files can then be
post-processed together with the particle dump file converted to VTK in
Paraview , www.paraview.org</p>
<p>By providing any ID (or a list of IDs) of <a class="reference internal" href="fix_mesh_surface.html"><em>fix mesh/surface</em></a>
commands, you can specify which meshes to dump. If no meshes are specified,
all meshes used in the simulation are dumped.</p>
<p>The <em>mesh/vtk</em> or the <em>mesh/vtm</em> (new) style can be used to dump active mesh
geometries defined via <code class="xref doc docutils literal"><span class="pre">fix</span> <span class="pre">mesh</span></code> commands to a series of VTK
files. The <em>mesh/vtk</em> style allows the file endings .vtk, .vtp and .pvtp. The
first two write the data only on one processor, the latter writes several files
in parallel. The <em>mesh/vtm</em> style currently only allows the .vtm file ending
and writes in serial only. Different keywords can be used to dump the
per-triangle averaged stress in normal and shear direction, id, velocity, wear,
stress components (fx / element area, fy / element area, fz / element area),
area (area of each element) or the process which owns the element
(visulatisation of the parallel decomposition) into the specified file using a
VTK file format. The &#8216;meshes&#8217; keyword (only for <em>mesh/vtm</em>) and the list of
mesh IDs is optional.  As with the stl style, all active meshes are dumped if
you do not supply the optional list of mesh IDs. By specifying list of mesh IDs
you can explicitly choose which meshes to dump. The group-ID is ignored. Again,
a series of files can be post-processed in Paraview , www.paraview.org Most
keywords as used for the <em>mesh/vtk</em> style are self-explanatory. Keyword
<em>output</em> controls how the data is written. If <em>face</em> (default) is selected then
all point variables will be interpolated to the triangle faces. For the value
<em>interpolated</em> all cell values will be interpolated to the respective points
and finally for <em>original</em> no interpolation will take place and cell and point
variables are written to cells and points, respectively. Keywords <em>aedges</em> and
<em>acorners</em> dump the number of active edges/corners per face.  Keyword <em>nneighs</em>
dumps the number of face neighbors LIGGGHTS(R)-PUBLIC has recognized for each face.</p>
<p><em>mesh/vtm</em> is similar to <em>mesh/vtk</em> but only the arguments are different. The
former requires the use of the keyword <em>meshes</em> which has to be followed either
by a list of mesh-ids or the keyword &#8216;all&#8217;. The latter will cause all meshes to
be dumped. After the mesh specification <em>mesh/vtm</em> can be provided with the
optional keyword <em>mesh_properties</em> that needs to be followed by the dump
identifiers. The list of such identifiers is identical to <em>mesh/vtk</em>.</p>
<p>By providing the &#8216;meshes&#8217; keyword and any ID (or a list of IDs) of
<a class="reference internal" href="fix_mesh_surface.html"><em>fix mesh/surface</em></a> commands, you can specify which meshes to dump.
If no meshes are specified, all meshes used in the simulation are dumped.</p>
<p>The <em>decomposition/vtk</em> style dumps the processor grid decomposition
into a series of VTK files. No further args are expected.</p>
<p>For all vkt outputs if <em>dump_modify binary</em> is used, the dump file (or files, if
&#8220;*&#8221; 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. Additionally, <em>dump_modify compressor</em> can be used to specify the
writing of compressed binary data. Options for compressors include:</p>
<div class="highlight-python"><div class="highlight"><pre>none: No compression
zlib: Zlib compression
lz4: Lz4 compression (VTK &gt;= 8.0 required)
</pre></div>
</div>
<hr class="docutils" />
<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 class="reference internal" href="dump_modify.html"><em>dump_modify first</em></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 class="reference internal" href="dump_modify.html"><em>dump_modify every</em></a> command.
The <a class="reference internal" href="dump_modify.html"><em>dump_modify every</em></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 class="reference internal" href="dump_modify.html"><em>dump_modify first</em></a> command is used.</p>
<p>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 <a class="reference internal" href="undump.html"><em>undump</em></a>
command is used or when LIGGGHTS(R)-PUBLIC exits.</p>
<p>Dump filenames can contain two wildcard characters.  If a &#8220;*&#8221;
character appears in the filename, then one file per snapshot is
written and the &#8220;*&#8221; character is replaced with the timestep value.
For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc.  Note that the <a class="reference internal" href="dump_modify.html"><em>dump_modify pad</em></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 &#8220;%&#8221; character appears in the filename, then each of P processors
writes a portion of the dump file, and the &#8220;%&#8221; 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</p>
<blockquote>
<div><em>xyz</em> style.</div></blockquote>
<p>By default, P = the number of processors meaning one file per
processor, but P can be set to a smaller value via the <em>nfile</em> or
<em>fileper</em> keywords of the <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> command.
These options can be the most efficient way of writing out dump files
when running on large numbers of processors.</p>
<p>Note that using the &#8220;*&#8221; and &#8220;%&#8221; characters together can produce a
large number of small dump files!</p>
<p>If the filename ends with &#8221;.bin&#8221;, the dump file (or files, if &#8220;*&#8221; or
&#8220;%&#8221; 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 option is only
available for the <em>atom</em> and <em>custom</em> styles.</p>
<p>If the filename ends with &#8221;.gz&#8221;, the dump file (or files, if &#8220;*&#8221; or &#8220;%&#8221;
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.</p>
<hr class="docutils" />
<p>This section explains the local attributes that can be specified as
part of the <em>local</em> style.</p>
<p>The <em>index</em> 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.</p>
<p>The <em>c_ID</em> and <em>c_ID[N]</em> attributes allow local vectors or arrays
calculated by a <a class="reference internal" href="compute.html"><em>compute</em></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 class="reference internal" href="compute.html"><em>compute</em></a> command for details.  There are computes for
calculating local information such as indices, types, and energies for
bonds.</p>
<p>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 <a class="reference internal" href="thermo_style.html"><em>thermo_style custom</em></a> command, and per-atom quantities can be
output by the dump custom command.</p>
<p>If <em>c_ID</em> is used as a attribute, then the local vector calculated by
the compute is printed.  If <em>c_ID[N]</em> 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.</p>
<p>The <em>f_ID</em> and <em>f_ID[N]</em> attributes allow local vectors or arrays
calculated by a <a class="reference internal" href="fix.html"><em>fix</em></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.</p>
<p>If <em>f_ID</em> is used as a attribute, then the local vector calculated by
the fix is printed.  If <em>f_ID[N]</em> 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.</p>
<p>Here is an example of how to dump bond info for a system,
including the distance and energy of each bond:</p>
<div class="highlight-python"><div class="highlight"><pre>compute 1 all property/local batom1 batom2 btype
compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]
</pre></div>
</div>
<hr class="docutils" />
<p>This section explains the atom attributes that can be specified as
part of the <em>custom</em> and style.</p>
<p>The <em>id</em>, <em>mol</em>, <em>type</em>, <em>element</em>, <em>mass</em>, <em>vx</em>, <em>vy</em>, <em>vz</em>, <em>fx</em>, <em>fy</em>,
<em>fz</em>, <em>q</em> attributes are self-explanatory.</p>
<p><em>Id</em> is the atom ID.  <em>Mol</em> is the molecule ID, included in the data
file for molecular systems. <em>id_multisphere</em> is the ID of the multisphere
body that the particle belongs to (if your version supports multisphere).
<em>Type</em> is the atom type.  <em>Element</em> is
typically the chemical name of an element, which you must assign to
each type via the <a class="reference internal" href="dump_modify.html"><em>dump_modify element</em></a> command.
More generally, it can be any string you wish to associated with an
atom type.  <em>Mass</em> is the atom mass.  <em>Vx</em>, <em>vy</em>, <em>vz</em>, <em>fx</em>, <em>fy</em>,
<em>fz</em>, and <em>q</em> are components of atom velocity and force and atomic
charge.</p>
<p>There are several options for outputting atom coordinates.  The <em>x</em>,
<em>y</em>, <em>z</em> attributes write atom coordinates &#8220;unscaled&#8221;, in the
appropriate distance <a class="reference internal" href="units.html"><em>units</em></a> (Angstroms, sigma, etc).  Use
<em>xs</em>, <em>ys</em>, <em>zs</em> if you want the coordinates &#8220;scaled&#8221; 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
<em>xu</em>, <em>yu</em>, <em>zu</em> if you want the coordinates &#8220;unwrapped&#8221; 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 <em>xu</em>, <em>yu</em>, <em>zu</em> means that the
coordinate values may be far outside the box bounds printed with the
snapshot.  Using <em>xsu</em>, <em>ysu</em>, <em>zsu</em> is similar to using <em>xu</em>, <em>yu</em>, <em>zu</em>,
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 <em>ix</em>, <em>iy</em>, <em>iz</em>
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.  LIGGGHTS(R)-PUBLIC updates these flags as atoms cross
periodic boundaries during the simulation.</p>
<p>The <em>mux</em>, <em>muy</em>, <em>muz</em> attributes are specific to dipolar systems
defined with an atom style of <em>dipole</em>.  They give the orientation of
the atom&#8217;s point dipole moment.  The <em>mu</em> attribute gives the
magnitude of the atom&#8217;s dipole moment.</p>
<p>The <em>radius</em> and <em>diameter</em> attributes are specific to spherical
particles that have a finite size, such as those defined with an atom
style of <em>sphere</em>.</p>
<p>The <em>omegax</em>, <em>omegay</em>, and <em>omegaz</em> attributes are specific to
finite-size spherical particles that have an angular velocity.  Only
certain atom styles, such as <em>sphere</em> define this quantity.</p>
<p>The <em>angmomx</em>, <em>angmomy</em>, and <em>angmomz</em> attributes are specific to
finite-size aspherical particles that have an angular momentum.  Only
the <em>ellipsoid</em> atom style defines this quantity.</p>
<p>The <em>tqx</em>, <em>tqy</em>, <em>tqz</em> attributes are for finite-size particles that
can sustain a rotational torque due to interactions with other
particles.</p>
<p>The <em>c_ID</em> and <em>c_ID[N]</em> attributes allow per-atom vectors or arrays
calculated by a <a class="reference internal" href="compute.html"><em>compute</em></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 class="reference internal" href="compute.html"><em>compute</em></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
command.  Instead, global quantities can be output by the
<a class="reference internal" href="thermo_style.html"><em>thermo_style custom</em></a> command, and local quantities
can be output by the dump local command.</p>
<p>If <em>c_ID</em> is used as a attribute, then the per-atom vector calculated
by the compute is printed.  If <em>c_ID[N]</em> 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 <em>f_ID</em> and <em>f_ID[N]</em> attributes allow vector or array per-atom
quantities calculated by a <a class="reference internal" href="fix.html"><em>fix</em></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 class="reference internal" href="fix_ave_atom.html"><em>fix ave/atom</em></a> command is one that calculates per-atom
quantities.  Since it can time-average per-atom quantities produced by
any <a class="reference internal" href="compute.html"><em>compute</em></a>, <a class="reference internal" href="fix.html"><em>fix</em></a>, or atom-style
<a class="reference internal" href="variable.html"><em>variable</em></a>, this allows those time-averaged results to
be written to a dump file.</p>
<p>If <em>f_ID</em> is used as a attribute, then the per-atom vector calculated
by the fix is printed.  If <em>f_ID[N]</em> 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 <em>v_name</em> attribute allows per-atom vectors calculated by a
<a class="reference internal" href="variable.html"><em>variable</em></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 <em>atom</em> 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 class="reference internal" href="Section_modify.html"><em>Section_modify</em></a> of the manual for information
on how to add new compute and fix styles to LIGGGHTS(R)-PUBLIC to calculate
per-atom quantities which could then be output into dump files.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>To write gzipped dump files, you must compile LIGGGHTS(R)-PUBLIC with the
-DLAMMPS_GZIP option - see the <span class="xref std std-ref">Making LAMMPS</span> section of the documentation.</p>
<p>To be able to use <em>atom/vtk</em>, you have to link to VTK libraries,
please adapt your Makefile accordingly.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="dump_image.html"><em>dump image</em></a>, <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a>,
<a class="reference internal" href="undump.html"><em>undump</em></a></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The defaults for the image style are listed on the <a class="reference internal" href="dump_image.html"><em>dump image</em></a> doc page.</p>
</div>
</div>


           </div>
           <div class="articleComments">
            
           </div>
          </div>
          <footer>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2016, DCS Computing GmbH, JKU Linz and Sandia Corporation.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'./',
            VERSION:'v3.X',
            LANGUAGE:'None',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true,
            SOURCELINK_SUFFIX: ''
        };
    </script>
      <script type="text/javascript" src="_static/jquery.js"></script>
      <script type="text/javascript" src="_static/underscore.js"></script>
      <script type="text/javascript" src="_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>