<HTML>
<CENTER><A HREF = "https://sparta.github.io">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>fix ave/grid command 
</H3>
<H3>fix ave/grid/kk command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>fix ID ave/grid group-ID Nevery Nrepeat Nfreq value1 value2 ... keyword args ... 
</PRE>
<UL><LI>ID is documented in <A HREF = "fix.html">fix</A> command 

<LI>ave/grid = style name of this fix command 

<LI>group-ID = group ID for which grid cells to perform calculation on 

<LI>Nevery = use input values every this many timesteps 

<LI>Nrepeat = # of times to use input values for calculating averages 

<LI>Nfreq = calculate averages every this many timesteps
zero or more input values can be listed 

<LI>value = c_ID, c_ID[N], f_ID, f_ID[N], v_name, g_name, g_name[N] 

<PRE>  c_ID = per-grid vector calculated by a compute with ID
  c_ID[N] = Nth column of per-grid array calculated by a compute with ID, N can include wildcard (see below)
  f_ID = per-grid vector calculated by a fix with ID
  f_ID[N] = Nth column of per-grid array calculated by a fix with ID, N can include wildcard (see below)
  v_name = per-grid vector calculated by a grid-style variable with name
  g_name = custom per-grid vector with name
  g_name[N] = Nth column of per-grid custom array with name, N can include wildcard (see below) 
</PRE>
<LI>zero or more keyword/arg pairs may be appended 

<PRE>keyword = <I>ave</I>
  <I>ave</I> args = one or running
    one = output a new average value every Nfreq steps
    running = accumulate average continuously 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>fix 1 ave/grid all 10 20 1000 c_mine
fix 1 ave/grid all 1 100 100 c_2[1] ave running
fix 1 ave/grid all 1 100 100 c_2[*] ave running
fix 1 ave/grid section1 5 20 100 v_myEng 
</PRE>
<P>These commands will dump averages for each species and each grid cell
to a file every 1000 steps:
</P>
<PRE>compute 1 grid species n u v w usq vsq wsq
fix 1 ave/grid 10 100 1000 c_1[*]
dump 1 grid all 1000 tmp.grid id f_1[*] 
</PRE>
<P><B>Description:</B>
</P>
<P>Use one or more per-grid vectors as inputs every few timesteps, and
average by grid cell over longer timescales, applying appropriate
normalization factors.  The resulting per grid cell averages can be
used by other output commands such as the <A HREF = "dump.html">dump grid</A>
command.  Only grid cells in the grid group specified by <I>group-ID</I>
are included in the averaging.  See the <A HREF = "group.html">group grid</A>
command for info on how grid cells can be assigned to grid
groups.
</P>
<P>Each input value can be the result of a <A HREF = "compute.html">compute</A> or
<A HREF = "fix.html">fix</A> or <A HREF = "variable.html">grid-style variable</A>.  The compute or
fix must produce a per-grid vector or array, not a global or
per-particle or per-surf quantity.  If you wish to time-average global
quantities from a compute, fix, or variable, then see the <A HREF = "fix_ave_time.html">fix
ave/time</A> command.  To time-average per-surf
quantities, see the <A HREF = "fix_ave_surf.html">fix ave/surf</A> command.
</P>
<P>Each per-grid value of each input vector is averaged independently.
</P>
<P><A HREF = "compute.html">Computes</A> that produce per-grid vectors or arrays are
those which have the word <I>grid</I> in their style name.  See the doc
pages for individual <A HREF = "fix.html">fixes</A> to determine which ones produce
per-grid vectors or arrays. 
</P>
<P>Note that for values from a compute or fix or custom attribute, the
bracketed index can be specified using a wildcard asterisk with the
index to effectively specify multiple values.  This takes the form "*"
or "*n" or "n*" or "m*n".  If N = the size of the vector (for <I>mode</I> =
scalar) or the number of columns in the array (for <I>mode</I> = vector),
then an asterisk with no numeric values means all indices from 1 to N.
A leading asterisk means all indices from 1 to n (inclusive).  A
trailing asterisk means all indices from n to N (inclusive).  A middle
asterisk means all indices from m to n (inclusive).
</P>
<P>Using a wildcard is the same as if the individual columns of the array
had been listed one by one.  E.g. these 2 fix ave/grid commands are
equivalent, since the <A HREF = "compute_grid.html">compute grid</A> command creates
a per-grid array with 3 columns:
</P>
<PRE>compute myGrid all all u v w
fix 1 ave/grid all 10 20 1000 c_myGrid[*]
fix 1 ave/grid all 10 20 1000 c_myGrid[1] c_myGrid[2] c_myGrid[3] 
</PRE>
<HR>

