← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/compute_chunk_atom.html

  • 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/compute_chunk_atom.html
 
1
<HTML>
 
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> 
 
3
</CENTER>
 
4
 
 
5
 
 
6
 
 
7
 
 
8
 
 
9
 
 
10
<HR>
 
11
 
 
12
<H3>compute chunk/atom command 
 
13
</H3>
 
14
<P><B>Syntax:</B>
 
15
</P>
 
16
<PRE>compute ID group-ID chunk/atom style args keyword values ... 
 
17
</PRE>
 
18
<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command 
 
19
 
 
20
<LI>chunk/atom = style name of this compute command 
 
21
 
 
22
<PRE>style = <I>bin/1d</I> or <I>bin/2d</I> or <I>bin/3d</I> or <I>type</I> or <I>molecule</I> or <I>compute/fix/variable</I>
 
23
  <I>bin/1d</I> args = dim origin delta
 
24
    dim = <I>x</I> or <I>y</I> or <I>z</I>
 
25
    origin = <I>lower</I> or <I>center</I> or <I>upper</I> or coordinate value (distance units)
 
26
    delta = thickness of spatial bins in dim (distance units)
 
27
  <I>bin/2d</I> args = dim origin delta dim origin delta
 
28
    dim = <I>x</I> or <I>y</I> or <I>z</I>
 
29
    origin = <I>lower</I> or <I>center</I> or <I>upper</I> or coordinate value (distance units)
 
30
    delta = thickness of spatial bins in dim (distance units)
 
31
  <I>bin/3d</I> args = dim origin delta dim origin delta dim origin delta
 
32
    dim = <I>x</I> or <I>y</I> or <I>z</I>
 
33
    origin = <I>lower</I> or <I>center</I> or <I>upper</I> or coordinate value (distance units)
 
34
    delta = thickness of spatial bins in dim (distance units)
 
35
  <I>type</I> args = none
 
36
  <I>molecule</I> args = none
 
37
  <I>compute/fix/variable</I> = c_ID, c_ID[I], f_ID, f_ID[I], v_name with no args
 
38
    c_ID = per-atom vector calculated by a compute with ID
 
39
    c_ID[I] = Ith column of per-atom array calculated by a compute with ID
 
40
    f_ID = per-atom vector calculated by a fix with ID
 
41
    f_ID[I] = Ith column of per-atom array calculated by a fix with ID
 
42
    v_name = per-atom vector calculated by an atom-style variable with name 
 
43
</PRE>
 
44
<LI>zero or more keyword/values pairs may be appended 
 
45
 
 
46
<LI>keyword = <I>region</I> or <I>nchunk</I> or <I>static</I> or <I>compress</I> or <I>bound</I> or <I>discard</I> or <I>units</I> 
 
47
 
 
48
<PRE>  <I>region</I> value = region-ID
 
49
    region-ID = ID of region atoms must be in to be part of a chunk
 
50
  <I>nchunk</I> value = <I>once</I> or <I>every</I>
 
51
    once = only compute the number of chunks once
 
52
    every = re-compute the number of chunks whenever invoked
 
53
  <I>limit</I> values = 0 or Nc max or Nc exact
 
54
    0 = no limit on the number of chunks
 
55
    Nc max = limit number of chunks to be <= Nc
 
56
    Nc exact = set number of chunks to exactly Nc
 
57
  <I>ids</I> value = <I>once</I> or <I>nfreq</I> or <I>every</I>
 
58
    once = assign chunk IDs to atoms only once, they persist thereafter
 
59
    nfreq = assign chunk IDs to atoms only once every Nfreq steps (if invoked by <A HREF = "fix_ave_chunk.html">fix ave/chunk</A> which sets Nfreq)
 
60
    every = assign chunk IDs to atoms whenever invoked
 
61
  <I>compress</I> value = <I>yes</I> or <I>no</I>
 
62
    yes = compress chunk IDs to eliminate IDs with no atoms
 
63
    no = do not compress chunk IDs even if some IDs have no atoms
 
64
  <I>discard</I> value = <I>yes</I> or <I>no</I> or <I>mixed</I>
 
65
    yes = discard atoms with out-of-range chunk IDs by assigning a chunk ID = 0
 
66
    no = keep atoms with out-of-range chunk IDs by assigning a valid chunk ID
 
67
    mixed = keep or discard such atoms according to spatial binning rule
 
68
  <I>bound</I> values = x/y/z lo hi
 
69
    x/y/z = <I>x</I> or <I>y</I> or <I>z</I> to bound sptial bins in this dimension
 
