<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>compute reduce command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>compute ID reduce mode input1 input2 ... keyword args ... 
</PRE>
<UL><LI>ID is documented in <A HREF = "compute.html">compute</A> command 

<LI>reduce = style name of this compute command 

<LI>mode = <I>sum</I> or <I>min</I> or <I>max</I> or <I>ave</I> or <I>sumsq</I> or <I>avesq</I> or <I>sum-area</I> or <I>ave-area</I> 

<LI>one or more inputs can be listed 

<LI>input = x, y, z, vx, vy, vz, ke, erot, evib, c_ID, c_ID[N], f_ID, f_ID[N], v_name, p_name, p_name[N], g_name, g_name[N], s_name, s_name[N] 

<PRE>  x,y,z,vx,vy,vz = particle position or velocity component
  ke,erot,evib = particle energy component
  c_ID = per-particle or per-grid vector calculated by a compute with ID
  c_ID[N] = Nth column of per-particle or per-grid array calculated by a compute with ID, N can include wildcard (see below)
  f_ID = per-particle or per-grid or per-surf vector calculated by a fix with ID
  f_ID[N] = Nth column of per-particle or per-grid or per-surf array calculated by a fix with ID, N can include wildcard (see below)
  v_name = per-particle or per-grid or per-surf vector calculated by a particle-style or grid-style or surf-style variable with name
  p_name = custom per-particle vector with name
  p_name[N] = Nth column of per-particle custom array with name, N can include wildcard (see below)
  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)
  s_name = custom per-surf vector with name
  s_name[N] = Nth column of per-surf custom array with name, N can include wildcard (see below) 
</PRE>
<LI>zero or more keyword/args pairs may be appended 

<LI>keyword = <I>replace</I> or <I>subset</I> 

<PRE>  <I>replace</I> args = vec1 vec2
    vec1 = reduced value from this input vector will be replaced
    vec2 = replace it with vec1[N] where N is index of max/min value from vec2
  <I>subset</I> arg = subsetID
    subsetID = mixture-ID or grid group-ID or surface group-ID 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>compute 1 reduce sum c_grid[*]
compute 2 reduce min f_ave v_myKE subset trace_species
compute 3 reduce max c_mine[1] c_mine[2] c_temp replace 1 3 replace 2 3 
</PRE>
<P>These commands will include the average grid cell temperature, across
all grid cells, in the stats output:
</P>
<PRE>compute 1 temp
compute	2 grid all all temp
compute 3 reduce ave c_2[1]
stats_style step c_temp c_3 
</PRE>
<P><B>Description:</B>
</P>
<P>Define a calculation that "reduces" one or more vector inputs into
scalar values, one per listed input.  The inputs can be per-particle
or per-grid or per-surf quantities; they cannot be global quantities.
Particle attributes are per-particle quantities.
<A HREF = "compute.html">Computes</A> and <A HREF = "fix.html">fixes</A> may generate any of the
three kinds of quantities.  <A HREF = "variable.html">Particle-style, grid-style, and
surf-style variables</A> generate per-particle, per-grid,
or per-surf quantities respectively.  Custom attributes can be
per-particle, per-grid, or per-surf quantities.  See the
<A HREF = "variable">variable</A> command and its special functions which can
perform the same operations as the compute reduce command on global
vectors.
</P>
<P>IMPORTANT NOTE: All inputs to a compute reduce command must be the
same type: per-particle, per-grid, or per-surf.  You can use the
command multiple times if you need to reduce values of different
types.
</P>
<P>The reduction operation is specified by the <I>mode</I> setting.  The <I>sum</I>
option adds the values in the vector into a global total.  The <I>min</I>
or <I>max</I> operations find the minimum or maximum value across all
vector values.  The <I>ave</I> operation adds the vector values into a
global total, then divides by the number of values in the vector.  The
<I>sumsq</I> operation sums the square of the values in the vector into a
global total.  The <I>avesq</I> oepration does the same as <I>sumsq</I>, then
divdes the sum of squares by the number of values.  These two
operations can be useful for calculating the variance of some
quantity, e.g. variance = sumsq - ave^2.
</P>
<P>The <I>sum-area</I> or <I>ave-area</I> options can only be used for per-surf
inputs.  Both options multiply each per-surf value by the area of the
surface element (triangle in 3d, line segment in 2d) and sum the
resulting values over all surface elements.  That is the output for
the <I>sum-area</I> option.  For the <I>ave-area</I> option the summed value is
divided by the summed area of all elements.  Note that both of these
options are designed to work with flux values (e.g. mass per area per
time) produced by the <A HREF = "compute_surf.html">compute surf</A> command with
its default <I>norm</I> = yes option.
</P>
<HR>