<P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
timesteps the input values will be used in order to contribute to the
average.  The final averaged quantities are generated on timesteps
that are a multiple of <I>Nfreq</I>.  The average is over <I>Nrepeat</I>
quantities, computed in the preceding portion of the simulation every
<I>Nevery</I> timesteps.  <I>Nfreq</I> must be a multiple of <I>Nevery</I> and
<I>Nevery</I> must be non-zero even if <I>Nrepeat</I> is 1.  Also, the timesteps
contributing to the average value cannot overlap, i.e. Nfreq >
(Nrepeat-1)*Nevery is required.
</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.
</P>
<HR>

<P>If a value begins with "c_", a compute ID must follow which has been
previously defined in the input script.  If no bracketed term is
appended, the compute must calculate a per-grid vector.  If
<I>c_ID[N]</I> is used, the compute must calculate a per-grud array with
M columns and N must be in the range from 1-M, which will use the Nth
column of the M-column per-grid array.  See the discussion above for
how N can be specified with a wildcard asterisk to effectively specify
multiple values.
</P>
<P>Users can also write code for their own compute styles and <A HREF = "Section_modify.html">add them
to SPARTA</A>.
</P>
<P>If a value begins with "f_", a fix ID must follow which has been
previously defined in the input script.  If no bracketed term is
appended, the fix must calculates a per-grid vector.  If <I>f_ID[N]</I>
is used, the fix must calculate a per-grid array with M columns and N
must be in the range from 1-M, which will use the Nth column of the
M-column per-grid array.  See the discussion above for how N can be
specified with a wildcard asterisk to effectively specify multiple
values.
</P>
<P>Note that some fixes only produce their values on certain timesteps,
which must be compatible with <I>Nevery</I>, else an error will result.
Users can also write code for their own fix styles and <A HREF = "Section_modify.html">add them to
SPARTA</A>.
</P>
<P>If a value begins with "v_", a variable name must follow which has
been previously defined in the input script.  Only grid-style
variables can be referenced.  See the <A HREF = "variable.html">variable</A> command
for details.  Note that grid-style variables define a formula which
can reference <A HREF = "stats_style.html">stats_style</A> keywords, or they can
invoke other computes, fixes, or variables when they are evaluated, so
this is a very general means of specifying quantities to time average.
</P>
<P>If a value begins with "g_", the name of a custom per-grid vector or
array must follow.  Custom attributes can store either a single or
multiple values per grid cell.  See <A HREF = "Section_howto.html#howto_17">Section
6.17</A> for more discussion of custom
attributes and command that define them.  For example, the
<A HREF = "read_grid.html">read_grid</A> and <A HREF = "surf_react_implicit.html">surf_react
implicit</A> commands can define per-grid
attributes.  (The surf/react implicit command has not yet been
released in public SPARTA).
</P>
<P>If <I>g_name</I> is used as a value, the custom attribute must be a vector.
If <I>g_name[N]</I> is used, the custom attribute must be an array, and N
must be in the range from 1-M for an M-column array.  See the
discussion above for how N can be specified with a wildcard asterisk
to effectively specify multiple values.
</P>
<HR>

<P>For averaging of a value that comes from a compute or fix,
normalization is performed as follows.  Note that no normalization is
performed on a value produced by a grid-style variable.
</P>
<P>If the compute or fix is summing over particles in a grid cell to
calculate a per-grid quantity (e.g. energy or temperature), this takes
the form of a numerator divided by a denominator.  For example, see
the formulas discussed on the <A HREF = "compute_grid.html">compute grid</A> doc
page, where the denominator is 1 (for keyword n), or the number of
particles (ke, mass, temp), or the sum of particle masses (u, usq,
etc).  When this command averages over a series of timesteps, the
numerator and denominator are summed separately.  This means the
numerator/denominator division only takes place when this fix produces
output, every Nfreq timesteps.
</P>
<P>For example, say the Nfreq output is over 2 timesteps, and the value
produced by <A HREF = "compute_grid.html">compute grid mass</A> is being averaged.
Say a grid cell has 10 particles on the 1st timestep with a numerator
value of 10.0, and 100 particles on the 2nd timestep with a numerator
value of 50.0.  The output of this fix will be (10+50) / (10+100) =
0.54, not ((10/10) + (50/100)) / 2 = 0.75.
</P>
<HR>