70
    lo = <I>lower</I> or coordinate value (distance units)
 
71
    hi = <I>upper</I> or coordinate value (distance units)
 
72
  <I>units</I> value = <I>box</I> or <I>lattice</I> or <I>reduced</I> 
 
73
</PRE>
 
74
 
 
75
</UL>
 
76
<P><B>Examples:</B>
 
77
</P>
 
78
<PRE>compute 1 all chunk/atom type
 
79
compute 1 all chunk/atom bin/1d z lower 0.02 units reduced
 
80
compute 1 all chunk/atom bin/2d z lower 1.0 y 0.0 2.5
 
81
compute 1 all chunk/atom molecule region sphere nchunk once ids once compress yes 
 
82
</PRE>
 
83
<P><B>Description:</B>
 
84
</P>
 
85
<P>Define a computation that calculates an integer chunk ID from 1 to
 
86
Nchunk for each atom in the group.  Values of chunk IDs are determined
 
87
by the <I>style</I> of chunk, which can be based on atom type or molecule
 
88
ID or spatial binning or a per-atom property or value calculated by
 
89
another <A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or <A HREF = "variable.html">atom-style
 
90
variable</A>.  Per-atom chunk IDs can be used by other
 
91
computes with "chunk" in their style name, such as <A HREF = "compute_com_chunk.html">compute
 
92
com/chunk</A> or <A HREF = "compute_msd_chunk.html">compute
 
93
msd/chunk</A>.  Or they can be used by the <A HREF = "fix_ave_chunk.html">fix
 
94
ave/chunk</A> command to sum and time average a
 
95
variety of per-atom properties over the atoms in each chunk.  Or they
 
96
can simply be accessed by any command that uses per-atom values from a
 
97
compute as input, as discussed in <A HREF = "Section_howto.html#howto_15">Section_howto
 
98
15</A>.
 
99
</P>
 
100
<P>See <A HREF = "Section_howto.html#howto_23">Section_howto 23</A> for an overview of
 
101
how this compute can be used with a variety of other commands to
 
102
tabulate properties of a simulation.  The howto section gives several
 
103
examples of input script commands that can be used to calculate
 
104
interesting properties.
 
105
</P>
 
106
<P>Conceptually it is important to realize that this compute does two
 
107
simple things.  First, it sets the value of <I>Nchunk</I> = the number of
 
108
chunks, which can be a constant value or change over time.  Second, it
 
109
assigns each atom to a chunk via a chunk ID.  Chunk IDs range from 1
 
110
to <I>Nchunk</I> inclusive; some chunks may have no atoms assigned to them.
 
111
Atoms that do not belong to any chunk are assigned a value of 0.  Note
 
112
that the two operations are not always performed together.  For
 
113
example, spatial bins can be setup once (which sets <I>Nchunk</I>), and
 
114
atoms assigned to those bins many times thereafter (setting their
 
115
chunk IDs).
 
116
</P>
 
117
<P>All other commands in LAMMPS that use chunk IDs assume there are
 
118
<I>Nchunk</I> number of chunks, and that every atom is assigned to one of
 
119
those chunks, or not assigned to any chunk.
 
120
</P>
 
121
<P>There are many options for specifying for how and when <I>Nchunk</I> is
 
122
calculated, and how and when chunk IDs are assigned to atoms.  The
 
123
details depend on the chunk <I>style</I> and its <I>args</I>, as well as
 
124
optional keyword settings.  They can also depend on whether a <A HREF = "fix_ave_chunk.html">fix
 
125
ave/chunk</A> command is using this compute, since
 
126
that command requires <I>Nchunk</I> to remain static across windows of
 
127
timesteps it specifies, while it accumulates per-chunk averages.
 
128
</P>
 
129
<P>The details are described below.
 
130
</P>
 
131
<HR>
 
132
 
 
133
<HR>
 
134
 
 
135
<P>The different chunk styles operate as follows.  For each style, how it
 
136
calculates <I>Nchunk</I> and assigns chunk IDs to atoms is explained.  Note
 
137
that using the optional keywords can change both of those actions, as
 
138
described further below where the keywords are discussed.
 
139
</P>
 
140
<HR>
 
141
 
 
142
<P>The <I>binning</I> styles perform a spatial binning of atoms, and assign an
 
143
atom the chunk ID corresponding to the bin number it is in.  <I>Nchunk</I>
 
144
is set to the number of bins, which can change if the simulation box
 
145
size changes.
 
146
</P>
 
147
<P>The <I>bin/1d</I>, <I>bin/2d</I>, and <I>bin/3d</I> styles define bins as 1d layers
 
