Line data Source code
1 0 : \cond NEVER
2 : Distributed under the MIT License.
3 : See LICENSE.txt for details.
4 : \endcond
5 : # OrientationMap {#tutorial_orientations}
6 :
7 : \tableofcontents
8 :
9 : ### Introduction
10 : Each element in a domain has a set of internal directions which it uses
11 : for computations in its own local coordinate system. These are referred to
12 : as the logical directions \f$\xi\f$, \f$\eta\f$, and \f$\zeta\f$, where
13 : \f$\xi\f$ is the first dimension, \f$\eta\f$ is the second dimension, and
14 : \f$\zeta\f$ is the third dimension. In a
15 : domain with multiple Blocks, the logical directions are not necessarily
16 : aligned on the interfaces between two Blocks, as shown in the figure below.
17 : As certain operations (e.g. fluxes, limiting) communicate information across
18 : the boundaries of adjacent elements, there needs to be a class that takes
19 : into account the relative orientations of elements which neighbor each other.
20 : This class is OrientationMap.
21 :
22 : ### %OrientationMaps between %Blocks
23 : Each Block in a Domain has a set of BlockNeighbors, which each hold an
24 : OrientationMap. In this scenario, the Block is referred to as the host, and
25 : the OrientationMap held by each BlockNeighbor is referred to as "the
26 : orientation the BlockNeighbor has with respect to the host Block." This is
27 : a convention, so we give an example of constructing and assigning the correct
28 : OrientationMaps:
29 :
30 : \image html twocubes.png "Two neighboring blocks."
31 :
32 : In the image above, we see a domain decomposition into two Blocks, which have
33 : their logical axes rotated relative to one another. With the left block as
34 : the host Block, we see that it has a neighbor in the \f$+\xi\f$ direction.
35 : The host Block holds a `std::unordered_map` from Directions to BlockNeighbors;
36 : the BlockNeighbor itself holds an OrientationMap that determines the mapping
37 : from each logical direction in the host Block to that in the neighboring Block.
38 : That is, the OrientationMap takes as input local information (i.e. logical
39 : directions in the host's coordinate system) and returns neighbor information
40 : (i.e. logical directions in the neighbor's coordinate system). An
41 : OrientationMap is constructed by passing in the block neighbor directions that
42 : correspond to the \f$+\xi\f$, \f$+\eta\f$, \f$+\zeta\f$ directions in the host.
43 : In this case, these directions in the host map to the \f$+\zeta\f$,
44 : \f$+\xi\f$, \f$+\eta\f$ directions in the neighbor, respectively.
45 : This BlockNeighbor thus holds the OrientationMap constructed with the list
46 : (\f$+\zeta\f$, \f$+\xi\f$, \f$+\eta\f$). With the right block as the host
47 : block, we see that it has a BlockNeighbor in the \f$-\zeta\f$ direction, and
48 : the OrientationMap held by this BlockNeighbor is the one constructed with the
49 : array (\f$+\eta\f$, \f$+\zeta\f$, \f$+\xi\f$). For convenience, OrientationMap
50 : has a method `inverse_map` which returns the OrientationMap that takes as input
51 : neighbor information and returns local information.
52 :
53 : OrientationMaps need to be provided for each BlockNeighbor in each direction
54 : for each Block. This quickly becomes too large of a number to determine by
55 : hand as the number of Blocks and the number of dimensions increases. A remedy
56 : to this problem is the corner numbering scheme.
57 :
58 : ### Encoding BlockNeighbor information using Corner Orderings and Numberings
59 : The orientation of the \f${dim}\f$ logical directions within each element
60 : determines an ordering of the \f$2^{dim}\f$ vertices of that element. This is
61 : called the local corner numbering scheme (Local CNS) with respect to that
62 : element. We give the ordering of the local corners below for the case of a
63 : three-dimensional element:
64 :
65 : \image html onecube_numbered.png "The local corner numbering."
66 :
67 : ```
68 : Corner 0 is the location of the lower xi, lower eta, lower zeta corner.
69 : Corner 1 is the location of the upper xi, lower eta, lower zeta corner.
70 : Corner 2 is the location of the lower xi, upper eta, lower zeta corner.
71 : Corner 3 is the location of the upper xi, upper eta, lower zeta corner.
72 : Corner 4 is the location of the lower xi, lower eta, upper zeta corner.
73 : Corner 5 is the location of the upper xi, lower eta, upper zeta corner.
74 : Corner 6 is the location of the lower xi, upper eta, upper zeta corner.
75 : Corner 7 is the location of the upper xi, upper eta, upper zeta corner.
76 : ```
77 :
78 : What remains is to endow the domain decomposition with a global corner
79 : numbering (Global CNS). We give an example below:
80 :
81 : \image html twocubes_numbered.png "A global corner numbering."
82 :
83 : In the image above, we see that each vertex of the two-block domain has
84 : been assigned a number. Although each block has eight corners, four are
85 : shared among them, so there are only twelve unique corners in this domain.
86 : Any numbering may be used in the global corner numbering, so long as the
87 : each distinct corner is given a single distinct corner number.
88 :
89 : \note This Global CNS assumes that there is no additional identifying of faces
90 : with one another for periodic boundary conditions. That is, each element must
91 : have \f$2^{dim}\f$ distinct corner numbers. If you wish to additionally
92 : identify faces of the same block with each other, that must be done in an
93 : additional step. This step is explained in the "Setting Periodic Boundary
94 : Conditions" section.
95 :
96 : ### The Ordered Subset of the Global CNS (Subset CNS):
97 : With the Global CNS in hand, each Block inherits an ordered subset of Global
98 : CNS. The ordering in this set is determined by the ordering of the Local CNS,
99 : and the elements of the set determined by how one assigned the Global CNS to
100 : the Domain. For the image above, the Subset CNS corresponding to the left block
101 : is {0, 1, 3, 4, 6, 7, 9, 10}, while the Subset CNS corresponding to the right
102 : block is {1, 4, 7, 10, 2, 5, 8, 11}. This ordering of the Subset CNS encodes
103 : the relative orientations between each Block. Subset CNSs need to be provided
104 : for each Block in a Domain. It turns out that for very regular domains,
105 : (i.e. spherical or rectilinear) we can generate the appropriate Subset CNSs.
106 : As this is a conceptual tutorial, how to construct these domains in SpECTRE
107 : is described in the \ref tutorial_domain_creation tutorial.
108 :
109 : ### Explanation of the Algorithms in DomainHelpers:
110 :
111 : For illustrative purposes, we will use the following Domain composed of two
112 : Blocks as described above as an example.
113 : Because there are 12 corners in this Domain, we will arbitrarily assign a
114 : unique id to each corner.
115 : Knowing the orientation of the logical axes within a block, we construct a
116 : Subset CNS for each Block.<br>
117 : Here is one possible result, given some relative orientation between the
118 : blocks:
119 :
120 : ```
121 : Block1: {0, 1, 3, 4, 6, 7, 9, 10}
122 : Block2: {1, 4, 7, 10, 2, 5, 8, 11}
123 : ```
124 :
125 : The values of the ids only serve to identify which corners are unique and which
126 : are shared. This is determined by the Global CNS. The order of the ids in the
127 : list is determined by the Local CNS. We take advantage of the fact that the
128 : array index of the global corner id is the number of the corner in the local
129 : CNS.
130 :
131 : The algorithm begins by determining the shared corners between the
132 : Blocks:
133 :
134 : ```
135 : result: {1, 4, 7, 10}
136 : ```
137 :
138 : The next step is to determine the local ids of these shared global ids:
139 :
140 : ```
141 : Block1 result: {1,3,5,7}
142 : Block2 result: {0,1,2,3}
143 : ```
144 :
145 : The next step is to convert these ids into their binary representation.
146 : For reference, we give the binary representation for each number 0-7:
147 :
148 : ```
149 : Corner 0: 000
150 : Corner 1: 001
151 : Corner 2: 010
152 : Corner 3: 011
153 : Corner 4: 100
154 : Corner 5: 101
155 : Corner 6: 110
156 : Corner 7: 111
157 : ```
158 :
159 : Here 0 and 1 indicate lower and upper in the corresponding axis (zeta,
160 : eta, xi), respectively, and the ordering has been reversed so that the
161 : rightmost column corresponds to the xi position and the leftmost column
162 : to the zeta position. Returning to the example at hand, we have:
163 :
164 :
165 : ```
166 : Block1 result: {001,011,101,111}
167 : Block2 result: {000,001,010,011}
168 : ```
169 :
170 : Note that we can now read off the shared face relative to each Block
171 : easily:
172 :
173 : ```
174 : Block1 result: Upper xi (All binary Block1 ids have a 1 in the third position)
175 : Block2 result: Lower zeta (All binary Block2 ids have a 0 in the first position)
176 : ```
177 :
178 : Now we know that `Direction<3>::%upper_xi()`
179 : in Block1 corresponds to `Direction<3>::%lower_zeta().%opposite()` in Block2.
180 :
181 : The use of `.%opposite()` is a result of the Directions to a Block face being
182 : anti-parallel because each Block lies on the opposite side of the shared face.
183 : <br>
184 :
185 : The remaining two correspondences are given by the alignment of the shared
186 : face. It is useful to know the following information:<br>
187 : In the Local CNS, if an edge lies along the xi direction, if one takes the
188 : two corners making up that edge and takes the difference of their ids, one
189 : always gets the result \f$ \pm 1\f$. Similarly, if the edge lies in the eta
190 : direction, the result will be \f$ \pm 2\f$. Finally, if the edge lies in the
191 : zeta direction, the result will be \f$ \pm 4\f$. We use this information to
192 : determine the alignment of the shared face:
193 :
194 : ```
195 : Block1: 3-1=2 => This edge is in the +eta direction.
196 : Block2: 1-0=1 => This edge is in the +xi direction.
197 : Then, +eta in Block1 corresponds to +xi in Block2.
198 :
199 : Block1: 5-1=4 => This edge is in the +zeta direction.
200 : Block2: 2-0=2 => This edge is in the +eta direction.
201 : Then, +zeta in Block1 corresponds to +eta in Block2.
202 : ```
203 :
204 : The corresponding directions in each Block have now been deduced.
205 :
206 : To confirm, we can use the other ids as well and arrive at the same result:<br>
207 :
208 : ```
209 : Block1: 7-5=2 => +eta
210 : Block2: 3-2=1 => +xi
211 :
212 : Block1: 7-3=4 => +zeta
213 : Block2: 3-1=2 => +eta
214 : ```
215 :
216 : ### Setting Periodic Boundary Conditions
217 : It is also possible to identify faces of a Block using the subset CNS. For
218 : example, to identify the lower zeta face with the upper zeta face of a Block
219 : where the corners are labeled `{3,0,4,1,9,6,10,7}`, one may supply the lists
220 : `{3,0,4,1}` and `{9,6,10,7}` to the `set_identified_boundaries` function.
221 : \note The `set_identified_boundaries` function is sensitive to the order of the
222 : corners in the lists supplied as arguments. This is because the function
223 : identifies corners and edges with each other as opposed to simply faces. This
224 : allows the user to specify more peculiar boundary conditions. For example,
225 : using `{3,0,4,1}` and `{6,7,9,10}` to set the periodic boundaries will identify
226 : the lower zeta face with the upper zeta face, but after a rotation of a
227 : quarter-turn.
228 :
229 : For reference, here are the corners to use for each face for a Block with
230 : corners labelled as `{0,1,2,3,4,5,6,7}` to set up periodic boundary conditions
231 : in each dimension, i.e. a \f$\mathrm{T}^3\f$ topology:
232 :
233 : Face | Corners
234 : ------|--------
235 : upper xi| `{1,3,5,7}`
236 : lower xi| `{0,2,4,6}`
237 : upper eta| `{2,3,6,7}`
238 : lower eta| `{0,1,4,5}`
239 : upper zeta| `{4,5,6,7}`
240 : lower zeta| `{0,1,2,3}`
|
