SpECTRE Documentation Coverage Report
Current view: top level - DataStructures/DataBox - Tag.hpp Hit Total Coverage
Commit: 9a905b0737f373631c1b8e8389b8f26e67fa5313 Lines: 5 6 83.3 %
Date: 2024-03-28 09:03:18
Legend: Lines: hit not hit

          Line data    Source code
       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : namespace db {
       7             : /*!
       8             :  * \ingroup DataBoxGroup
       9             :  * \brief Mark a struct as a simple tag by inheriting from this.
      10             :  *
      11             :  * \details
      12             :  * A simple tag is used to uniquely identify an item in a tagged container such
      13             :  * as a `DataBox`, `Variables`, or tuples::TaggedTuple.
      14             :  *
      15             :  * A simple tag may be the base class of a compute tag. In such a case, the
      16             :  * simple tag can be used to fetch the item corresponding to the compute tag
      17             :  * from a DataBox.
      18             :  *
      19             :  * A simple tag may be derived from a base tag.  In such a case, the base tag
      20             :  * can be used to fetch the item corresponding to the simple tag from a DataBox.
      21             :  * Also the simple tags should have a type alias `base` that is the base tag.
      22             :  *
      23             :  * \derivedrequires
      24             :  * - type alias `type` of the type of the item corresponding to the simple tag
      25             :  *
      26             :  * A simple tag may optionally specify a static `std::string name()` method to
      27             :  * override the default name produced by db::tag_name.
      28             :  *
      29             :  * \warning Do not derive a simple tag from another simple tag.
      30             :  *
      31             :  * \example
      32             :  * \snippet Test_DataBox.cpp databox_tag_example
      33             :  *
      34             :  * \see DataBoxGroup BaseTag ComputeTag PrefixTag
      35             :  */
      36           1 : struct SimpleTag {};
      37             : 
      38             : /*!
      39             :  * \ingroup DataBoxGroup
      40             :  * \brief Mark a (usually) empty struct as a base tag by inheriting from this.
      41             :  *
      42             :  * \details
      43             :  * A base tag may be the base class of a simple tag.  In such a case, the base
      44             :  * tag can be used to fetch the item corresponding to the simple tag (or a
      45             :  * compute tag derived from that simple tag) from a DataBox.
      46             :  *
      47             :  * Base tags are empty structs and therefore do not contain information about
      48             :  * the type of the object to which they refer.  Base tags are designed so that
      49             :  * retrieving items from the DataBox or setting argument tags in compute items
      50             :  * can be done without any knowledge of the type of the item.
      51             :  *
      52             :  * Base tags should be used rarely, only in cases where it is difficult to
      53             :  * propagate the type information to the call site.  Please consult a core
      54             :  * developer before introducing a new base tag.
      55             :  *
      56             :  * By convention, the name of a base tag should either be the name of the simple
      57             :  * tag that derives from it appended by `Base`.  Alternatively, if the simple
      58             :  * tag is templated with a type used to determine its `type` type alias, the
      59             :  * base tag can have the same name as the simple tag template with an empty
      60             :  * template parameter list.
      61             :  *
      62             :  * A base tag may optionally specify a static `std::string name()` method to
      63             :  * override the default name produced by db::tag_name.
      64             :  *
      65             :  * \warning Do not derive a base tag from anything besides db::BaseTag.
      66             :  *
      67             :  * \see DataBoxGroup SimpleTag
      68             :  */
      69           1 : struct BaseTag {};
      70             : 
      71             : /*!
      72             :  * \ingroup DataBoxGroup
      73             :  * \brief Mark a struct as a prefix tag by inheriting from this.
      74             :  *
      75             :  * \details
      76             :  * A prefix tag is used to create a new simple tag from another simple tag, and
      77             :  * therefore should also be marked as a simple tag by inheriting from
      78             :  * db::SimpleTag.
      79             :  *
      80             :  * The primary reason to mark a simple tag as a prefix tag is that the name
      81             :  * generated by db::tag_name will be constructed from the names of the prefix
      82             :  * tag and the wrapped simple tag.
      83             :  *
      84             :  * \derivedrequires
      85             :  * - type alias `tag` of the wrapped simple tag
      86             :  * - type alias `type` of the type of the item corresponding to the prefix tag
      87             :  *
      88             :  * A prefix tag may optionally specify a static `std::string name()` method to
      89             :  * override the default name produced by db::tag_name.
      90             :  *
      91             :  * \warning A prefix tag should only be derived from db::PrefixTag and
      92             :  * db::SimpleTag.
      93             :  *
      94             :  * \warning A prefix tag should only wrap a single tag.  This is assumed by all
      95             :  * metafunctions that make use of the `tag` type alias of a prefix tag.
      96             :  *
      97             :  * \example
      98             :  * A PrefixTag tag has the structure:
      99             :  * \snippet Test_DataBox.cpp databox_prefix_tag_example
     100             :  *
     101             :  * \see SimpleTag
     102             :  */
     103           1 : struct PrefixTag {};
     104             : 
     105             : /*!
     106             :  * \ingroup DataBoxGroup
     107             :  * \brief Mark a struct as a compute tag by inheriting from this.
     108             :  *
     109             :  * \details
     110             :  * A compute tag is used to identify an item in a DataBox that will be computed
     111             :  * on-demand from other items in the DataBox.  A compute tag must be derived
     112             :  * from a simple tag corresponding to the type of object that is computed.  This
     113             :  * simple tag can be used to fetch the item corresponding to the compute tag
     114             :  * from a DataBox.
     115             :  *
     116             :  * A compute tag contains a member named `function` that is either a static
     117             :  * constexpr function pointer, or a static function. The compute tag must also
     118             :  * have a a type alias `argument_tags` that is a typelist of the tags that will
     119             :  * be retrieved from the DataBox and whose data will be passed to the function
     120             :  * (pointer). Compute tags must also contain a type alias named `return_type`
     121             :  * that is the type the function is mutating. The type must be default
     122             :  * constructible.
     123             :  *
     124             :  * By convention, the name of a compute tag should be the name of the simple tag
     125             :  * that it derives from, appended by `Compute`.
     126             :  *
     127             :  * \derivedrequires
     128             :  * - type alias `return_type` of the type of the item computed
     129             :  * - type alias `base` that is the simple tag from which it is derived
     130             :  * - member `function`that is either a function pointer, or a static constexpr
     131             :  *   function that is used to compute the item from the `argument_tags` fetched
     132             :  *   from the DataBox
     133             :  * - type alias `argument_tags` that is a `tmpl::list` of the tags of the items
     134             :  *   that will be passed (in order) to the function specified by `function`
     135             :  *
     136             :  * A compute tag may optionally specify a static `std::string name()` method to
     137             :  * override the default name produced by db::tag_name.
     138             :  *
     139             :  * \warning A compute tag should only be derived from a simple tag and
     140             :  * db::ComputeTag.
     141             :  *
     142             :  * \example
     143             :  * Compute tags are of the form:
     144             :  * \snippet Test_DataBox.cpp databox_mutating_compute_item_tag
     145             :  * where the function is:
     146             :  * \snippet Test_DataBox.cpp databox_mutating_compute_item_function
     147             :  *
     148             :  * You can also have `function` be a function instead of a function pointer,
     149             :  * which offers a lot of simplicity for very simple compute items.
     150             :  * \snippet Test_DataBox.cpp compute_item_tag_function
     151             :  *
     152             :  * Note that the arguments can be empty:
     153             :  * \snippet Test_DataBox.cpp compute_item_tag_no_tags
     154             :  *
     155             :  * \see DataBoxGroup SimpleTag
     156             :  */
     157           1 : struct ComputeTag {};
     158             : 
     159             : /*!
     160             :  * \ingroup DataBoxGroup
     161             :  * \brief Mark a struct as a reference tag by inheriting from this.
     162             :  *
     163             :  * \details
     164             :  * A reference tag is used to identify an item in a DataBox that is a const
     165             :  * reference to a sub-item of another item (such as a Variables or GlobalCache)
     166             :  * in the DataBox
     167             :  *
     168             :  * \derivedrequires
     169             :  * - type alias `base` that is the simple tag from which the reference tag is
     170             :  *   derived
     171             :  * - type alias `argument_tags` that lists tags needed to evaluate `get`
     172             :  * - static function `get` that, given the items fetched by `argument_tags`,
     173             :  *   returns a const reference to the sub-item
     174             :  *
     175             :  * A reference tag may optionally specify a static `std::string name()` method
     176             :  * to override the default name produced by db::tag_name.
     177             :  *
     178             :  * \warning A reference tag should only be derived from a simple tag and
     179             :  * db::ReferenceTag.
     180             :  *
     181             :  * \example
     182             :  * \snippet Test_DataBox.cpp databox_reference_tag_example
     183             :  *
     184             :  * \see DataBoxGroup SimpleTag
     185             :  */
     186           1 : struct ReferenceTag {};
     187             : }  // namespace db

Generated by: LCOV version 1.14