148
(slabs), 2d pencils, or 3d boxes.  The <I>dim</I>, <I>origin</I>, and <I>delta</I>
 
149
settings are specified 1, 2, or 3 times.  For 2d or 3d bins, there is
 
150
no restriction on specifying dim = x before dim = y or z, or dim = y
 
151
before dim = z.  Bins in a particular <I>dim</I> have a bin size in that
 
152
dimension given by <I>delta</I>.  In each dimension, bins are defined
 
153
relative to a specified <I>origin</I>, which may be the lower/upper edge of
 
154
the simulation box (in that dimension), or its center point, or a
 
155
specified coordinate value.  Starting at the origin, sufficient bins
 
156
are created in both directions to completely span the simulation box
 
157
or the bounds specified by the optional <I>bounds</I> keyword.
 
158
</P>
 
159
<P>For orthogonal simulation boxes, the bins are layers, pencils, or
 
160
boxes aligned with the xyz coordinate axes.  For triclinic
 
161
(non-orthogonal) simulation boxes, the bin faces are parallel to the
 
162
tilted faces of the simulation box.  See <A HREF = "Section_howto.html#howto_12">this
 
163
section</A> of the manual for a discussion of
 
164
the geometry of triclinic boxes in LAMMPS.  As described there, a
 
165
tilted simulation box has edge vectors a,b,c.  In that nomenclature,
 
166
bins in the x dimension have faces with normals in the "b" cross "c"
 
167
direction.  Bins in y have faces normal to the "a" cross "c"
 
168
direction.  And bins in z have faces normal to the "a" cross "b"
 
169
direction.  Note that in order to define the size and position of
 
170
these bins in an unambiguous fashion, the <I>units</I> option must be set
 
171
to <I>reduced</I> when using a triclinic simulation box, as noted below.
 
172
</P>
 
173
<P>The meaning of <I>origin</I> and <I>delta</I> for triclinic boxes is as follows.
 
174
Consider a triclinic box with bins that are 1d layers or slabs in the
 
175
x dimension.  No matter how the box is tilted, an <I>origin</I> of 0.0
 
176
means start layers at the lower "b" cross "c" plane of the simulation
 
177
box and an <I>origin</I> of 1.0 means to start layers at the upper "b"
 
178
cross "c" face of the box.  A <I>delta</I> value of 0.1 in <I>reduced</I> units
 
179
means there will be 10 layers from 0.0 to 1.0, regardless of the
 
180
current size or shape of the simulation box.
 
181
</P>
 
182
<P>The created bins (and hence the chunk IDs) are numbered consecutively
 
183
from 1 to the number of bins = <I>Nchunk</I>.  For 2d and 3d bins, the
 
184
numbering varies most rapidly in the first dimension (which could be
 
185
x, y, or z), next rapidly in the 2nd dimension, and most slowly in the
 
186
3rd dimension.
 
187
</P>
 
188
<P>Each time this compute is invoked, each atom is mapped to a bin based
 
189
on its current position.  Note that between reneighboring timesteps,
 
190
atoms can move outside the current simulation box.  If the box is
 
191
periodic (in that dimension) the atom is remapping into the periodic
 
192
box for purposes of binning.  If the box in not periodic, the atom may
 
193
have moved outside the bounds of all bins.  If an atom is not inside
 
194
any bin, the <I>discard</I> keyword is used to determine how a chunk ID is
 
195
assigned to the atom.
 
196
</P>
 
197
<HR>
 
198
 
 
199
<P>The <I>type</I> style uses the atom type as the chunk ID.  <I>Nchunk</I> is set
 
200
to the number of atom types defined for the simulation, e.g. via the
 
201
<A HREF = "create_box.html">create_box</A> or <A HREF = "read_data.html">read_data</A> commands.
 
202
</P>
 
203
<HR>
 
204
 
 
205
<P>The <I>molecule</I> style uses the molecule ID of each atom as its chunk
 
206
ID.  <I>Nchunk</I> is set to the largest chunk ID.  Note that this excludes
 
207
molecule IDs for atoms which are not in the specified group or
 
208
optional region.
 
209
</P>
 
210
<P>There is no requirement that all atoms in a particular molecule are
 
211
assigned the same chunk ID (zero or non-zero), though you probably
 
212
want that to be the case, if you wish to compute a per-molecule
 
213
property.  LAMMPS will issue a warning if that is not the case, but
 
214
only the first time that <I>Nchunk</I> is calculated.
 
215
</P>
 
