1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
|
<!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>processors command — LIGGGHTS v3.X documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="top" title="LIGGGHTS v3.X 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-scroll">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LIGGGHTS
</a>
<div class="version">
v3.X
</div>
<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_input_script.html">3. Input Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">4. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_gran_models.html">5. Contact models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_mesh_modules.html">6. Mesh modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">7. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">8. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">9. Modifying & extending LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">10. Python interface to LIGGGHTS(R)-PUBLIC</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">11. Errors</a></li>
</ul>
</div>
</div>
</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">LIGGGHTS</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> »</li>
<li>processors command</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/processors.txt" rel="nofollow"> View page source</a>
<a href="http://www.cfdem.com"> Website</a>
<a href="Section_commands.html#comm" rel="nofollow"> 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="processors-command">
<span id="index-0"></span><h1>processors command<a class="headerlink" href="#processors-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>processors Px Py Pz keyword args ...
</pre></div>
</div>
<ul class="simple">
<li>Px,Py,Pz = # of processors in each dimension of 3d grid overlaying the simulation domain</li>
<li>zero or more keyword/arg pairs may be appended</li>
<li>keyword = <em>grid</em> or <em>map</em> or <em>part</em> or <em>file</em></li>
</ul>
<pre class="literal-block">
<em>grid</em> arg = gstyle params ...
gstyle = <em>onelevel</em> or <em>twolevel</em> or <em>numa</em> or <em>custom</em>
onelevel params = none
twolevel params = Nc Cx Cy Cz
Nc = number of cores per node
Cx,Cy,Cz = # of cores in each dimension of 3d sub-grid assigned to each node
numa params = none
custom params = infile
infile = file containing grid layout
<em>map</em> arg = <em>cart</em> or <em>cart/reorder</em> or <em>xyz</em> or <em>xzy</em> or <em>yxz</em> or <em>yzx</em> or <em>zxy</em> or <em>zyx</em>
cart = use MPI_Cart() methods to map processors to 3d grid with reorder = 0
cart/reorder = use MPI_Cart() methods to map processors to 3d grid with reorder = 1
xyz,xzy,yxz,yzx,zxy,zyx = map procesors to 3d grid in IJK ordering
<em>numa</em> arg = none
<em>part</em> args = Psend Precv cstyle
Psend = partition # (1 to Np) which will send its processor layout
Precv = partition # (1 to Np) which will recv the processor layout
cstyle = <em>multiple</em>
<em>multiple</em> = Psend grid will be multiple of Precv grid in each dimension
<em>file</em> arg = outfile
outfile = name of file to write 3d grid of processors to
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>processors * * 5
processors 2 4 4
processors * * 8 map xyz
processors * * * grid numa
processors * * * grid twolevel 4 * * 1
processors 4 8 16 grid custom myfile
processors * * * part 1 2 multiple
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Specify how processors are mapped as a 3d logical grid to the global
simulation box. This involves 2 steps. First if there are P
processors it means choosing a factorization P = Px by Py by Pz so
that there are Px processors in the x dimension, and similarly for the
y and z dimensions. Second, the P processors are mapped to the
logical 3d grid. The arguments to this command control each of these
2 steps.</p>
<p>The Px, Py, Pz parameters affect the factorization. Any of the 3
parameters can be specified with an asterisk “*”, which means LIGGGHTS(R)-PUBLIC
will choose the number of processors in that dimension of the grid.
It will do this based on the size and shape of the global simulation
box so as to minimize the surface-to-volume ratio of each processor’s
sub-domain.</p>
<p>Since LIGGGHTS(R)-PUBLIC does not load-balance by changing the grid of 3d
processors on-the-fly, choosing explicit values for Px or Py or Pz can
be used to override the LIGGGHTS(R)-PUBLIC default if it is known to be
sub-optimal for a particular problem. E.g. a problem where the extent
of atoms will change dramatically in a particular dimension over the
course of the simulation.</p>
<p>The product of Px, Py, Pz must equal P, the total # of processors
LIGGGHTS(R)-PUBLIC is running on. For a <a class="reference internal" href="dimension.html"><em>2d simulation</em></a>, Pz must
equal 1.</p>
<p>Note that if you run on a prime number of processors P, then a grid
such as 1 x P x 1 will be required, which may incur extra
communication costs due to the high surface area of each processor’s
sub-domain.</p>
<p>Also note that if multiple partitions are being used then P is the
number of processors in this partition; see <span class="xref std std-ref">this section</span> for an explanation of the
-partition command-line switch. Also note that you can prefix the
processors command with the <a class="reference internal" href="partition.html"><em>partition</em></a> command to
easily specify different Px,Py,Pz values for different partitions.</p>
<p>You can use the <a class="reference internal" href="partition.html"><em>partition</em></a> command to specify
different processor grids for different partitions, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre>partition yes 1 processors 4 4 4
partition yes 2 processors 2 3 2
</pre></div>
</div>
<hr class="docutils" />
<p>The <em>grid</em> keyword affects the factorization of P into Px,Py,Pz and it
can also affect how the P processor IDs are mapped to the 3d grid of
processors.</p>
<p>The <em>onelevel</em> style creates a 3d grid that is compatible with the
Px,Py,Pz settings, and which minimizes the surface-to-volume ratio of
each processor’s sub-domain, as described above. The mapping of
processors to the grid is determined by the <em>map</em> keyword setting.</p>
<p>The <em>twolevel</em> style can be used on machines with multicore nodes to
minimize off-node communication. It insures that contiguous
sub-sections of the 3d grid are assigned to all the cores of a node.
For example if <em>Nc</em> is 4, then 2x2x1 or 2x1x2 or 1x2x2 sub-sections of
the 3d grid will correspond to the cores of each node. This affects
both the factorization and mapping steps.</p>
<p>The <em>Cx</em>, <em>Cy</em>, <em>Cz</em> settings are similar to the <em>Px</em>, <em>Py</em>, <em>Pz</em>
settings, only their product should equal <em>Nc</em>. Any of the 3
parameters can be specified with an asterisk “*”, which means LIGGGHTS(R)-PUBLIC
will choose the number of cores in that dimension of the node’s
sub-grid. As with Px,Py,Pz, it will do this based on the size and
shape of the global simulation box so as to minimize the
surface-to-volume ratio of each processor’s sub-domain.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">For the <em>twolevel</em> style to work correctly, it
assumes the MPI ranks of processors LIGGGHTS(R)-PUBLIC is running on are ordered
by core and then by node. E.g. if you are running on 2 quad-core
nodes, for a total of 8 processors, then it assumes processors 0,1,2,3
are on node 1, and processors 4,5,6,7 are on node 2. This is the
default rank ordering for most MPI implementations, but some MPIs
provide options for this ordering, e.g. via environment variable
settings.</p>
</div>
<p>The <em>numa</em> style operates similar to the <em>twolevel</em> keyword except
that it auto-detects which cores are running on which nodes.
Currently, it does this in only 2 levels, but it may be extended in
the future to account for socket topology and other non-uniform memory
access (NUMA) costs. It also uses a different algorithm than the
<em>twolevel</em> keyword for doing the two-level factorization of the
simulation box into a 3d processor grid to minimize off-node
communication, and it does its own MPI-based mapping of nodes and
cores to the logical 3d grid. Thus it may produce a different layout
of the processors than the <em>twolevel</em> options.</p>
<p>The <em>numa</em> style will give an error if the number of MPI processes is
not divisible by the number of cores used per node, or any of the Px
or Py of Pz values is greater than 1.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Unlike the <em>twolevel</em> style, the <em>numa</em> style does not
require any particular ordering of MPI ranks i norder to work
correctly. This is because it auto-detects which processes are
running on which nodes.</p>
</div>
<p>The <em>custom</em> style uses the file <em>infile</em> to define both the 3d
factorization and the mapping of processors to the grid.</p>
<p>The file should have the following format. Any number of initial
blank or comment lines (starting with a “#” character) can be present.
The first non-blank, non-comment line should have
3 values:</p>
<div class="highlight-python"><div class="highlight"><pre>Px Py Py
</pre></div>
</div>
<p>These must be compatible with the total number of processors
and the Px, Py, Pz settings of the processors commmand.</p>
<p>This line should be immediately followed by
P = Px*Py*Pz lines of the form:</p>
<div class="highlight-python"><div class="highlight"><pre>ID I J K
</pre></div>
</div>
<p>where ID is a processor ID (from 0 to P-1) and I,J,K are the
processors location in the 3d grid. I must be a number from 1 to Px
(inclusive) and similarly for J and K. The P lines can be listed in
any order, but no processor ID should appear more than once.</p>
<hr class="docutils" />
<p>The <em>map</em> keyword affects how the P processor IDs (from 0 to P-1) are
mapped to the 3d grid of processors. It is only used by the
<em>onelevel</em> and <em>twolevel</em> grid settings.</p>
<p>The <em>cart</em> style uses the family of MPI Cartesian functions to perform
the mapping, namely MPI_Cart_create(), MPI_Cart_get(),
MPI_Cart_shift(), and MPI_Cart_rank(). It invokes the
MPI_Cart_create() function with its reorder flag = 0, so that MPI is
not free to reorder the processors.</p>
<p>The <em>cart/reorder</em> style does the same thing as the <em>cart</em> style
except it sets the reorder flag to 1, so that MPI can reorder
processors if it desires.</p>
<p>The <em>xyz</em>, <em>xzy</em>, <em>yxz</em>, <em>yzx</em>, <em>zxy</em>, and <em>zyx</em> styles are all
similar. If the style is IJK, then it maps the P processors to the
grid so that the processor ID in the I direction varies fastest, the
processor ID in the J direction varies next fastest, and the processor
ID in the K direction varies slowest. For example, if you select
style <em>xyz</em> and you have a 2x2x2 grid of 8 processors, the assignments
of the 8 octants of the simulation domain will be:</p>
<div class="highlight-python"><div class="highlight"><pre>proc 0 = lo x, lo y, lo z octant
proc 1 = hi x, lo y, lo z octant
proc 2 = lo x, hi y, lo z octant
proc 3 = hi x, hi y, lo z octant
proc 4 = lo x, lo y, hi z octant
proc 5 = hi x, lo y, hi z octant
proc 6 = lo x, hi y, hi z octant
proc 7 = hi x, hi y, hi z octant
</pre></div>
</div>
<p>Note that, in principle, an MPI implementation on a particular machine
should be aware of both the machine’s network topology and the
specific subset of processors and nodes that were assigned to your
simulation. Thus its MPI_Cart calls can optimize the assignment of
MPI processes to the 3d grid to minimize communication costs. In
practice, however, few if any MPI implementations actually do this.
So it is likely that the <em>cart</em> and <em>cart/reorder</em> styles simply give
the same result as one of the IJK styles.</p>
<p>Also note, that for the <em>twolevel</em> grid style, the <em>map</em> setting is
used to first map the nodes to the 3d grid, then again to the cores
within each node. For the latter step, the <em>cart</em> and <em>cart/reorder</em>
styles are not supported, so an <em>xyz</em> style is used in their place.</p>
<hr class="docutils" />
<p>The <em>part</em> keyword affects the factorization of P into Px,Py,Pz.</p>
<p>It can be useful when running in multi-partition mode, e.g. with the
<a class="reference internal" href="run_style.html"><em>run_style verlet/split</em></a> command. It specifies a
dependency bewteen a sending partition <em>Psend</em> and a receiving
partition <em>Precv</em> which is enforced when each is setting up their own
mapping of their processors to the simulation box. Each of <em>Psend</em>
and <em>Precv</em> must be integers from 1 to Np, where Np is the number of
partitions you have defined via the <span class="xref std std-ref">-partition command-line switch</span>.</p>
<p>A “dependency” means that the sending partition will create its 3d
logical grid as Px by Py by Pz and after it has done this, it will
send the Px,Py,Pz values to the receiving partition. The receiving
partition will wait to receive these values before creating its own 3d
logical grid and will use the sender’s Px,Py,Pz values as a
constraint. The nature of the constraint is determined by the
<em>cstyle</em> argument.</p>
<p>For a <em>cstyle</em> of <em>multiple</em>, each dimension of the sender’s processor
grid is required to be an integer multiple of the corresponding
dimension in the receiver’s processor grid. This is a requirement of
the <a class="reference internal" href="run_style.html"><em>run_style verlet/split</em></a> command.</p>
<p>For example, assume the sending partition creates a 4x6x10 grid = 240
processor grid. If the receiving partition is running on 80
processors, it could create a 4x2x10 grid, but it will not create a
2x4x10 grid, since in the y-dimension, 6 is not an integer multiple of
4.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you use the <a class="reference internal" href="partition.html"><em>partition</em></a> command to
invoke different “processsors” commands on different partitions, and
you also use the <em>part</em> keyword, then you must insure that both the
sending and receiving partitions invoke the “processors” command that
connects the 2 partitions via the <em>part</em> keyword. LIGGGHTS(R)-PUBLIC cannot
easily check for this, but your simulation will likely hang in its
setup phase if this error has been made.</p>
</div>
<hr class="docutils" />
<p>The <em>file</em> keyword writes the mapping of the factorization of P
processors and their mapping to the 3d grid to the specified file
<em>outfile</em>. This is useful to check that you assigned physical
processors in the manner you desired, which can be tricky to figure
out, especially when running on multiple partitions or on, a multicore
machine or when the processor ranks were reordered by use of the
<span class="xref std std-ref">-reorder command-line switch</span> or due to
use of MPI-specific launch options such as a config file.</p>
<p>If you have multiple partitions you should insure that each one writes
to a different file, e.g. using a <a class="reference internal" href="variable.html"><em>world-style variable</em></a>
for the filename. The file has a self-explanatory header, followed by
one-line per processor in this format:</p>
<p>world-ID universe-ID original-ID: I J K: name</p>
<p>The IDs are the processor’s rank in this simulation (the world), the
universe (of multiple simulations), and the original MPI communicator
used to instantiate LIGGGHTS(R)-PUBLIC, respectively. The world and universe IDs
will only be different if you are running on more than one partition;
see the <span class="xref std std-ref">-partition command-line switch</span>.
The universe and original IDs will only be different if you used the
<span class="xref std std-ref">-reorder command-line switch</span> to reorder
the processors differently than their rank in the original
communicator LIGGGHTS(R)-PUBLIC was instantiated with.</p>
<p>I,J,K are the indices of the processor in the 3d logical grid, each
from 1 to Nd, where Nd is the number of processors in that dimension
of the grid.</p>
<p>The <em>name</em> is what is returned by a call to MPI_Get_processor_name()
and should represent an identifier relevant to the physical processors
in your machine. Note that depending on the MPI implementation,
multiple cores can have the same <em>name</em>.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>This command cannot be used after the simulation box is defined by a
<a class="reference internal" href="read_data.html"><em>read_data</em></a> or <a class="reference internal" href="create_box.html"><em>create_box</em></a> command.
It can be used before a restart file is read to change the 3d
processor grid from what is specified in the restart file.</p>
<p>The <em>grid numa</em> keyword only currently works with the <em>map cart</em>
option.</p>
<p>The <em>part</em> keyword (for the receiving partition) only works with the
<em>grid onelevel</em> or <em>grid twolevel</em> options.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="partition.html"><em>partition</em></a>, <span class="xref std std-ref">-reorder command-line switch</span></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The option defaults are Px Py Pz = * * <a href="#id1"><span class="problematic" id="id2">*</span></a>, grid = onelevel, and map =
cart.</p>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2016, DCS Computing GmbH, JKU Linz and 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:'v3.X',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: ''
};
</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="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|
