← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/fix_ave_spatial.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.txt
32
32
  v_name = per-atom vector calculated by an atom-style variable with name :pre
33
33
 
34
34
zero or more keyword/arg pairs may be appended :l
35
 
keyword = {norm} or {units} or {file} or {ave} or {overwrite} or {title1} or {title2} or {title3} :l
36
 
  {units} arg = {box} or {lattice} or {reduced}
 
35
keyword = {region} or {bound} or {discard} or {norm} or {ave} or {units} or {file} or {overwrite} or {title1} or {title2} or {title3} :l
 
36
  {region} arg = region-ID
 
37
  {bound} args = x/y/z lo hi
 
38
    x/y/z = {x} or {y} or {z} to bound bins in this dimension
 
39
    lo = {lower} or coordinate value (distance units)
 
40
    hi = {upper} or coordinate value (distance units)
 
41
  {discard} arg = {mixed} or {no} or {yes}
 
42
    mixed = discard atoms outside bins only if bin bounds are explicitly set
 
43
    no = always keep out-of-bounds atoms
 
44
    yes = always discard out-of-bounds atoms
37
45
  {norm} arg = {all} or {sample}
38
 
  {region} arg = region-ID
39
46
    region-ID = ID of region atoms must be in to contribute to spatial averaging
40
47
  {ave} args = {one} or {running} or {window M}
41
48
    one = output new average value every Nfreq steps
42
49
    running = output cumulative average of all previous Nfreq steps
43
50
    window M = output average of M most recent Nfreq steps
 
51
  {units} arg = {box} or {lattice} or {reduced}
44
52
  {file} arg = filename
45
53
    filename = file to write results to
46
54
  {overwrite} arg = none = overwrite output file with only latest output
57
65
fix 1 all ave/spatial 10000 1 10000 z lower 0.02 c_myCentro units reduced &
58
66
                      title1 "My output values"
59
67
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile
60
 
fix 1 flow ave/spatial 100 5 1000 z lower 1.0 y 0.0 2.5 density/mass ave running :pre
 
68
fix 1 flow ave/spatial 100 5 1000 z lower 1.0 y 0.0 2.5 density/mass ave running
 
69
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 :pre
 
70
 
 
71
[IMPORTANT NOTE:]
 
72
 
 
73
 The fix ave/spatial command has been replaced by the more flexible
 
74
"fix ave/chunk"_fix_ave_chunk.html and "compute
 
75
chunk/atom"_compute_chunk_atom.html commands.  The fix ave/spatial
 
76
command will be removed from LAMMPS sometime in the summer of 2015.
 
77
 
 
78
Any fix ave/spatial command can be replaced by the two new commands.
 
79
You simply need to split the fix ave/spatial arguments across the two
 
80
new commands.  For example, this command:
 
81
 
 
82
fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile :pre
 
83
 
 
84
could be replaced by:
 
85
 
 
86
compute cc1 flow chunk/atom bin/1d y 0.0 1.0 
 
87
fix 1 flow ave/chunk 100 10 1000 cc1 vx vz norm sample file vel.profile :pre
61
88
 
62
89
[Description:]
63
90
 
69
96
custom"_thermo_style.html, and can also be written to a file.
70
97
 
71
98
The group specified with the command means only atoms within the group
72
 
contribute to bin averages.  If the {region} keyword is used, the
73
 
atom must be in both the group and the specified geometric
 
99
contribute to bin averages.  If the {region} keyword is used, the atom
 
100
must be in both the specified group and the specified geometric
74
101
"region"_region.html in order to contribute to bin averages.
75
102
 