216
<P>Note that atoms with a molecule ID = 0, which may be non-molecular
 
217
solvent atoms, have an out-of-range chunk ID.  These atoms are
 
218
discarded (not assigned to any chunk) or assigned to <I>Nchunk</I>,
 
219
depending on the value of the <I>discard</I> keyword.
 
220
</P>
 
221
<HR>
 
222
 
 
223
<P>The <I>compute/fix/variable</I> styles set the chunk ID of each atom based
 
224
on a quantity calculated and stored by a compute, fix, or variable.
 
225
In each case, it must be a per-atom quantity.  In each case the
 
226
referenced floating point values are converted to an integer chunk ID
 
227
as follows.  The floating point value is truncated (rounded down) to
 
228
an integer value.  If the integer value is <= 0, then a chunk ID of 0
 
229
is assigned to the atom.  If the integer value is > 0, it becomes the
 
230
chunk ID to the atom.  <I>Nchunk</I> is set to the largest chunk ID.  Note
 
231
that this excludes atoms which are not in the specified group or
 
232
optional region.
 
233
</P>
 
234
<P>If the style begins with "c_", a compute ID must follow which has been
 
235
previously defined in the input script.  If no bracketed integer is
 
236
appended, the per-atom vector calculated by the compute is used.  If a
 
237
bracketed integer is appended, the Ith column of the per-atom array
 
238
calculated by the compute is used.  Users can also write code for
 
239
their own compute styles and <A HREF = "Section_modify.html">add them to LAMMPS</A>.
 
240
</P>
 
241
<P>If the style begins with "f_", a fix ID must follow which has been
 
242
previously defined in the input script.  If no bracketed integer is
 
243
appended, the per-atom vector calculated by the fix is used.  If a
 
244
bracketed integer is appended, the Ith column of the per-atom array
 
245
calculated by the fix is used.  Note that some fixes only produce
 
246
their values on certain timesteps, which must be compatible with the
 
247
timestep on which this compute accesses the fix, else an error
 
248
results.  Users can also write code for their own fix styles and <A HREF = "Section_modify.html">add
 
249
them to LAMMPS</A>.
 
250
</P>
 
251
<P>If a value begins with "v_", a variable name for an <I>atom</I> or
 
252
<I>atomfile</I> style <A HREF = "variable.html">variable</A> must follow which has been
 
253
previously defined in the input script.  Variables of style <I>atom</I> can
 
254
reference thermodynamic keywords and various per-atom attributes, or
 
255
invoke other computes, fixes, or variables when they are evaluated, so
 
256
this is a very general means of generating per-atom quantities to
 
257
treat as a chunk ID.
 
258
</P>
 
259
<HR>
 
260
 
 
261
<HR>
 
262
 
 
263
<P>Normally, <I>Nchunk</I> = the number of chunks, is re-calculated every time
 
264
this fix is invoked, though the value may or may not change.  As
 
265
explained below, the <I>nchunk</I> keyword can be set to <I>once</I> which means
 
266
<I>Nchunk</I> will never change.
 
267
</P>
 
268
<P>If a <A HREF = "fix_ave_chunk.html">fix ave/chunk</A> command uses this compute, it
 
269
can also turn off the re-calculation of <I>Nchunk</I> for one or more
 
270
windows of timesteps.  The extent of the windows, during which Nchunk
 
271
is held constant, are determined by the <I>Nevery</I>, <I>Nrepeat</I>, <I>Nfreq</I>
 
272
values and the <I>ave</I> keyword setting that are used by the <A HREF = "fix_ave_chunk.html">fix
 
273
ave/chunk</A> command.
 
274
</P>
 
275
<P>Specifically, if <I>ave</I> = <I>one</I>, then for each span of <I>Nfreq</I>
 
276
timesteps, <I>Nchunk</I> is held constant between the first timestep when
 
277
averaging is done (within the Nfreq-length window), and the last
 
278
timestep when averaging is done (multiple of Nfreq).  If <I>ave</I> =
 
279
<I>running</I> or <I>window</I>, then <I>Nchunk</I> is held constant forever,
 
280
starting on the first timestep when the <A HREF = "fix_ave_chunk.html">fix
 
281
ave/chunk</A> command invokes this compute.
 
282
</P>
 
283
<P>Note that multiple <A HREF = "fix_ave_chunk.html">fix ave/chunk</A> commands can use
 
284
the same compute chunk/atom compute.  However, the time windows they
 
285
induce for holding <I>Nchunk</I> constant must be identical, else an error
 
286
will be generated.
 
287
</P>
 
288
<HR>
 
