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 file style args keyword value ... :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 written to file :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
file = filename to write results to :l
style = {density} or {compute} or {fix} :l
  {density} arg = {mass} or {number}
    {mass} = compute mass density
    {number} = compute 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

:pre

zero or more keyword/value pairs may be appended :l
keyword = {norm} or {units}
  {norm} value = {all} or {sample}
  {units} value = {box} or {lattice} or {reduced} :pre
  
:ule

[Examples:]

fix 1 all ave/spatial 10000 1 10000 z lower 2.0 centro.profile compute myCentro
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vel.profile compute Vx norm sample
fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 dens.profile density mass :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, and print the results to a file.  This 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).

The {density} styles means to simply count the number of atoms in each
layer, either by mass or 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 the {compute} style, 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 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 per-atom quantities calculated by a per-atom compute.

For the {fix} style, 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.

In all cases, the calculated property is 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 a property is calculated
for the first time (after a previous write), 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 align with 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}.

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-orthongal (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 {Nevery}, {Nrepeat}, and {Nfreq} arguments specify how the
property will be time-averaged.  The final averaged value(s) are
computed every {Nfreq} timesteps.  The average is over {Nrepeat}
values, computed in the preceeding portion of the simulation every
{Nevery} timesteps.  Thus 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 written to the file on timestep 100.  Similary for
timesteps 190,192,194,196,198,200 on timestep 200, etc.

The {norm} keyword also affects how time-averaging is done.  For an
{all} setting, a layer quantity is summed over all atoms in all
Nfreq/Nevery 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 M "average sample values", where M =
Nfreq/Nevery.  In other words it is an average of an average.

Each time info is written to the file, it is 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 {density} keyword is used, or the {compute} or {fix} keyword
with a compute/fix that calculates a single quantity per atom, then a
single value will be printed for each layer.  If the {compute} or
{fix} keyword is used with a compute/fix that calculates N quantities
per atom, then N values per line will be written, each of them
averaged independently.

For the {compute} and {fix} keywords, the calculation performed by the
compute or fix is on the group defined by the that command.  However,
only atoms in the fix group are included in the layer averaging.

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

[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.  No global scalar or vector or per-atom
quantities are stored by this fix for access by various "output
commands"_Section_howto.html#4_15.  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:] none

[Related commands:]

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

[Default:]

The option defaults are norm = all and units = lattice.