From 2eacfc04656f1e9a406ff58f8554544aa389428d Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Wed, 27 Oct 2010 15:48:03 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@5166
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/fix_ave_spatial.html | 224 ++++++++++++++++++++++-----------------
 doc/fix_ave_spatial.txt  | 221 +++++++++++++++++++++-----------------
 2 files changed, 249 insertions(+), 196 deletions(-)

diff --git a/doc/fix_ave_spatial.html b/doc/fix_ave_spatial.html
index 1653aa8535..059d44f7c3 100644
--- a/doc/fix_ave_spatial.html
+++ b/doc/fix_ave_spatial.html
@@ -13,7 +13,7 @@
 </H3>
 <P><B>Syntax:</B>
 </P>
-<PRE>fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta value1 value2 ... keyword args ... 
+<PRE>fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta ... value1 value2 ... keyword args ... 
 </PRE>
 <UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command 
 
@@ -25,12 +25,12 @@
 
 <LI>Nfreq = calculate averages every this many timesteps 
 
-<LI>dim = <I>x</I> or <I>y</I> or <I>z</I> 
-
-<LI>origin = <I>lower</I> or <I>center</I> or <I>upper</I> or coordinate value (distance units) 
-
-<LI>delta = thickness of spatial layers in dim (distance units) 
+<LI>dim, origin, delta can be repeated 1, 2, or 3 times for 1d, 2d, or 3d bins 
 
+<PRE>  dim = <I>x</I> or <I>y</I> or <I>z</I>
+  origin = <I>lower</I> or <I>center</I> or <I>upper</I> or coordinate value (distance units)
+  delta = thickness of spatial bins in dim (distance units) 
+</PRE>
 <LI>one or more input values can be listed 
 
 <LI>value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name 
@@ -71,20 +71,21 @@
 <PRE>fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
                       title1 "My output values"
 fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
-fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running 
+fix 1 flow ave/spatial 100 5 1000 z lower 1.0 y 0.0 2.5 density/mass ave running 
 </PRE>
 <P><B>Description:</B>
 </P>
 <P>Use one or more per-atom vectors as inputs every few timesteps, bin
-them spatially by layer in a dimension, and average the layer values
-over longer timescales.  The resulting layer averages can be used by
-other <A HREF = "Section_howto.html#4_15">output commands</A> such as <A HREF = "thermo_style.html">thermo_style
+their values spatially into 1d, 2d, or 3d bins based on current atom
+coordinates, and average the bin values over longer timescales.  The
+resulting bin averages can be used by other <A HREF = "Section_howto.html#4_15">output
+commands</A> such as <A HREF = "thermo_style.html">thermo_style
 custom</A>, and can also be written to a file.
 </P>
 <P>The group specified with the command means only atoms within the group
-contribute to layer averages.  If the <I>region</I> keyword is used, the
+contribute to bin averages.  If the <I>region</I> keyword is used, the
 atom must be in both the group and the specified geometric
-<A HREF = "region.html">region</A> in order to contribute to layer averages.
+<A HREF = "region.html">region</A> in order to contribute to bin averages.
 </P>
 <P>Each listed value can be an atom attribute (position, velocity, force
 component), a mass or number density, or the result of a
@@ -105,17 +106,31 @@ produce global quantities.
 <P>The per-atom values of each input vector are binned and averaged
 independently of the per-atom values in other input vectors.
 </P>
+<P>The size and dimensionality of the bins (1d = layers or slabs, 2d =
+pencils, 3d = boxes) are determined by the <I>dim</I>, <I>origin</I>, and
+<I>delta</I> settings and how many times they are specified (1, 2, or 3).
+See details below.
+</P>
+<P>IMPORTANT NOTE: This fix works by creating an array of size Nbins by
+Nvalues on each processor.  Nbins is the total number of bins; Nvalues
+is the number of input values specified.  Each processor loops over
+its atoms, tallying its values to the appropriate bin.  Then the
+entire array is summed across all processors.  This means that using a
+large number of bins (easy to do for 2d or 3d bins) will incur an
+overhead in memory and computational cost (summing across processors),
+so be careful to use reasonable numbers of bins.
+</P>
 <HR>
 
 <P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
-timesteps the input values will be used to bin them into layers and
-contribute to the average.  The final averaged quantities are
-generated every <I>Nfreq</I> timesteps.  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.
+timesteps the input values will be used to bin them and contribute to
+the average.  The final averaged quantities are generated every
+<I>Nfreq</I> timesteps.  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
@@ -126,33 +141,38 @@ averaging is done; values are simply generated on timesteps
 </P>
 <HR>
 