289
 
 
290
<HR>
 
291
 
 
292
<P>The various optional keywords operate as follows.  Note that some of
 
293
them function differently or are ignored by different chunk styles.
 
294
Some of them also have different default values, depending on
 
295
the chunk style, as listed below.
 
296
</P>
 
297
<P>The <I>region</I> keyword applies to all chunk styles.  If used, an atom
 
298
must be in both the specified group and the specified geometric
 
299
<A HREF = "region.html">region</A> to be assigned to a chunk.
 
300
</P>
 
301
<HR>
 
302
 
 
303
<P>The <I>nchunk</I> keyword applies to all chunk styles.  It specifies how
 
304
often <I>Nchunk</I> is recalculated, which in turn can affect the chunk IDs
 
305
assigned to individual atoms.
 
306
</P>
 
307
<P>If <I>nchunk</I> is set to <I>once</I>, then <I>Nchunk</I> is only calculated once,
 
308
the first time this compute is invoked.  If <I>nchunk</I> is set to
 
309
<I>every</I>, then <I>Nchunk</I> is re-calculated every time the compute is
 
310
invoked.  Note that, as described above, the use of this compute
 
311
by the <A HREF = "fix_ave_chunk.html">fix ave/chunk</A> command can override
 
312
the <I>every</I> setting.
 
313
</P>
 
314
<P>The default values for <I>nchunk</I> are listed below and depend on the
 
315
chunk style and other system and keyword settings.  They attempt to
 
316
represent typical use cases for the various chunk styles.  The
 
317
<I>nchunk</I> value can always be set explicitly if desired.
 
318
</P>
 
319
<HR>
 
320
 
 
321
<P>The <I>limit</I> keyword can be used to limit the calculated value of
 
322
<I>Nchunk</I> = the number of chunks.  The limit is applied each time
 
323
<I>Nchunk</I> is calculated, which also limits the chunk IDs assigned to
 
324
any atom.  The <I>limit</I> keyword is used by all chunk styles except the
 
325
<I>binning</I> styles, which ignore it.  This is because the number of bins
 
326
can be tailored using the <I>bound</I> keyword (described below) which
 
327
effectively limits the size of <I>Nchunk</I>.
 
328
</P>
 
329
<P>If <I>limit</I> is set to <I>Nc</I> = 0, then no limit is imposed on <I>Nchunk</I>,
 
330
though the <I>compress</I> keyword can still be used to reduce <I>Nchunk</I>, as
 
331
described below.
 
332
</P>
 
333
<P>If <I>Nc</I> > 0, then the effect of the <I>limit</I> keyword depends on whether
 
334
the <I>compress</I> keyword is also used with a setting of <I>yes</I>, and
 
335
whether the <I>compress</I> keyword is specified before the <I>limit</I> keyword
 
336
or after.
 
337
</P>
 
338
<P>In all cases, <I>Nchunk</I> is first calculated in the usual way for each
 
339
chunk style, as described above.
 
340
</P>
 
341
<P>First, here is what occurs if <I>compress yes</I> is not set.  If <I>limit</I>
 
342
is set to <I>Nc max</I>, then <I>Nchunk</I> is reset to the smaller of <I>Nchunk</I>
 
343
and <I>Nc</I>.  If <I>limit</I> is set to <I>Nc exact</I>, then <I>Nchunk</I> is reset to
 
344
<I>Nc</I>, whether the original <I>Nchunk</I> was larger or smaller than <I>Nc</I>.
 
345
If <I>Nchunk</I> shrank due to the <I>limit</I> setting, then atom chunk IDs >
 
346
<I>Nchunk</I> will be reset to 0 or <I>Nchunk</I>, depending on the setting of
 
347
the <I>discard</I> keyword.  If <I>Nchunk</I> grew, there will simply be some
 
348
chunks with no atoms assigned to them.
 
349
</P>
 
350
<P>If <I>compress yes</I> is set, and the <I>compress</I> keyword comes before the
 
351
<I>limit</I> keyword, the compression operation is performed first, as
 
352
described below, which resets <I>Nchunk</I>.  The <I>limit</I> keyword is then
 
353
applied to the new <I>Nchunk</I> value, exactly as described in the
 
354
preceeding paragraph.  Note that in this case, all atoms will end up
 
355
with chunk IDs <= <I>Nc</I>, but their original values (e.g. molecule ID or
 
356
compute/fix/variable value) may have been > <I>Nc</I>, because of the
 
357
compression operation.
 
358
</P>
 
359
<P>If <I>compress yes</I> is set, and the <I>compress</I> keyword comes after the
 
