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