jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@15072 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2016-05-31 14:53:34 +00:00
parent 9d3d6193f3
commit 402b7a7231
5 changed files with 0 additions and 1843 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

447
doc/html/_sources/fix_ave_spatial.txt
View File

@ -1,447 +0,0 @@
.. index:: fix ave/spatial
fix ave/spatial command
=======================
Syntax
""""""
.. parsed-literal::
fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta ... value1 value2 ... keyword args ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* ave/spatial = style name of this fix command
* Nevery = use input values every this many timesteps
* Nrepeat = # of times to use input values for calculating averages
* Nfreq = calculate averages every this many timesteps
* dim, origin, delta can be repeated 1, 2, or 3 times for 1d, 2d, or 3d bins
.. parsed-literal::
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)
* one or more input values can be listed
* value = vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name
.. parsed-literal::
vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
density/number, density/mass = number or mass density
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
* zero or more keyword/arg pairs may be appended
* keyword = *region* or *bound* or *discard* or *norm* or *ave* or *units* or *file* or *overwrite* or *title1* or *title2* or *title3*
.. parsed-literal::
*region* arg = region-ID
*bound* args = x/y/z lo hi
x/y/z = *x* or *y* or *z* to bound bins in this dimension
lo = *lower* or coordinate value (distance units)
hi = *upper* or coordinate value (distance units)
*discard* arg = *mixed* or *no* or *yes*
mixed = discard atoms outside bins only if bin bounds are explicitly set
no = always keep out-of-bounds atoms
yes = always discard out-of-bounds atoms
*norm* arg = *all* or *sample*
region-ID = ID of region atoms must be in to contribute to spatial averaging
*ave* args = *one* or *running* or *window M*
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
*units* arg = *box* or *lattice* or *reduced*
*file* arg = filename
filename = file to write results to
*overwrite* arg = none = overwrite output file with only latest output
*title1* arg = string
string = text to print as 1st line of output file
*title2* arg = string
string = text to print as 2nd line of output file
*title3* arg = string
string = text to print as 3rd line of output file
Examples
""""""""
.. parsed-literal::
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 z lower 1.0 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 bound y 5.0 20.0 discard yes ave running
**NOTE:**
The fix ave/spatial command has been replaced by the more flexible
:doc:`fix ave/chunk <fix_ave_chunk>` and :doc:`compute chunk/atom <compute_chunk_atom>` commands. The fix ave/spatial
command will be removed from LAMMPS sometime in the summer of 2015.
Any fix ave/spatial command can be replaced by the two new commands.
You simply need to split the fix ave/spatial arguments across the two
new commands. For example, this command:
.. parsed-literal::
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
could be replaced by:
.. parsed-literal::
compute cc1 flow chunk/atom bin/1d y 0.0 1.0
fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile
Description
"""""""""""
Use one or more per-atom vectors as inputs every few timesteps, bin
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 :ref:`output commands <howto_15>` such as :doc:`thermo_style custom <thermo_style>`, and can also be written to a file.
The group specified with the command means only atoms within the group
contribute to bin averages. If the *region* keyword is used, the atom
must be in both the specified group and the specified geometric
:doc:`region <region>` 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
:doc:`compute <compute>` or :doc:`fix <fix>` or the evaluation of an
atom-style :doc:`variable <variable>`. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. If you wish to time-average global quantities from a
compute, fix, or variable, then see the :doc:`fix ave/time <fix_ave_time>` command.
:doc:`Computes <compute>` that produce per-atom quantities are those
which have the word *atom* in their style name. See the doc pages for
individual :doc:`fixes <fix>` to determine which ones produce per-atom
quantities. :doc:`Variables <variable>` of style *atom* are the only
ones that can be used with this fix since all other styles of variable
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.
.. 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.
----------
The *Nevery*\ , *Nrepeat*\ , and *Nfreq* arguments specify on what
timesteps the input values will be used to bin them and contribute to
the average. The final averaged quantities are generated on timesteps
that are a multiples of *Nfreq*\ . 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. Nrepeat*Nevery can not exceed Nfreq.
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. If Nrepeat=1 and Nfreq = 100, then no time
averaging is done; values are simply generated on timesteps
100,200,etc.
----------
Each per-atom property is also averaged over atoms in each bin. The
way the averaging is one across the *Nrepeat* timesteps to produce
output on the *Nfreq* timesteps, and across multiple *Nfreq* outputs,
is determined by the *norm* and *av* keyword settings, as discussed
below.
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 that
dimension, or its center point, or a specified coordinate value.
Starting at the origin, sufficient bins are created in both directions
to completely span the bin extent in that dimension. By default the
bin extent is the entire simulation box.
The *bound* keyword can be used one or more times to limit the extent
of bin coverage in specified dimensions, i.e. to only bin a portion of
the box. If the *lo* setting is *lower* or the *hi* setting is
*upper*\ , the bin extent in that direction extends to the box boundary.
If a numeric value is used for *lo* and/or *hi*\ , then the bin extent
in the *lo* or *hi* direction extends only to that value, which is
assumed to be inside (or at least near) the simulation box boundaries,
though LAMMPS does not check for this.
On each sampling timestep, each atom is mapped to the bin it currently
belongs to, based on its current position. Note that the group-ID and
region keyword can exclude specific atoms from this operation, as
discussed above. Note that between reneighboring timesteps, atoms can
move outside the current simulation box. If the box is periodic (in
that dimension) the atom is remapping into the periodic box for
purposes of binning. If the box in not periodic, the atom may have
moved outside the bounds of any bin.
The *discard* keyword determines what is done with any atom which is
outside the bounds of any bin. If *discard* is set to *yes*\ , the atom
will be ignored and not contribute to any bin averages. If *discard*
is set to *no*\ , the atom will be counted as if it were in the first or
last bin in that dimension. If (discard* is set to *mixed*\ , which is
the default, it will only be counted in the first or last bin if bins
extend to the box boundary in that dimension. This is the case if the
*bound* keyword settings are *lower* and *upper*\ , which is the
default. If the *bound* keyword settings are numeric values, then the
atom will be ignored if it is outside the bounds of any bin. Note
that in this case, it is possible that the first or last bin extends
beyond the numeric *bounds* settings, depending on the specified
*origin*\ . If this is the case, the atom is only ignored if it is
outside the first or last bin, not if it is simply outside the numeric
*bounds* setting.
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 :ref:`this section <howto_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.
----------
The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
Note that other atom attributes (including atom postitions x,y,z) can
be used as inputs to this fix by using the :doc:`compute property/atom <compute_property_atom>` command and then specifying
an input value from that compute.
The *density/number* value means the number density is computed in
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 bin so that units of number/volume or density are
output. See the :doc:`units <units>` command doc page for the
definition of density for each choice of units, e.g. gram/cm^3.
If a value begins with "c_", a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and :doc:`add them to LAMMPS <Section_modify>`.
If a value begins with "f_", a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
*Nevery*\ , else an error results. Users can also write code for their
own fix styles and :doc:`add them to LAMMPS <Section_modify>`.
If a value begins with "v_", a variable name must follow which has
been previously defined in the input script. Variables of style
*atom* can reference thermodynamic keywords and various per-atom
attributes, or invoke other computes, fixes, or variables when they
are evaluated, so this is a very general means of generating per-atom
quantities to spatially average.
----------
Additional optional keywords also affect the operation of this fix.
The *region*\ , *bound*\ , and *discard* keywords were discussed above.
The *norm* keyword affects how averaging is done for the output
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 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 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 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 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 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 bin values produced on
timesteps that are multiples of *Nfreq* are summed and averaged in a
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 :doc:`unfix <unfix>` command, or re-defining the fix by
re-specifying it.
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 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 *units* keyword determines the meaning of the distance units used
for the bin size *delta* and for *origin* and *bounds* values if they
are 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
:doc:`units <units>` command, e.g. Angstroms for units = real or metal.
A *lattice* value means the distance units are in lattice spacings.
The :doc:`lattice <lattice>` 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 bins span the box in that dimension.
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 *file* keyword allows a filename to be specified. Every *Nfreq*
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).
The *overwrite* keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the *ave running* setting.
The *title1* and *title2* and *title3* keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the *file* keyword was used. LAMMPS uses default
values for each of these, so they do not need to be specified.
By default, these header lines are as follows:
.. parsed-literal::
# Spatial-averaged data for fix ID and group name
# Timestep Number-of-bins
# Bin Coord1 Coord2 Coord3 Count value1 value2 ...
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.
----------
Restart, fix_modify, output, run start/stop, minimize info
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix.
This fix computes a global array of values which can be accessed by
various :ref:`output commands <howto_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 =
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 :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
When the *ave* keyword is set to *running* or *window* then the number
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*\ .
Related commands
""""""""""""""""
:doc:`compute <compute>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix ave/time <fix_ave_time>`,
:doc:`variable <variable>`, :doc:`fix ave/correlate <fix_ave_correlate>`,
:doc:`fix ave/spatial/sphere <fix_ave_spatial_sphere>`
Default
"""""""
The option defaults are bound = lower and upper in all dimensions,
discard = mixed, norm = all, ave = one, units = lattice, no file
output, and title 1,2,3 = strings as described above.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