360
<I>limit</I> keyword, then the <I>limit</I> value of <I>Nc</I> is applied first to
 
361
the uncompressed value of <I>Nchunk</I>, but only if <I>Nc</I> < <I>Nchunk</I>
 
362
(whether <I>Nc max</I> or <I>Nc exact</I> is used).  This effectively means all
 
363
atoms with chunk IDs > <I>Nc</I> have their chunk IDs reset to 0 or <I>Nc</I>,
 
364
depending on the setting of the <I>discard</I> keyword.  The compression
 
365
operation is then performed, which may shrink <I>Nchunk</I> further.  If
 
366
the new <I>Nchunk</I> < <I>Nc</I> and <I>limit</I> = <I>Nc exact</I> is specified, then
 
367
<I>Nchunk</I> is reset to <I>Nc</I>, which results in extra chunks with no atoms
 
368
assigned to them.  Note that in this case, all atoms will end up with
 
369
chunk IDs <= <I>Nc</I>, and their original values (e.g. molecule ID or
 
370
compute/fix/variable value) will also have been <= <I>Nc</I>.
 
371
</P>
 
372
<HR>
 
373
 
 
374
<P>The <I>ids</I> keyword applies to all chunk styles.  If the setting is
 
375
<I>once</I> then the chunk IDs assigned to atoms the first time this
 
376
compute is invoked will be permanent, and never be re-computed.
 
377
</P>
 
378
<P>If the setting is <I>nfreq</I> and if a <A HREF = "fix_ave_chunk.html">fix ave/chunk</A>
 
379
command is using this compute, then in each of the <I>Nchunk</I> = constant
 
380
time windows (discussed above), the chunk ID's assigned to atoms on
 
381
the first step of the time window will persist until the end of the
 
382
time window.
 
383
</P>
 
384
<P>If the setting is <I>every</I>, which is the default, then chunk IDs are
 
385
re-calculated on any timestep this compute is invoked.
 
386
</P>
 
387
<P>IMPORTANT NOTE: If you want the persistent chunk-IDs calculated by
 
388
this compute to be continuous when running from a <A HREF = "read_restart.html">restart
 
389
file</A>, then you should use the same ID for this
 
390
compute, as in the original run.  This is so that the fix this compute
 
391
creates to store per-atom quantities will also have the same ID, and
 
392
thus be initialized correctly with chunk IDs from the restart file.
 
393
</P>
 
394
<HR>
 
395
 
 
396
<P>The <I>compress</I> keyword applies to all chunk styles and affects how
 
397
<I>Nchunk</I> is calculated, which in turn affects the chunk IDs assigned
 
398
to each atom.  It is useful for converting a "sparse" set of chunk IDs
 
399
(with many IDs that have no atoms assigned to them), into a "dense"
 
400
set of IDs, where every chunk has one or more atoms assigned to it.
 
401
</P>
 
402
<P>Two possible use cases are as follows.  If a large simulation box is
 
403
mostly empty space, then the <I>binning</I> style may produce many bins
 
404
with no atoms.  If <I>compress</I> is set to <I>yes</I>, only bins with atoms
 
405
will be contribute to <I>Nchunk</I>.  Likewise, the <I>molecule</I> or
 
406
<I>compute/fix/variable</I> styles may produce large <I>Nchunk</I> values.  For
 
407
example, the <A HREF = "compute_cluster_atom.html">compute cluster/atom</A> command
 
408
assigns every atom an atom ID for one of the atoms it is clustered
 
409
with.  For a million-atom system with 5 clusters, there would only be
 
410
5 unique chunk IDs, but the largest chunk ID might be 1 million,
 
411
resulting in <I>Nchunk</I> = 1 million.  If <I>compress</I> is set to <I>yes</I>,
 
412
<I>Nchunk</I> will be reset to 5.
 
413
</P>
 
414
<P>If <I>compress</I> is set to <I>no</I>, which is the default, no compression is
 
415
done.  If it is set to <I>yes</I>, all chunk IDs with no atoms are removed
 
416
from the list of chunk IDs, and the list is sorted.  The remaining
 
417
chunk IDs are renumbered from 1 to <I>Nchunk</I> where <I>Nchunk</I> is the new
 
418
length of the list.  The chunk IDs assigned to each atom reflect
 
419
the new renumbering from 1 to <I>Nchunk</I>.
 
420
</P>
 
421
<P>The original chunk IDs (before renumbering) can be accessed by the
 
422
<A HREF = "compute_property_chunk.html">compute property/chunk</A> command and its
 
