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
|
