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 or reference tag. In such
      16             :  * a case, the simple tag can be used to fetch the item corresponding to the
      17             :  * compute or reference tag from a DataBox.
      18             :  *
      19             :  * A simple tag may be the base class of another simple tag.  This should be
      20             :  * done rarely, usually as a means of specifying an alternative way to create
      21             :  * the simple item from input-file options.  In such a case, the base simple
      22             :  * tag can be used to fetch the item, while either the base simple tag or one
      23             :  * othe derived simple tags can be used to insert the item into the DataBox
      24             :  * Te derived simple tags should have a type alias `base` that is the base
      25             :  * simple tag.
      26             :  *
      27             :  * \derivedrequires
      28             :  * - type alias `type` of the type of the item corresponding to the simple tag
      29             :  *
      30             :  * A simple tag may optionally specify a static `std::string name()` method to
      31             :  * override the default name produced by db::tag_name.
      32             :  *
      33             :  * \example
      34             :  * \snippet Test_DataBox.cpp databox_tag_example
      35             :  *
      36             :  * \see DataBoxGroup ComputeTag PrefixTag ReferenceTag
      37             :  */
      38           1 : struct SimpleTag {};
      39             : 
      40             : /*!
      41             :  * \ingroup DataBoxGroup
      42             :  * \brief Mark a struct as a prefix tag by inheriting from this.
      43             :  *
      44             :  * \details
      45             :  * A prefix tag is used to create a new simple tag from another simple tag, and
      46             :  * therefore should also be marked as a simple tag by inheriting from
      47             :  * db::SimpleTag.
      48             :  *
      49             :  * The primary reason to mark a simple tag as a prefix tag is that the name
      50             :  * generated by db::tag_name will be constructed from the names of the prefix
      51             :  * tag and the wrapped simple tag.
      52             :  *
      53             :  * \derivedrequires
      54             :  * - type alias `tag` of the wrapped simple tag
      55             :  * - type alias `type` of the type of the item corresponding to the prefix tag
      56             :  *
      57             :  * A prefix tag may optionally specify a static `std::string name()` method to
      58             :  * override the default name produced by db::tag_name.
      59             :  *
      60             :  * \warning A prefix tag should only be derived from db::PrefixTag and
      61             :  * db::SimpleTag.
      62             :  *
      63             :  * \warning A prefix tag should only wrap a single tag.  This is assumed by all
      64             :  * metafunctions that make use of the `tag` type alias of a prefix tag.
      65             :  *
      66             :  * \example
      67             :  * A PrefixTag tag has the structure:
      68             :  * \snippet Test_DataBox.cpp databox_prefix_tag_example
      69             :  *
      70             :  * \see SimpleTag
      71             :  */
      72           1 : struct PrefixTag {};
      73             : 
      74             : /*!
      75             :  * \ingroup DataBoxGroup
      76             :  * \brief Mark a struct as a compute tag by inheriting from this.
      77             :  *
      78             :  * \details
      79             :  * A compute tag is used to identify an item in a DataBox that will be computed
      80             :  * on-demand from other items in the DataBox.  A compute tag must be derived
      81             :  * from a simple tag corresponding to the type of object that is computed.  This
      82             :  * simple tag can be used to fetch the item corresponding to the compute tag
      83             :  * from a DataBox.
      84             :  *
      85             :  * A compute tag contains a member named `function` that is either a static
      86             :  * constexpr function pointer, or a static function. The compute tag must also
      87             :  * have a a type alias `argument_tags` that is a typelist of the tags that will
      88             :  * be retrieved from the DataBox and whose data will be passed to the function
      89             :  * (pointer). Compute tags must also contain a type alias named `return_type`
      90             :  * that is the type the function is mutating. The type must be default
      91             :  * constructible.
      92             :  *
      93             :  * By convention, the name of a compute tag should be the name of the simple tag
      94             :  * that it derives from, appended by `Compute`.
      95             :  *
      96             :  * \derivedrequires
      97             :  * - type alias `return_type` of the type of the item computed
      98             :  * - type alias `base` that is the simple tag from which it is derived
      99             :  * - member `function`that is either a function pointer, or a static constexpr
     100             :  *   function that is used to compute the item from the `argument_tags` fetched
     101             :  *   from the DataBox
     102             :  * - type alias `argument_tags` that is a `tmpl::list` of the tags of the items
     103             :  *   that will be passed (in order) to the function specified by `function`
     104             :  *
     105             :  * A compute tag may optionally specify a static `std::string name()` method to
     106             :  * override the default name produced by db::tag_name.
     107             :  *
     108             :  * \warning A compute tag should only be derived from a simple tag and
     109             :  * db::ComputeTag.
     110             :  *
     111             :  * \example
     112             :  * Compute tags are of the form:
     113             :  * \snippet Test_DataBox.cpp databox_mutating_compute_item_tag
     114             :  * where the function is:
     115             :  * \snippet Test_DataBox.cpp databox_mutating_compute_item_function
     116             :  *
     117             :  * You can also have `function` be a function instead of a function pointer,
     118             :  * which offers a lot of simplicity for very simple compute items.
     119             :  * \snippet Test_DataBox.cpp compute_item_tag_function
     120             :  *
     121             :  * Note that the arguments can be empty:
     122             :  * \snippet Test_DataBox.cpp compute_item_tag_no_tags
     123             :  *
     124             :  * \see DataBoxGroup SimpleTag
     125             :  */
     126           1 : struct ComputeTag {};
     127             : 
     128             : /*!
     129             :  * \ingroup DataBoxGroup
     130             :  * \brief Mark a struct as a reference tag by inheriting from this.
     131             :  *
     132             :  * \details
     133             :  * A reference tag is used to identify an item in a DataBox that is a const
     134             :  * reference to a sub-item of another item (such as a Variables or GlobalCache)
     135             :  * in the DataBox
     136             :  *
     137             :  * \derivedrequires
     138             :  * - type alias `base` that is the simple tag from which the reference tag is
     139             :  *   derived
     140             :  * - type alias `argument_tags` that lists tags needed to evaluate `get`
     141             :  * - static function `get` that, given the items fetched by `argument_tags`,
     142             :  *   returns a const reference to the sub-item
     143             :  *
     144             :  * A reference tag may optionally specify a static `std::string name()` method
     145             :  * to override the default name produced by db::tag_name.
     146             :  *
     147             :  * \warning A reference tag should only be derived from a simple tag and
     148             :  * db::ReferenceTag.
     149             :  *
     150             :  * \example
     151             :  * \snippet Test_DataBox.cpp databox_reference_tag_example
     152             :  *
     153             :  * \see DataBoxGroup SimpleTag
     154             :  */
     155           1 : struct ReferenceTag {};
     156             : }  // namespace db