-<P>Each per-atom property is also averaged over atoms in each layer,
-where the layers are in a particular <I>dim</I> and have a thickness given
-by <I>delta</I>.  Every Nfreq steps, when an averaging is being performed
-and the per-atom property is calculated for the first time, the number
-of layers and the layer boundaries are computed.  Thus if the
-simulation box changes size during a simulation, the number of layers
-and their boundaries may also change.  Layers are defined relative to
-a specified <I>origin</I>, which may be the lower/upper edge of the box (in
-<I>dim</I>) or its center point, or a specified coordinate value.  Starting
-at the origin, sufficient layers are created in both directions to
-completely cover the box.  On subsequent timesteps every atom is
-mapped to one of the layers.  Atoms beyond the lowermost/uppermost
-layer are counted in the first/last layer.
+<P>Each per-atom property is also averaged over atoms in each bin.  Bins
+can be 1d layers or slabs, 2d pencils, or 3d boxes.  This depends on
+how many times (1, 2, or 3) the <I>dim</I>, <I>origin</I>, and <I>delta</I> settings
+are specified in the fix ave/spatial command.  For 2d or 3d bins,
+there is no restriction on specifying dim = x before dim = y, or dim =
+y before dim = z.  Bins in a particular <I>dim</I> have a bin size in that
+dimension given by <I>delta</I>.  Every Nfreq steps, when averaging is
+being performed and the per-atom property is calculated for the first
+time, the number of bins and the bin sizes and boundaries are
+computed.  Thus if the simulation box changes size during a
+simulation, the number of bins and their boundaries may also change.
+In each dimension, bins are defined relative to a specified <I>origin</I>,
+which may be the lower/upper edge of the simulation box (in <I>dim</I>) or
+its center point, or a specified coordinate value.  Starting at the
+origin, sufficient bins are created in both directions to completely
+cover the box.  On subsequent timesteps every atom is mapped to one of
+the bins.  Atoms beyond the lowermost/uppermost bin in a dimension are
+counted in the first/last bin in that dimension.
 </P>
-<P>For orthogonal simulation boxes, the layers are "slices" aligned with
-the xyz coordinate axes.  For non-orthogonal (triclinic) simulation
-boxes, the layers are "tilted slices" that are parallel to the tilted
-faces of the box.  See the <A HREF = "region.html">region prism</A> command for a
-discussion of the geometry of tilted boxes in LAMMPS.  As described
-there, a tilted simulation box has edge vectors a,b,c.  In that
-nomenclature, layers in the x dimension have faces with normals in the
-"b" cross "c" direction.  Layers in y have faces normal to the "a"
-cross "c" direction.  And layers in z have faces normal to the "a"
-cross "b" direction.  Note that in order to define the thickness and
-position of these tilted layers in an unambiguous fashion, the <I>units</I>
-option must be set to <I>reduced</I> when using a non-orthogonal simulation
-box, as discussed below.
+<P>For orthogonal simulation boxes, the bins are also layers, pencils, or
+boxes aligned with the xyz coordinate axes.  For triclinic
+(non-orthogonal) simulation boxes, the bins are so that they are
+parallel to the tilted faces of the simulation box.  See <A HREF = "Section_howto.html#4_12">this
+section</A> of the manual for a discussion of the
+geometry of triclinic boxes in LAMMPS.  As described there, a tilted
+simulation box has edge vectors a,b,c.  In that nomenclature, bins in
+the x dimension have faces with normals in the "b" cross "c"
+direction.  Bins in y have faces normal to the "a" cross "c"
+direction.  And bins in z have faces normal to the "a" cross "b"
+direction.  Note that in order to define the size and position of
+these bins in an unambiguous fashion, the <I>units</I> option must be set
+to <I>reduced</I> when using a triclinic simulation box, as noted below.
 </P>
 <HR>
 
@@ -163,10 +183,10 @@ property/atom</A> command and then specifying
 an input value from that compute.
 </P>
 <P>The <I>density/number</I> value means the number density is computed in
-each layer, i.e. a weighting of 1 for each atom.  The <I>density/mass</I>
-value means the mass density is computed in each layer, i.e. each atom
+each bin, i.e. a weighting of 1 for each atom.  The <I>density/mass</I>
+value means the mass density is computed in each bind, i.e. each atom
 is weighted by its mass.  The resulting density is normalized by the
