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