Line data Source code
1 0 : \cond NEVER
2 : Distributed under the MIT License.
3 : See LICENSE.txt for details.
4 : \endcond
5 : # %Domain Creation {#tutorial_domain_creation}
6 :
7 : \tableofcontents
8 :
9 : ### Domain Decomposition
10 : The spatial domain on which the solution is computed is divided into
11 : non-overlapping cells. For 2D and 3D domains, we use curvilinear
12 : quadrilateral and curvilinear hexahedral elements, respectively. The
13 : specification of a particular spatial domain is given by the DomainCreator.
14 : DomainCreators specify the properties of the initial elements (before AMR takes
15 : place), which are then used by Domain to create Blocks. Each Block
16 : holds a CoordinateMap (described below) as well as information about its
17 : neighbors. For geometrical domains, (e.g. rectilinear, spherical) there are a
18 : few shortcuts that can be used such that a user does not need to specify by
19 : hand the map and neighbor information for each %Block; these methods are
20 : explained below.
21 :
22 : ## CoordinateMaps
23 : Each Block in the Domain must hold a CoordinateMap which describes how to
24 : map the logical cube (a reference cell that covers the interval \f$[-1, 1]\f$
25 : in each dimension) to the curvilinear hexahedral element the %Block describes.
26 : The %CoordinateMap also provides the jacobian of the mapping.
27 :
28 : ### Shortcuts for CoordinateMaps
29 : For spherical domains, `Wedge<3>` implements the cubed-sphere map, and there
30 : exists the method `sph_wedge_coordinate_maps` in Domain/DomainHelpers.hpp to
31 : quickly construct six of these maps at once. For rectilinear multicube domains,
32 : Affine and Equiangular map the logical cubes to cartesian cubes. The method
33 : `maps_for_rectilinear_domains` in DomainHelpers allows the user to obtain
34 : the CoordinateMaps for all of the Blocks in such a domain at once. These
35 : can both be used to provide the map arguments to the Domain constructor.
36 :
37 : ## Boundary Information
38 : Each Block must know which of the other Blocks in the Domain are its
39 : neighbors and which of its logical directions points to an external boundary.
40 :
41 : ### Shortcuts for Boundary Information
42 : A quick way to encode the neighbor and boundary information for the blocks
43 : in a domain is through our convention of numbering and ordering the corners
44 : of the blocks in a well-defined way. The corner numbering scheme is described
45 : in the \ref tutorial_orientations tutorial. For spherical domains,
46 : DomainHelpers has the methods `corners_for_radially_layered_domains` and
47 : `corners_for_biradially_layered_domains`, which provides the proper corner
48 : numberings for the maps obtained from the method `sph_wedge_coordinate_maps`.
49 : These methods are used in the
50 : \ref domain::creators::Sphere "Sphere" DomainCreator.
51 : For rectilinear multicube domains, DomainHelpers has the methods
52 : `corners_for_rectilinear_domains`, which provides the proper corner
53 : numberings for the maps obtained from the method
54 : `maps_for_rectilinear_domains`.
55 :
56 : ## Creating Rectilinear Domains with Shortcuts:
57 : The construction of a rectilinear domain begins with the specification of
58 : the total extents of the domain in each cartesian direction, in terms of
59 : the number of blocks. These extents are held in an Index object.
60 : For an illustrative example, we will explain how to construct a cubical
61 : domain which has an extent of two blocks in each dimension:
62 :
63 : \image html eightcubes.png "A 2x2x2 domain."
64 :
65 : The first step is to generate the corner numbering for this Domain. For
66 : the purposes of this example, we will construct all blocks with their
67 : logical directions aligned with one another. As each block must also have
68 : an associated block id, we must be aware of the order in which the corners
69 : for each block are constructed.
70 :
71 : The algorithm `corners_for_rectilinear_domains` always begins with the block
72 : located in the lowest cartesian corner of the domain. The second block is
73 : its immediate neighbor in the \f$+x\f$ direction, and so on until the block
74 : in this row with the highest \f$x\f$ coordinate is reached. The next block is
75 : the the immediate neighbor of the lowest corner block in the \f$+y\f$
76 : direction, and then continues through the neighboring blocks in the \f$+x\f$ as
77 : before. This is the same order in which the global corners numbers are assigned
78 : to the vertices of the blocks.
79 :
80 : \image html eightcubes_numbered.png "With global corners."
81 :
82 : The block corners generated by `corners_for_rectilinear_domains` are then:
83 :
84 : ```
85 : {0,1,3,4,9,10,12,13},
86 : {1,2,4,5,10,11,13,14},
87 : {3,4,6,7,12,13,15,16},
88 : {4,5,7,8,13,14,16,17},
89 : {9,10,12,13,18,19,21,22},
90 : {10,11,13,14,19,20,22,23},
91 : {12,13,15,16,21,22,24,25},
92 : {13,14,16,17,22,23,25,26}
93 :
94 : ```
95 :
96 : What remains is to specify the CoordinateMaps that each Block will hold.
97 : This is handled by `maps_for_rectilinear_domains` and currently supports
98 : both Affine and Equiangular mappings. The coordinate extents of each map
99 : is set by the argument to `block_demarcations`. For a 2x2x1 domain, the
100 : call to `maps_for_rectilinear_domains` could be:
101 :
102 : \snippet Test_DomainHelpers.cpp show_maps_for_rectilinear_domains
103 :
104 : For this choice of arguments we obtain the maps for a domain that extends
105 : from 0.0 to 2.0 in the \f$x\f$-direction, from 0.0 to 2.0 in the \f$y\f$
106 : -direction, and from -0.4 to 0.3 in the \f$z\f$ direction.
107 :
108 : With the corners and maps in hand, we can pass these as arguments to the
109 : Domain constructor.
110 :
111 : ### Non-trivial Domain Example
112 : The aforementioned functions can also take an additional argument to exclude
113 : blocks from a domain. For this one needs to know the Index<Dim> for each block
114 : they wish to exclude from the domain. For the 2x2x2 domain example, the block
115 : indices are:
116 :
117 : ```
118 : {0,0,0},
119 : {1,0,0},
120 : {0,1,0},
121 : {1,1,0},
122 : {0,0,1},
123 : {1,0,1},
124 : {0,1,1},
125 : {1,1,1}
126 :
127 : ```
128 :
129 : In this example, we construct a domain with topology \f$S^3\f$, which begins
130 : with the net for a tesseract. We begin by specifying that the domain extents
131 : are three blocks along the \f$x\f$ and \f$y\f$ directions, and four blocks
132 : along the \f$z\f$ direction. In addition, we exclude the following block
133 : indices:
134 :
135 : ```
136 : {0,0,0}, //first block
137 : {1,0,0}, //second block
138 : {2,0,0}, //third block
139 : {0,1,0}, //fourth block
140 : {2,1,0}, //sixth block
141 : {0,2,0}, //seventh block
142 : {1,2,0}, //eight block
143 : {2,2,0}, //ninth block
144 :
145 : {0,0,1}, //10th block
146 : {1,0,1}, //11th block
147 : {2,0,1}, //12th block
148 : {0,1,1}, //13th block
149 : {2,1,1}, //15th block
150 : {0,2,1}, //16th block
151 : {1,2,1}, //17th block
152 : {2,2,1}, //18th block
153 :
154 : {0,0,2}, //19th block
155 : {2,0,2}, //21st block
156 : {0,2,2}, //25th block
157 : {2,2,2}, //27th block
158 :
159 : {0,0,2}, //28rd block
160 : {1,0,2}, //29th block
161 : {2,0,2}, //30th block
162 : {0,1,2}, //31th block
163 : {2,1,2}, //33th block
164 : {0,2,2}, //34th block
165 : {1,2,2}, //35th block
166 : {2,2,2}, //36th block
167 :
168 : ```
169 : Alternatively, we can exclude none of the blocks in this way and instead
170 : selectively copy the block corners from the returned vector into a new vector
171 : that only contains the corners for the desired blocks, if one prefers to work
172 : with single-number array indices as opposed to tuples.
173 :
174 : Either way, we end up with a vector of block corners corresponding to the
175 : following diagram:
176 :
177 : \image html tesseract_numbered.png "A numbered tesseract net."
178 :
179 : The maps are obtained similarly. In this case we suggest using the Equiangular
180 : maps for this Domain since they adapt the logical coordinates to the angular
181 : coordinates on a sphere. We also need to identify corresponding faces with each
182 : other to obtain a domain of topology \f$S^3\f$, so we also need to supply the
183 : constructor of Domain with PairsOfFaces. For the \f$S^3\f$ domain, these faces
184 : are:
185 :
186 : ```
187 :
188 : //Folding highest cube downward:
189 : {{53,54,69,70},{53,54,49,50}},
190 : {{53,57,69,73},{53,57,52,56}},
191 : {{57,58,61,62},{57,58,73,74}},
192 : {{54,58,70,74},{54,58,55,59}},
193 :
194 : //Folding cross cubes together:
195 : {{54,55,38,39},{54,50,38,34}},
196 : {{58,59,42,43},{58,62,42,46}},
197 : {{53,52,37,36},{53,49,37,33}},
198 : {{57,56,41,40},{57,61,41,45}},
199 :
200 : //Folding second lowest cube upward:
201 : {{38,42,39,43},{38,42,22,26}},
202 : {{33,34,37,38},{21,22,37,38}},
203 : {{36,37,40,41},{21,37,25,41}},
204 : {{41,42,45,46},{41,42,25,26}},
205 :
206 : //Folding bottom cube around domain:
207 : {{33,34,49,50},{21,22,5,6}},
208 : {{39,43,55,59},{22,26,6,10}},
209 : {{45,46,61,62},{25,26,9,10}},
210 : {{36,40,52,56},{21,25,5,9}},
211 : {{5,6,9,10},{69,70,73,74}}
212 :
213 : ```
|