349
doc/html/_sources/fix_ave_spatial_sphere.txt
View File

@ -1,349 +0,0 @@
.. index:: fix ave/spatial/sphere
fix ave/spatial/sphere command
==============================
Syntax
""""""
.. parsed-literal::
fix ID group-ID ave/spatial/sphere Nevery Nrepeat Nfreq origin_x origin_y origin_z r_min r_max nbins value1 value2 ... keyword args ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* ave/spatial = style name of this fix command
* Nevery = use input values every this many timesteps
* Nrepeat = # of times to use input values for calculating averages
* Nfreq = calculate averages every this many timesteps
* origin_x, origin_y, origin_z = center of the sphere. can be the result of variables or computes (see below)
* r_min = radial distance at which binning begins
* r_max = radial distance at which binning ends
* nbins = number of spherical shells to create between r_min and r_max
* one or more input values can be listed
* value = vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name
.. parsed-literal::
vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
density/number, density/mass = number or mass density
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
f_ID = per-atom vector calculated by a fix with ID
f_ID[I] = Ith column of per-atom array calculated by a fix with ID
v_name = per-atom vector calculated by an atom-style variable with name
* zero or more keyword/arg pairs may be appended
* keyword = *region* or *norm* or *units* or *ave* or *file* or *overwrite* or *title1* or *title2* or *title3*
.. parsed-literal::
*region* arg = region-ID
region-ID = ID of region atoms must be in to contribute to spatial averaging
*norm* arg = *all* or *sample*
*units* arg = *box* or *lattice* or *reduced*
*ave* args = *one* or *running* or *window M*
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
*file* arg = filename
filename = file to write results to
*overwrite* arg = none = overwrite output file with only latest output
*title1* arg = string
string = text to print as 1st line of output file
*title2* arg = string
string = text to print as 2nd line of output file
*title3* arg = string
string = text to print as 3rd line of output file
Examples
""""""""
.. parsed-literal::
fix 1 all ave/spatial/sphere 10000 1 10000 0.5 0.5 0.5 0.1 0.5 5 density/number vx vy vz units reduced title1 "My output values"
fix 1 flow ave/spatial/sphere 100 10 1000 20.0 20.0 20.0 0.0 20.0 20 vx vz norm sample file vel.profile
Description
"""""""""""
Use one or more per-atom vectors as inputs every few timesteps, bin
their values spatially into spherical shells based on current atom
coordinates, and average the bin values over longer timescales. The
resulting bin averages can be used by other :ref:`output commands <howto_15>` such as :doc:`thermo_style custom <thermo_style>`, and can also be written to a file.
The group specified with the command means only atoms within the group
contribute to bin averages. If the *region* keyword is used, the atom
must be in both the group and the specified geometric
:doc:`region <region>` 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
:doc:`compute <compute>` or :doc:`fix <fix>` or the evaluation of an
atom-style :doc:`variable <variable>`. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. If you wish to time-average global quantities from a
compute, fix, or variable, then see the :doc:`fix ave/time <fix_ave_time>` command.
:doc:`Computes <compute>` that produce per-atom quantities are those
which have the word *atom* in their style name. See the doc pages for
individual :doc:`fixes <fix>` to determine which ones produce per-atom
quantities. :doc:`Variables <variable>` of style *atom* are the only
ones that can be used with this fix since all other styles of variable
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.
*Nbins* specifies the number of spherical shells which will be created
between r_min and r_max centered at (origin_x, origin_y, origin_z).
.. 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 will incur an overhead in memory and computational cost
(summing across processors), so be careful to use reasonable numbers
of bins.
----------
The *Nevery*\ , *Nrepeat*\ , and *Nfreq* arguments specify on what
timesteps the input values will be used to bin them and contribute to
the average. The final averaged quantities are generated on timesteps
that are a multiples of *Nfreq*\ . 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. Nrepeat*Nevery can not exceed Nfreq.
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. If Nrepeat=1 and Nfreq = 100, then no time
averaging is done; values are simply generated on timesteps
100,200,etc.
----------
The *origin_x*\ , *origin_y*\ , and *origin_z* parameters may be specified
by either a compute or a variable. This allows, for example, the
center of the spherical bins to be attached to the center of mass of a
group of atoms. If a variable origin is used and periodic boundary
conditions are in effect, then the origin will be wrapped across
periodic boundaries whenever it changes so that it is always inside
the simulation box.
----------
The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
Note that other atom attributes (including atom postitions x,y,z) can
be used as inputs to this fix by using the :doc:`compute property/atom <compute_property_atom>` command and then specifying
an input value from that compute.
The *density/number* value means the number density is computed in
each bin, i.e. a weighting of 1 for each atom. The *density/mass*
value means the mass density is computed in each bin, i.e. each atom
is weighted by its mass. The resulting density is normalized by the
volume of the bin so that units of number/volume or density are
output. See the :doc:`units <units>` command doc page for the
definition of density for each choice of units, e.g. gram/cm^3.
The bin volume will always be calculated in box units, independent
of the use of the *units* keyword in this command.
If a value begins with "c_", a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and :doc:`add them to LAMMPS <Section_modify>`.
If a value begins with "f_", a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
*Nevery*\ , else an error results. Users can also write code for their
own fix styles and :doc:`add them to LAMMPS <Section_modify>`.
If a value begins with "v_", a variable name must follow which has
been previously defined in the input script. Variables of style
*atom* can reference thermodynamic keywords and various per-atom
attributes, or invoke other computes, fixes, or variables when they
are evaluated, so this is a very general means of generating per-atom
quantities to spatially average.
----------
Additional optional keywords also affect the operation of this fix.
The *region* keyword was discussed above.
The *norm* keyword affects how averaging is done for the output
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 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 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 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 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 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 bin values produced on
timesteps that are multiples of *Nfreq* are summed and averaged in a
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 :doc:`unfix <unfix>` command, or re-defining the fix by
re-specifying it.
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 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 *units* keyword determines the meaning of the distance units used
for the sphere origin and the two radial lengths. 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
:doc:`units <units>` command, e.g. Angstroms for units = real or metal.
A *lattice* value means the distance units are in lattice spacings.
The :doc:`lattice <lattice>` command must have been previously used to
define the lattice spacing.
.. note::
The *lattice* style may only be used if the lattice spacing is
the same in each direction.
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.
The *file* keyword allows a filename to be specified. Every *Nfreq*
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).
The *overwrite* keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the *ave running* setting.
The *title1* and *title2* and *title3* keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the *file* keyword was used. LAMMPS uses default
values for each of these, so they do not need to be specified.
By default, these header lines are as follows:
.. parsed-literal::
# Spatial-averaged data for fix ID and group name
# Timestep Number-of-bins
# Bin r Count value1 value2 ...
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.
----------
Restart, fix_modify, output, run start/stop, minimize info
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix.
This fix computes a global array of values which can be accessed by
various :ref:`output commands <howto_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 =
Nbins and # of columns = 2+Nvalues. The first column contains the
radius at the center of the shell. For units *reduced*\ , this is in
reduced units, while for units *box* and *lattice* this is in box
units. 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. 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 :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
When the *ave* keyword is set to *running* or *window* then the number
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*\ .
This style is part of the USER-MISC package. It is only enabled if
LAMMPS is build with that package. See the :ref:`Making of LAMMPS <3>` section for more info.
Related commands
""""""""""""""""
:doc:`compute <compute>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix ave/time <fix_ave_time>`,
:doc:`variable <variable>`, :doc:`fix ave/correlate <fix_ave_correlate>`,
:doc:`fix ave/spatial <fix_ave_spatial>`,
Default
"""""""
The option defaults are norm = all, ave = one, units = lattice, no
file output, and title 1,2,3 = strings as described above.
.. _lws: http://lammps.sandia.gov
.. _ld: Manual.html
.. _lc: Section_commands.html#comm