-volume of the layer so that units of number/volume or density are
+volume of the bin so that units of number/volume or density are
 output.  See the <A HREF = "units.html">units</A> command doc page for the
 definition of density for each choice of units, e.g. gram/cm^3.
 </P>
@@ -198,7 +218,7 @@ quantities to spatially average.
 <P>Additional optional keywords also affect the operation of this fix.
 </P>
 <P>The <I>units</I> keyword determines the meaning of the distance units used
-for the layer thickness <I>delta</I> and for <I>origin</I> if it is a coordinate
+for the bin size <I>delta</I> and for <I>origin</I> if it is a coordinate
 value.  For orthogonal simulation boxes, any of the 3 options may be
 used.  For non-orthogonal (triclinic) simulation boxes, only the
 <I>reduced</I> option may be used.
@@ -211,63 +231,64 @@ define the lattice spacing.  A <I>reduced</I> value means normalized
 unitless values between 0 and 1, which represent the lower and upper
 faces of the simulation box respectively.  Thus an <I>origin</I> value of
 0.5 means the center of the box in any dimension.  A <I>delta</I> value of
-0.1 means 10 layers span the box in any dimension. 
+0.1 means 10 bins span the box in that dimension.
 </P>
-<P>Consider a non-orthogonal box, with layers in the x dimension.  No
-matter how the box is tilted, an <I>origin</I> of 0.0 means start layers at
-the lower "b" cross "c" plane of the simulation box and an <I>origin</I> of
-1.0 means to start layers at the upper "b" cross "c" face of the box.
-A <I>delta</I> value of 0.1 means there will be 10 layers from 0.0 to 1.0,
-regardless of the current size or shape of the simulation box.
+<P>Consider a non-orthogonal box, with bins that are 1d layers or slabs
+in the x dimension.  No matter how the box is tilted, an <I>origin</I> of
+0.0 means start layers at the lower "b" cross "c" plane of the
+simulation box and an <I>origin</I> of 1.0 means to start layers at the
+upper "b" cross "c" face of the box.  A <I>delta</I> value of 0.1 means
+there will be 10 layers from 0.0 to 1.0, regardless of the current
+size or shape of the simulation box.
 </P>
 <P>The <I>norm</I> keyword affects how averaging is done for the output
-produced every <I>Nfreq</I> timesteps.  For an <I>all</I> setting, a layer
+produced every <I>Nfreq</I> timesteps.  For an <I>all</I> setting, a bin
 quantity is summed over all atoms in all <I>Nrepeat</I> samples, as is the
-count of atoms in the layer.  The printed value for the layer is
+count of atoms in the bin.  The printed value for the bin is
 Total-quantity / Total-count.  In other words it is an average over
 the entire <I>Nfreq</I> timescale.
 </P>
-<P>For a <I>sample</I> setting, the layer quantity is summed over atoms for
-only a single sample, as is the count, and a "average sample value" is
+<P>For a <I>sample</I> setting, the bin quantity is summed over atoms for only
+a single sample, as is the count, and a "average sample value" is
 computed, i.e. Sample-quantity / Sample-count.  The printed value for
-the layer is the average of the <I>Nrepeat</I> "average sample values", In
+the bin is the average of the <I>Nrepeat</I> "average sample values", In
 other words it is an average of an average.
 </P>
-<P>The <I>ave</I> keyword determines how the layer values produced every
-<I>Nfreq</I> steps are averaged with layer values produced on previous
-steps that were multiples of <I>Nfreq</I>, before they are accessed by
-another output command or written to a file.
+<P>The <I>ave</I> keyword determines how the bin values produced every <I>Nfreq</I>
+steps are averaged with bin values produced on previous steps that
+were multiples of <I>Nfreq</I>, before they are accessed by another output
+command or written to a file.
 </P>
-<P>If the <I>ave</I> setting is <I>one</I>, then the layer values produced on
+<P>If the <I>ave</I> setting is <I>one</I>, then the bin values produced on
 timesteps that are multiples of <I>Nfreq</I> are independent of each other;
 they are output as-is without further averaging.
 </P>
-<P>If the <I>ave</I> setting is <I>running</I>, then the layer values produced on
+<P>If the <I>ave</I> setting is <I>running</I>, then the bin values produced on
 timesteps that are multiples of <I>Nfreq</I> are summed and averaged in a