76
103
Each listed value can be an atom attribute (position, velocity, force
127
154
 
128
155
:line
129
156
 
130
 
Each per-atom property is also averaged over atoms in each bin.  Bins
131
 
can be 1d layers or slabs, 2d pencils, or 3d boxes.  This depends on
132
 
how many times (1, 2, or 3) the {dim}, {origin}, and {delta} settings
133
 
are specified in the fix ave/spatial command.  For 2d or 3d bins,
134
 
there is no restriction on specifying dim = x before dim = y, or dim =
135
 
y before dim = z.  Bins in a particular {dim} have a bin size in that
136
 
dimension given by {delta}.  Every Nfreq steps, when averaging is
 
157
Each per-atom property is also averaged over atoms in each bin.  The
 
158
way the averaging is one across the {Nrepeat} timesteps to produce
 
159
output on the {Nfreq} timesteps, and across multiple {Nfreq} outputs,
 
160
is determined by the {norm} and {av} keyword settings, as discussed
 
161
below.
 
162
 
 
163
Bins can be 1d layers or slabs, 2d pencils, or 3d boxes.  This depends
 
164
on how many times (1, 2, or 3) the {dim}, {origin}, and {delta}
 
165
settings are specified in the fix ave/spatial command.  For 2d or 3d
 
166
bins, there is no restriction on specifying dim = x before dim = y, or
 
167
dim = y before dim = z.  Bins in a particular {dim} have a bin size in
 
168
that dimension given by {delta}.  Every Nfreq steps, when averaging is
137
169
being performed and the per-atom property is calculated for the first
138
170
time, the number of bins and the bin sizes and boundaries are
139
171
computed.  Thus if the simulation box changes size during a
140
172
simulation, the number of bins and their boundaries may also change.
141
173
In each dimension, bins are defined relative to a specified {origin},
142
 
which may be the lower/upper edge of the simulation box (in {dim}) or
143
 
its center point, or a specified coordinate value.  Starting at the
144
 
origin, sufficient bins are created in both directions to completely
145
 
cover the box.  On subsequent timesteps every atom is mapped to one of
146
 
the bins.  Atoms beyond the lowermost/uppermost bin in a dimension are
147
 
counted in the first/last bin in that dimension.
 
174
which may be the lower/upper edge of the simulation box in that
 
175
dimension, or its center point, or a specified coordinate value.
 
176
Starting at the origin, sufficient bins are created in both directions
 
177
to completely span the bin extent in that dimension.  By default the
 
178
bin extent is the entire simulation box.
 
179
 
 
180
The {bound} keyword can be used one or more times to limit the extent
 
181
of bin coverage in specified dimensions, i.e. to only bin a portion of
 
182
the box.  If the {lo} setting is {lower} or the {hi} setting is
 
183
{upper}, the bin extent in that direction extends to the box boundary.
 
184
If a numeric value is used for {lo} and/or {hi}, then the bin extent
 
185
in the {lo} or {hi} direction extends only to that value, which is
 
186
assumed to be inside (or at least near) the simulation box boundaries,
 
187
though LAMMPS does not check for this.
 
188
 
 
189
On each sampling timestep, each atom is mapped to the bin it currently
 
190
belongs to, based on its current position.  Note that the group-ID and
 
191
region keyword can exclude specific atoms from this operation, as
 
192
discussed above.  Note that between reneighboring timesteps, atoms can
 
193
move outside the current simulation box.  If the box is periodic (in
 
194
that dimension) the atom is remapping into the periodic box for
 
195
purposes of binning.  If the box in not periodic, the atom may have
 
196
moved outside the bounds of any bin.
 
197
 
 
198
The {discard} keyword determines what is done with any atom which is
 
199
outside the bounds of any bin.  If {discard} is set to {yes}, the atom
 
200
will be ignored and not contribute to any bin averages.  If {discard}
 
201
is set to {no}, the atom will be counted as if it were in the first or
 
202
last bin in that dimension.  If (discard} is set to {mixed}, which is
 
203
the default, it will only be counted in the first or last bin if bins
 
204
extend to the box boundary in that dimension.  This is the case if the
 
205
{bound} keyword settings are {lower} and {upper}, which is the
 
206
default.  If the {bound} keyword settings are numeric values, then the
 
207
atom will be ignored if it is outside the bounds of any bin.  Note
 
208
that in this case, it is possible that the first or last bin extends
 
209
beyond the numeric {bounds} settings, depending on the specified
 
210
{origin}.  If this is the case, the atom is only ignored if it is
 
211
outside the first or last bin, not if it is simply outside the numeric
 
212
{bounds} setting.
148
213
 
149
214
For orthogonal simulation boxes, the bins are also layers, pencils, or
150
215
boxes aligned with the xyz coordinate axes.  For triclinic
202
267
:line
203
268
 
204
269
Additional optional keywords also affect the operation of this fix.
205
 
 
206
 
The {units} keyword determines the meaning of the distance units used
207
 
for the bin size {delta} and for {origin} if it is a coordinate
208
 
value.  For orthogonal simulation boxes, any of the 3 options may be
209
 
used.  For non-orthogonal (triclinic) simulation boxes, only the
210
 
{reduced} option may be used.
211
 
 
212
 
A {box} value selects standard distance units as defined by the
213
 
"units"_units.html command, e.g. Angstroms for units = real or metal.
214
 
A {lattice} value means the distance units are in lattice spacings.
215
 
The "lattice"_lattice.html command must have been previously used to
216
 
define the lattice spacing.  A {reduced} value means normalized
217
 
unitless values between 0 and 1, which represent the lower and upper
218
 
faces of the simulation box respectively.  Thus an {origin} value of
219
 
0.5 means the center of the box in any dimension.  A {delta} value of
220
 
0.1 means 10 bins span the box in that dimension.
221
 
 
222
 
Consider a non-orthogonal box, with bins that are 1d layers or slabs
223
 
in the x dimension.  No matter how the box is tilted, an {origin} of
224
 
0.0 means start layers at the lower "b" cross "c" plane of the
225
 
simulation box and an {origin} of 1.0 means to start layers at the
226
 
upper "b" cross "c" face of the box.  A {delta} value of 0.1 means
227
 
there will be 10 layers from 0.0 to 1.0, regardless of the current
228
 
size or shape of the simulation box.
 
270
The {region}, {bound}, and {discard} keywords were discussed above.
229
271
 
230
272
The {norm} keyword affects how averaging is done for the output
231
273
produced every {Nfreq} timesteps.  For an {all} setting, a bin
234
276
Total-quantity / Total-count.  In other words it is an average over
235
277
the entire {Nfreq} timescale.
236
278
 
237
 
As described above, if the {region} keyword is used, the atom must be
238
 
in both the group and the specified geometric "region"_region.html in
239
 
order to contribute to bin averages.
240
 
 
241
279
For a {sample} setting, the bin quantity is summed over atoms for only
242
280
a single sample, as is the count, and a "average sample value" is
243
281
computed, i.e. Sample-quantity / Sample-count.  The printed value for
270
308
values on steps 8000,9000,10000.  Outputs on early steps will average
271
309
over less than M values if they are not available.
272
310
 
 
311
The {units} keyword determines the meaning of the distance units used
 
312
for the bin size {delta} and for {origin} and {bounds} values if they
 
313
are coordinate value.  For orthogonal simulation boxes, any of the 3
 
314
options may be used.  For non-orthogonal (triclinic) simulation boxes,
 
315
only the {reduced} option may be used.
 
316
 
 
317
A {box} value selects standard distance units as defined by the
 
318
"units"_units.html command, e.g. Angstroms for units = real or metal.
 
319
A {lattice} value means the distance units are in lattice spacings.
 
320
The "lattice"_lattice.html command must have been previously used to
 
321
define the lattice spacing.  A {reduced} value means normalized
 
322
unitless values between 0 and 1, which represent the lower and upper
 
323
faces of the simulation box respectively.  Thus an {origin} value of
 
324
0.5 means the center of the box in any dimension.  A {delta} value of
 
325
0.1 means 10 bins span the box in that dimension.
 
326
 
 
327
Consider a non-orthogonal box, with bins that are 1d layers or slabs
 
328
in the x dimension.  No matter how the box is tilted, an {origin} of
 
329
0.0 means start layers at the lower "b" cross "c" plane of the
 
330
simulation box and an {origin} of 1.0 means to start layers at the
 
331
upper "b" cross "c" face of the box.  A {delta} value of 0.1 means
 
332
there will be 10 layers from 0.0 to 1.0, regardless of the current
 
333
size or shape of the simulation box.
 
334
 
273
335
The {file} keyword allows a filename to be specified.  Every {Nfreq}
274
336
timesteps, a section of bin info will be written to a text file in the
275
337
following format.  A line with the timestep and number of bin is
347
409
"compute"_compute.html, "fix ave/atom"_fix_ave_atom.html, "fix
348
410
ave/histo"_fix_ave_histo.html, "fix ave/time"_fix_ave_time.html,
349
411
"variable"_variable.html, "fix ave/correlate"_fix_ave_correlate.html,
 
412
"fix ave/spatial/sphere"_fix_ave_spatial_sphere.html
350
413
 
351
414
[Default:]
352
415
 
353
 
The option defaults are units = lattice, norm = all, no file output,
354
 
and ave = one, title 1,2,3 = strings as described above.
 
416
The option defaults are bound = lower and upper in all dimensions,
 
417
discard = mixed, norm = all, ave = one, units = lattice, no file
 
418
output, and title 1,2,3 = strings as described above.