567
doc/html/fix_ave_spatial.html
View File

@ -1,567 +0,0 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>fix ave/spatial command &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> &raquo;</li>
<li>fix ave/spatial command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="fix-ave-spatial-command">
<span id="index-0"></span><h1>fix ave/spatial command</h1>
<div class="section" id="syntax">
<h2>Syntax</h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="n">ID</span> <span class="n">group</span><span class="o">-</span><span class="n">ID</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span> <span class="n">Nevery</span> <span class="n">Nrepeat</span> <span class="n">Nfreq</span> <span class="n">dim</span> <span class="n">origin</span> <span class="n">delta</span> <span class="o">...</span> <span class="n">value1</span> <span class="n">value2</span> <span class="o">...</span> <span class="n">keyword</span> <span class="n">args</span> <span class="o">...</span>
</pre></div>
</div>
<ul class="simple">
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>ave/spatial = style name of this fix command</li>
<li>Nevery = use input values every this many timesteps</li>
<li>Nrepeat = # of times to use input values for calculating averages</li>
<li>Nfreq = calculate averages every this many timesteps</li>
<li>dim, origin, delta can be repeated 1, 2, or 3 times for 1d, 2d, or 3d bins</li>
</ul>
<pre class="literal-block">
dim = <em>x</em> or <em>y</em> or <em>z</em>
origin = <em>lower</em> or <em>center</em> or <em>upper</em> or coordinate value (distance units)
delta = thickness of spatial bins in dim (distance units)
</pre>
<ul class="simple">
<li>one or more input values can be listed</li>
<li>value = vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name</li>
</ul>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">vx</span><span class="p">,</span><span class="n">vy</span><span class="p">,</span><span class="n">vz</span><span class="p">,</span><span class="n">fx</span><span class="p">,</span><span class="n">fy</span><span class="p">,</span><span class="n">fz</span> <span class="o">=</span> <span class="n">atom</span> <span class="n">attribute</span> <span class="p">(</span><span class="n">velocity</span><span class="p">,</span> <span class="n">force</span> <span class="n">component</span><span class="p">)</span>
<span class="n">density</span><span class="o">/</span><span class="n">number</span><span class="p">,</span> <span class="n">density</span><span class="o">/</span><span class="n">mass</span> <span class="o">=</span> <span class="n">number</span> <span class="ow">or</span> <span class="n">mass</span> <span class="n">density</span>
<span class="n">c_ID</span> <span class="o">=</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">compute</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">c_ID</span><span class="p">[</span><span class="n">I</span><span class="p">]</span> <span class="o">=</span> <span class="n">Ith</span> <span class="n">column</span> <span class="n">of</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">array</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">compute</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">f_ID</span> <span class="o">=</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">fix</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">f_ID</span><span class="p">[</span><span class="n">I</span><span class="p">]</span> <span class="o">=</span> <span class="n">Ith</span> <span class="n">column</span> <span class="n">of</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">array</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">fix</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">v_name</span> <span class="o">=</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">an</span> <span class="n">atom</span><span class="o">-</span><span class="n">style</span> <span class="n">variable</span> <span class="k">with</span> <span class="n">name</span>
</pre></div>
</div>
<ul class="simple">
<li>zero or more keyword/arg pairs may be appended</li>
<li>keyword = <em>region</em> or <em>bound</em> or <em>discard</em> or <em>norm</em> or <em>ave</em> or <em>units</em> or <em>file</em> or <em>overwrite</em> or <em>title1</em> or <em>title2</em> or <em>title3</em></li>
</ul>
<pre class="literal-block">
<em>region</em> arg = region-ID
<em>bound</em> args = x/y/z lo hi
x/y/z = <em>x</em> or <em>y</em> or <em>z</em> to bound bins in this dimension
lo = <em>lower</em> or coordinate value (distance units)
hi = <em>upper</em> or coordinate value (distance units)
<em>discard</em> arg = <em>mixed</em> or <em>no</em> or <em>yes</em>
mixed = discard atoms outside bins only if bin bounds are explicitly set
no = always keep out-of-bounds atoms
yes = always discard out-of-bounds atoms
<em>norm</em> arg = <em>all</em> or <em>sample</em>
region-ID = ID of region atoms must be in to contribute to spatial averaging
<em>ave</em> args = <em>one</em> or <em>running</em> or <em>window M</em>
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
<em>units</em> arg = <em>box</em> or <em>lattice</em> or <em>reduced</em>
<em>file</em> arg = filename
filename = file to write results to
<em>overwrite</em> arg = none = overwrite output file with only latest output
<em>title1</em> arg = string
string = text to print as 1st line of output file
<em>title2</em> arg = string
string = text to print as 2nd line of output file
<em>title3</em> arg = string
string = text to print as 3rd line of output file
</pre>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="mi">1</span> <span class="nb">all</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span> <span class="mi">10000</span> <span class="mi">1</span> <span class="mi">10000</span> <span class="n">z</span> <span class="n">lower</span> <span class="mf">0.02</span> <span class="n">c_myCentro</span> <span class="n">units</span> <span class="n">reduced</span> <span class="o">&amp;</span>
<span class="n">title1</span> <span class="s2">&quot;My output values&quot;</span>
<span class="n">fix</span> <span class="mi">1</span> <span class="n">flow</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span> <span class="mi">100</span> <span class="mi">10</span> <span class="mi">1000</span> <span class="n">y</span> <span class="mf">0.0</span> <span class="mf">1.0</span> <span class="n">vx</span> <span class="n">vz</span> <span class="n">norm</span> <span class="n">sample</span> <span class="n">file</span> <span class="n">vel</span><span class="o">.</span><span class="n">profile</span>
<span class="n">fix</span> <span class="mi">1</span> <span class="n">flow</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span> <span class="mi">100</span> <span class="mi">5</span> <span class="mi">1000</span> <span class="n">z</span> <span class="n">lower</span> <span class="mf">1.0</span> <span class="n">y</span> <span class="mf">0.0</span> <span class="mf">2.5</span> <span class="n">density</span><span class="o">/</span><span class="n">mass</span> <span class="n">ave</span> <span class="n">running</span>
<span class="n">fix</span> <span class="mi">1</span> <span class="n">flow</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span> <span class="mi">100</span> <span class="mi">5</span> <span class="mi">1000</span> <span class="n">z</span> <span class="n">lower</span> <span class="mf">1.0</span> <span class="n">y</span> <span class="mf">0.0</span> <span class="mf">2.5</span> <span class="n">density</span><span class="o">/</span><span class="n">mass</span> <span class="n">bound</span> <span class="n">y</span> <span class="mf">5.0</span> <span class="mf">20.0</span> <span class="n">discard</span> <span class="n">yes</span> <span class="n">ave</span> <span class="n">running</span>
</pre></div>
</div>
<p><strong>NOTE:</strong></p>
<p>The fix ave/spatial command has been replaced by the more flexible
<a class="reference internal" href="fix_ave_chunk.html"><span class="doc">fix ave/chunk</span></a> and <a class="reference internal" href="compute_chunk_atom.html"><span class="doc">compute chunk/atom</span></a> commands. The fix ave/spatial
command will be removed from LAMMPS sometime in the summer of 2015.</p>
<p>Any fix ave/spatial command can be replaced by the two new commands.
You simply need to split the fix ave/spatial arguments across the two
new commands. For example, this command:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="mi">1</span> <span class="n">flow</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span> <span class="mi">100</span> <span class="mi">10</span> <span class="mi">1000</span> <span class="n">y</span> <span class="mf">0.0</span> <span class="mf">1.0</span> <span class="n">vx</span> <span class="n">vz</span> <span class="n">norm</span> <span class="n">sample</span> <span class="n">file</span> <span class="n">vel</span><span class="o">.</span><span class="n">profile</span>
</pre></div>
</div>
<p>could be replaced by:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">compute</span> <span class="n">cc1</span> <span class="n">flow</span> <span class="n">chunk</span><span class="o">/</span><span class="n">atom</span> <span class="nb">bin</span><span class="o">/</span><span class="mi">1</span><span class="n">d</span> <span class="n">y</span> <span class="mf">0.0</span> <span class="mf">1.0</span>
<span class="n">fix</span> <span class="mi">1</span> <span class="n">flow</span> <span class="n">ave</span><span class="o">/</span><span class="n">chunk</span> <span class="mi">100</span> <span class="mi">10</span> <span class="mi">1000</span> <span class="n">cc1</span> <span class="n">vx</span> <span class="n">vz</span> <span class="n">norm</span> <span class="n">sample</span> <span class="n">file</span> <span class="n">vel</span><span class="o">.</span><span class="n">profile</span>
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Use one or more per-atom vectors as inputs every few timesteps, bin
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 class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a> such as <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></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 bin averages. If the <em>region</em> keyword is used, the atom
must be in both the specified group and the specified geometric
<a class="reference internal" href="region.html"><span class="doc">region</span></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
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> or <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or the evaluation of an
atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. If you wish to time-average global quantities from a
compute, fix, or variable, then see the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a> command.</p>
<p><a class="reference internal" href="compute.html"><span class="doc">Computes</span></a> that produce per-atom quantities are those
which have the word <em>atom</em> in their style name. See the doc pages for
individual <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a> to determine which ones produce per-atom
quantities. <a class="reference internal" href="variable.html"><span class="doc">Variables</span></a> of style <em>atom</em> are the only
ones that can be used with this fix since all other styles of variable
produce global quantities.</p>
<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 <em>dim</em>, <em>origin</em>, and
<em>delta</em> settings and how many times they are specified (1, 2, or 3).
See details below.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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>
</div>
<hr class="docutils" />
<p>The <em>Nevery</em>, <em>Nrepeat</em>, and <em>Nfreq</em> arguments specify on what
timesteps the input values will be used to bin them and contribute to
the average. The final averaged quantities are generated on timesteps
that are a multiples of <em>Nfreq</em>. The average is over <em>Nrepeat</em>
quantities, computed in the preceding portion of the simulation every
<em>Nevery</em> timesteps. <em>Nfreq</em> must be a multiple of <em>Nevery</em> and
<em>Nevery</em> must be non-zero even if <em>Nrepeat</em> is 1. Also, the timesteps
contributing to the average value cannot overlap,
i.e. Nrepeat*Nevery can not exceed Nfreq.</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. If Nrepeat=1 and Nfreq = 100, then no time
averaging is done; values are simply generated on timesteps
100,200,etc.</p>
<hr class="docutils" />
<p>Each per-atom property is also averaged over atoms in each bin. The
way the averaging is one across the <em>Nrepeat</em> timesteps to produce
output on the <em>Nfreq</em> timesteps, and across multiple <em>Nfreq</em> outputs,
is determined by the <em>norm</em> and <em>av</em> keyword settings, as discussed
below.</p>
<p>Bins can be 1d layers or slabs, 2d pencils, or 3d boxes. This depends
on how many times (1, 2, or 3) the <em>dim</em>, <em>origin</em>, and <em>delta</em>
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 <em>dim</em> have a bin size in
that dimension given by <em>delta</em>. 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 <em>origin</em>,
which may be the lower/upper edge of the simulation box in that
dimension, or its center point, or a specified coordinate value.
Starting at the origin, sufficient bins are created in both directions
to completely span the bin extent in that dimension. By default the
bin extent is the entire simulation box.</p>
<p>The <em>bound</em> keyword can be used one or more times to limit the extent
of bin coverage in specified dimensions, i.e. to only bin a portion of
the box. If the <em>lo</em> setting is <em>lower</em> or the <em>hi</em> setting is
<em>upper</em>, the bin extent in that direction extends to the box boundary.
If a numeric value is used for <em>lo</em> and/or <em>hi</em>, then the bin extent
in the <em>lo</em> or <em>hi</em> direction extends only to that value, which is
assumed to be inside (or at least near) the simulation box boundaries,
though LAMMPS does not check for this.</p>
<p>On each sampling timestep, each atom is mapped to the bin it currently
belongs to, based on its current position. Note that the group-ID and
region keyword can exclude specific atoms from this operation, as
discussed above. Note that between reneighboring timesteps, atoms can
move outside the current simulation box. If the box is periodic (in
that dimension) the atom is remapping into the periodic box for
purposes of binning. If the box in not periodic, the atom may have
moved outside the bounds of any bin.</p>
<p>The <em>discard</em> keyword determines what is done with any atom which is
outside the bounds of any bin. If <em>discard</em> is set to <em>yes</em>, the atom
will be ignored and not contribute to any bin averages. If <em>discard</em>
is set to <em>no</em>, the atom will be counted as if it were in the first or
last bin in that dimension. If (discard* is set to <em>mixed</em>, which is
the default, it will only be counted in the first or last bin if bins
extend to the box boundary in that dimension. This is the case if the
<em>bound</em> keyword settings are <em>lower</em> and <em>upper</em>, which is the
default. If the <em>bound</em> keyword settings are numeric values, then the
atom will be ignored if it is outside the bounds of any bin. Note
that in this case, it is possible that the first or last bin extends
beyond the numeric <em>bounds</em> settings, depending on the specified
<em>origin</em>. If this is the case, the atom is only ignored if it is
outside the first or last bin, not if it is simply outside the numeric
<em>bounds</em> setting.</p>
<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 class="reference internal" href="Section_howto.html#howto-12"><span class="std std-ref">this section</span></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 &#8220;b&#8221; cross &#8220;c&#8221;
direction. Bins in y have faces normal to the &#8220;a&#8221; cross &#8220;c&#8221;
direction. And bins in z have faces normal to the &#8220;a&#8221; cross &#8220;b&#8221;
direction. Note that in order to define the size and position of
these bins in an unambiguous fashion, the <em>units</em> option must be set
to <em>reduced</em> when using a triclinic simulation box, as noted below.</p>
<hr class="docutils" />
<p>The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
Note that other atom attributes (including atom postitions x,y,z) can
be used as inputs to this fix by using the <a class="reference internal" href="compute_property_atom.html"><span class="doc">compute property/atom</span></a> command and then specifying
an input value from that compute.</p>
<p>The <em>density/number</em> value means the number density is computed in
each bin, i.e. a weighting of 1 for each atom. The <em>density/mass</em>
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 bin so that units of number/volume or density are
output. See the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command doc page for the
definition of density for each choice of units, e.g. gram/cm^3.</p>
<p>If a value begins with &#8220;<a href="#id1"><span class="problematic" id="id2">c_</span></a>&#8221;, a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If a value begins with &#8220;<a href="#id3"><span class="problematic" id="id4">f_</span></a>&#8221;, a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
<em>Nevery</em>, else an error results. Users can also write code for their
own fix styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If a value begins with &#8220;<a href="#id5"><span class="problematic" id="id6">v_</span></a>&#8221;, a variable name must follow which has
been previously defined in the input script. Variables of style
<em>atom</em> can reference thermodynamic keywords and various per-atom
attributes, or invoke other computes, fixes, or variables when they
are evaluated, so this is a very general means of generating per-atom
quantities to spatially average.</p>
<hr class="docutils" />
<p>Additional optional keywords also affect the operation of this fix.
The <em>region</em>, <em>bound</em>, and <em>discard</em> keywords were discussed above.</p>
<p>The <em>norm</em> keyword affects how averaging is done for the output
produced every <em>Nfreq</em> timesteps. For an <em>all</em> setting, a bin
quantity is summed over all atoms in all <em>Nrepeat</em> samples, as is the
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 <em>Nfreq</em> timescale.</p>
<p>For a <em>sample</em> setting, the bin quantity is summed over atoms for only
a single sample, as is the count, and a &#8220;average sample value&#8221; is
computed, i.e. Sample-quantity / Sample-count. The printed value for
the bin is the average of the <em>Nrepeat</em> &#8220;average sample values&#8221;, In
other words it is an average of an average.</p>
<p>The <em>ave</em> keyword determines how the bin values produced every <em>Nfreq</em>
steps are averaged with bin values produced on previous steps that
were multiples of <em>Nfreq</em>, before they are accessed by another output
command or written to a file.</p>
<p>If the <em>ave</em> setting is <em>one</em>, then the bin values produced on
timesteps that are multiples of <em>Nfreq</em> are independent of each other;
they are output as-is without further averaging.</p>
<p>If the <em>ave</em> setting is <em>running</em>, then the bin values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged in a
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 class="reference internal" href="unfix.html"><span class="doc">unfix</span></a> command, or re-defining the fix by
re-specifying it.</p>
<p>If the <em>ave</em> setting is <em>window</em>, then the bin values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged within
a moving &#8220;window&#8221; 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 <em>units</em> keyword determines the meaning of the distance units used
for the bin size <em>delta</em> and for <em>origin</em> and <em>bounds</em> values if they
are coordinate value. For orthogonal simulation boxes, any of the 3
options may be used. For non-orthogonal (triclinic) simulation boxes,
only the <em>reduced</em> option may be used.</p>
<p>A <em>box</em> value selects standard distance units as defined by the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or metal.
A <em>lattice</em> value means the distance units are in lattice spacings.
The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have been previously used to
define the lattice spacing. A <em>reduced</em> value means normalized
unitless values between 0 and 1, which represent the lower and upper
faces of the simulation box respectively. Thus an <em>origin</em> value of
0.5 means the center of the box in any dimension. A <em>delta</em> value of
0.1 means 10 bins span the box in that dimension.</p>
<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 <em>origin</em> of
0.0 means start layers at the lower &#8220;b&#8221; cross &#8220;c&#8221; plane of the
simulation box and an <em>origin</em> of 1.0 means to start layers at the
upper &#8220;b&#8221; cross &#8220;c&#8221; face of the box. A <em>delta</em> 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 <em>file</em> keyword allows a filename to be specified. Every <em>Nfreq</em>
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 <em>units</em> keyword is <em>box</em> or
<em>lattice</em>, the &#8220;coord&#8221; is printed in box units. If the value of the
<em>units</em> keyword is <em>reduced</em>, the &#8220;coord&#8221; is printed in reduced units
(0-1).</p>
<p>The <em>overwrite</em> keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the <em>ave running</em> setting.</p>
<p>The <em>title1</em> and <em>title2</em> and <em>title3</em> keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the <em>file</em> keyword was used. LAMMPS uses default
values for each of these, so they do not need to be specified.</p>
<p>By default, these header lines are as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Spatial-averaged data for fix ID and group name</span>
<span class="c1"># Timestep Number-of-bins</span>
<span class="c1"># Bin Coord1 Coord2 Coord3 Count value1 value2 ...</span>
</pre></div>
</div>
<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>
</div>
<hr class="docutils" />
<div class="section" id="restart-fix-modify-output-run-start-stop-minimize-info">
<h2>Restart, fix_modify, output, run start/stop, minimize info</h2>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>This fix computes a global array of values which can be accessed by
various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The values can
only be accessed on timesteps that are multiples of <em>Nfreq</em> since that
is when averaging is performed. The global array has # of rows =
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 &#8220;intensive&#8221;, 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 <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>When the <em>ave</em> keyword is set to <em>running</em> or <em>window</em> then the number
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&#8217;t change or if the <em>units</em> keyword is set to
<em>reduced</em>.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands</h2>
<p><a class="reference internal" href="compute.html"><span class="doc">compute</span></a>, <a class="reference internal" href="fix_ave_atom.html"><span class="doc">fix ave/atom</span></a>, <a class="reference internal" href="fix_ave_histo.html"><span class="doc">fix ave/histo</span></a>, <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>,
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, <a class="reference internal" href="fix_ave_correlate.html"><span class="doc">fix ave/correlate</span></a>,
<a class="reference internal" href="fix_ave_spatial_sphere.html"><span class="doc">fix ave/spatial/sphere</span></a></p>
</div>
<div class="section" id="default">
<h2>Default</h2>
<p>The option defaults are bound = lower and upper in all dimensions,
discard = mixed, norm = all, ave = one, units = lattice, no file
output, and title 1,2,3 = strings as described above.</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013 Sandia Corporation.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>

478
doc/html/fix_ave_spatial_sphere.html
View File

@ -1,478 +0,0 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>fix ave/spatial/sphere command &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> &raquo;</li>
<li>fix ave/spatial/sphere command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="fix-ave-spatial-sphere-command">
<span id="index-0"></span><h1>fix ave/spatial/sphere command</h1>
<div class="section" id="syntax">
<h2>Syntax</h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="n">ID</span> <span class="n">group</span><span class="o">-</span><span class="n">ID</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span><span class="o">/</span><span class="n">sphere</span> <span class="n">Nevery</span> <span class="n">Nrepeat</span> <span class="n">Nfreq</span> <span class="n">origin_x</span> <span class="n">origin_y</span> <span class="n">origin_z</span> <span class="n">r_min</span> <span class="n">r_max</span> <span class="n">nbins</span> <span class="n">value1</span> <span class="n">value2</span> <span class="o">...</span> <span class="n">keyword</span> <span class="n">args</span> <span class="o">...</span>
</pre></div>
</div>
<ul class="simple">
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> command</li>
<li>ave/spatial = style name of this fix command</li>
<li>Nevery = use input values every this many timesteps</li>
<li>Nrepeat = # of times to use input values for calculating averages</li>
<li>Nfreq = calculate averages every this many timesteps</li>
<li>origin_x, origin_y, origin_z = center of the sphere. can be the result of variables or computes (see below)</li>
<li>r_min = radial distance at which binning begins</li>
<li>r_max = radial distance at which binning ends</li>
<li>nbins = number of spherical shells to create between r_min and r_max</li>
<li>one or more input values can be listed</li>
<li>value = vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name</li>
</ul>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">vx</span><span class="p">,</span><span class="n">vy</span><span class="p">,</span><span class="n">vz</span><span class="p">,</span><span class="n">fx</span><span class="p">,</span><span class="n">fy</span><span class="p">,</span><span class="n">fz</span> <span class="o">=</span> <span class="n">atom</span> <span class="n">attribute</span> <span class="p">(</span><span class="n">velocity</span><span class="p">,</span> <span class="n">force</span> <span class="n">component</span><span class="p">)</span>
<span class="n">density</span><span class="o">/</span><span class="n">number</span><span class="p">,</span> <span class="n">density</span><span class="o">/</span><span class="n">mass</span> <span class="o">=</span> <span class="n">number</span> <span class="ow">or</span> <span class="n">mass</span> <span class="n">density</span>
<span class="n">c_ID</span> <span class="o">=</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">compute</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">c_ID</span><span class="p">[</span><span class="n">I</span><span class="p">]</span> <span class="o">=</span> <span class="n">Ith</span> <span class="n">column</span> <span class="n">of</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">array</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">compute</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">f_ID</span> <span class="o">=</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">fix</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">f_ID</span><span class="p">[</span><span class="n">I</span><span class="p">]</span> <span class="o">=</span> <span class="n">Ith</span> <span class="n">column</span> <span class="n">of</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">array</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">a</span> <span class="n">fix</span> <span class="k">with</span> <span class="n">ID</span>
<span class="n">v_name</span> <span class="o">=</span> <span class="n">per</span><span class="o">-</span><span class="n">atom</span> <span class="n">vector</span> <span class="n">calculated</span> <span class="n">by</span> <span class="n">an</span> <span class="n">atom</span><span class="o">-</span><span class="n">style</span> <span class="n">variable</span> <span class="k">with</span> <span class="n">name</span>
</pre></div>
</div>
<ul class="simple">
<li>zero or more keyword/arg pairs may be appended</li>
<li>keyword = <em>region</em> or <em>norm</em> or <em>units</em> or <em>ave</em> or <em>file</em> or <em>overwrite</em> or <em>title1</em> or <em>title2</em> or <em>title3</em></li>
</ul>
<pre class="literal-block">
<em>region</em> arg = region-ID
region-ID = ID of region atoms must be in to contribute to spatial averaging
<em>norm</em> arg = <em>all</em> or <em>sample</em>
<em>units</em> arg = <em>box</em> or <em>lattice</em> or <em>reduced</em>
<em>ave</em> args = <em>one</em> or <em>running</em> or <em>window M</em>
one = output new average value every Nfreq steps
running = output cumulative average of all previous Nfreq steps
window M = output average of M most recent Nfreq steps
<em>file</em> arg = filename
filename = file to write results to
<em>overwrite</em> arg = none = overwrite output file with only latest output
<em>title1</em> arg = string
string = text to print as 1st line of output file
<em>title2</em> arg = string
string = text to print as 2nd line of output file
<em>title3</em> arg = string
string = text to print as 3rd line of output file
</pre>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">fix</span> <span class="mi">1</span> <span class="nb">all</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span><span class="o">/</span><span class="n">sphere</span> <span class="mi">10000</span> <span class="mi">1</span> <span class="mi">10000</span> <span class="mf">0.5</span> <span class="mf">0.5</span> <span class="mf">0.5</span> <span class="mf">0.1</span> <span class="mf">0.5</span> <span class="mi">5</span> <span class="n">density</span><span class="o">/</span><span class="n">number</span> <span class="n">vx</span> <span class="n">vy</span> <span class="n">vz</span> <span class="n">units</span> <span class="n">reduced</span> <span class="n">title1</span> <span class="s2">&quot;My output values&quot;</span>
<span class="n">fix</span> <span class="mi">1</span> <span class="n">flow</span> <span class="n">ave</span><span class="o">/</span><span class="n">spatial</span><span class="o">/</span><span class="n">sphere</span> <span class="mi">100</span> <span class="mi">10</span> <span class="mi">1000</span> <span class="mf">20.0</span> <span class="mf">20.0</span> <span class="mf">20.0</span> <span class="mf">0.0</span> <span class="mf">20.0</span> <span class="mi">20</span> <span class="n">vx</span> <span class="n">vz</span> <span class="n">norm</span> <span class="n">sample</span> <span class="n">file</span> <span class="n">vel</span><span class="o">.</span><span class="n">profile</span>
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>Use one or more per-atom vectors as inputs every few timesteps, bin
their values spatially into spherical shells based on current atom
coordinates, and average the bin values over longer timescales. The
resulting bin averages can be used by other <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a> such as <a class="reference internal" href="thermo_style.html"><span class="doc">thermo_style custom</span></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 bin averages. If the <em>region</em> keyword is used, the atom
must be in both the group and the specified geometric
<a class="reference internal" href="region.html"><span class="doc">region</span></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
<a class="reference internal" href="compute.html"><span class="doc">compute</span></a> or <a class="reference internal" href="fix.html"><span class="doc">fix</span></a> or the evaluation of an
atom-style <a class="reference internal" href="variable.html"><span class="doc">variable</span></a>. In the latter cases, the
compute, fix, or variable must produce a per-atom quantity, not a
global quantity. If you wish to time-average global quantities from a
compute, fix, or variable, then see the <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a> command.</p>
<p><a class="reference internal" href="compute.html"><span class="doc">Computes</span></a> that produce per-atom quantities are those
which have the word <em>atom</em> in their style name. See the doc pages for
individual <a class="reference internal" href="fix.html"><span class="doc">fixes</span></a> to determine which ones produce per-atom
quantities. <a class="reference internal" href="variable.html"><span class="doc">Variables</span></a> of style <em>atom</em> are the only
ones that can be used with this fix since all other styles of variable
produce global quantities.</p>
<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><em>Nbins</em> specifies the number of spherical shells which will be created
between r_min and r_max centered at (origin_x, origin_y, origin_z).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">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 will incur an overhead in memory and computational cost
(summing across processors), so be careful to use reasonable numbers
of bins.</p>
</div>
<hr class="docutils" />
<p>The <em>Nevery</em>, <em>Nrepeat</em>, and <em>Nfreq</em> arguments specify on what
timesteps the input values will be used to bin them and contribute to
the average. The final averaged quantities are generated on timesteps
that are a multiples of <em>Nfreq</em>. The average is over <em>Nrepeat</em>
quantities, computed in the preceding portion of the simulation every
<em>Nevery</em> timesteps. <em>Nfreq</em> must be a multiple of <em>Nevery</em> and
<em>Nevery</em> must be non-zero even if <em>Nrepeat</em> is 1.
Also, the timesteps
contributing to the average value cannot overlap,
i.e. Nrepeat*Nevery can not exceed Nfreq.</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. If Nrepeat=1 and Nfreq = 100, then no time
averaging is done; values are simply generated on timesteps
100,200,etc.</p>
<hr class="docutils" />
<p>The <em>origin_x</em>, <em>origin_y</em>, and <em>origin_z</em> parameters may be specified
by either a compute or a variable. This allows, for example, the
center of the spherical bins to be attached to the center of mass of a
group of atoms. If a variable origin is used and periodic boundary
conditions are in effect, then the origin will be wrapped across
periodic boundaries whenever it changes so that it is always inside
the simulation box.</p>
<hr class="docutils" />
<p>The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
Note that other atom attributes (including atom postitions x,y,z) can
be used as inputs to this fix by using the <a class="reference internal" href="compute_property_atom.html"><span class="doc">compute property/atom</span></a> command and then specifying
an input value from that compute.</p>
<p>The <em>density/number</em> value means the number density is computed in
each bin, i.e. a weighting of 1 for each atom. The <em>density/mass</em>
value means the mass density is computed in each bin, i.e. each atom
is weighted by its mass. The resulting density is normalized by the
volume of the bin so that units of number/volume or density are
output. See the <a class="reference internal" href="units.html"><span class="doc">units</span></a> command doc page for the
definition of density for each choice of units, e.g. gram/cm^3.
The bin volume will always be calculated in box units, independent
of the use of the <em>units</em> keyword in this command.</p>
<p>If a value begins with &#8220;<a href="#id1"><span class="problematic" id="id2">c_</span></a>&#8221;, a compute ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the compute is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the compute is used. Users can also write code for
their own compute styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If a value begins with &#8220;<a href="#id3"><span class="problematic" id="id4">f_</span></a>&#8221;, a fix ID must follow which has been
previously defined in the input script. If no bracketed integer is
appended, the per-atom vector calculated by the fix is used. If a
bracketed integer is appended, the Ith column of the per-atom array
calculated by the fix is used. Note that some fixes only produce
their values on certain timesteps, which must be compatible with
<em>Nevery</em>, else an error results. Users can also write code for their
own fix styles and <a class="reference internal" href="Section_modify.html"><span class="doc">add them to LAMMPS</span></a>.</p>
<p>If a value begins with &#8220;<a href="#id5"><span class="problematic" id="id6">v_</span></a>&#8221;, a variable name must follow which has
been previously defined in the input script. Variables of style
<em>atom</em> can reference thermodynamic keywords and various per-atom
attributes, or invoke other computes, fixes, or variables when they
are evaluated, so this is a very general means of generating per-atom
quantities to spatially average.</p>
<hr class="docutils" />
<p>Additional optional keywords also affect the operation of this fix.
The <em>region</em> keyword was discussed above.</p>
<p>The <em>norm</em> keyword affects how averaging is done for the output
produced every <em>Nfreq</em> timesteps. For an <em>all</em> setting, a bin
quantity is summed over all atoms in all <em>Nrepeat</em> samples, as is the
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 <em>Nfreq</em> timescale.</p>
<p>For a <em>sample</em> setting, the bin quantity is summed over atoms for only
a single sample, as is the count, and a &#8220;average sample value&#8221; is
computed, i.e. Sample-quantity / Sample-count. The printed value for
the bin is the average of the <em>Nrepeat</em> &#8220;average sample values&#8221;, In
other words it is an average of an average.</p>
<p>The <em>ave</em> keyword determines how the bin values produced every <em>Nfreq</em>
steps are averaged with bin values produced on previous steps that
were multiples of <em>Nfreq</em>, before they are accessed by another output
command or written to a file.</p>
<p>If the <em>ave</em> setting is <em>one</em>, then the bin values produced on
timesteps that are multiples of <em>Nfreq</em> are independent of each other;
they are output as-is without further averaging.</p>
<p>If the <em>ave</em> setting is <em>running</em>, then the bin values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged in a
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 class="reference internal" href="unfix.html"><span class="doc">unfix</span></a> command, or re-defining the fix by
re-specifying it.</p>
<p>If the <em>ave</em> setting is <em>window</em>, then the bin values produced on
timesteps that are multiples of <em>Nfreq</em> are summed and averaged within
a moving &#8220;window&#8221; 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 <em>units</em> keyword determines the meaning of the distance units used
for the sphere origin and the two radial lengths. For orthogonal
simulation boxes, any of the 3 options may be used. For
non-orthogonal (triclinic) simulation boxes, only the <em>reduced</em> option
may be used.</p>
<p>A <em>box</em> value selects standard distance units as defined by the
<a class="reference internal" href="units.html"><span class="doc">units</span></a> command, e.g. Angstroms for units = real or metal.
A <em>lattice</em> value means the distance units are in lattice spacings.
The <a class="reference internal" href="lattice.html"><span class="doc">lattice</span></a> command must have been previously used to
define the lattice spacing.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <em>lattice</em> style may only be used if the lattice spacing is
the same in each direction.</p>
</div>
<p>A <em>reduced</em> value means normalized unitless values between 0 and 1,
which represent the lower and upper faces of the simulation box
respectively. Thus an <em>origin</em> value of 0.5 means the center of the
box in any dimension.</p>
<p>The <em>file</em> keyword allows a filename to be specified. Every <em>Nfreq</em>
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 <em>units</em> keyword is <em>box</em> or
<em>lattice</em>, the &#8220;coord&#8221; is printed in box units. If the value of the
<em>units</em> keyword is <em>reduced</em>, the &#8220;coord&#8221; is printed in reduced units
(0-1).</p>
<p>The <em>overwrite</em> keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the <em>ave running</em> setting.</p>
<p>The <em>title1</em> and <em>title2</em> and <em>title3</em> keywords allow specification of
the strings that will be printed as the first 3 lines of the output
file, assuming the <em>file</em> keyword was used. LAMMPS uses default
values for each of these, so they do not need to be specified.</p>
<p>By default, these header lines are as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Spatial-averaged data for fix ID and group name</span>
<span class="c1"># Timestep Number-of-bins</span>
<span class="c1"># Bin r Count value1 value2 ...</span>
</pre></div>
</div>
<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>
</div>
<hr class="docutils" />
<div class="section" id="restart-fix-modify-output-run-start-stop-minimize-info">
<h2>Restart, fix_modify, output, run start/stop, minimize info</h2>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><span class="doc">binary restart files</span></a>. None of the <a class="reference internal" href="fix_modify.html"><span class="doc">fix_modify</span></a> options
are relevant to this fix.</p>
<p>This fix computes a global array of values which can be accessed by
various <a class="reference internal" href="Section_howto.html#howto-15"><span class="std std-ref">output commands</span></a>. The values can
only be accessed on timesteps that are multiples of <em>Nfreq</em> since that
is when averaging is performed. The global array has # of rows =
Nbins and # of columns = 2+Nvalues. The first column contains the
radius at the center of the shell. For units <em>reduced</em>, this is in
reduced units, while for units <em>box</em> and <em>lattice</em> this is in box
units. 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. The array values
calculated by this fix are &#8220;intensive&#8221;, 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 <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><span class="doc">run</span></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><span class="doc">energy minimization</span></a>.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>When the <em>ave</em> keyword is set to <em>running</em> or <em>window</em> then the number
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&#8217;t change or if the <em>units</em> keyword is set to
<em>reduced</em>.</p>
<p>This style is part of the USER-MISC package. It is only enabled if
LAMMPS is build with that package. See the <span class="xref std std-ref">Making of LAMMPS</span> section for more info.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands</h2>
<p><a class="reference internal" href="compute.html"><span class="doc">compute</span></a>, <a class="reference internal" href="fix_ave_atom.html"><span class="doc">fix ave/atom</span></a>, <a class="reference internal" href="fix_ave_histo.html"><span class="doc">fix ave/histo</span></a>, <a class="reference internal" href="fix_ave_time.html"><span class="doc">fix ave/time</span></a>,
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a>, <a class="reference internal" href="fix_ave_correlate.html"><span class="doc">fix ave/correlate</span></a>,
<a class="reference internal" href="fix_ave_spatial.html"><span class="doc">fix ave/spatial</span></a>,</p>
</div>
<div class="section" id="default">
<h2>Default</h2>
<p>The option defaults are norm = all, ave = one, units = lattice, no
file output, and title 1,2,3 = strings as described above.</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013 Sandia Corporation.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>

2
doc/lammps.book
View File

@ -118,8 +118,6 @@ fix_ave_correlate.html
fix_ave_correlate_long.html
fix_ave_chunk.html
fix_ave_histo.html
fix_ave_spatial.html
fix_ave_spatial_sphere.html
fix_ave_time.html
fix_aveforce.html
fix_balance.html