-cumulative sense before being output.  Each output layer value is
-thus the average of the layer value produced on that timestep with all
-preceding values for the same layer.  This running average begins
-when the fix is defined; it can only be restarted by deleting the fix
-via the <A HREF = "unfix.html">unfix</A> command, or re-defining the fix by
+cumulative sense before being output.  Each output bin value is thus
+the average of the bin value produced on that timestep with all
+preceding values for the same bin.  This running average begins when
+the fix is defined; it can only be restarted by deleting the fix via
+the <A HREF = "unfix.html">unfix</A> command, or re-defining the fix by
 re-specifying it.
 </P>
-<P>If the <I>ave</I> setting is <I>window</I>, then the layer values produced on
+<P>If the <I>ave</I> setting is <I>window</I>, then the bin values produced on
 timesteps that are multiples of <I>Nfreq</I> are summed and averaged within
-a moving "window" of time, so that the last M values for the same
-layer 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
-layer values on steps 8000,9000,10000.  Outputs on early steps will
-average over less than M values if they are not available.
+a moving "window" of time, so that the last M values for the same bin
+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 bin
+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 <I>file</I> keyword allows a filename to be specified.  Every <I>Nfreq</I>
-timesteps, a section of layer info will be written to a text file in
-the following format.  A line with the timestep and number of layers
-is written.  Then one line per layer is written, containing the layer
-ID (1-N), the coordinate of the center of the layer, the number of
-atoms in the layer, and one or more calculated values.  The number of
-values in each line corresponds to the number of values specified in
-the fix ave/spatial command.  The number of atoms and the value(s) are
-average quantities.  If the value of the <I>units</I> keyword is <I>box</I> or
+timesteps, a section of bin info will be written to a text file in the
+following format.  A line with the timestep and number of bin is
+written.  Then one line per bin is written, containing the bin ID
+(1-N), the coordinate of the center of the bin, the number of atoms
+in the bin, and one or more calculated values.  The number of values
+in each line corresponds to the number of values specified in the fix
+ave/spatial command.  The number of atoms and the value(s) are average
+quantities.  If the value of the <I>units</I> keyword is <I>box</I> or
 <I>lattice</I>, the "coord" is printed in box units.  If the value of the
 <I>units</I> keyword is <I>reduced</I>, the "coord" is printed in reduced units
 (0-1).
@@ -280,13 +301,16 @@ values for each of these, so they do not need to be specified.
 <P>By default, these header lines are as follows:
 </P>
 <PRE># Spatial-averaged data for fix ID and group name
-# Timestep Number-of-layers
-# Layer Coord Count value1 value2 ... 
+# Timestep Number-of-bins
+# Bin Coord1 Coord2 Coord3 Count value1 value2 ... 
 </PRE>
 <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 fields from the fix ave/spatial command.
+The Coord2 and Coord3 entries in the third line only appear for 2d and
+3d bins respectively.  For 1d bins, the word Coord1 is replaced by
+just Coord.
 </P>
 <HR>
 
@@ -300,15 +324,17 @@ are relevant to this fix.
 various <A HREF = "Section_howto.html#4_15">output commands</A>.  The values can
 only be accessed on timesteps that are multiples of <I>Nfreq</I> since that
 is when averaging is performed.  The global array has # of rows =
-Nlayers and # of columns = Nvalues+2.  The first column has the layer
-coordinate (center of the layer), the 2nd column has the count of
-atoms in that layer, and the remaining columns are the Nvalue
-quantities.  When the array is accessed with an I that exceeds the
-current number of layers, than a 0.0 is returned by the fix instead of
-an error, since the number of layers can vary as a simulation runs,
-depending on the simulation box size.  The array values calculated by
-this fix are "intensive", since they are already normalized by the
-count of atoms in each layer.
+Nbins and # of columns = Ndim+1+Nvalues, where Ndim = 1,2,3 for
+1d,2d,3d bins.  The first 1 or 2 or 3 columns have the bin coordinates
+(center of the bin) in the appropriate dimensions, the next column has
+the count of atoms in that bin, and the remaining columns are the
+Nvalue quantities.  When the array is accessed with an I that exceeds
+the current number of bins, than a 0.0 is returned by the fix instead
+of an error, since the number of bins can vary as a simulation runs,
+depending on the simulation box size.  2d or 3d bins are ordered so
+that the last dimension(s) vary fastest.  The array values calculated
+by this fix are "intensive", since they are already normalized by the
+count of atoms in each bin.
 </P>
 <P>No parameter of this fix can be used with the <I>start/stop</I> keywords of
 the <A HREF = "run.html">run</A> command.  This fix is not invoked during <A HREF = "minimize.html">energy
