Tag.hpp
1 // 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 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 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 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 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 `parent_tag` that is the tag for the item from which the
172  * reference item is retrieved
173  * - static function `get` that, given the item fetched by `parent_tag`, returns
174  * a const reference to the sub-item
175  * - type alias `argument_tags` that is `tmpl::list<parent_tag>`
176  *
177  * A reference tag may optionally specify a static `std::string name()` method
178  * to override the default name produced by db::tag_name.
179  *
180  * \warning A reference tag should only be derived from a simple tag and
181  * db::ReferenceTag.
182  *
183  * \example
184  * \snippet Test_DataBox.cpp databox_reference_tag_example
185  *
186  * \see DataBoxGroup SimpleTag
187  */
188 struct ReferenceTag {};
189 } // namespace db
db::ComputeTag
Mark a struct as a compute tag by inheriting from this.
Definition: Tag.hpp:157
db::PrefixTag
Mark a struct as a prefix tag by inheriting from this.
Definition: Tag.hpp:103
db::SimpleTag
Mark a struct as a simple tag by inheriting from this.
Definition: Tag.hpp:36
db::ReferenceTag
Mark a struct as a reference tag by inheriting from this.
Definition: Tag.hpp:188
db::BaseTag
Mark a (usually) empty struct as a base tag by inheriting from this.
Definition: Tag.hpp:69
db
Namespace for DataBox related things.
Definition: DataBox.hpp:44