423
<I>id</I> keyword, or by the <A HREF = "fix_ave_chunk.html">fix ave/chunk</A> command
 
424
which outputs the original IDs as one of the columns in its global
 
425
output array.  For example, using the "compute cluster/atom" command
 
426
discussed above, the original 5 unique chunk IDs might be atom IDs
 
427
(27,4982,58374,857838,1000000).  After compresion, these will be
 
428
renumbered to (1,2,3,4,5).  The original values (27,...,1000000) can
 
429
be output to a file by the <A HREF = "fix_ave_chunk.html">fix ave/chunk</A> command,
 
430
or by using the <A HREF = "fix_ave_time.html">fix ave/time</A> command in
 
431
conjunction with the <A HREF = "compute_property_chunk.html">compute
 
432
property/chunk</A> command.
 
433
</P>
 
434
<P>IMPORTANT NOTE: The compression operation requires global
 
435
communication across all processors to share their chunk ID values.
 
436
It can require large memory on every processor to store them, even
 
437
after they are compressed, if there are are a large number of unique
 
438
chunk IDs with atoms assigned to them.  It uses a STL map to find
 
439
unique chunk IDs and store them in sorted order.  Each time an atom is
 
440
assigned a compressed chunk ID, it must access the STL map.  All of
 
441
this means that compression can be expensive, both in memory and CPU
 
442
time.  The use of the <I>limit</I> keyword in conjunction with the
 
443
<I>compress</I> keyword can affect these costs, depending on which keyword
 
444
is used first.  So use this option with care.
 
445
</P>
 
446
<HR>
 
447
 
 
448
<P>The <I>discard</I> keyword applies to all chunk styles.  It affects what
 
449
chunk IDs are assigned to atoms that do not match one of the valid
 
450
chunk IDs from 1 to <I>Nchunk</I>.  Note that it does not apply to atoms
 
451
that are not in the specified group or optionally specified region.
 
452
Those atoms are always assigned a chunk ID = 0.
 
453
</P>
 
454
<P>If the calculated chunk ID for an atom is not within the range 1 to
 
455
<I>Nchunk</I> then it is a "discard" atom.  Note that <I>Nchunk</I> may have
 
456
been shrunk by the <I>limit</I> keyword.  Or the <I>compress</I> keyword may
 
457
have eliminated chunk IDs that were valid before the compression took
 
458
place, and are now not in the compressed list.  Also note that for the
 
459
<I>molecule</I> chunk style, if new molecules are added to the system,
 
460
their chunk IDs may exceed a previously calculated <I>Nchunk</I>.
 
461
Likewise, evaluation of a compute/fix/variable on a later timestep may
 
462
return chunk IDs that are invalid for the previously calculated
 
463
<I>Nchunk</I>.
 
464
</P>
 
465
<P>All the chunk styles except the <I>binning</I> styles, must use <I>discard</I>
 
466
set to either <I>yes</I> or <I>no</I>.  If <I>discard</I> is set to <I>yes</I>, which is
 
467
the default, then every "discard" atom has its chunk ID set to 0.  If
 
468
<I>discard</I> is set to <I>no</I>, every "discard" atom has its chunk ID set to
 
469
<I>Nchunk</I>.  I.e. it becomes part of the last chunk.
 
470
</P>
 
471
<P>The <I>binning</I> styles use the <I>discard</I> keyword to decide whether to
 
472
discard atoms outside the spatial domain covered by bins, or to assign
 
473
them to the bin they are nearest to.  Details are as follows.
 
474
</P>
 
475
<P>If <I>discard</I> is set to <I>yes</I>, an out-of-domain atom will have its
 
476
chunk ID set to 0.  If <I>discard</I> is set to <I>no</I>, the atom will have
 
477
its chunk ID set to the first or last bin in that dimension.  If
 
