Line data    Source code

       1           1 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : /// \file
       5             : /// Defines class ElementId.
       6             : 
       7             : #pragma once
       8             : 
       9             : #include <array>
      10             : #include <cstddef>
      11             : #include <cstdint>
      12             : #include <functional>
      13             : #include <iosfwd>
      14             : #include <optional>
      15             : #include <string>
      16             : 
      17             : #include "Domain/Structure/Direction.hpp"
      18             : #include "Domain/Structure/SegmentId.hpp"
      19             : #include "Domain/Structure/Side.hpp"
      20             : 
      21             : /// \cond
      22             : namespace PUP {
      23             : class er;
      24             : }  // namespace PUP
      25             : /// \endcond
      26             : 
      27             : /*!
      28             :  * \ingroup ComputationalDomainGroup
      29             :  * \brief An ElementId uniquely labels an Element.
      30             :  *
      31             :  * It is constructed from the BlockId of the Block to which the Element belongs
      32             :  * and the VolumeDim SegmentIds that label the segments of the Block that the
      33             :  * Element covers. An optional `grid_index` identifies elements with the same
      34             :  * BlockId and SegmentIds across multiple grids.
      35             :  *
      36             :  * \details
      37             :  * The `ElementId` serves as an index that is compatible with Charm++ and
      38             :  * therefore must adhere to the restrictions imposed by Charm++. These are:
      39             :  * - `ElementId` must satisfy `std::is_pod`
      40             :  * - `ElementId` must not be larger than the size of three `int`s, i.e.
      41             :  *   `sizeof(ElementId) <= 3 * sizeof(int)`
      42             :  */
      43             : template <size_t VolumeDim>
      44           1 : class alignas(int[2]) ElementId {  // NOLINT(modernize-avoid-c-arrays)
      45             :  public:
      46             :   // We restrict the ElementId size to 64 bits for easy hashing into
      47             :   // size_t. This still allows us to have over 9 quadrillion elements, which is
      48             :   // probably enough. 2^45 * 2^8 9 quadrillion elements per grid index, with
      49             :   // up to 16 grid indices.
      50             :   //
      51             :   // Note: C++ populates bits from right to left in order of the
      52             :   // variables. This gives us the direction_mask we use below.
      53           0 :   static constexpr size_t block_id_bits = 8;
      54           0 :   static constexpr size_t grid_index_bits = 4;
      55           0 :   static constexpr size_t direction_bits = 4;
      56             :   /// The maximum allowed refinement level
      57           1 :   static constexpr size_t max_refinement_level = 15;
      58           0 :   static constexpr uint64_t direction_shift =
      59             :       static_cast<uint64_t>(block_id_bits + grid_index_bits);
      60           0 :   static constexpr uint64_t direction_mask = static_cast<uint64_t>(0b1111)
      61             :                                              << direction_shift;
      62             :   static_assert(block_id_bits + 3 * (1 + max_refinement_level) +
      63             :                         grid_index_bits + direction_bits ==
      64             :                     static_cast<size_t>(2 * 8) * sizeof(int),
      65             :                 "Bit representation requires padding or is too large");
      66             : 
      67           0 :   static constexpr size_t volume_dim = VolumeDim;
      68             : 
      69             :   /// Default constructor needed for Charm++ serialization.
      70           1 :   ElementId() = default;
      71           0 :   ElementId(const ElementId&) = default;
      72           0 :   ElementId& operator=(const ElementId&) = default;
      73           0 :   ElementId(ElementId&&) = default;
      74           0 :   ElementId& operator=(ElementId&&) = default;
      75           0 :   ~ElementId() = default;
      76             : 
      77             :   /// Create the ElementId of the root Element of a Block.
      78           1 :   explicit ElementId(size_t block_id, size_t grid_index = 0);
      79             : 
      80             :   /// Create an arbitrary ElementId.
      81           1 :   ElementId(size_t block_id,
      82             :             const std::array<SegmentId, VolumeDim>& segment_ids,
      83             :             size_t grid_index = 0);
      84             : 
      85             :   /// Create an ElementId from its string representation (see `operator<<`).
      86           1 :   explicit ElementId(const std::string& grid_name);
      87             : 
      88           0 :   ElementId<VolumeDim> id_of_child(size_t dim, Side side) const;
      89             : 
      90           0 :   ElementId<VolumeDim> id_of_parent(size_t dim) const;
      91             : 
      92           0 :   size_t block_id() const { return block_id_; }
      93             : 
      94           0 :   size_t grid_index() const { return grid_index_; }
      95             : 
      96           0 :   std::array<size_t, VolumeDim> refinement_levels() const;
      97             : 
      98           0 :   std::array<SegmentId, VolumeDim> segment_ids() const;
      99             : 
     100           0 :   SegmentId segment_id(size_t dim) const;
     101             : 
     102             :   /// Returns an ElementId meant for identifying data on external boundaries,
     103             :   /// which does not correspond to the Id of an actual element.
     104           1 :   static ElementId<VolumeDim> external_boundary_id();
     105             : 
     106             :   /*!
     107             :    * \brief Returns a compact ID containing only the segment ID bits,
     108             :    * with block_id, grid_index, and direction bits stripped.
     109             :    *
     110             :    * This is useful for identifying elements in visualization tools
     111             :    * like ParaView.
     112             :    */
     113           1 :   size_t to_short_id() const;
     114             : 
     115             :   /// Returns the number of block boundaries the element has.
     116           1 :   size_t number_of_block_boundaries() const;
     117             : 
     118             :  protected:
     119             :   /// Create an `ElementId` in a specified direction.
     120           1 :   ElementId(const Direction<VolumeDim>& direction,
     121             :             const ElementId<VolumeDim>& element_id);
     122             : 
     123           0 :   Direction<VolumeDim> direction() const;
     124             : 
     125           0 :   ElementId without_direction() const;
     126             : 
     127             :  private:
     128             :   template <size_t Dim>
     129             :   // NOLINTNEXTLINE(readability-redundant-declaration)
     130           0 :   friend bool operator==(const ElementId<Dim>& lhs, const ElementId<Dim>& rhs);
     131             : 
     132             :   template <size_t Dim>
     133             :   // NOLINTNEXTLINE(readability-redundant-declaration)
     134           0 :   friend bool operator<(const ElementId<Dim>& lhs, const ElementId<Dim>& rhs);
     135             : 
     136             :   template <size_t Dim>
     137             :   // NOLINTNEXTLINE(readability-redundant-declaration)
     138           1 :   friend bool is_zeroth_element(const ElementId<Dim>& id,
     139             :                                 const std::optional<size_t>& grid_index);
     140             : 
     141           0 :   ElementId(uint8_t block_id, uint8_t grid_index, uint8_t direction,
     142             :             uint16_t compact_segment_id_xi, uint16_t compact_segment_id_eta,
     143             :             uint16_t compact_segment_id_zeta);
     144             : 
     145           0 :   uint8_t block_id_ : block_id_bits;
     146           0 :   uint8_t grid_index_ : grid_index_bits;
     147           0 :   uint8_t direction_ : direction_bits;  // end first 16 bits
     148             :   // each of the following is 16 bits in length
     149           0 :   uint16_t compact_segment_id_xi_ : max_refinement_level + 1;
     150           0 :   uint16_t compact_segment_id_eta_ : max_refinement_level + 1;
     151           0 :   uint16_t compact_segment_id_zeta_ : max_refinement_level + 1;
     152             : };
     153             : 
     154             : /// \cond
     155             : // clang-format off
     156             : // macro that generate the pup operator for SegmentId
     157             : PUPbytes(ElementId<1>)      // NOLINT
     158             : PUPbytes(ElementId<2>)  // NOLINT
     159             : PUPbytes(ElementId<3>)  // NOLINT
     160             : /// \endcond
     161             : 
     162             : /// Output operator for ElementId.
     163             : template <size_t VolumeDim>
     164           1 : std::ostream& operator<<(std::ostream& os, const ElementId<VolumeDim>& id);
     165             : // clang-format on
     166             : 
     167             : /// Equivalence operator for ElementId.
     168             : template <size_t VolumeDim>
     169             : bool operator==(const ElementId<VolumeDim>& lhs,
     170             :                 const ElementId<VolumeDim>& rhs);
     171             : 
     172             : /// Inequivalence operator for ElementId.
     173             : template <size_t VolumeDim>
     174             : bool operator!=(const ElementId<VolumeDim>& lhs,
     175             :                 const ElementId<VolumeDim>& rhs);
     176             : 
     177             : /// Define an ordering of element IDs first by grid index, then by block ID,
     178             : /// then by segment ID in each dimension in turn. In each dimension, segment IDs
     179             : /// are ordered first by refinement level (which will typically be the same when
     180             : /// comparing two element IDs), and second by index. There's no particular
     181             : /// reason for this choice of ordering. For applications such as distributing
     182             : /// elements among cores, orderings such as defined by
     183             : /// `domain::BlockZCurveProcDistribution` may be more appropriate.
     184             : template <size_t VolumeDim>
     185           1 : bool operator<(const ElementId<VolumeDim>& lhs,
     186             :                const ElementId<VolumeDim>& rhs);
     187             : 
     188             : template <size_t VolumeDim>
     189           0 : bool operator>(const ElementId<VolumeDim>& lhs,
     190             :                const ElementId<VolumeDim>& rhs) {
     191             :   return rhs < lhs;
     192             : }
     193             : template <size_t VolumeDim>
     194           0 : bool operator<=(const ElementId<VolumeDim>& lhs,
     195             :                 const ElementId<VolumeDim>& rhs) {
     196             :   return !(lhs > rhs);
     197             : }
     198             : template <size_t VolumeDim>
     199           0 : bool operator>=(const ElementId<VolumeDim>& lhs,
     200             :                 const ElementId<VolumeDim>& rhs) {
     201             :   return !(lhs < rhs);
     202             : }
     203             : 
     204             : /// \ingroup ComputationalDomainGroup
     205             : /// Check if two elements overlap, i.e., they are in the same block
     206             : /// and all their segments overlap.
     207             : template <size_t VolumeDim>
     208           1 : bool overlapping(const ElementId<VolumeDim>& a, const ElementId<VolumeDim>& b);
     209             : 
     210             : /// @{
     211             : /// \brief Returns a bool if the element is the zeroth element in the domain.
     212             : ///
     213             : /// \details An element is considered to be the zeroth element if its ElementId
     214             : /// `id` has
     215             : /// 1. id.block_id() == 0
     216             : /// 2. All id.segment_ids() have SegmentId.index() == 0
     217             : /// 3. If the argument `grid_index` is specified, id.grid_index() == grid_index.
     218             : ///
     219             : /// This means that the only element in a domain that this function will return
     220             : /// `true` for is the element in the lower corner of Block0 of that domain. The
     221             : /// `grid_index` will determine which domain is used for the comparison. During
     222             : /// evolutions, only one domain will be active at a time so it doesn't make
     223             : /// sense to compare the `grid_index`. However, during an elliptic solve
     224             : /// when there are multiple grids, this `grid_index` is useful for specifying
     225             : /// only one element over all domains.
     226             : ///
     227             : /// This function is useful if you need a unique element in the domain because
     228             : /// only one element in the whole domain can be the zeroth element.
     229             : ///
     230             : /// \parblock
     231             : /// \warning If you have multiple grids and you don't specify the `grid_index`
     232             : /// argument, this function will return `true` for one element in every grid
     233             : /// and thus can't be used to determine a unique element in a simulation; only a
     234             : /// unique element in each grid.
     235             : /// \endparblock
     236             : /// \parblock
     237             : /// \warning If the domain is re-gridded, a different ElementId may represent
     238             : /// the zeroth element.
     239             : /// \endparblock
     240             : template <size_t Dim>
     241           1 : bool is_zeroth_element(const ElementId<Dim>& id,
     242             :                        const std::optional<size_t>& grid_index);
     243             : 
     244             : // This overload is added (instead of adding a default value for grid_index)
     245             : // in order to avoid adding DomainStructures as a dependency of Parallel
     246             : // by using a forward declaration in Parallel/DistributedObject.hpp
     247             : template <size_t Dim>
     248           1 : bool is_zeroth_element(const ElementId<Dim>& id);
     249             : /// @}
     250             : // ######################################################################
     251             : // INLINE DEFINITIONS
     252             : // ######################################################################
     253             : 
     254             : template <size_t VolumeDim>
     255           0 : size_t hash_value(const ElementId<VolumeDim>& id);
     256             : 
     257             : // NOLINTNEXTLINE(cert-dcl58-cpp)
     258             : namespace std {
     259             : template <size_t VolumeDim>
     260             : struct hash<ElementId<VolumeDim>> {
     261             :   size_t operator()(const ElementId<VolumeDim>& id) const;
     262             : };
     263             : }  // namespace std
     264             : 
     265             : template <size_t VolumeDim>
     266           1 : inline bool operator==(const ElementId<VolumeDim>& lhs,
     267             :                        const ElementId<VolumeDim>& rhs) {
     268             :   // Note: Direction is intentionally skipped.
     269             :   return lhs.block_id_ == rhs.block_id_ and
     270             :          lhs.grid_index_ == rhs.grid_index_ and
     271             :          lhs.compact_segment_id_xi_ == rhs.compact_segment_id_xi_ and
     272             :          lhs.compact_segment_id_eta_ == rhs.compact_segment_id_eta_ and
     273             :          lhs.compact_segment_id_zeta_ == rhs.compact_segment_id_zeta_;
     274             : }
     275             : 
     276             : template <size_t VolumeDim>
     277           1 : inline bool operator!=(const ElementId<VolumeDim>& lhs,
     278             :                        const ElementId<VolumeDim>& rhs) {
     279             :   return not(lhs == rhs);
     280             : }