@@ -317,7 +343,7 @@ minimization</A>.
 <P><B>Restrictions:</B>
 </P>
 <P>When the <I>ave</I> keyword is set to <I>running</I> or <I>window</I> then the number
-of layers must remain the same during the simulation, so that the
+of bins must remain the same during the simulation, so that the
 appropriate averaging can be done.  This will be the case if the
 simulation box size doesn't change or if the <I>units</I> keyword is set to
 <I>reduced</I>.
diff --git a/doc/fix_ave_spatial.txt b/doc/fix_ave_spatial.txt
index 11880661b0..0764cb4f24 100644
--- a/doc/fix_ave_spatial.txt
+++ b/doc/fix_ave_spatial.txt
@@ -10,16 +10,17 @@ fix ave/spatial command :h3
 
 [Syntax:]
 
-fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta value1 value2 ... keyword args ... :pre
+fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta ... value1 value2 ... keyword args ... :pre
 
 ID, group-ID are documented in "fix"_fix.html command :ulb,l
 ave/spatial = style name of this fix command :l
 Nevery = use input values every this many timesteps :l
 Nrepeat = # of times to use input values for calculating averages :l
 Nfreq = calculate averages every this many timesteps :l
-dim = {x} or {y} or {z} :l
-origin = {lower} or {center} or {upper} or coordinate value (distance units) :l
-delta = thickness of spatial layers in dim (distance units) :l
+dim, origin, delta can be repeated 1, 2, or 3 times for 1d, 2d, or 3d bins :l
+  dim = {x} or {y} or {z}
+  origin = {lower} or {center} or {upper} or coordinate value (distance units)
+  delta = thickness of spatial bins in dim (distance units) :pre
 one or more input values can be listed :l
 value = x, y, z, vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name :l
   x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