<P>Each listed input vector is operated on independently.
</P>
<P>Each listed input vector can be a particle attribute or can be the
result of a <A HREF = "compute.html">compute</A> or <A HREF = "fix.html">fix</A> or the evaluation
of a <A HREF = "variable.html">variable</A>.  Or it can be a custom attribute of a
particle, grid cell, or surface element.
</P>
<P>Note that for values from a compute or fix or custom attribute, the
bracketed index I 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 compute reduce 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 grid all all u v w
compute 2 all reduce min c_myGrid[*]
compute 2 all reduce min c_myGrid[1] c_myGrid[2] c_myGrid[3] 
</PRE>
<HR>

<P>The particle attributes x,y,z,vx,vy,vz are position and velocity
components.  The ke,erot,evib attributes are for kinetic, rotational,
and vibrational energy of particles.
</P>
<P>If a value begins with "c_", a compute ID must follow which has been
previously defined in the input script.  Computes can generate
per-particle or per-grid quantities.  See the individual
<A HREF = "compute.html">compute</A> doc page for details.  If no bracketed integer
is appended, the vector calculated by the compute is used.  If a
bracketed integer is appended, the Nth column of the array calculated
by the compute is used.  Users can also write code for their own
compute styles and <A HREF = "Section_modify.html">add them to SPARTA</A>.  See the
discussion above for how N can be specified with a wildcard asterisk
to effectively specify multiple values.
</P>
<P>If a value begins with "f_", a fix ID must follow which has been
previously defined in the input script.  Fixes can generate
per-particle or per-grid or per-surf quantities.  See the individual
<A HREF = "fix.html">fix</A> doc page for details.  Note that some fixes only
produce their values on certain timesteps, which must be compatible
with when this compute references the values, else an error results.
If no bracketed integer is appended, the vector calculated by the fix
is used.  If a bracketed integer is appended, the Nth column of the
array calculated by the fix is used.  Users can also write code for
their own fix style and <A HREF = "Section_modify.html">add them to SPARTA</A>.  See
the discussion above for how N can be specified with a wildcard
asterisk to effectively specify multiple values.
</P>
<P>If a value begins with "v_", a variable name must follow which has
been previously defined in the input script.  It must be a
<A HREF = "variable.html">particle-style or grid-style or surf-style variable</A>.
These styles define formulas which can reference stats keywords or
invoke other computes, fixes, or variables when they are evaluated.
Particle-style variables can also reference various per-particle
attributes (position, velocity, etc).  So these variables are a very
general means of creating per-particle or per-grid or per-surf
quantities to reduce.
</P>
<P>If a value begins with "p_" or "g_" or "s_", then a custom
per-particle, per-grid, or per-surf attribute with the specified name
is used.  Particles, grid cells, and surface elements can have custom
attributes which store either single or multiple values per particle,
per grid cell, or per surface element.  They can be defined and
initialized in data files, e.g. via the <A HREF = "read_surf.html">read_surf</A>
command.  Or they can be defined and used by specific commands,
e.g. <A HREF = "fix_ambipolar.html">fix ambipolar</A> or <A HREF = "fix_surf_temp.html">fix
surf/temp</A> or <A HREF = "surf_react_adsorb.html">surf_react
adsorb</A>.  The name of each attribute is set by
the user or defined by the command.  See <A HREF = "Section_howto.html#howto_17">Section
6.17</A> for more discussion of custom
attributes.
</P>
<P>If no bracketed integer is appended, the custom attribute must be a
per-particle, per-grid, or per-surf vector (single value).  If a
bracketed integer is appended, the custom attribute must be a
per-particle, per-grid, or per-surf arayy (multiple values) and the
Nth column of the custom array is used.  See the discussion above for
how N can be specified with a wildcard asterisk to effectively specify
multiple values.
</P>
<HR>

