2
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
12
<H3>fix ave/spatial/sphere command
16
<PRE>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 ...
18
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
20
<LI>ave/spatial = style name of this fix command
22
<LI>Nevery = use input values every this many timesteps
24
<LI>Nrepeat = # of times to use input values for calculating averages
26
<LI>Nfreq = calculate averages every this many timesteps
28
<LI>origin_x, origin_y, origin_z = center of the sphere. can be the result of variables or computes (see below)
30
<LI>r_min = radial distance at which binning begins
32
<LI>r_max = radial distance at which binning ends
34
<LI>nbins = number of spherical shells to create between r_min and r_max
36
<LI>one or more input values can be listed
38
<LI>value = vx, vy, vz, fx, fy, fz, density/mass, density/number, c_ID, c_ID[I], f_ID, f_ID[I], v_name
40
<PRE> vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component)
41
density/number, density/mass = number or mass density
42
c_ID = per-atom vector calculated by a compute with ID
43
c_ID[I] = Ith column of per-atom array calculated by a compute with ID
44
f_ID = per-atom vector calculated by a fix with ID
45
f_ID[I] = Ith column of per-atom array calculated by a fix with ID
46
v_name = per-atom vector calculated by an atom-style variable with name
48
<LI>zero or more keyword/arg pairs may be appended
50
<LI>keyword = <I>region</I> or <I>norm</I> or <I>units</I> or <I>ave</I> or <I>file</I> or <I>overwrite</I> or <I>title1</I> or <I>title2</I> or <I>title3</I>
52
<PRE> <I>region</I> arg = region-ID
53
region-ID = ID of region atoms must be in to contribute to spatial averaging
54
<I>norm</I> arg = <I>all</I> or <I>sample</I>
55
<I>units</I> arg = <I>box</I> or <I>lattice</I> or <I>reduced</I>
56
<I>ave</I> args = <I>one</I> or <I>running</I> or <I>window M</I>
57
one = output new average value every Nfreq steps
58
running = output cumulative average of all previous Nfreq steps
59
window M = output average of M most recent Nfreq steps
60
<I>file</I> arg = filename
61
filename = file to write results to
62
<I>overwrite</I> arg = none = overwrite output file with only latest output
63
<I>title1</I> arg = string
64
string = text to print as 1st line of output file
65
<I>title2</I> arg = string
66
string = text to print as 2nd line of output file
67
<I>title3</I> arg = string
68
string = text to print as 3rd line of output file
74
<PRE>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"
75
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
77
<P><B>Description:</B>
79
<P>Use one or more per-atom vectors as inputs every few timesteps, bin
80
their values spatially into spherical shells based on current atom
81
coordinates, and average the bin values over longer timescales. The
82
resulting bin averages can be used by other <A HREF = "Section_howto.html#howto_15">output
83
commands</A> such as <A HREF = "thermo_style.html">thermo_style
84
custom</A>, and can also be written to a file.
86
<P>The group specified with the command means only atoms within the group
87
contribute to bin averages. If the <I>region</I> keyword is used, the atom
88
must be in both the group and the specified geometric
89
<A HREF = "region.html">region</A> in order to contribute to bin averages.
91
<P>Each listed value can be an atom attribute (position, velocity, force
92
component), a mass or number density, or the result of a
93
<A HREF = "compute.html">compute</A> or <A HREF = "fix.html">fix</A> or the evaluation of an
94
atom-style <A HREF = "variable.html">variable</A>. In the latter cases, the
95
compute, fix, or variable must produce a per-atom quantity, not a
96
global quantity. If you wish to time-average global quantities from a
97
compute, fix, or variable, then see the <A HREF = "fix_ave_time.html">fix
100
<P><A HREF = "compute.html">Computes</A> that produce per-atom quantities are those
101
which have the word <I>atom</I> in their style name. See the doc pages for
102
individual <A HREF = "fix.html">fixes</A> to determine which ones produce per-atom
103
quantities. <A HREF = "variable.html">Variables</A> of style <I>atom</I> are the only
104
ones that can be used with this fix since all other styles of variable
105
produce global quantities.
107
<P>The per-atom values of each input vector are binned and averaged
108
independently of the per-atom values in other input vectors.
110
<P><I>Nbins</I> specifies the number of spherical shells which will be created
111
between r_min and r_max centered at (origin_x, origin_y, origin_z).
113
<P>IMPORTANT NOTE: This fix works by creating an array of size Nbins by
114
Nvalues on each processor. Nbins is the total number of bins; Nvalues
115
is the number of input values specified. Each processor loops over
116
its atoms, tallying its values to the appropriate bin. Then the
117
entire array is summed across all processors. This means that using a
118
large number of bins will incur an overhead in memory and computational
119
cost (summing across processors), so be careful to use reasonable numbers
124
<P>The <I>Nevery</I>, <I>Nrepeat</I>, and <I>Nfreq</I> arguments specify on what
125
timesteps the input values will be used to bin them and contribute to
126
the average. The final averaged quantities are generated on timesteps
127
that are a multiples of <I>Nfreq</I>. The average is over <I>Nrepeat</I>
128
quantities, computed in the preceding portion of the simulation every
129
<I>Nevery</I> timesteps. <I>Nfreq</I> must be a multiple of <I>Nevery</I> and
130
<I>Nevery</I> must be non-zero even if <I>Nrepeat</I> is 1. Also, the timesteps
131
contributing to the average value cannot overlap, i.e. Nfreq >
132
(Nrepeat-1)*Nevery is required.
134
<P>For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
135
timesteps 90,92,94,96,98,100 will be used to compute the final average
136
on timestep 100. Similarly for timesteps 190,192,194,196,198,200 on
137
timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time
138
averaging is done; values are simply generated on timesteps
143
<P>The <I>origin_x</I>, <I>origin_y</I>, and <I>origin_z</I> parameters may be specified
144
by either a compute or a variable. This allows, for example, the
145
center of the spherical bins to be attached to the center of mass of a
146
group of atoms. If a variable origin is used and periodic boundary
147
conditions are in effect, then the origin will be wrapped across
148
periodic boundaries whenever it changes so that it is always inside
153
<P>The atom attribute values (vx,vy,vz,fx,fy,fz) are self-explanatory.
154
Note that other atom attributes (including atom postitions x,y,z) can
155
be used as inputs to this fix by using the <A HREF = "compute_property_atom.html">compute
156
property/atom</A> command and then specifying
157
an input value from that compute.
159
<P>The <I>density/number</I> value means the number density is computed in
160
each bin, i.e. a weighting of 1 for each atom. The <I>density/mass</I>
161
value means the mass density is computed in each bin, i.e. each atom
162
is weighted by its mass. The resulting density is normalized by the
163
volume of the bin so that units of number/volume or density are
164
output. See the <A HREF = "units.html">units</A> command doc page for the
165
definition of density for each choice of units, e.g. gram/cm^3.
166
The bin volume will always be calculated in box units, independent
167
of the use of the <I>units</I> keyword in this command.
169
<P>If a value begins with "c_", a compute ID must follow which has been
170
previously defined in the input script. If no bracketed integer is
171
appended, the per-atom vector calculated by the compute is used. If a
172
bracketed integer is appended, the Ith column of the per-atom array
173
calculated by the compute is used. Users can also write code for
174
their own compute styles and <A HREF = "Section_modify.html">add them to LAMMPS</A>.
176
<P>If a value begins with "f_", a fix ID must follow which has been
177
previously defined in the input script. If no bracketed integer is
178
appended, the per-atom vector calculated by the fix is used. If a
179
bracketed integer is appended, the Ith column of the per-atom array
180
calculated by the fix is used. Note that some fixes only produce
181
their values on certain timesteps, which must be compatible with
182
<I>Nevery</I>, else an error results. Users can also write code for their
183
own fix styles and <A HREF = "Section_modify.html">add them to LAMMPS</A>.
185
<P>If a value begins with "v_", a variable name must follow which has
186
been previously defined in the input script. Variables of style
187
<I>atom</I> can reference thermodynamic keywords and various per-atom
188
attributes, or invoke other computes, fixes, or variables when they
189
are evaluated, so this is a very general means of generating per-atom
190
quantities to spatially average.
194
<P>Additional optional keywords also affect the operation of this fix.
195
The <I>region</I> keyword was discussed above.
197
<P>The <I>norm</I> keyword affects how averaging is done for the output
198
produced every <I>Nfreq</I> timesteps. For an <I>all</I> setting, a bin
199
quantity is summed over all atoms in all <I>Nrepeat</I> samples, as is the
200
count of atoms in the bin. The printed value for the bin is
201
Total-quantity / Total-count. In other words it is an average over
202
the entire <I>Nfreq</I> timescale.
204
<P>For a <I>sample</I> setting, the bin quantity is summed over atoms for only
205
a single sample, as is the count, and a "average sample value" is
206
computed, i.e. Sample-quantity / Sample-count. The printed value for
207
the bin is the average of the <I>Nrepeat</I> "average sample values", In
208
other words it is an average of an average.
210
<P>The <I>ave</I> keyword determines how the bin values produced every <I>Nfreq</I>
211
steps are averaged with bin values produced on previous steps that
212
were multiples of <I>Nfreq</I>, before they are accessed by another output
213
command or written to a file.
215
<P>If the <I>ave</I> setting is <I>one</I>, then the bin values produced on
216
timesteps that are multiples of <I>Nfreq</I> are independent of each other;
217
they are output as-is without further averaging.
219
<P>If the <I>ave</I> setting is <I>running</I>, then the bin values produced on
220
timesteps that are multiples of <I>Nfreq</I> are summed and averaged in a
221
cumulative sense before being output. Each output bin value is thus
222
the average of the bin value produced on that timestep with all
223
preceding values for the same bin. This running average begins when
224
the fix is defined; it can only be restarted by deleting the fix via
225
the <A HREF = "unfix.html">unfix</A> command, or re-defining the fix by
228
<P>If the <I>ave</I> setting is <I>window</I>, then the bin values produced on
229
timesteps that are multiples of <I>Nfreq</I> are summed and averaged within
230
a moving "window" of time, so that the last M values for the same bin
231
are used to produce the output. E.g. if M = 3 and Nfreq = 1000, then
232
the output on step 10000 will be the average of the individual bin
233
values on steps 8000,9000,10000. Outputs on early steps will average
234
over less than M values if they are not available.
236
<P>The <I>units</I> keyword determines the meaning of the distance units used
237
for the sphere origin and the two radial lengths. For orthogonal
238
simulation boxes, any of the 3 options may be used. For
239
non-orthogonal (triclinic) simulation boxes, only the <I>reduced</I> option
242
<P>A <I>box</I> value selects standard distance units as defined by the
243
<A HREF = "units.html">units</A> command, e.g. Angstroms for units = real or metal.
244
A <I>lattice</I> value means the distance units are in lattice spacings.
245
The <A HREF = "lattice.html">lattice</A> command must have been previously used to
246
define the lattice spacing.
248
<P>IMPORTANT NOTE: The <I>lattice</I> style may only be used if the lattice
249
spacing is the same in each direction.
251
<P>A <I>reduced</I> value means normalized unitless values between 0 and 1,
252
which represent the lower and upper faces of the simulation box
253
respectively. Thus an <I>origin</I> value of 0.5 means the center of the
254
box in any dimension.
256
<P>The <I>file</I> keyword allows a filename to be specified. Every <I>Nfreq</I>
257
timesteps, a section of bin info will be written to a text file in the
258
following format. A line with the timestep and number of bin is
259
written. Then one line per bin is written, containing the bin ID
260
(1-N), the coordinate of the center of the bin, the number of atoms in
261
the bin, and one or more calculated values. The number of values in
262
each line corresponds to the number of values specified in the fix
263
ave/spatial command. The number of atoms and the value(s) are average
264
quantities. If the value of the <I>units</I> keyword is <I>box</I> or
265
<I>lattice</I>, the "coord" is printed in box units. If the value of the
266
<I>units</I> keyword is <I>reduced</I>, the "coord" is printed in reduced units
269
<P>The <I>overwrite</I> keyword will continuously overwrite the output file
270
with the latest output, so that it only contains one timestep worth of
271
output. This option can only be used with the <I>ave running</I> setting.
273
<P>The <I>title1</I> and <I>title2</I> and <I>title3</I> keywords allow specification of
274
the strings that will be printed as the first 3 lines of the output
275
file, assuming the <I>file</I> keyword was used. LAMMPS uses default
276
values for each of these, so they do not need to be specified.
278
<P>By default, these header lines are as follows:
280
<PRE># Spatial-averaged data for fix ID and group name
281
# Timestep Number-of-bins
282
# Bin r Count value1 value2 ...
284
<P>In the first line, ID and name are replaced with the fix-ID and group
285
name. The second line describes the two values that are printed at
286
the first of each section of output. In the third line the values are
287
replaced with the appropriate fields from the fix ave/spatial command.
288
The Coord2 and Coord3 entries in the third line only appear for 2d and
289
3d bins respectively. For 1d bins, the word Coord1 is replaced by
294
<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
296
<P>No information about this fix is written to <A HREF = "restart.html">binary restart
297
files</A>. None of the <A HREF = "fix_modify.html">fix_modify</A> options
298
are relevant to this fix.
300
<P>This fix computes a global array of values which can be accessed by
301
various <A HREF = "Section_howto.html#howto_15">output commands</A>. The values can
302
only be accessed on timesteps that are multiples of <I>Nfreq</I> since that
303
is when averaging is performed. The global array has # of rows =
304
Nbins and # of columns = 2+Nvalues. The first column contains the
305
radius at the center of the shell. For units <I>reduced</I>, this is in
306
reduced units, while for units <I>box</I> and <I>lattice</I> this is in box
307
units. The next column has the count of atoms in that bin, and the
308
remaining columns are the Nvalue quantities. When the array is
309
accessed with an I that exceeds the current number of bins, than a 0.0
310
is returned by the fix instead of an error. The array values
311
calculated by this fix are "intensive", since they are already
312
normalized by the count of atoms in each bin.
314
<P>No parameter of this fix can be used with the <I>start/stop</I> keywords of
315
the <A HREF = "run.html">run</A> command. This fix is not invoked during <A HREF = "minimize.html">energy
318
<P><B>Restrictions:</B>
320
<P>When the <I>ave</I> keyword is set to <I>running</I> or <I>window</I> then the number
321
of bins must remain the same during the simulation, so that the
322
appropriate averaging can be done. This will be the case if the
323
simulation box size doesn't change or if the <I>units</I> keyword is set to
326
<P>This style is part of the USER-MISC package. It is only enabled if
327
LAMMPS is build with that package. See the <A HREF = "Section_start.html#3">Making of
328
LAMMPS</A> section for more info.
330
<P><B>Related commands:</B>
332
<P><A HREF = "compute.html">compute</A>, <A HREF = "fix_ave_atom.html">fix ave/atom</A>, <A HREF = "fix_ave_histo.html">fix
333
ave/histo</A>, <A HREF = "fix_ave_time.html">fix ave/time</A>,
334
<A HREF = "variable.html">variable</A>, <A HREF = "fix_ave_correlate.html">fix ave/correlate</A>,
335
<A HREF = "fix_ave_spatial.html">fix ave/spatial</A>,
339
<P>The option defaults are norm = all, ave = one, units = lattice, no
340
file output, and title 1,2,3 = strings as described above.