@@ -55,20 +56,21 @@ keyword = {norm} or {units} or {file} or {ave} or {title1} or {title2} or {title
 fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
                       title1 "My output values"
 fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
-fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running :pre
+fix 1 flow ave/spatial 100 5 1000 z lower 1.0 y 0.0 2.5 density/mass ave running :pre
 
 [Description:]
 
 Use one or more per-atom vectors as inputs every few timesteps, bin
-them spatially by layer in a dimension, and average the layer values
-over longer timescales.  The resulting layer averages can be used by
-other "output commands"_Section_howto.html#4_15 such as "thermo_style
+their values spatially into 1d, 2d, or 3d bins based on current atom
+coordinates, and average the bin values over longer timescales.  The
+resulting bin averages can be used by other "output
+commands"_Section_howto.html#4_15 such as "thermo_style
 custom"_thermo_style.html, and can also be written to a file.
 
 The group specified with the command means only atoms within the group
-contribute to layer averages.  If the {region} keyword is used, the
+contribute to bin averages.  If the {region} keyword is used, the
 atom must be in both the group and the specified geometric
-"region"_region.html in order to contribute to layer averages.
+"region"_region.html in order to contribute to bin averages.
 
 Each listed value can be an atom attribute (position, velocity, force
 component), a mass or number density, or the result of a
@@ -89,17 +91,31 @@ produce global quantities.
 The per-atom values of each input vector are binned and averaged
 independently of the per-atom values in other input vectors.
 
+The size and dimensionality of the bins (1d = layers or slabs, 2d =
+pencils, 3d = boxes) are determined by the {dim}, {origin}, and
+{delta} settings and how many times they are specified (1, 2, or 3).
+See details below.
+
+IMPORTANT NOTE: This fix works by creating an array of size Nbins by
+Nvalues on each processor.  Nbins is the total number of bins; Nvalues
+is the number of input values specified.  Each processor loops over
+its atoms, tallying its values to the appropriate bin.  Then the
+entire array is summed across all processors.  This means that using a
+large number of bins (easy to do for 2d or 3d bins) will incur an
+overhead in memory and computational cost (summing across processors),
+so be careful to use reasonable numbers of bins.
+
 :line
 
 The {Nevery}, {Nrepeat}, and {Nfreq} arguments specify on what
-timesteps the input values will be used to bin them into layers and
-contribute to the average.  The final averaged quantities are
-generated every {Nfreq} timesteps.  The average is over {Nrepeat}
-quantities, computed in the preceding portion of the simulation every
-{Nevery} timesteps.  {Nfreq} must be a multiple of {Nevery} and
-{Nevery} must be non-zero even if {Nrepeat} is 1.  Also, the timesteps
-contributing to the average value cannot overlap, i.e. Nfreq >
-(Nrepeat-1)*Nevery is required.
+timesteps the input values will be used to bin them and contribute to
+the average.  The final averaged quantities are generated every
+{Nfreq} timesteps.  The average is over {Nrepeat} quantities, computed
+in the preceding portion of the simulation every {Nevery} timesteps.
+{Nfreq} must be a multiple of {Nevery} and {Nevery} must be non-zero
+even if {Nrepeat} is 1.  Also, the timesteps contributing to the
+average value cannot overlap, i.e. Nfreq > (Nrepeat-1)*Nevery is
+required.
 
 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
@@ -110,33 +126,38 @@ averaging is done; values are simply generated on timesteps
 
 :line
 
-Each per-atom property is also averaged over atoms in each layer,
-where the layers are in a particular {dim} and have a thickness given
-by {delta}.  Every Nfreq steps, when an averaging is being performed
-and the per-atom property is calculated for the first time, the number
-of layers and the layer boundaries are computed.  Thus if the
-simulation box changes size during a simulation, the number of layers
-and their boundaries may also change.  Layers are defined relative to
-a specified {origin}, which may be the lower/upper edge of the box (in
-{dim}) or its center point, or a specified coordinate value.  Starting
-at the origin, sufficient layers are created in both directions to
-completely cover the box.  On subsequent timesteps every atom is
-mapped to one of the layers.  Atoms beyond the lowermost/uppermost
-layer are counted in the first/last layer.
+Each per-atom property is also averaged over atoms in each bin.  Bins
+can be 1d layers or slabs, 2d pencils, or 3d boxes.  This depends on
+how many times (1, 2, or 3) the {dim}, {origin}, and {delta} settings
+are specified in the fix ave/spatial command.  For 2d or 3d bins,
+there is no restriction on specifying dim = x before dim = y, or dim =
+y before dim = z.  Bins in a particular {dim} have a bin size in that
+dimension given by {delta}.  Every Nfreq steps, when averaging is
+being performed and the per-atom property is calculated for the first
+time, the number of bins and the bin sizes and boundaries are
+computed.  Thus if the simulation box changes size during a
+simulation, the number of bins and their boundaries may also change.
+In each dimension, bins are defined relative to a specified {origin},
+which may be the lower/upper edge of the simulation box (in {dim}) or
+its center point, or a specified coordinate value.  Starting at the
+origin, sufficient bins are created in both directions to completely
+cover the box.  On subsequent timesteps every atom is mapped to one of
+the bins.  Atoms beyond the lowermost/uppermost bin in a dimension are
+counted in the first/last bin in that dimension.
 
-For orthogonal simulation boxes, the layers are "slices" aligned with
-the xyz coordinate axes.  For non-orthogonal (triclinic) simulation
-boxes, the layers are "tilted slices" that are parallel to the tilted
-faces of the box.  See the "region prism"_region.html command for a
-discussion of the geometry of tilted boxes in LAMMPS.  As described
-there, a tilted simulation box has edge vectors a,b,c.  In that
-nomenclature, layers in the x dimension have faces with normals in the
-"b" cross "c" direction.  Layers in y have faces normal to the "a"
-cross "c" direction.  And layers in z have faces normal to the "a"
-cross "b" direction.  Note that in order to define the thickness and
-position of these tilted layers in an unambiguous fashion, the {units}
-option must be set to {reduced} when using a non-orthogonal simulation
-box, as discussed below.
+For orthogonal simulation boxes, the bins are also layers, pencils, or
+boxes aligned with the xyz coordinate axes.  For triclinic
+(non-orthogonal) simulation boxes, the bins are so that they are
+parallel to the tilted faces of the simulation box.  See "this
+section"_Section_howto.html#4_12 of the manual for a discussion of the
+geometry of triclinic boxes in LAMMPS.  As described there, a tilted
+simulation box has edge vectors a,b,c.  In that nomenclature, bins in
+the x dimension have faces with normals in the "b" cross "c"
+direction.  Bins in y have faces normal to the "a" cross "c"
+direction.  And bins in z have faces normal to the "a" cross "b"
+direction.  Note that in order to define the size and position of
+these bins in an unambiguous fashion, the {units} option must be set
+to {reduced} when using a triclinic simulation box, as noted below.
 
 :line
 
@@ -147,10 +168,10 @@ property/atom"_compute_property_atom.html command and then specifying
 an input value from that compute.
 
 The {density/number} value means the number density is computed in
-each layer, i.e. a weighting of 1 for each atom.  The {density/mass}
-value means the mass density is computed in each layer, i.e. each atom
+each bin, i.e. a weighting of 1 for each atom.  The {density/mass}
+value means the mass density is computed in each bind, i.e. each atom
 is weighted by its mass.  The resulting density is normalized by the
-volume of the layer so that units of number/volume or density are
+volume of the bin so that units of number/volume or density are
 output.  See the "units"_units.html command doc page for the
 definition of density for each choice of units, e.g. gram/cm^3.
 
@@ -182,7 +203,7 @@ quantities to spatially average.
 Additional optional keywords also affect the operation of this fix.
 
 The {units} keyword determines the meaning of the distance units used
-for the layer thickness {delta} and for {origin} if it is a coordinate
+for the bin size {delta} and for {origin} if it is a coordinate
 value.  For orthogonal simulation boxes, any of the 3 options may be
 used.  For non-orthogonal (triclinic) simulation boxes, only the
 {reduced} option may be used.
@@ -195,63 +216,64 @@ define the lattice spacing.  A {reduced} value means normalized
 unitless values between 0 and 1, which represent the lower and upper
 faces of the simulation box respectively.  Thus an {origin} value of
 0.5 means the center of the box in any dimension.  A {delta} value of
-0.1 means 10 layers span the box in any dimension. 
+0.1 means 10 bins span the box in that dimension.
 
-Consider a non-orthogonal box, with layers in the x dimension.  No
-matter how the box is tilted, an {origin} of 0.0 means start layers at
-the lower "b" cross "c" plane of the simulation box and an {origin} of
-1.0 means to start layers at the upper "b" cross "c" face of the box.
-A {delta} value of 0.1 means there will be 10 layers from 0.0 to 1.0,
-regardless of the current size or shape of the simulation box.
+Consider a non-orthogonal box, with bins that are 1d layers or slabs
+in the x dimension.  No matter how the box is tilted, an {origin} of
+0.0 means start layers at the lower "b" cross "c" plane of the
+simulation box and an {origin} of 1.0 means to start layers at the
+upper "b" cross "c" face of the box.  A {delta} value of 0.1 means
+there will be 10 layers from 0.0 to 1.0, regardless of the current
+size or shape of the simulation box.
 
 The {norm} keyword affects how averaging is done for the output
-produced every {Nfreq} timesteps.  For an {all} setting, a layer
+produced every {Nfreq} timesteps.  For an {all} setting, a bin
 quantity is summed over all atoms in all {Nrepeat} samples, as is the
-count of atoms in the layer.  The printed value for the layer is
+count of atoms in the bin.  The printed value for the bin is
 Total-quantity / Total-count.  In other words it is an average over
 the entire {Nfreq} timescale.
 
-For a {sample} setting, the layer quantity is summed over atoms for
-only a single sample, as is the count, and a "average sample value" is
+For a {sample} setting, the bin quantity is summed over atoms for only
+a single sample, as is the count, and a "average sample value" is
 computed, i.e. Sample-quantity / Sample-count.  The printed value for
-the layer is the average of the {Nrepeat} "average sample values", In
+the bin is the average of the {Nrepeat} "average sample values", In
 other words it is an average of an average.
 
-The {ave} keyword determines how the layer values produced every
-{Nfreq} steps are averaged with layer values produced on previous
-steps that were multiples of {Nfreq}, before they are accessed by
-another output command or written to a file.
+The {ave} keyword determines how the bin values produced every {Nfreq}
+steps are averaged with bin values produced on previous steps that
+were multiples of {Nfreq}, before they are accessed by another output
+command or written to a file.
 
-If the {ave} setting is {one}, then the layer values produced on
+If the {ave} setting is {one}, then the bin values produced on
 timesteps that are multiples of {Nfreq} are independent of each other;
 they are output as-is without further averaging.
 
-If the {ave} setting is {running}, then the layer values produced on
+If the {ave} setting is {running}, then the bin values produced on
 timesteps that are multiples of {Nfreq} are summed and averaged in a
-cumulative sense before being output.  Each output layer value is
-thus the average of the layer value produced on that timestep with all
-preceding values for the same layer.  This running average begins
-when the fix is defined; it can only be restarted by deleting the fix
-via the "unfix"_unfix.html command, or re-defining the fix by
+cumulative sense before being output.  Each output bin value is thus
+the average of the bin value produced on that timestep with all
+preceding values for the same bin.  This running average begins when
+the fix is defined; it can only be restarted by deleting the fix via
+the "unfix"_unfix.html command, or re-defining the fix by
 re-specifying it.
 
-If the {ave} setting is {window}, then the layer values produced on
+If the {ave} setting is {window}, then the bin values produced on
 timesteps that are multiples of {Nfreq} are summed and averaged within
-a moving "window" of time, so that the last M values for the same
-layer 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
-layer values on steps 8000,9000,10000.  Outputs on early steps will
-average over less than M values if they are not available.
+a moving "window" of time, so that the last M values for the same bin
+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 bin
+values on steps 8000,9000,10000.  Outputs on early steps will average
+over less than M values if they are not available.
 
 The {file} keyword allows a filename to be specified.  Every {Nfreq}
-timesteps, a section of layer info will be written to a text file in
-the following format.  A line with the timestep and number of layers
-is written.  Then one line per layer is written, containing the layer
-ID (1-N), the coordinate of the center of the layer, the number of
-atoms in the layer, and one or more calculated values.  The number of
-values in each line corresponds to the number of values specified in
-the fix ave/spatial command.  The number of atoms and the value(s) are
-average quantities.  If the value of the {units} keyword is {box} or
+timesteps, a section of bin info will be written to a text file in the
+following format.  A line with the timestep and number of bin is
+written.  Then one line per bin is written, containing the bin ID
+(1-N), the coordinate of the center of the bin, the number of atoms
+in the bin, and one or more calculated values.  The number of values
+in each line corresponds to the number of values specified in the fix
+ave/spatial command.  The number of atoms and the value(s) are average
+quantities.  If the value of the {units} keyword is {box} or
 {lattice}, the "coord" is printed in box units.  If the value of the
 {units} keyword is {reduced}, the "coord" is printed in reduced units
 (0-1).
@@ -264,13 +286,16 @@ values for each of these, so they do not need to be specified.
 By default, these header lines are as follows:
 
 # Spatial-averaged data for fix ID and group name
-# Timestep Number-of-layers
-# Layer Coord Count value1 value2 ... :pre
+# Timestep Number-of-bins
+# Bin Coord1 Coord2 Coord3 Count value1 value2 ... :pre
 
 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 fields from the fix ave/spatial command.
+The Coord2 and Coord3 entries in the third line only appear for 2d and
+3d bins respectively.  For 1d bins, the word Coord1 is replaced by
+just Coord.
 
 :line
 
@@ -284,15 +309,17 @@ This fix computes a global array of values which can be accessed by
 various "output commands"_Section_howto.html#4_15.  The values can
 only be accessed on timesteps that are multiples of {Nfreq} since that
 is when averaging is performed.  The global array has # of rows =
-Nlayers and # of columns = Nvalues+2.  The first column has the layer
-coordinate (center of the layer), the 2nd column has the count of
-atoms in that layer, and the remaining columns are the Nvalue
-quantities.  When the array is accessed with an I that exceeds the
-current number of layers, than a 0.0 is returned by the fix instead of
-an error, since the number of layers can vary as a simulation runs,
-depending on the simulation box size.  The array values calculated by
-this fix are "intensive", since they are already normalized by the
-count of atoms in each layer.
+Nbins and # of columns = Ndim+1+Nvalues, where Ndim = 1,2,3 for
+1d,2d,3d bins.  The first 1 or 2 or 3 columns have the bin coordinates
+(center of the bin) in the appropriate dimensions, the next column has
+the count of atoms in that bin, and the remaining columns are the
+Nvalue quantities.  When the array is accessed with an I that exceeds
+the current number of bins, than a 0.0 is returned by the fix instead
+of an error, since the number of bins can vary as a simulation runs,
+depending on the simulation box size.  2d or 3d bins are ordered so
+that the last dimension(s) vary fastest.  The array values calculated
+by this fix are "intensive", since they are already normalized by the
+count of atoms in each bin.
 
 No parameter of this fix can be used with the {start/stop} keywords of
 the "run"_run.html command.  This fix is not invoked during "energy
@@ -301,7 +328,7 @@ minimization"_minimize.html.
 [Restrictions:]
 
 When the {ave} keyword is set to {running} or {window} then the number
-of layers must remain the same during the simulation, so that the
+of bins must remain the same during the simulation, so that the
 appropriate averaging can be done.  This will be the case if the
 simulation box size doesn't change or if the {units} keyword is set to
 {reduced}.