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
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/sphinx_docs/html/manual/dmplex.html" />
<meta charset="utf-8" />
<title>DMPlex: Unstructured Grids in PETSc — PETSc 3.14.5 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" />
<link rel="stylesheet" type="text/css" href="../_static/katex-math.css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js"></script>
<script src="../_static/katex_autorenderer.js"></script>
<link rel="shortcut icon" href="../_static/PETSc_RGB-logo.png"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Additional Information" href="additional.html" />
<link rel="prev" title="High Level Support for Multigrid with KSPSetDM() and SNESSetDM()" href="high_level_mg.html" />
</head><body>
<div id="version" align=right><b>petsc-3.14.5 2021-03-03</b></div>
<div id="bugreport" align=right><a href="mailto:petsc-maint@mcs.anl.gov?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: petsc-3.14.5 v3.14.5 docs/sphinx_docs/html/manual/dmplex.html "><small>Report Typos and Errors</small></a></div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="additional.html" title="Additional Information"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="high_level_mg.html" title="High Level Support for Multigrid with KSPSetDM() and SNESSetDM()"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">PETSc 3.14.5 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >PETSc Users Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="programming.html" accesskey="U">Programming with PETSc</a> »</li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/PETSc-TAO_RGB.svg" alt="Logo"/>
</a></p>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">DMPlex: Unstructured Grids in PETSc</a><ul>
<li><a class="reference internal" href="#representing-unstructured-grids">Representing Unstructured Grids</a></li>
<li><a class="reference internal" href="#data-on-unstructured-grids">Data on Unstructured Grids</a><ul>
<li><a class="reference internal" href="#data-layout">Data Layout</a></li>
<li><a class="reference internal" href="#partitioning-and-ordering">Partitioning and Ordering</a></li>
<li><a class="reference internal" href="#influence-of-variables-on-one-another">Influence of Variables on One Another</a></li>
</ul>
</li>
<li><a class="reference internal" href="#evaluating-residuals">Evaluating Residuals</a></li>
<li><a class="reference internal" href="#networks">Networks</a><ul>
<li><a class="reference internal" href="#application-flow">Application flow</a></li>
<li><a class="reference internal" href="#utility-functions">Utility functions</a></li>
<li><a class="reference internal" href="#retrieving-components">Retrieving components</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="high_level_mg.html"
title="previous chapter">High Level Support for Multigrid with KSPSetDM() and SNESSetDM()</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="additional.html"
title="next chapter">Additional Information</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/manual/dmplex.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="dmplex-unstructured-grids-in-petsc">
<span id="chapter-unstructured"></span><h1>DMPlex: Unstructured Grids in PETSc<a class="headerlink" href="#dmplex-unstructured-grids-in-petsc" title="Permalink to this headline">¶</a></h1>
<p>This chapter introduces the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPLEX.html#DMPLEX">DMPLEX</a></span></code> subclass of <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span></code>, which allows
the user to handle unstructured grids using the generic <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span></code> interface
for hierarchy and multi-physics. <code class="docutils literal notranslate"><span class="pre">DMPlex</span></code> was created to remedy a huge
problem in all current PDE simulation codes, namely that the
discretization was so closely tied to the data layout and solver that
switching discretizations in the same code was not possible. Not only
does this preclude the kind of comparison that is necessary for
scientific investigation, but it makes library (as opposed to monolithic
application) development impossible.</p>
<div class="section" id="representing-unstructured-grids">
<h2>Representing Unstructured Grids<a class="headerlink" href="#representing-unstructured-grids" title="Permalink to this headline">¶</a></h2>
<p>The main advantage of <code class="docutils literal notranslate"><span class="pre">DMPlex</span></code> in representing topology is that it
treats all the different pieces of a mesh, e.g. cells, faces, edges, and
vertices, in exactly the same way. This allows the interface to be very
small and simple, while remaining flexible and general. This also allows
“dimension independent programming”, which means that the same algorithm
can be used unchanged for meshes of different shapes and dimensions.</p>
<p>All pieces of the mesh are treated as <em>points</em>, which are identified by
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span></code>s. A mesh is built by relating points to other points, in
particular specifying a “covering” relation among the points. For
example, an edge is defined by being covered by two vertices, and a
triangle can be defined by being covered by three edges (or even by
three vertices). In fact, this structure has been known for a long time.
It is a Hasse Diagram <a class="reference external" href="http://en.wikipedia.org/wiki/Hasse_diagram">Hasse Diagram</a>, which is a
Directed Acyclic Graph (DAG) representing a cell complex using the
covering relation. The graph edges represent the relation, which also
encodes a partially ordered set (poset).</p>
<p>For example, we can encode the doublet mesh as in <a class="reference internal" href="#fig-doubletmesh"><span class="std std-numref">Fig. 6</span></a>,</p>
<div class="figure align-default" id="fig-doubletmesh">
<img alt="../_images/dmplex_doublet_mesh.svg" src="../_images/dmplex_doublet_mesh.svg" /><p class="caption"><span class="caption-number">Fig. 6 </span><span class="caption-text">A 2D doublet mesh, two triangles sharing an edge.</span><a class="headerlink" href="#fig-doubletmesh" title="Permalink to this image">¶</a></p>
</div>
<p>which can also be represented as the DAG in
<a class="reference internal" href="#fig-doubletdag"><span class="std std-numref">Fig. 7</span></a>.</p>
<div class="figure align-default" id="fig-doubletdag">
<img alt="../_images/dmplex_doublet_dag.svg" src="../_images/dmplex_doublet_dag.svg" /><p class="caption"><span class="caption-number">Fig. 7 </span><span class="caption-text">The Hasse diagram for our 2D doublet mesh, expressed as a DAG.</span><a class="headerlink" href="#fig-doubletdag" title="Permalink to this image">¶</a></p>
</div>
<p>To use the PETSc API, we first consecutively number the mesh pieces. The
PETSc convention in 3 dimensions is to number first cells, then
vertices, then faces, and then edges. In 2 dimensions the convention is
to number faces, vertices, and then edges. The user is free to violate
these conventions. In terms of the labels in
<a class="reference internal" href="#fig-doubletmesh"><span class="std std-numref">Fig. 6</span></a>, these numberings are</p>
<div class="math">
\[f_0 \mapsto \mathtt{0}, f_1 \mapsto \mathtt{1}, \quad v_0 \mapsto \mathtt{2}, v_1 \mapsto \mathtt{3}, v_2 \mapsto \mathtt{4}, v_3 \mapsto \mathtt{5}, \quad e_0 \mapsto \mathtt{6}, e_1 \mapsto \mathtt{7}, e_2 \mapsto \mathtt{8}, e_3 \mapsto \mathtt{9}, e_4 \mapsto \mathtt{10}
\]</div>
<p>First, we declare the set of points present in a mesh,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetChart.html#DMPlexSetChart">DMPlexSetChart</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">11</span><span class="p">);</span>
</pre></div>
</div>
<p>Note that a <em>chart</em> here corresponds to a semi-closed interval (e.g
<span class="math">\([0,11) = \{0,1,\ldots,10\}\)</span>) specifying the range of indices we’d
like to use to define points on the current rank. We then define the
covering relation, which we call the <em>cone</em>, which are also the in-edges
in the DAG. In order to preallocate correctly, we first setup sizes,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetConeSize.html#DMPlexSetConeSize">DMPlexSetConeSize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMSetUp.html#DMSetUp">DMSetUp</a></span><span class="p">(</span><span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
<p>and then point values,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="p">[</span><span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="p">[</span><span class="mi">7</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">10</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="p">[</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">2</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetCone.html#DMPlexSetCone">DMPlexSetCone</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="p">[</span><span class="mi">5</span><span class="p">,</span> <span class="mi">3</span><span class="p">]);</span>
</pre></div>
</div>
<p>There is also an API for the dual relation, using
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetSupportSize.html#DMPlexSetSupportSize">DMPlexSetSupportSize</a>()</span></code> and <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSetSupport.html#DMPlexSetSupport">DMPlexSetSupport</a>()</span></code>, but this can be
calculated automatically by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexSymmetrize.html#DMPlexSymmetrize">DMPlexSymmetrize</a></span><span class="p">(</span><span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
<p>In order to support efficient queries, we also want to construct fast
search structures and indices for the different types of points, which
is done using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexStratify.html#DMPlexStratify">DMPlexStratify</a></span><span class="p">(</span><span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="data-on-unstructured-grids">
<h2>Data on Unstructured Grids<a class="headerlink" href="#data-on-unstructured-grids" title="Permalink to this headline">¶</a></h2>
<p>The strongest links between solvers and discretizations are</p>
<ul class="simple">
<li><p>the layout of data over the mesh,</p></li>
<li><p>problem partitioning, and</p></li>
<li><p>ordering of unknowns.</p></li>
</ul>
<p>To enable modularity, we encode the operations above in simple data
structures that can be understood by the linear algebra engine in PETSc
without any reference to the mesh (topology) or discretization
(analysis).</p>
<div class="section" id="data-layout">
<h3>Data Layout<a class="headerlink" href="#data-layout" title="Permalink to this headline">¶</a></h3>
<p>Data is associated with a mesh using the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code> object. A
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code> can be thought of as a generalization of
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/PetscLayout.html#PetscLayout">PetscLayout</a></span></code>, in the same way that a fiber bundle is a generalization
of the normal Euclidean basis used in linear algebra. With
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/PetscLayout.html#PetscLayout">PetscLayout</a></span></code>, we associate a unit vector (<span class="math">\(e_i\)</span>) with every
point in the space, and just divide up points between processes. Using
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code>, we can associate a set of dofs, a small space
<span class="math">\(\{e_k\}\)</span>, with every point, and though our points must be
contiguous like <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/PetscLayout.html#PetscLayout">PetscLayout</a></span></code>, they can be in any range
<span class="math">\([\mathrm{pStart}, \mathrm{pEnd})\)</span>.</p>
<p>The sequence for setting up any <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code> is the following:</p>
<ol class="arabic simple">
<li><p>Specify the chart,</p></li>
<li><p>Specify the number of dofs per point, and</p></li>
<li><p>Set up the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code>.</p></li>
</ol>
<p>For example, using the mesh from
<a class="reference internal" href="#fig-doubletmesh"><span class="std std-numref">Fig. 6</span></a>, we can lay out data for
a continuous Galerkin <span class="math">\(P_3\)</span> finite element method,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">pStart</span><span class="p">,</span> <span class="n">pEnd</span><span class="p">,</span> <span class="n">cStart</span><span class="p">,</span> <span class="n">cEnd</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">vStart</span><span class="p">,</span> <span class="n">vEnd</span><span class="p">,</span> <span class="n">v</span><span class="p">,</span> <span class="n">eStart</span><span class="p">,</span> <span class="n">eEnd</span><span class="p">,</span> <span class="n">e</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetChart.html#DMPlexGetChart">DMPlexGetChart</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="o">&</span><span class="n">pStart</span><span class="p">,</span> <span class="o">&</span><span class="n">pEnd</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetHeightStratum.html#DMPlexGetHeightStratum">DMPlexGetHeightStratum</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="o">&</span><span class="n">cStart</span><span class="p">,</span> <span class="o">&</span><span class="n">cEnd</span><span class="p">);</span> <span class="cm">/* cells */</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetHeightStratum.html#DMPlexGetHeightStratum">DMPlexGetHeightStratum</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="o">&</span><span class="n">eStart</span><span class="p">,</span> <span class="o">&</span><span class="n">eEnd</span><span class="p">);</span> <span class="cm">/* edges */</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetHeightStratum.html#DMPlexGetHeightStratum">DMPlexGetHeightStratum</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="o">&</span><span class="n">vStart</span><span class="p">,</span> <span class="o">&</span><span class="n">vEnd</span><span class="p">);</span> <span class="cm">/* vertices, equivalent to <a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetDepthStratum.html#DMPlexGetDepthStratum">DMPlexGetDepthStratum</a>(dm, 0, &vStart, &vEnd); */</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionSetChart.html#PetscSectionSetChart">PetscSectionSetChart</a></span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">pStart</span><span class="p">,</span> <span class="n">pEnd</span><span class="p">);</span>
<span class="k">for</span><span class="p">(</span><span class="n">c</span> <span class="o">=</span> <span class="n">cStart</span><span class="p">;</span> <span class="n">c</span> <span class="o"><</span> <span class="n">cEnd</span><span class="p">;</span> <span class="o">++</span><span class="n">c</span><span class="p">)</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionSetDof.html#PetscSectionSetDof">PetscSectionSetDof</a></span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
<span class="k">for</span><span class="p">(</span><span class="n">v</span> <span class="o">=</span> <span class="n">vStart</span><span class="p">;</span> <span class="n">v</span> <span class="o"><</span> <span class="n">vEnd</span><span class="p">;</span> <span class="o">++</span><span class="n">v</span><span class="p">)</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionSetDof.html#PetscSectionSetDof">PetscSectionSetDof</a></span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">v</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
<span class="k">for</span><span class="p">(</span><span class="n">e</span> <span class="o">=</span> <span class="n">eStart</span><span class="p">;</span> <span class="n">e</span> <span class="o"><</span> <span class="n">eEnd</span><span class="p">;</span> <span class="o">++</span><span class="n">e</span><span class="p">)</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionSetDof.html#PetscSectionSetDof">PetscSectionSetDof</a></span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionSetUp.html#PetscSectionSetUp">PetscSectionSetUp</a></span><span class="p">(</span><span class="n">s</span><span class="p">);</span>
</pre></div>
</div>
<p>DMPlexGetHeightStratum() returns all the points of the requested height
in the DAG. Since this problem is in two dimensions the edges are at
height 1 and the vertices at height 2 (the cells are always at height
0). One can also use <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetDepthStratum.html#DMPlexGetDepthStratum">DMPlexGetDepthStratum</a>()</span></code> to use the depth in the
DAG to select the points. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetDepth.html#DMPlexGetDepth">DMPlexGetDepth</a>(,&depth)</span></code> routines the depth
of the DAG, hence <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetDepthStratum.html#DMPlexGetDepthStratum">DMPlexGetDepthStratum</a>(dm,depth-1-h,)</span></code> returns the
same values as <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetHeightStratum.html#DMPlexGetHeightStratum">DMPlexGetHeightStratum</a>(dm,h,)</span></code>.</p>
<p>For P3 elements there is one degree of freedom at each vertex, 2 along
each edge (resulting in a total of 4 degrees of freedom alone each edge
including the vertices, thus being able to reproduce a cubic function)
and 1 degree of freedom within the cell (the bubble function which is
zero along all edges).</p>
<p>Now a PETSc local vector can be created manually using this layout,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetStorageSize.html#PetscSectionGetStorageSize">PetscSectionGetStorageSize</a></span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="o">&</span><span class="n">n</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecSetSizes.html#VecSetSizes">VecSetSizes</a></span><span class="p">(</span><span class="n">localVec</span><span class="p">,</span> <span class="n">n</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_DETERMINE.html#PETSC_DETERMINE">PETSC_DETERMINE</a></span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecSetFromOptions.html#VecSetFromOptions">VecSetFromOptions</a></span><span class="p">(</span><span class="n">localVec</span><span class="p">);</span>
</pre></div>
</div>
<p>though it is usually easier to use the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span></code> directly, which also
provides global vectors,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMSetLocalSection.html#DMSetLocalSection">DMSetLocalSection</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="n">s</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMGetLocalVector.html#DMGetLocalVector">DMGetLocalVector</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="o">&</span><span class="n">localVec</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMGetGlobalVector.html#DMGetGlobalVector">DMGetGlobalVector</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="o">&</span><span class="n">globalVec</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="partitioning-and-ordering">
<h3>Partitioning and Ordering<a class="headerlink" href="#partitioning-and-ordering" title="Permalink to this headline">¶</a></h3>
<p>In exactly the same way as in <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatPartitioning.html#MatPartitioning">MatPartitioning</a></span></code> or with
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/MatOrderings/MatGetOrdering.html#MatGetOrdering">MatGetOrdering</a>()</span></code>, the results of a partition using
<code class="docutils literal notranslate"><span class="pre">DMPlexPartition</span></code> or reordering using <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexPermute.html#DMPlexPermute">DMPlexPermute</a></span></code> are encoded in
an <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/IS/IS.html#IS">IS</a></span></code>. However, the graph is not the adjacency graph of the problem
Jacobian, but the mesh itself. Once the mesh is partitioned and
reordered, the data layout from a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code> can be used to
automatically derive a problem partitioning/ordering.</p>
</div>
<div class="section" id="influence-of-variables-on-one-another">
<h3>Influence of Variables on One Another<a class="headerlink" href="#influence-of-variables-on-one-another" title="Permalink to this headline">¶</a></h3>
<p>The Jacobian of a problem is intended to represent the influence of some
variable on other variables in the problem. Very often, this influence
pattern is determined jointly by the computational mesh and
discretization. <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMCreateMatrix.html#DMCreateMatrix">DMCreateMatrix</a></span></code> must compute this pattern when it
automatically creates the properly preallocated Jacobian matrix. In
<code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMDA/DMDA.html#DMDA">DMDA</a></span></code> the influence pattern, or what we will call variable
<em>adjacency</em>, depends only on the stencil since the topology is Cartesian
and the discretization is implicitly finite difference. In <code class="docutils literal notranslate"><span class="pre">DMPlex</span></code>,
we allow the user to specify the adjacency topologically, while
maintaining good defaults.</p>
<p>The pattern is controlled by two flags. The first flag, <code class="docutils literal notranslate"><span class="pre">useCone</span></code>,
indicates whether variables couple first to their boundary and then to
neighboring entities, or the reverse. For example, in finite elements,
the variables couple to the set of neighboring cells containing the mesh
point, and we set the flag to <code class="docutils literal notranslate"><span class="pre">useCone</span> <span class="pre">=</span> <span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</a></span></code>. By constrast,
in finite volumes, cell variables first couple to the cell boundary, and
then to the neighbors, so we set the flag to <code class="docutils literal notranslate"><span class="pre">useCone</span> <span class="pre">=</span> <span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span></code>.
The second flag, <code class="docutils literal notranslate"><span class="pre">useClosure</span></code>, indicates whether we consider the
transitive closure of the neighbor relation above, or just a single
level. For example, in finite elements, the entire boundary of any cell
couples to the interior, and we set the flag to
<code class="docutils literal notranslate"><span class="pre">useClosure</span> <span class="pre">=</span> <span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span></code>. By contrast, in most finite volume methods,
cells couple only across faces, and not through vertices, so we set the
flag to <code class="docutils literal notranslate"><span class="pre">useClosure</span> <span class="pre">=</span> <span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</a></span></code>. However, the power of this method
is its flexibility. If we wanted a finite volume method that coupled all
cells around a vertex, we could easily prescribe that by changing to
<code class="docutils literal notranslate"><span class="pre">useClosure</span> <span class="pre">=</span> <span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span></code>.</p>
</div>
</div>
<div class="section" id="evaluating-residuals">
<h2>Evaluating Residuals<a class="headerlink" href="#evaluating-residuals" title="Permalink to this headline">¶</a></h2>
<p>The evaluation of a residual or Jacobian, for most discretizations has
the following general form:</p>
<ul class="simple">
<li><p>Traverse the mesh, picking out pieces (which in general overlap),</p></li>
<li><p>Extract some values from the solution vector, associated with this
piece,</p></li>
<li><p>Calculate some values for the piece, and</p></li>
<li><p>Insert these values into the residual vector</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">DMPlex</span></code> separates these different concerns by passing sets of points,
which are just <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span></code>s, from mesh traversal routines to data
extraction routines and back. In this way, the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code> which
structures the data inside a <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/Vec.html#Vec">Vec</a></span></code> does not need to know anything
about the mesh inside a <code class="docutils literal notranslate"><span class="pre">DMPlex</span></code>.</p>
<p>The most common mesh traversal is the transitive closure of a point,
which is exactly the transitive closure of a point in the DAG using the
covering relation. In other words, the transitive closure consists of
all points that cover the given point (generally a cell) plus all points
that cover those points, etc. So in 2d the transitive closure for a cell
consists of edges and vertices while in 3d it consists of faces, edges,
and vertices. Note that this closure can be calculated orienting the
arrows in either direction. For example, in a finite element
calculation, we calculate an integral over each element, and then sum up
the contributions to the basis function coefficients. The closure of the
element can be expressed discretely as the transitive closure of the
element point in the mesh DAG, where each point also has an orientation.
Then we can retrieve the data using <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSection.html#PetscSection">PetscSection</a></span></code> methods,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscScalar.html#PetscScalar">PetscScalar</a></span> <span class="o">*</span><span class="n">a</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">numPoints</span><span class="p">,</span> <span class="o">*</span><span class="n">points</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">,</span> <span class="n">p</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecGetArray.html#VecGetArray">VecGetArray</a></span><span class="p">(</span><span class="n">u</span><span class="p">,</span><span class="o">&</span><span class="n">a</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetTransitiveClosure.html#DMPlexGetTransitiveClosure">DMPlexGetTransitiveClosure</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="n">cell</span><span class="p">,</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span><span class="p">,</span><span class="o">&</span><span class="n">numPoints</span><span class="p">,</span><span class="o">&</span><span class="n">points</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="n">p</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">p</span> <span class="o"><=</span> <span class="n">numPoints</span><span class="o">*</span><span class="mi">2</span><span class="p">;</span> <span class="n">p</span> <span class="o">+=</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">dof</span><span class="p">,</span> <span class="n">off</span><span class="p">,</span> <span class="n">d</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetDof.html#PetscSectionGetDof">PetscSectionGetDof</a></span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">points</span><span class="p">[</span><span class="n">p</span><span class="p">],</span> <span class="o">&</span><span class="n">dof</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetOffset.html#PetscSectionGetOffset">PetscSectionGetOffset</a></span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">points</span><span class="p">[</span><span class="n">p</span><span class="p">],</span> <span class="o">&</span><span class="n">off</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="n">d</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">d</span> <span class="o"><=</span> <span class="n">dof</span><span class="p">;</span> <span class="o">++</span><span class="n">d</span><span class="p">)</span> <span class="p">{</span>
<span class="n">myfunc</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="n">off</span><span class="o">+</span><span class="n">d</span><span class="p">]);</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexRestoreTransitiveClosure.html#DMPlexRestoreTransitiveClosure">DMPlexRestoreTransitiveClosure</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="n">cell</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_TRUE.html#PETSC_TRUE">PETSC_TRUE</a></span><span class="p">,</span> <span class="o">&</span><span class="n">numPoints</span><span class="p">,</span> <span class="o">&</span><span class="n">points</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecRestoreArray.html#VecRestoreArray">VecRestoreArray</a></span><span class="p">(</span><span class="n">u</span><span class="p">,</span> <span class="o">&</span><span class="n">a</span><span class="p">);</span>
</pre></div>
</div>
<p>This operation is so common that we have built a convenience method
around it which returns the values in a contiguous array, correctly
taking into account the orientations of various mesh points:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">const</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscScalar.html#PetscScalar">PetscScalar</a></span> <span class="o">*</span><span class="n">values</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">csize</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexVecGetClosure.html#DMPlexVecGetClosure">DMPlexVecGetClosure</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="n">section</span><span class="p">,</span> <span class="n">u</span><span class="p">,</span> <span class="n">cell</span><span class="p">,</span> <span class="o">&</span><span class="n">csize</span><span class="p">,</span> <span class="o">&</span><span class="n">values</span><span class="p">);</span>
<span class="cm">/* Do integral in quadrature loop */</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexVecRestoreClosure.html#DMPlexVecRestoreClosure">DMPlexVecRestoreClosure</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="n">section</span><span class="p">,</span> <span class="n">u</span><span class="p">,</span> <span class="n">cell</span><span class="p">,</span> <span class="o">&</span><span class="n">csize</span><span class="p">,</span> <span class="o">&</span><span class="n">values</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexVecSetClosure.html#DMPlexVecSetClosure">DMPlexVecSetClosure</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="n">section</span><span class="p">,</span> <span class="n">residual</span><span class="p">,</span> <span class="n">cell</span><span class="p">,</span> <span class="o">&</span><span class="n">r</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/ADD_VALUES.html#ADD_VALUES">ADD_VALUES</a></span><span class="p">);</span>
</pre></div>
</div>
<p>A simple example of this kind of calculation is in
<code class="docutils literal notranslate"><span class="pre">DMPlexComputeL2Diff_Plex()</span></code> (<a class="reference external" href="https://www.mcs.anl.gov/petsc/petsc-current/src/dm/impls/plex/plexfem.c.html#DMComputeL2Diff_Plex">source</a>).
Note that there is no restriction on the type of cell or dimension of
the mesh in the code above, so it will work for polyhedral cells, hybrid
meshes, and meshes of any dimension, without change. We can also reverse
the covering relation, so that the code works for finite volume methods
where we want the data from neighboring cells for each face:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscScalar.html#PetscScalar">PetscScalar</a></span> <span class="o">*</span><span class="n">a</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">points</span><span class="p">[</span><span class="mi">2</span><span class="o">*</span><span class="mi">2</span><span class="p">],</span> <span class="n">numPoints</span><span class="p">,</span> <span class="n">p</span><span class="p">,</span> <span class="n">dofA</span><span class="p">,</span> <span class="n">offA</span><span class="p">,</span> <span class="n">dofB</span><span class="p">,</span> <span class="n">offB</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecGetArray.html#VecGetArray">VecGetArray</a></span><span class="p">(</span><span class="n">u</span><span class="p">,</span> <span class="o">&</span><span class="n">a</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMPLEX/DMPlexGetTransitiveClosure.html#DMPlexGetTransitiveClosure">DMPlexGetTransitiveClosure</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="n">cell</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</a></span><span class="p">,</span> <span class="o">&</span><span class="n">numPoints</span><span class="p">,</span> <span class="o">&</span><span class="n">points</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">numPoints</span> <span class="o">==</span> <span class="mi">2</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetDof.html#PetscSectionGetDof">PetscSectionGetDof</a></span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">points</span><span class="p">[</span><span class="mi">0</span><span class="o">*</span><span class="mi">2</span><span class="p">],</span> <span class="o">&</span><span class="n">dofA</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetDof.html#PetscSectionGetDof">PetscSectionGetDof</a></span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">points</span><span class="p">[</span><span class="mi">1</span><span class="o">*</span><span class="mi">2</span><span class="p">],</span> <span class="o">&</span><span class="n">dofB</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">dofA</span> <span class="o">==</span> <span class="n">dofB</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetOffset.html#PetscSectionGetOffset">PetscSectionGetOffset</a></span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">points</span><span class="p">[</span><span class="mi">0</span><span class="o">*</span><span class="mi">2</span><span class="p">],</span> <span class="o">&</span><span class="n">offA</span><span class="p">);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PetscSection/PetscSectionGetOffset.html#PetscSectionGetOffset">PetscSectionGetOffset</a></span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">points</span><span class="p">[</span><span class="mi">1</span><span class="o">*</span><span class="mi">2</span><span class="p">],</span> <span class="o">&</span><span class="n">offB</span><span class="p">);</span>
<span class="n">myfunc</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="n">offA</span><span class="p">],</span> <span class="n">a</span><span class="p">[</span><span class="n">offB</span><span class="p">]);</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Vec/VecRestoreArray.html#VecRestoreArray">VecRestoreArray</a></span><span class="p">(</span><span class="n">u</span><span class="p">,</span> <span class="o">&</span><span class="n">a</span><span class="p">);</span>
</pre></div>
</div>
<p>This kind of calculation is used in
<a class="reference external" href="https://www.mcs.anl.gov/petsc/petsc-current/src/ts/tutorials/ex11.c.html">TS Tutorial ex11</a>.</p>
</div>
<div class="section" id="networks">
<h2>Networks<a class="headerlink" href="#networks" title="Permalink to this headline">¶</a></h2>
<p>Built on top of <code class="docutils literal notranslate"><span class="pre">DMPlex</span></code>, the <code class="docutils literal notranslate"><span class="pre">DMNetwork</span></code> subclass provides
abstractions for representing general unstructured networks such as
communication networks, power grid, computer networks, transportation
networks, electrical circuits, graphs, and others.</p>
<div class="section" id="application-flow">
<h3>Application flow<a class="headerlink" href="#application-flow" title="Permalink to this headline">¶</a></h3>
<p>The general flow of an application code using <code class="docutils literal notranslate"><span class="pre">DMNetwork</span></code> is as
follows:</p>
<ol class="arabic">
<li><p>Create a network object</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkCreate.html#DMNetworkCreate">DMNetworkCreate</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</a></span> <span class="n">comm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="o">*</span><span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>Create components and register them with the network. A “component”
is specific application data at a vertex/edge of the network required
for its residual evaluation. For example, components could be
resistor, inductor data for circuit applications, edge weights for
graph problems, generator/transmission line data for power grids.
Components are registered by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkRegisterComponent.html#DMNetworkRegisterComponent">DMNetworkRegisterComponent</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">name</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">compkey</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">name</span></code> is the component name, <code class="docutils literal notranslate"><span class="pre">size</span></code> is the size of
component data type, and <code class="docutils literal notranslate"><span class="pre">compkey</span></code> is an integer key that can be
used for setting/getting the component at a vertex or an edge.
DMNetwork currently allows upto 16 components to be registered for a
network.</p>
</li>
<li><p>A DMNetwork can consist of one or more <em>physical</em> subnetworks. When
multiple physical subnetworks are used one can (optionally) provide
<em>coupling information between subnetworks</em> which consist only of
edges connecting the vertices of the physical subnetworks. The
topological sizes of the network are set by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkSetSizes.html#DMNetworkSetSizes">DMNetworkSetSizes</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">Nsubnet</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">nV</span><span class="p">[],</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">nE</span><span class="p">[],</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">NsubnetCouple</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">nec</span><span class="p">[]);</span>
</pre></div>
</div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">Nsubnet</span></code> is the number of subnetworks, <code class="docutils literal notranslate"><span class="pre">nV</span></code> and <code class="docutils literal notranslate"><span class="pre">nE</span></code> is
the number of vertices and edges for each subnetwork,
<code class="docutils literal notranslate"><span class="pre">NsubnetCouple</span></code> is the number of pairs of subnetworks that are
coupled, and <code class="docutils literal notranslate"><span class="pre">nec</span></code> is the number of edges coupling each subnetwork
pair. DMNetwork assumes coupling between the subnetworks through
coupling edges. For a single network, set <code class="docutils literal notranslate"><span class="pre">Nsubnet</span></code> = 1,
<code class="docutils literal notranslate"><span class="pre">NsubnetCouple</span></code> = 0, and <code class="docutils literal notranslate"><span class="pre">nec</span></code> = NULL. Note that the coupling
between subnetworks is still an experimental feature and under
development.</p>
</li>
<li><p>The next step is to set up the connectivity for the network. This is
done by specifying the connectivity within each subnetwork
(<code class="docutils literal notranslate"><span class="pre">edgelist</span></code>) and between subnetworks (<code class="docutils literal notranslate"><span class="pre">edgelistCouple</span></code>).</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkSetEdgeList.html#DMNetworkSetEdgeList">DMNetworkSetEdgeList</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">edgelist</span><span class="p">[],</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">edgelistCouple</span><span class="p">[]);</span>
</pre></div>
</div>
<p>Each element of <code class="docutils literal notranslate"><span class="pre">edgelist</span></code> is an integer array of size 2*nE[i]
containing the edge connectivity for the i-th subnetwork. Each
element in <code class="docutils literal notranslate"><span class="pre">edgelistCouple</span></code> has four entries - from subnetwork
number (net.id), from subnetwork vertex number (vertex.id), to
subnetwork number (net.id), to subetwork vertex number (vertex.id).</p>
<div class="line-block">
<div class="line">As an example, consider a network comprising of 2 subnetworks that
are coupled. The topological information for the network is as
follows:</div>
<div class="line">subnetwork 0: v0 — v1 — v2 — v3</div>
<div class="line">subnetwork 1: v1 — v2 — v0</div>
<div class="line">coupling between subnetworks: subnetwork 1: v2 — subnetwork 0: v0</div>
<div class="line">The <code class="docutils literal notranslate"><span class="pre">edgelist</span></code> and <code class="docutils literal notranslate"><span class="pre">edgelistCouple</span></code> for this network are</div>
<div class="line">edgelist[0] = {0,1,1,2,2,3}</div>
<div class="line">edgelist[1] = {1,2,2,0}</div>
<div class="line">edgelistCouple[0] = {1,2,0,0}.</div>
</div>
</li>
<li><p>The next step is to have DMNetwork to create a bare layout (graph) of
the network by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkLayoutSetUp.html#DMNetworkLayoutSetUp">DMNetworkLayoutSetUp</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>After completing the previous steps, the network graph is set up, but
no physics is associated yet. This is done by adding the components
and setting the number of variables for the vertices and edges.</p>
<p>A component is added to a vertex/edge by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkAddComponent.html#DMNetworkAddComponent">DMNetworkAddComponent</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">compkey</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span> <span class="n">compdata</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">p</span></code> is the network vertex/edge point in the range obtained by
either DMNetworkGetEdgeRange or DMNetworkGetVertexRange, <code class="docutils literal notranslate"><span class="pre">compkey</span></code>
is the component key returned when registering the component
(DMNetworkRegisterComponent), and <code class="docutils literal notranslate"><span class="pre">compdata</span></code> holds the data for the
component. DMNetwork supports setting multiple components (max. 36)
at a vertex/edge.</p>
<p>DMNetwork currently assumes the component data to be stored in a
contiguous chunk of memory. As such, it does not do any
packing/unpacking before/after the component data gets distributed.
Any such serialization (packing/unpacking) should be done by the
application.</p>
<p>The number of variables at each vertex/edge are set by</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkSetNumVariables.html#DMNetworkSetNumVariables">DMNetworkSetNumVariables</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">nvar</span><span class="p">);</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkAddNumVariables.html#DMNetworkAddNumVariables">DMNetworkAddNumVariables</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">nvar</span><span class="p">);</span>
</pre></div>
</div>
<p>Alternatively, the number of variables can be set for a component
directly. This allows much finer control, specifically for
vertices/edges that have multiple components set on them.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkSetComponentNumVariables.html#DMNetworkSetComponentNumVariables">DMNetworkSetComponentNumVariables</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">compnum</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">nvar</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>Set up network internal data structures.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMSetUp.html#DMSetUp">DMSetUp</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>Distribute the network (also moves components attached with
vertices/edges) to multiple processors.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkDistribute.html#DMNetworkDistribute">DMNetworkDistribute</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="n">partitioner</span><span class="p">[],</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">overlap</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="o">*</span><span class="n">distDM</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>Associate the <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span></code> with a PETSc solver:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetDM.html#KSPSetDM">KSPSetDM</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSP.html#KSP">KSP</a></span> <span class="n">ksp</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">)</span> <span class="n">or</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/SNES/SNESSetDM.html#SNESSetDM">SNESSetDM</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/SNES/SNES.html#SNES">SNES</a></span> <span class="n">snes</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">)</span> <span class="n">or</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/TS/TSSetDM.html#TSSetDM">TSSetDM</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/TS/TS.html#TS">TS</a></span> <span class="n">ts</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">).</span>
</pre></div>
</div>
</li>
</ol>
</div>
<div class="section" id="utility-functions">
<h3>Utility functions<a class="headerlink" href="#utility-functions" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">DMNetwork</span></code> provides several utility functions for operations on the
network. The mostly commonly used functions are: obtaining iterators for
vertices/edges,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetEdgeRange.html#DMNetworkGetEdgeRange">DMNetworkGetEdgeRange</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">eStart</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">eEnd</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetVertexRange.html#DMNetworkGetVertexRange">DMNetworkGetVertexRange</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">vStart</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">vEnd</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetSubnetworkInfo.html#DMNetworkGetSubnetworkInfo">DMNetworkGetSubnetworkInfo</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">netid</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">nv</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">ne</span><span class="p">,</span> <span class="k">const</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">**</span><span class="n">vtx</span><span class="p">,</span> <span class="k">const</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">**</span><span class="n">edge</span><span class="p">);</span>
</pre></div>
</div>
<p>Checking the “ghost” status of a vertex,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkIsGhostVertex.html#DMNetworkIsGhostVertex">DMNetworkIsGhostVertex</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</a></span> <span class="o">*</span><span class="n">isghost</span><span class="p">);</span>
</pre></div>
</div>
<p>and retrieving local/global indices of vertex/edge variables for
inserting elements in vectors/matrices.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetVariableOffset.html#DMNetworkGetVariableOffset">DMNetworkGetVariableOffset</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">offset</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetVariableGlobalOffset.html#DMNetworkGetVariableGlobalOffset">DMNetworkGetVariableGlobalOffset</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">offsetg</span><span class="p">);</span>
</pre></div>
</div>
<p>If the number of variables are set at the component level, then their
local/global offsets can be retrieved via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetComponentVariableOffset.html#DMNetworkGetComponentVariableOffset">DMNetworkGetComponentVariableOffset</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">compnum</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">offset</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetComponentVariableGlobalOffset.html#DMNetworkGetComponentVariableGlobalOffset">DMNetworkGetComponentVariableGlobalOffset</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">compnum</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">offsetg</span><span class="p">);</span>
</pre></div>
</div>
<p>In network applications, one frequently needs to find the supporting
edges for a vertex or the connecting vertices covering an edge. These
can be obtained by the following two routines.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetConnectedVertices.html#DMNetworkGetConnectedVertices">DMNetworkGetConnectedVertices</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">edge</span><span class="p">,</span> <span class="k">const</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">vertices</span><span class="p">[]);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetSupportingEdges.html#DMNetworkGetSupportingEdges">DMNetworkGetSupportingEdges</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">vertex</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">nedges</span><span class="p">,</span> <span class="k">const</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">edges</span><span class="p">[]);</span>
</pre></div>
</div>
</div>
<div class="section" id="retrieving-components">
<h3>Retrieving components<a class="headerlink" href="#retrieving-components" title="Permalink to this headline">¶</a></h3>
<p>The components set at a vertex/edge can be accessed by</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetComponent.html#DMNetworkGetComponent">DMNetworkGetComponent</a></span><span class="p">(</span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DM.html#DM">DM</a></span> <span class="n">dm</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">p</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">compnum</span><span class="p">,</span> <span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="o">*</span><span class="n">compkey</span><span class="p">,</span> <span class="kt">void</span><span class="o">**</span> <span class="n">component</span><span class="p">);</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">compkey</span></code> is the key set by <code class="docutils literal notranslate"><span class="pre"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkRegisterComponent.html#DMNetworkRegisterComponent">DMNetworkRegisterComponent</a></span></code>. An example
of accessing and retrieving the components at vertices is:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscInt.html#PetscInt">PetscInt</a></span> <span class="n">Start</span><span class="p">,</span> <span class="n">End</span><span class="p">,</span> <span class="n">numcomps</span><span class="p">,</span><span class="n">key</span><span class="p">,</span><span class="n">v</span><span class="p">,</span><span class="n">compnum</span><span class="p">;</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">component</span><span class="p">;</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetVertexRange.html#DMNetworkGetVertexRange">DMNetworkGetVertexRange</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span> <span class="o">&</span><span class="n">Start</span><span class="p">,</span> <span class="o">&</span><span class="n">End</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="n">v</span><span class="o">=</span><span class="n">Start</span><span class="p">;</span> <span class="n">v</span> <span class="o"><</span> <span class="n">End</span><span class="p">;</span> <span class="n">v</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetNumComponents.html#DMNetworkGetNumComponents">DMNetworkGetNumComponents</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="n">v</span><span class="p">,</span> <span class="o">&</span><span class="n">numcomps</span><span class="p">);</span>
<span class="k">for</span> <span class="p">(</span><span class="n">compnum</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">compnum</span> <span class="o"><</span> <span class="n">numcomps</span><span class="p">;</span><span class="n">compnum</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMNetwork/DMNetworkGetComponent.html#DMNetworkGetComponent">DMNetworkGetComponent</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="n">v</span><span class="p">,</span><span class="n">compnum</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">,</span> <span class="o">&</span><span class="n">component</span><span class="p">);</span>
<span class="n">compdata</span> <span class="o">=</span> <span class="p">(</span><span class="n">UserCompDataType</span><span class="p">)(</span><span class="n">component</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The above example does not explicitly make use the component key. It is
used when different component types are set at different vertices. In
this case, the compkey is used to differentiate the component type.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="additional.html" title="Additional Information"
>next</a> |</li>
<li class="right" >
<a href="high_level_mg.html" title="High Level Support for Multigrid with KSPSetDM() and SNESSetDM()"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">PETSc 3.14.5 documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >PETSc Users Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="programming.html" >Programming with PETSc</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 1991-2021, UChicago Argonne, LLC and the PETSc Development Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.4.4.
</div>
</body>
</html>
|
