<div class="highlight-python"><div class="highlight"><pre>vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
density/number, density/mass = number or mass density
temp = temperature
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith 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>
<ul class="simple">
<li>zero or more keyword/arg pairs may be appended</li>
<li>keyword = <em>norm</em> or <em>ave</em> or <em>bias</em> or <em>adof</em> or <em>cdof</em> or <em>file</em> or <em>overwrite</em> or <em>title1</em> or <em>title2</em> or <em>title3</em></li>
</ul>
<pre class="literal-block">
<em>norm</em> arg = <em>all</em> or <em>sample</em> or <em>none</em> = how output on <em>Nfreq</em> steps is normalized
all = output is sum of atoms across all <em>Nrepeat</em> samples, divided by atom count
sample = output is sum of <em>Nrepeat</em> sample averages, divided by <em>Nrepeat</em>
none = output is sum of <em>Nrepeat</em> sample sums, divided by <em>Nrepeat</em>
<em>ave</em> args = <em>one</em> or <em>running</em> or <em>window M</em>
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
<em>bias</em> arg = bias-ID
bias-ID = ID of a temperature compute that removes a velocity bias for temperature calculation
<em>adof</em> value = dof_per_atom
dof_per_atom = define this many degrees-of-freedom per atom for temperature calculation
<em>cdof</em> value = dof_per_chunk
dof_per_chunk = define this many degrees-of-freedom per chunk for temperature calculation
<em>file</em> arg = filename
filename = file to write results to
<em>overwrite</em> arg = none = overwrite output file with only latest output
<em>format</em> arg = string
string = C-style format string
<em>title1</em> arg = string
string = text to print as 1st line of output file
<em>title2</em> arg = string
string = text to print as 2nd line of output file
<em>title3</em> arg = string
string = text to print as 3rd line of output file
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>If you are trying to replace an older fix ave/spatial command with the
newer, more flexible fix ave/chunk and <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> commands, you simply need to split
the fix ave/spatial arguments across the two new commands. For
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Use one or more per-atom vectors as inputs every few timesteps, sum
the values over the atoms in each chunk at each timestep, then average
the per-chunk values over longer timescales. The resulting chunk
averages can be used by other <a class="reference internal" href="Section_howto.html#howto-15"><span>output commands</span></a> such as <a class="reference internal" href="thermo_style.html"><em>thermo_style custom</em></a>, and can also be written to a file.</p>
<p>In LAMMPS, chunks are collections of atoms defined by a <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> doc page and “<a class="reference internal" href="Section_howto.html#howto-23"><span>Section_howto 23</span></a> for details of how chunks can be
defined and examples of how they can be used to measure properties of
a system.</p>
<p>Note that only atoms in the specified group contribute to the summing
and averaging calculations. The <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command defines its own group as
well as an optional region. Atoms will have a chunk ID = 0, meaning
they belong to no chunk, if they are not in that group or region.
Thus you can specify the “all” group for this command if you simply
want to use the chunk definitions provided by chunkID.</p>
<p>Each specified per-atom value can be an atom attribute (position,
velocity, force component), a mass or number density, or the result of
a <a class="reference internal" href="compute.html"><em>compute</em></a> or <a class="reference internal" href="fix.html"><em>fix</em></a> or the evaluation of an
atom-style <a class="reference internal" href="variable.html"><em>variable</em></a>. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. Note that the <a class="reference internal" href="compute_property_atom.html"><em>compute property/atom</em></a> command provides access to
any attribute defined and stored by atoms. If you wish to
time-average global quantities from a compute, fix, or variable, then
see the <a class="reference internal" href="fix_ave_time.html"><em>fix ave/time</em></a> command.</p>
<p><a class="reference internal" href="compute.html"><em>Computes</em></a> that produce per-atom quantities are those
which have the word <em>atom</em> in their style name. See the doc pages for
individual <a class="reference internal" href="fix.html"><em>fixes</em></a> to determine which ones produce per-atom
quantities. <a class="reference internal" href="variable.html"><em>Variables</em></a> of style <em>atom</em> are the only
ones that can be used with this fix since all other styles of variable
produce global quantities.</p>
<p>The per-atom values of each input vector are summed and averaged
independently of the per-atom values in other input vectors.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This fix works by creating an array of size <em>Nchunk</em> by Nvalues
on each processor. <em>Nchunk</em> is the number of chunks which is defined
by the <code class="xref doc docutils literal"><span class="pre">compute</span> <span class="pre">chunk/atom</span></code> command.
Nvalues is the number of input values specified. Each processor loops
over its atoms, tallying its values to the appropriate chunk. Then
the entire array is summed across all processors. This means that
using a large number of chunks will incur an overhead in memory and
computational cost (summing across processors), so be careful to
define a reasonable number of chunks.</p>
</div>
<hr class="docutils" />
<p>The <em>Nevery</em>, <em>Nrepeat</em>, and <em>Nfreq</em> arguments specify on what
timesteps the input values will be accessed and contribute to the
average. The final averaged quantities are generated on timesteps
that are a multiples of <em>Nfreq</em>. The average is over <em>Nrepeat</em>
quantities, computed in the preceding portion of the simulation every
<em>Nevery</em> timesteps. <em>Nfreq</em> must be a multiple of <em>Nevery</em> and
<em>Nevery</em> must be non-zero even if <em>Nrepeat</em> is 1. Also, the timesteps
contributing to the average value cannot overlap, i.e. Nrepeat*Nevery
can not exceed Nfreq.</p>
<p>For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
timesteps 90,92,94,96,98,100 will be used to compute the final average
on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on
timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time
averaging is done; values are simply generated on timesteps
100,200,etc.</p>
<p>Each input value can also be averaged over the atoms in each chunk.
The way the averaging is done across the <em>Nrepeat</em> timesteps to
produce output on the <em>Nfreq</em> timesteps, and across multiple <em>Nfreq</em>
outputs, is determined by the <em>norm</em> and <em>ave</em> keyword settings, as
discussed below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To perform per-chunk averaging within a <em>Nfreq</em> time window, the
number of chunks <em>Nchunk</em> defined by the <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command must remain constant. If
the <em>ave</em> keyword is set to <em>running</em> or <em>window</em> then <em>Nchunk</em> must
remain constant for the duration of the simulation. This fix forces
the chunk/atom compute specified by chunkID to hold <em>Nchunk</em> constant
for the appropriate time windows, by not allowing it to re-calcualte
<em>Nchunk</em>, which can also affect how it assigns chunk IDs to atoms.
More details are given on the <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> doc page.</p>
</div>
<hr class="docutils" />
<p>The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
As noted above, any other atom attributes can be used as input values
to this fix by using the <a class="reference internal" href="compute_property_atom.html"><em>compute property/atom</em></a> command and then specifying
an input value from that compute.</p>
<p>The <em>density/number</em> value means the number density is computed for
each chunk, i.e. number/volume. The <em>density/mass</em> value means the
mass density is computed for each chunk, i.e. total-mass/volume. The
output values are in units of 1/volume or density (mass/volume). See
the <a class="reference internal" href="units.html"><em>units</em></a> command doc page for the definition of density
for each choice of units, e.g. gram/cm^3. If the chunks defined by
the <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command are spatial
bins, the volume is the bin volume. Otherwise it is the volume of the
entire simulation box.</p>
<p>The <em>temp</em> value means the temperature is computed for each chunk, by
the formula KE = DOF/2 k T, where KE = total kinetic energy of the
chunk of atoms (sum of 1/2 m v^2), DOF = the total number of degrees
of freedom for all atoms in the chunk, k = Boltzmann constant, and T =
temperature.</p>
<p>The DOF is calculated as N*adof + cdof, where N = number of atoms in
the chunk, adof = degrees of freedom per atom, and cdof = degrees of
freedom per chunk. By default adof = 2 or 3 = dimensionality of
system, as set via the <a class="reference internal" href="dimension.html"><em>dimension</em></a> command, and cdof =
0.0. This gives the usual formula for temperature.</p>
<p>Note that currently this temperature only includes translational
degrees of freedom for each atom. No rotational degrees of freedom
are included for finite-size particles. Also no degrees of freedom
are subtracted for any velocity bias or constraints that are applied,
such as <a class="reference internal" href="compute_temp_partial.html"><em>compute temp/partial</em></a>, or <a class="reference internal" href="fix_shake.html"><em>fix shake</em></a> or <a class="reference internal" href="fix_rigid.html"><em>fix rigid</em></a>. This is because
those degrees of freedom (e.g. a constrained bond) could apply to sets
of atoms that are both included and excluded from a specific chunk,
and hence the concept is somewhat ill-defined. In some cases, you can
use the <em>adof</em> and <em>cdof</em> keywords to adjust the calculated degress of
freedom appropriately, as explained below.</p>
<p>Also note that a bias can be subtracted from atom velocities before
they are used in the above formula for KE, by using the <em>bias</em>
keyword. This allows, for example, a thermal temperature to be
computed after removal of a flow velocity profile.</p>
<p>Note that the per-chunk temperature calculated by this fix and the
<a class="reference internal" href="compute_temp_chunk.html"><em>compute temp/chunk</em></a> command can be different.
The compute calculates the temperature for each chunk for a single
snapshot. This fix can do that but can also time average those values
over many snapshots, or it can compute a temperature as if the atoms
in the chunk on different timesteps were collected together as one set
of atoms to calculate their temperature. The compute allows the
center-of-mass velocity of each chunk to be subtracted before
calculating the temperature; this fix does not.</p>
<p>If a value begins with “<a href="#id1"><span class="problematic" id="id2">c_</span></a>”, a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and <a class="reference internal" href="Section_modify.html"><em>add them to LAMMPS</em></a>.</p>
<p>If a value begins with “<a href="#id3"><span class="problematic" id="id4">f_</span></a>”, a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
<em>Nevery</em>, else an error results. Users can also write code for their
own fix styles and <a class="reference internal" href="Section_modify.html"><em>add them to LAMMPS</em></a>.</p>
<p>If a value begins with “<a href="#id5"><span class="problematic" id="id6">v_</span></a>”, a variable name must follow which has
been previously defined in the input script. Variables of style
<em>atom</em> can reference thermodynamic keywords and various per-atom
attributes, or invoke other computes, fixes, or variables when they
are evaluated, so this is a very general means of generating per-atom
quantities to average within chunks.</p>
<hr class="docutils" />
<p>Additional optional keywords also affect the operation of this fix
and its outputs.</p>
<p>The <em>norm</em> keyword affects how averaging is done for the per-chunk
values that are output every <em>Nfreq</em> timesteps.</p>
<p>It the <em>norm</em> setting is <em>all</em>, which is the default, a chunk value is
summed over all atoms in all <em>Nrepeat</em> samples, as is the count of
atoms in the chunk. The averaged output value for the chunk on the
<em>Nfreq</em> timesteps is Total-sum / Total-count. In other words it is an
average over atoms across the entire <em>Nfreq</em> timescale.</p>
<p>If the <em>norm</em> setting is <em>sample</em>, the chunk value is summed over atoms
for each sample, as is the count, and an “average sample value” is
computed for each sample, i.e. Sample-sum / Sample-count. The output
value for the chunk on the <em>Nfreq</em> timesteps is the average of the
<em>Nrepeat</em> “average sample values”, i.e. the sum of <em>Nrepeat</em> “average
sample values” divided by <em>Nrepeat</em>. In other words it is an average
of an average.</p>
<p>If the <em>norm</em> setting is <em>none</em>, a similar computation as for the
<em>sample</em> seting is done, except the individual “average sample values”
are “summed sample values”. A summed sample value is simply the chunk
value summed over atoms in the sample, without dividing by the number
of atoms in the sample. The output value for the chunk on the
<em>Nfreq</em> timesteps is the average of the <em>Nrepeat</em> “summed sample
values”, i.e. the sum of <em>Nrepeat</em> “summed sample values” divided by
<em>Nrepeat</em>.</p>
<p>The <em>ave</em> keyword determines how the per-chunk values produced every
<em>Nfreq</em> steps are averaged with values produced on previous steps that
were multiples of <em>Nfreq</em>, before they are accessed by another output
command or written to a file.</p>
<p>If the <em>ave</em> setting is <em>one</em>, which is the default, then the chunk
values produced on timesteps that are multiples of <em>Nfreq</em> are
independent of each other; they are output as-is without further
averaging.</p>
<p>If the <em>ave</em> setting is <em>running</em>, then the chunk values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged in a
cumulative sense before being output. Each output chunk value is thus
the average of the chunk value produced on that timestep with all
preceding values for the same chunk. This running average begins when
the fix is defined; it can only be restarted by deleting the fix via
the <a class="reference internal" href="unfix.html"><em>unfix</em></a> command, or re-defining the fix by
re-specifying it.</p>
<p>If the <em>ave</em> setting is <em>window</em>, then the chunk values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged within
a moving “window” of time, so that the last M values for the same
chunk are used to produce the output. E.g. if M = 3 and Nfreq = 1000,
then the output on step 10000 will be the average of the individual
chunk values on steps 8000,9000,10000. Outputs on early steps will
average over less than M values if they are not available.</p>
<p>The <em>bias</em> keyword specifies the ID of a temperature compute that
removes a “bias” velocity from each atom, specified as <em>bias-ID</em>. It
is only used when the <em>temp</em> value is calculated, to compute the
thermal temperature of each chunk after the translational kinetic
energy components have been altered in a prescribed way, e.g. to
remove a flow velocity profile. See the doc pages for individual
computes that calculate a temperature to see which ones implement a
bias.</p>
<p>The <em>adof</em> and <em>cdof</em> keywords define the values used in the degree of
freedom (DOF) formula described above for for temperature calculation
for each chunk. They are only used when the <em>temp</em> value is
calculated. They can be used to calculate a more appropriate
temperature for some kinds of chunks. Here are 3 examples:</p>
<p>If spatially binned chunks contain some number of water molecules and
<a class="reference internal" href="fix_shake.html"><em>fix shake</em></a> is used to make each molecule rigid, then
you could calculate a temperature with 6 degrees of freedom (DOF) (3
translational, 3 rotational) per molecule by setting <em>adof</em> to 2.0.</p>
<p>If <a class="reference internal" href="compute_temp_partial.html"><em>compute temp/partial</em></a> is used with the
<em>bias</em> keyword to only allow the x component of velocity to contribute
to the temperature, then <em>adof</em> = 1.0 would be appropriate.</p>
<p>If each chunk consists of a large molecule, with some number of its
bonds constrained by <a class="reference internal" href="fix_shake.html"><em>fix shake</em></a> or the entire molecule
by <a class="reference internal" href="fix_rigid.html"><em>fix rigid/small</em></a>, <em>adof</em> = 0.0 and <em>cdof</em> could be
set to the remaining degrees of freedom for the entire molecule
(entire chunk in this case), e.g. 6 for 3d, or 3 for 2d, for a rigid
molecule.</p>
<p>The <em>file</em> keyword allows a filename to be specified. Every <em>Nfreq</em>
timesteps, a section of chunk info will be written to a text file in
the following format. A line with the timestep and number of chunks
is written. Then one line per chunk is written, containing the chunk
ID (1-Nchunk), an optional original ID value, optional coordinate
values for chunks that represent spatial bins, the number of atoms in
the chunk, and one or more calculated values. More explanation of the
optional values is given below. The number of values in each line
corresponds to the number of values specified in the fix ave/chunk
command. The number of atoms and the value(s) are summed or average
quantities, as explained above.</p>
<p>The <em>overwrite</em> keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the <em>ave running</em> setting.</p>
<p>The <em>format</em> keyword sets the numeric format of each value when it is
printed to a file via the <em>file</em> keyword. Note that all values are
floating point quantities. The default format is %g. You can specify
a higher precision if desired, e.g. %20.16g.</p>
<p>The <em>title1</em> and <em>title2</em> and <em>title3</em> keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the <em>file</em> keyword was used. LAMMPS uses default
values for each of these, so they do not need to be specified.</p>
<p>By default, these header lines are as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Chunk-averaged data for fix ID and group name</span>
<p>In the first line, ID and name are replaced with the fix-ID and group
name. The second line describes the two values that are printed at
the first of each section of output. In the third line the values are
replaced with the appropriate value names, e.g. fx or c_myCompute**2**.</p>
<p>The words in parenthesis only appear with corresponding columns if the
chunk style specified for the <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command supports them. The OrigID
column is only used if the <em>compress</em> keyword was set to <em>yes</em> for the
<a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command. This means that
the original chunk IDs (e.g. molecule IDs) will have been compressed
to remove chunk IDs with no atoms assigned to them. Thus a compresed
chunk ID of 3 may correspond to an original chunk ID or molecule ID of
415. The OrigID column will list 415 for the 3rd chunk.</p>
<p>The CoordN columns only appear if a <em>binning</em> style was used in the
<a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command. For <em>bin/1d</em>,
<em>bin/2d</em>, and <em>bin/3d</em> styles the column values are the center point
of the bin in the corresponding dimension. Just Coord1 is used for
<em>bin/1d</em>, Coord2 is added for <em>bin/2d</em>, Coord3 is added for <em>bin/3d</em>.
For <em>bin/sphere</em>, just Coord1 is used, and it is the radial
coordinate. For <em>bin/cylinder</em>, Coord1 and Coord2 are used. Coord1
is the radial coordinate (away from the cylinder axis), and coord2 is
the coordinate along the cylinder axis.</p>
<p>Note that if the value of the <em>units</em> keyword used in the <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom command</em></a> is <em>box</em> or <em>lattice</em>, the
coordinate values will be in distance <a class="reference internal" href="units.html"><em>units</em></a>. If the
value of the <em>units</em> keyword is <em>reduced</em>, the coordinate values will
be in unitless reduced units (0-1). This is not true for the Coord1 value
of style <em>bin/sphere</em> or <em>bin/cylinder</em> which both represent radial
dimensions. Those values are always in distance <a class="reference internal" href="units.html"><em>units</em></a>.</p>
<h2>Restart, fix_modify, output, run start/stop, minimize info<a class="headerlink" href="#restart-fix-modify-output-run-start-stop-minimize-info" title="Permalink to this headline">¶</a></h2>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><em>binary restart files</em></a>. None of the <a class="reference internal" href="fix_modify.html"><em>fix_modify</em></a> options
are relevant to this fix.</p>
<p>This fix computes a global array of values which can be accessed by
various <a class="reference internal" href="Section_howto.html#howto-15"><span>output commands</span></a>. The values can
only be accessed on timesteps that are multiples of <em>Nfreq</em> since that
is when averaging is performed. The global array has # of rows =
the number of chunks <em>Nchunk</em> as calculated by the specified <a class="reference internal" href="compute_chunk_atom.html"><em>compute chunk/atom</em></a> command. The # of columns =
M+1+Nvalues, where M = 1 to 4, depending on whether the optional
columns for OrigID and CoordN are used, as explained above.
Following the optional columns, the next column contains the count of
atoms in the chunk, and the remaining columns are the Nvalue
quantities. When the array is accessed with a row I that exceeds the
current number of chunks, than a 0.0 is returned by the fix instead of
an error, since the number of chunks can vary as a simulation runs
depending on how that value is computed by the compute chunk/atom
command.</p>
<p>The array values calculated by this fix are treated as “intensive”,
since they are typically already normalized by the count of atoms in
each chunk.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><em>run</em></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><em>energy minimization</em></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div>none</div></blockquote>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
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>.