-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathtutorial-connectivity.html
176 lines (171 loc) · 6.8 KB
/
tutorial-connectivity.html
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
<!doctype html>
<html lang="en">
<head>
<title>p4est 2020 HCM Summer School: Connectivity</title>
<meta name="author" content="Carsten Burstedde">
<link type="text/css" rel="stylesheet" href="p4est.css">
<link type="text/css" rel="stylesheet" href="added.css">
<!-- mathjax !-->
<script type="text/javascript"
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>
<header>
<h1><tt>p4est</tt> 2020 HCM Summer School: Connectivity</h1>
<nav>
<div class="nav-container">
<h2 class="nav-item"><a href="index.html" alt="p4est main page">Main</a></h2>
<h2 class="nav-item">
<a href="gallery.html" alt="p4est Gallery of Research Results">Gallery</a></h2>
<h2 class="nav-item">
<a href="cite.html" alt="p4est Citations and Bibliography">Cite</a></h2>
<h2 class="nav-item">
<a href="school.html" alt="p4est 2020 HCM Summer School">School</a></h2>
</div>
</nav>
</header>
<main>
<p>
We are organizing a <tt>p4est</tt> summer school
sponsored by the
<a href="https://www.hcm.uni-bonn.de">Hausdorff Center for Mathematics</a>
at the <a href="https://www.uni-bonn.de/">University of Bonn</a>, Germany.
Please see also the school's <a
href="https://www.hcm.uni-bonn.de/events/eventpages/hausdorff-school/hausdoff-school-2020/the-p4est-software-for-parallel-amr/">home
page and application forms</a>.
</p>
<article>
<section>
<h2>The roots of the forest</h2>
<p class="book">
The mesh topology of <tt>p4est</tt> is a general forest of octrees.
Each octree is a logical hypercube.
To represent a general and possibly non-cubic domain \(\Omega\),
we begin by covering it with a conforming mesh of (potentially mapped)
squares (2D) or cubes (3D).
This coarsest possible mesh or <emph>connectivity</emph> cannot be changed
during the simulation.
In particular, it cannot be coarsened further.
It is thus wise to design it carefully.
A few guidelines are:
</p>
<ol class="book">
<li>Use as many cubes as needed to capture the domain's topology (connected
components, holes, tunnels, etc.).</li>
<li>Invest some more cubes to achieve an ideally uniform individual aspect
ratio of each cube.</li>
<li>Invest some more cubes if the distortion in any single mapped octree
appears too large.</li>
<li>Reduce the number of octrees if the coarse mesh must be
limited for numerical reasons.</li>
</ol>
<p class="book">
We have successfully connected millions of octrees. Below 100k, there is no
need to even think about reducing their number if the procedure would not be
obvious.
The connectivity is the first data structure that is built in a
<tt>p4est</tt> program.
This tutorial covers its definition and ways to construct it.
</p>
<dl class="spec">
<dt>Dependencies</dt><dd>
<a href="tutorial-build.html">Build</a></dd>
<dt>Required skills</dt><dd>
Knowing about the C language's <code>struct</code> and array data types</code>.
Optional: using valgrind; using a debugger.
</dd>
<dt>Skills acquired</dt><dd>
Creating and destroying <tt>p4est</tt> connectivity structures.
Saving them to a file and loading them later.
</dd>
<dt>Next steps</dt><dd>
Construct several connectivities by builtin constructor functions.
Construct a connectivity by hard-coding its members yourself.
Use each connectivity to construct a coarse <tt>p4est</tt> and visualize it via
the <a href="tutorial-io.html#vtk">VTK output</a>.
</dd>
</dl>
</section>
</section>
<h3>The <tt>p4est_connectivity</tt> data structure</h3>
<p class="book">
The convention for the connectivity's members is documented separately for the
<a href="https://github.com/cburstedde/p4est/blob/prev3-develop/src/p4est_connectivity.h#L114-L144">2D connectivity</a> and the
<a href="https://github.com/cburstedde/p4est/blob/prev3-develop/src/p8est_connectivity.h#L117-L165">3D connectivity</a>.
Note that we prefix 2D functions and objects with <code>p4est</code> and their
3D cousins with <code>p8est</code>.
</p>
<div class="image-container">
<div class="image">
<img src="images/moebius_partitioned.png">
<p class="cont">
The
<a href="https://github.com/cburstedde/p4est/blob/prev3-develop/src/p4est_connectivity.h#L391-L393">
Moebius strip</a>
is an example of a 2D connectivity embedded into 3D space.
We construct it from five trees, where an odd number of face connections has
a non-standard relative orientation.
Note that we do not need to add corner connections to the connectivity data
structure for this mesh, since there is no corner connection that is not
already a face connection.
</p>
</div>
<div class="image">
<img src="images/numbering3d.png">
<p class="cont">
The z-order convention for all boundary entities of a mesh hypercube.
This picture shows the 3D case; the 2D case is contained in the x-y-plane.
When writing all numbers in binary format, each bit corresponds
to a coordinate/normal direction.
This convention facilitates dimension-independent programming:
All entities relevant to 2D are bitwise reductions of 3D entities.
</p>
</div>
</div>
<p class="book">
In principle, there is nothing wrong with allocating and populating the
connectivity yourself.
This is, in fact, a great way to learn the meaning of its members.
However, there are other ways, too.
The easiest is to look through say the
<a href="https://github.com/cburstedde/p4est/blob/prev3-develop/src/p8est_connectivity.h">3D connectivity header</a> and call one of our predefined
<code>p8est_connectivity_new_*</code> functions.
We also offer a function to read the connectivity from an Abaqus .inp file.
</p>
<p class="book">
You may build any numbers of forests with the same connectivity object, but
please (a) destroy it only after the last of the forests has been freed and (b)
definitely destroy it.
It is advised to use the <a
href="https://valgrind.org/docs/manual/quick-start.html">valgrind tool</a>
to check for proper deallocation.
</p>
<p class="exer">
Exercise C1:
On one MPI rank, call <code>p4est_connectivity_save</code>,
<code>p4est_connectivity_load</code> and
<code>p4est_connectivity_is_equal</code> to verify that
the connectivity structure survived the file I/O.
Examine its contents with <code>gdb</code> and compare with the documentation
block in the header file.
Further down in the program, collectively call
<code>p4est_connectivity_bcast</code> to replicate the connectivity on all MPI
ranks of the world communicator.
Destroy the connectivities on all ranks.
Use <code>valgrind</code> to make sure no memory is leaked.
</p>
<p class="exer">
Exercise C2:
Write a converter to load your favorite conforming hexahedral mesh format from
disk and populate a <tt>p4est</tt> connectivity structure in memory.
Use <code>p{4,8}est_connectivity_new</code> to allocate the required memory
once the numbers of trees and edge/corner connections have been determined,
then hand-code a bunch of loops to fill all data fields with values.
Finally, check the object with <code>p{4,8}est_connectivity_is_valid</code>.
</p>
</section>
</article>
</main>
</body>
</html>