478
(discard</I> is set to <I>mixed</I>, which is the default, it will only have
 
479
its chunk ID set to the first or last bin if bins extend to the
 
480
simulation box boundary in that dimension.  This is the case if the
 
481
<I>bound</I> keyword settings are <I>lower</I> and <I>upper</I>, which is the
 
482
default.  If the <I>bound</I> keyword settings are numeric values, then the
 
483
atom will have its chunk ID set to 0 if it is outside the bounds of
 
484
any bin.  Note that in this case, it is possible that the first or
 
485
last bin extends beyond the numeric <I>bounds</I> settings, depending on
 
486
the specified <I>origin</I>.  If this is the case, the chunk ID of the atom
 
487
is only set to 0 if it is outside the first or last bin, not if it is
 
488
simply outside the numeric <I>bounds</I> setting.
 
489
</P>
 
490
<HR>
 
491
 
 
492
<P>The <I>bound</I> keyword only applies to the <I>binning</I> styles; otherwise it
 
493
is ignored.  It can be used one or more times to limit the extent of
 
494
bin coverage in a specified dimension, i.e. to only bin a portion of
 
495
the box.  If the <I>lo</I> setting is <I>lower</I> or the <I>hi</I> setting is
 
496
<I>upper</I>, the bin extent in that direction extends to the box boundary.
 
497
If a numeric value is used for <I>lo</I> and/or <I>hi</I>, then the bin extent
 
498
in the <I>lo</I> or <I>hi</I> direction extends only to that value, which is
 
499
assumed to be inside (or at least near) the simulation box boundaries,
 
500
though LAMMPS does not check for this.  Note that using the <I>bound</I>
 
501
keyword typically reduces the total number of bins and thus the number
 
502
of chunks <I>Nchunk</I>.
 
503
</P>
 
504
<P>The <I>units</I> keyword only applies to the <I>binning</I> styles; otherwise it
 
505
is ignored.  It determines the meaning of the distance units used for
 
506
the bin sizes <I>delta</I> and for <I>origin</I> and <I>bounds</I> values if they are
 
507
coordinate values.  For orthogonal simulation boxes, any of the 3
 
508
options may be used.  For non-orthogonal (triclinic) simulation boxes,
 
509
only the <I>reduced</I> option may be used.
 
510
</P>
 
511
<P>A <I>box</I> value selects standard distance units as defined by the
 
512
<A HREF = "units.html">units</A> command, e.g. Angstroms for units = real or metal.
 
513
A <I>lattice</I> value means the distance units are in lattice spacings.
 
514
The <A HREF = "lattice.html">lattice</A> command must have been previously used to
 
515
define the lattice spacing.  A <I>reduced</I> value means normalized
 
516
unitless values between 0 and 1, which represent the lower and upper
 
517
faces of the simulation box respectively.  Thus an <I>origin</I> value of
 
518
0.5 means the center of the box in any dimension.  A <I>delta</I> value of
 
519
0.1 means 10 bins span the box in that dimension.
 
520
</P>
 
521
<HR>
 
522
 
 
523
<HR>
 
524
 
 
525
<P><B>Output info:</B>
 
526
</P>
 
527
<P>This compute calculates a per-atom vector, which can be accessed by
 
528
any command that uses per-atom values from a compute as input.  See
 
529
<A HREF = "Section_howto.html#howto_15">Section_howto 15</A> for an overview of
 
530
LAMMPS output options.
 
531
</P>
 
532
<P>The per-atom vector values are unitless chunk IDs, ranging from 1 to
 
533
<I>Nchunk</I> (inclusive) for atoms assigned to chunks, and 0 for atoms not
 
534
belonging to a chunk.
 
535
</P>
 
536
<P><B>Restrictions:</B>
 
537
</P>
 
538
<P>Even if the <I>nchunk</I> keyword is set to <I>once</I>, the chunk IDs assigned
 
539
to each atom are not stored in a restart files.  This means you cannot
 
540
expect those assignments to persist in a restarted simulation.
 
541
Instead you must re-specify this command and assign atoms to chunks when
 
542
the restarted simulation begins.
 
543
</P>
 
544
<P><B>Related commands:</B>
 
545
</P>
 
546
<P><A HREF = "fix_ave_chunk.html">fix ave/chunk</A>
 
547
</P>
 
548
<P><B>Default:</B>
 
549
</P>
 
550
<P>The option defaults are as follows:
 
551
</P>
 
552
<UL><LI>region = none
 
553
<LI>nchunk = every if compress is yes, overriding other defaults listed here
 
554
<LI>nchunk = once for type style
 
555
<LI>nchunk = once for mol style if region is none
 
556
<LI>nchunk = every for mol style if region is set
 
557
<LI>nchunk = once for binning style if the simulation box size is static or units = reduced
 
558
<LI>nchunk = every for binning style if the simulation box size is dynamic and units is lattice or box
 
559
<LI>nchunk = every for compute/fix/variable style
 
560
<LI>limit = 0
 
561
<LI>ids = every
 
562
<LI>compress = no
 
563
<LI>discard = yes for all styles except binning
 
564
<LI>discard = mixed for binning styles
 
565
<LI>bound = lower and upper in all dimensions
 
566
<LI>units = lattice 
 
567
</UL>
 
568
</HTML>