← Back to branch summary

~ubuntu-branches/debian/sid/lammps/sid

« back to all changes in this revision

Viewing changes to doc/fix_ave_spatial_sphere.txt

  • Committer: Package Import Robot
  • Author(s): Anton Gladky
  • Date: 2015-04-29 23:44:49 UTC
  • mfrom: (5.1.3 experimental)
  • Revision ID: package-import@ubuntu.com-20150429234449-mbhy9utku6hp6oq8
Tags: 0~20150313.gitfa668e1-1
Upload into unstable.

Show diffs side-by-side

added added

removed removed

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