SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs/Tutorials - DomainCreation.md Hit Total Coverage
Commit: d0fc80462417e83e5cddfa1b9901bb4a9b6af4d6 Lines: 0 1 0.0 %
Date: 2024-03-29 00:33:31
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             : \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             : ```

Generated by: LCOV version 1.14