<P>If the <I>replace</I> keyword is used, two indices <I>vec1</I> and <I>vec2</I> are
specified, where each index ranges from 1 to the # of input values.
The replace keyword can only be used if the <I>mode</I> is <I>min</I> or <I>max</I>.
It works as follows.  A min/max is computed as usual on the <I>vec2</I>
input vector.  The index N of that value within <I>vec2</I> is also stored.
Then, instead of performing a min/max on the <I>vec1</I> input vector, the
stored index is used to select the Nth element of the <I>vec1</I> vector.
</P>
<P>Here is an example which prints out both the grid cell ID and number
of particles for the grid cell with the maximum number of particles:
</P>
<PRE>compute 1 property/grid id
compute	2 grid all n
compute	3 reduce max c_1 c_2[1] replace 1 2
stats_style step c_temp c_3[1] c_3[2] 
</PRE>
<P>The first two input values in the compute reduce command are vectors
with the ID and particle count of each grid cell.  Instead of taking
the max of the ID vector, which does not yield useful information in
this context, the <I>replace</I> keyword will extract the ID for the grid
cell which has the maximum number of particles.  This ID and the
cell's particle count will be printed with the statistical output.
</P>
<P>Note that the <I>replace</I> keyword can be used multiple times with
different pairs of indices.
</P>
<HR>

<P>The <I>subset</I> keyword allows selection of a subset of each input
vectors quantities to be used for the reduce operation.  This may
affect all of the reduction operations.  E.g. the ave and avesq
operations will become averages for only a subset of numerical values.
</P>
<P>If inputs are per-particle values, then a mixture ID should be
specified.  Only particle species belonging to the mixture will be
included in the calculations.  See the <A HREF = "mixture.html">mixture</A> command
for how a set of species is included in a mixture.
</P>
<P>If inputs are per-grid values, then a grid group ID should be
specified.  Only grid cells in the grid group will be included in the
calculations.  See the <A HREF = "group.html">group grid</A> command for info on how
grid cells can be assigned to grid groups.
</P>
<P>If inputs are per-surf values, then a surface group ID should be
specified.  Only surface elements in the surface group will be
included in the calculations.  See the <A HREF = "group.html">group surf</A> command
for info on how surface elements can be assigned to surface groups.
</P>
<P>IMPORTANT NOTE: If computes or fixes are used as inputs to compute
reduce, they may define their own subsets of particles, grid cells, or
surface elements which contribute to their output.  Typically output
from those computes or fixes will be zero for grid cells or surface
elements not in the grid or surface group specified for those
commands.  Thus you may want to use an argument for the <I>subset</I>
keyword which is consistent with the inputs, but that is not required.
</P>
<HR>

<P>If a single input is specified this compute produces a global scalar
value.  If multiple inputs are specified, this compute produces a
global vector of values, the length of which is equal to the number of
inputs specified.
</P>
<HR>

<P><B>Output info:</B>
</P>
<P>This compute calculates a global scalar if a single input value is
specified or a global vector of length N where N is the number of
inputs, and which can be accessed by indices 1 to N.  These values can
be used by any command that uses global scalar or vector values from a
compute as input.  See <A HREF = "Section_howto.html#howto_4">Section 6.4</A> for an
overview of SPARTA output options.
</P>
<P>The scalar or vector values will be in whatever <A HREF = "units.html">units</A> the
quantities being reduced are in.
</P>
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, <A HREF = "variable.html">variable</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
