SpECTRE Documentation Coverage Report
 Current view: top level - __w/spectre/spectre/docs/Tutorials - DomainCreation.md Hit Total Coverage Commit: 2db722c93a8e9b106e406b439b79c8e05c2057fb Lines: 0 1 0.0 % Date: 2021-03-03 22:01:00 Legend: Lines: hit not hit
  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 : non-overlapping 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 cubed-sphere 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 well-defined 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 : ### Non-trivial 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 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 single-number 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 :  

 Generated by: LCOV version 1.14