lammps/doc/fix_ave_spatial.txt

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

fix ave/spatial command :h3

[Syntax:]

fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta style arg 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 = calculate property every this many timesteps :l
Nrepeat = # of times to repeat the Nevery calculation before averaging :l
Nfreq = timestep frequency at which the average value is computed :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
style = {density} or {compute} or {fix} :l
  {density} arg = {mass} or {number}
    {mass} = calculate mass density
    {number} = calculate number density
  {compute} arg = compute-ID that stores or calculates per-atom quantities
  {fix} arg = fix-ID that stores or calculates per-atom quantities :pre
zero or more keyword/arg pairs may be appended :l
keyword = {norm} or {units} or {file} or {ave} :l
  {units} arg = {box} or {lattice} or {reduced}
  {norm} arg = {all} or {sample}
  {file} arg = filename
    filename = file to write results to
  {ave} args = {one} or {running} or {window M}
    one = output new average value every Nfreq steps
    running = output cummulative average of all previous Nfreq steps
    window M = output average of M most recent Nfreq steps :pre
:ule

[Examples:]

fix 1 all ave/spatial 10000 1 10000 z lower 0.02 compute myCentro units reduced
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 compute Vx norm sample file vel.profile
fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density mass ave running :pre

[Description:]

Calculate one or more instantaneous per-atom quantities every few
timesteps, average them by layer in a chosen dimension and over a
longer timescale.  The resulting averages can be used by other "output
commands"_Section_howto.html#4_15 such as "thermo_style
custom"_thermo_style.html, and also written to a file.

This fix can be used to spatially average per-atom properties
(velocity, force) or per-atom quantities calculated by a
"compute"_compute.html (energy, stress) or by another fix (see the
"fix ave/atom"_fix_ave_atom.html command) or by a variable via an
equation you define (see the "compute
variable/atom"_compute_variable_atom.html command).

For style {density}, the number of atoms in each layer is counted,
either by mass or by number.  The {compute} style allows specification
of a "compute"_compute.html which will be invoked to calculate the
desired property.  The compute can be previously defined in the input
script or it can be a compute defined by a "dump custom"_dump.html
command.

For style {compute}, the fix ave/spatial command accesses the
per-atom scalar or vector values stored by the compute.  Thus it must
be a "per-atom" compute with the word "atom" in its style name, rather
than a "global" compute.  See the "fix ave/time"_fix_ave_time.html
command if you wish to time-average a global quantity calculated by a
compute without the word atom in its style name, e.g. a compute that
calculates a temperature or pressure.

See the "compute"_compute.html command for a list of pre-defined
per-atom computes.  Two special computes of note are as follows.  The
"compute attribute/atom"_compute_attribute_atom.html command selects
one or more atom attributes like vx or fz.  The "compute
variable/atom" style can calculate a value for an atom that can be
specified by a "variable atom"_variable.html equation.  Users can also
write code for their own per-atom compute styles and "add them to
LAMMPS"_Section_modify.html.  Note that the "dump custom"_dump.html
command can also be used to directly output quantities calculated by a
per-atom compute in a per-atom fashion.

For style {fix}, the fix ave/spatial command accesses the per-atom
scalar or vector values stored by another fix.  The "fix
ave/atom"_fix_ave_atom.html command is an example of such a fix.

The {Nevery}, {Nrepeat}, and {Nfreq} arguments specify on what
timesteps the per-atom property will be evaluated in order to
contribute to the average.  The final averaged values are computed
every {Nfreq} timesteps.  The average is over {Nrepeat} values,
computed in the preceeding 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.

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.  Similary for timesteps 190,192,194,196,198,200 on
timestep 200, etc.

The 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 simlation
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.

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 the {compute} and {fix} keywords, the per-atom calculation
performed by the compute or fix is on the group defined by that
command.  However, only atoms in the fix group are included in the
layer averaging.

Note that some computes perform costly calculations, involving the
creation or use of neighbor lists.  If the compute is invoked too
often by fix ave/spatial, it can slow down a simulation.

:line

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
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.

A {box} value selects standard distance units as defined by the
"units"_units.html command, e.g. Angstroms for units = real or metal.
A {lattice} value means the distance units are in lattice spacings.
The "lattice"_lattice.html command must have been previously used to
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. 

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.

The {norm} keyword affects how time-averaging is done within for the
output produced every {Nfreq} timesteps.  For an {all} setting, a
layer 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 Total-quantity / Total-count.  In other words it is an average over
the entire {Nfreq} timescale.

For a {sample} setting, the 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
other words it is an average of an average.

The {file} keyword allows a filename to be specified.  Every {Nfreq}
timesteps, 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 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).

If the style is {density}, or the style is {compute} or {fix} with a
compute/fix that calculates a single quantity per atom, then a single
value will be printed for each layer.  If the style is {compute} or
{fix} with a compute/fix that calculates N quantities per atom, then N
values per line will be written, each of them averaged independently.

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.

If the {ave} setting is {one}, then the layuer 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
timesteps that are multiples of {Nfreq} are summed and averaged in a
cummulative sense before being output.  Each output layer value is
thus the average of the layer value produced on that timestep with all
preceeding 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
re-specifying it.

If the {ave} setting is {window}, then the layer 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.

:line

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about this fix is written to "binary restart
files"_restart.html.  None of the "fix_modify"_fix_modify.html options
are relevant to this fix.

This fix computes a vector of quantities which can be accessed by
various "output commands"_Section_howto.html#4_15.  The values should
only be accessed on timesteps that are multiples of {Nfreq} since that
is when averaging is complete.  The vector is of length N =
nlayers*nvalues where nvalues is the number of per-atom quantities
produced by the compute or fix that fix ave/spatial accesses.  Nvalues
= 1 if the style is {density}.  If nvalues > 1 and vector value N is
accessed by another output command, then the average quantity for the
Ith layer and Jth value in that layer is accessed, where I = N /
nvalues + 1 and J = N % nvalues + 1.

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
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
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}.

[Related commands:]

"compute"_compute.html, "fix ave/time"_fix_ave_time.html

[Default:]

The option defaults are units = lattice, norm = all, no file output,
and ave = one.