<P>Additional optional keywords also affect the operation of this fix. 
</P>
<P>The <I>ave</I> keyword determines what happens to the accumulation of
statistics every <I>Nfreq</I> timesteps.
</P>
<P>If the <I>ave</I> setting is <I>one</I>, then the values produced on timesteps
that are multiples of Nfreq are independent of each other.
Normalization as described above is performed, and all tallies are
zeroed before accumulating over the next <I>Nfreq</I> steps.
</P>
<P>If the <I>ave</I> setting is <I>running</I>, then tallies are never zeroed.
Thus the output at any <I>Nfreq</I> timestep is normalized over all
previously accumulated samples since the fix was defined.  The tallies
can only be zeroed by deleting the fix via the unfix command, or by
re-defining the fix, or by re-specifying it.
</P>
<HR>

<P><B>Restart, output info:</B>
</P>
<P>No information about this fix is written to <A HREF = "restart.html">binary restart
files</A>.
</P>
<P>This fix produces a per-grid vector or array which can be accessed by
various output commands.  A vector is produced if only a single
quantity is averaged by this fix.  If two or more quantities are
averaged, then an array of values is produced, where the number of
columns is the number of quantities averaged.  The per-grid values can
only be accessed on timesteps that are multiples of <I>Nfreq</I> since that
is when averaging is performed.
</P>
<P>This fix performs averaging for all child grid cells in the
simulation, which includes unsplit, split, and sub cells.  <A HREF = "Section_howto.html#howto_">Section
4.8</A> of the manual gives details of how
SPARTA defines child, unsplit, split, and sub cells.
</P>
<P>Grid cells not in the specified <I>group-ID</I> will output zeroes for all
their values.
</P>
<HR>

<P>Styles with a <I>kk</I> suffix are functionally the same as the
corresponding style without the suffix.  They have been optimized to
run faster, depending on your available hardware, as discussed in the
<A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the manual.
The accelerated styles take the same arguments and should produce the
same results, except for different random number, round-off and
precision issues.
</P>
<P>These accelerated styles are part of the KOKKOS package. They are only
enabled if SPARTA was built with that package.  See the <A HREF = "Section_start.html#start_3">Making
SPARTA</A> section for more info.
</P>
<P>You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the <A HREF = "Section_start.html#start_7">-suffix command-line
switch</A> when you invoke SPARTA, or you can
use the <A HREF = "suffix.html">suffix</A> command in your input script.
</P>
<P>See the <A HREF = "Section_accelerate.html">Accelerating SPARTA</A> section of the
manual for more instructions on how to use the accelerated styles
effectively.
</P>
<HR>

<P><B>Restrictions:</B>
</P>
<P>If one of the specified values is a compute which tallies information
on collisions between particles and implicit surface element within
each grid cell, then all the values must be for compute(s) which do
this.  I.e. you cannot mix computes which operate on implicit surfaces
with other kinds of per-grid values in the same fix ave/grid command.
</P>
<P>Examples of computes which tally particle/implicit surface element
collision info within each grid cell are <A HREF = "compute_isurf_grid.html">compute
isurf/grid</A> and <A HREF = "compute_react_isurf_grid.html">compute
react/isurf/grid</A>.
</P>
<P>If performing on-the-fly grid adaptation every N timesteps, using the
<A HREF = "fix_adapt.html">fix adapt</A> command, this fix cannot time-average
across time windows > N steps, since the grid may change.  This means
<I>Nfreq</I> cannot be > N, and keyword <I>ave</I> = <I>running</I> is not allowed.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix_ave_time.html">fix ave/time</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are ave = one.
</P>
</HTML>
