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<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 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