Line data Source code
1 1 : // Distributed under the MIT License.
2 : // See LICENSE.txt for details.
3 :
4 : /// \file
5 : /// Defines generic tensor indices used in `TensorExpression`s
6 :
7 : #pragma once
8 :
9 : #include <array>
10 : #include <cassert>
11 : #include <cstddef>
12 : #include <type_traits>
13 :
14 : #include "DataStructures/Tensor/IndexType.hpp"
15 : #include "Utilities/ForceInline.hpp"
16 : #include "Utilities/Requires.hpp"
17 : #include "Utilities/TMPL.hpp"
18 :
19 : namespace tenex {
20 : namespace TensorIndex_detail {
21 : // The below values are used to separate upper indices from lower indices and
22 : // spatial indices from spacetime indices.
23 : //
24 : // Tensor expressions perform as many calculations as possible in a constexpr
25 : // context, which means working with fundamental types, specifically integer
26 : // types, is easiest. By using sentinel values defined in one location we can
27 : // easily control the encoding without having magic values floating around in
28 : // many places. Furthermore, encoding all the information in the `size_t` means
29 : // that when a failure occurs in one of the constexpr calculations it is
30 : // reasonably easy to debug because, while encoded, the full type information is
31 : // present. This approach can effectively be thought of as using specific bits
32 : // in the `size_t` to mark information, using the size_t more as a bitfield than
33 : // anything else. For human readability, we use base-10 numbers instead of
34 : // base-2 values that would truly set individual bits.
35 : //
36 : // Spacetime indices are represented by values [0, `spatial_sentinel`) and
37 : // spatial indices are represented by values
38 : // [`spatial_sentinel`, `max_sentinel`). Lower spacetime indices are represented
39 : // by values [0, `upper_sentinel`), and upper spacetime indices are represented
40 : // by values [`upper_sentinel`, `spatial_sentinel`). Lower spatial indices are
41 : // represented by values
42 : // [`spatial_sentinel`, `spatial_sentinel` + `upper_sentinel`), and upper
43 : // spatial indices are represented by values
44 : // [`spatial_sentinel` + `upper_sentinel`, `max_sentinel`). Values equal to or
45 : // above `max_sentinel` are considered invalid for representing an index.
46 : static constexpr size_t spatial_sentinel = 1000;
47 : static constexpr size_t upper_sentinel = 500;
48 : static constexpr size_t upper_spatial_sentinel =
49 : spatial_sentinel + upper_sentinel;
50 : static constexpr size_t max_sentinel = 2000;
51 : } // namespace TensorIndex_detail
52 : } // namespace tenex
53 :
54 : /*!
55 : * \ingroup TensorExpressionsGroup
56 : * \brief Represents the geeric indices in a TensorExpression
57 : *
58 : * \details
59 : * Used to denote a tensor index in a tensor slot. This allows the following
60 : * type of expressions to work:
61 : * \code{.cpp}
62 : * auto T = evaluate<ti::a, ti::b>(F(ti::a, ti::b) + S(ti::b, ti::a));
63 : * \endcode
64 : * where `decltype(ti::a) == TensorIndex<0>` and
65 : * `decltype(ti::b) == TensorIndex<1>`. That is, `ti::a` and `ti::b` are
66 : * placeholders for objects of type `TensorIndex<0>` and `TensorIndex<1>`,
67 : * respectively.
68 : */
69 : template <std::size_t I,
70 : Requires<(I < tenex::TensorIndex_detail::max_sentinel)> = nullptr>
71 1 : struct TensorIndex {
72 0 : using value_type = std::size_t;
73 0 : using type = TensorIndex<I>;
74 0 : static constexpr value_type value = I;
75 0 : static constexpr UpLo valence =
76 : ((I < tenex::TensorIndex_detail::upper_sentinel) or
77 : (I >= tenex::TensorIndex_detail::spatial_sentinel and
78 : I < tenex::TensorIndex_detail::upper_spatial_sentinel))
79 : ? UpLo::Lo
80 : : UpLo::Up;
81 0 : static constexpr bool is_spacetime =
82 : I < tenex::TensorIndex_detail::spatial_sentinel;
83 : };
84 :
85 : /*!
86 : * \ingroup TensorExpressionsGroup
87 : * \brief Contains definitions for the available `TensorIndex`s to use in a
88 : * `TensorExpression`
89 : */
90 1 : namespace ti {
91 : /// @{
92 : /*!
93 : * \brief The available `TensorIndex`s to use in a `TensorExpression`
94 : *
95 : * \details The suffix following `ti::` indicates index properties:
96 : * - Uppercase: contravariant/upper index
97 : * - Lowercase: covariant/lower index
98 : * - A/a - H/h: generic spacetime index
99 : * - I/i - M/m: generic spatial index
100 : * - T/t: concrete time index (defined as a spacetime `TensorIndex`)
101 : *
102 : * \snippet Test_AddSubtract.cpp use_tensor_index
103 : *
104 : * If you want to support a new generic index, definitions for the upper and
105 : * lower versions of the index must be added as unique `TensorIndex` types, e.g.
106 : * \code
107 : * static constexpr TensorIndex<UNIQUE_INTEGER_IN_PROPER_RANGE_LOWER> ti::x{};
108 : * static constexpr TensorIndex<UNIQUE_INTEGER_IN_PROPER_RANGE_UPPER> ti::X{};
109 : * \endcode
110 : * where `UNIQUE_INTEGER_IN_PROPER_RANGE_LOWER` and
111 : * `UNIQUE_INTEGER_IN_PROPER_RANGE_UPPER` are unique, but related integers that
112 : * fall in the integer ranges that properly encode the index's properties
113 : * according to the `_sentinel` values defined at the top of
114 : * `src/DataStructures/Tensor/Expressions/TensorIndex.hpp`. This enables the new
115 : * index to be distinguishable from others and for the upper and lower versions
116 : * to be recognized as related by opposite valence. See comments there on these
117 : * integer ranges to properly encode the new index (both upper and lower
118 : * definitions) that you wish to add. In short, you should simply be able to
119 : * continue the pattern used for the existing `TensorIndex` types that are
120 : * already defined. For example, if `ti::M`/`ti::m` is the highest-valued
121 : * generic spatial index currently defined and you want to add `ti::N`/`ti::n`
122 : * as a new generic spatial index, you can simply define `ti::N` and `ti::n`'s
123 : * unique integer values to be `INTEGER_VALUE_FOR_M + 1` and
124 : * `INTEGER_VALUE_FOR_m + 1`, respectively. For adding a new generic spacetime
125 : * index, you should be able to do the same thing with respect to the upper and
126 : * lower versions of the highest-valued currently defined generic spacetime
127 : * `TensorIndex`.
128 : */
129 1 : static constexpr TensorIndex<0> a{};
130 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel> A{};
131 1 : static constexpr TensorIndex<1> b{};
132 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 1> B{};
133 1 : static constexpr TensorIndex<2> c{};
134 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 2> C{};
135 1 : static constexpr TensorIndex<3> d{};
136 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 3> D{};
137 1 : static constexpr TensorIndex<4> e{};
138 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 4> E{};
139 1 : static constexpr TensorIndex<5> f{};
140 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 5> F{};
141 1 : static constexpr TensorIndex<6> g{};
142 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 6> G{};
143 1 : static constexpr TensorIndex<7> h{};
144 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel + 7> H{};
145 :
146 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_sentinel - 1> t{};
147 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel - 1>
148 1 : T{};
149 :
150 1 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel> i{};
151 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_spatial_sentinel>
152 1 : I{};
153 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel + 1>
154 1 : j{};
155 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_spatial_sentinel +
156 : 1>
157 1 : J{};
158 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel + 2>
159 1 : k{};
160 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_spatial_sentinel +
161 : 2>
162 1 : K{};
163 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel + 3>
164 1 : l{};
165 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_spatial_sentinel +
166 : 3>
167 1 : L{};
168 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel + 4>
169 1 : m{};
170 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_spatial_sentinel +
171 : 4>
172 1 : M{};
173 : static constexpr TensorIndex<tenex::TensorIndex_detail::spatial_sentinel + 5>
174 1 : n{};
175 : static constexpr TensorIndex<tenex::TensorIndex_detail::upper_spatial_sentinel +
176 : 5>
177 1 : N{};
178 : /// @}
179 : } // namespace ti
180 :
181 : namespace tenex {
182 : /*!
183 : * \ingroup TensorExpressionsGroup
184 : * \brief Returns the TensorIndex value of with opposite valence.
185 : *
186 : * \details The input value represents a TensorIndex value, which encodes
187 : * both the valence of the index and whether the index is spacetime or
188 : * spatial. This function returns the value that corresponds to the encoding of
189 : * the TensorIndex with the same index type, but opposite valence.
190 : *
191 : * For example, 0 is the TensorIndex value for `ti::a`. If `i == 0`, then 500
192 : * will be returned, which is the TensorIndex value for `ti::A`. If `i == 500`
193 : * (representing `ti::A`), then 0 (representing `ti::a`) is returned.
194 : *
195 : * @param i a TensorIndex value that represents a generic index
196 : * @return the TensorIndex value that encodes the generic index with the
197 : * opposite valence
198 : */
199 : SPECTRE_ALWAYS_INLINE static constexpr size_t
200 1 : get_tensorindex_value_with_opposite_valence(const size_t i) {
201 : assert(i < TensorIndex_detail::max_sentinel); // NOLINT
202 : if ((i >= TensorIndex_detail::upper_sentinel and
203 : i < TensorIndex_detail::spatial_sentinel) or
204 : (i >= TensorIndex_detail::upper_spatial_sentinel)) {
205 : // `i` represents an upper index, so return the lower index's encoding
206 : return i - TensorIndex_detail::upper_sentinel;
207 : } else {
208 : // `i` represents a lower index, so return the upper index's encoding
209 : return i + TensorIndex_detail::upper_sentinel;
210 : }
211 : }
212 : } // namespace tenex
213 :
214 1 : namespace tt {
215 : /*!
216 : * \ingroup TypeTraitsGroup TensorExpressionsGroup
217 : * \brief Check if a type `T` is a TensorIndex used in TensorExpressions
218 : */
219 : template <typename T>
220 1 : struct is_tensor_index : std::false_type {};
221 : template <size_t I>
222 0 : struct is_tensor_index<TensorIndex<I>> : std::true_type {};
223 :
224 : template <typename T>
225 : struct is_time_index;
226 : } // namespace tt
227 :
228 : namespace tenex {
229 : namespace detail {
230 : template <auto&... TensorIndices>
231 : struct make_tensorindex_list_impl {
232 : static_assert(
233 : (... and
234 : tt::is_tensor_index<std::decay_t<decltype(TensorIndices)>>::value),
235 : "Template parameters of make_tensorindex_list must be TensorIndex "
236 : "objects.");
237 : using type = tmpl::list<std::decay_t<decltype(TensorIndices)>...>;
238 : };
239 :
240 : template <typename TensorIndexList>
241 : struct tensorindex_list_is_valid_impl;
242 :
243 : template <typename... TensorIndices>
244 : struct tensorindex_list_is_valid_impl<tmpl::list<TensorIndices...>> {
245 : static_assert(
246 : (... and tt::is_tensor_index<TensorIndices>::value),
247 : "Template parameters of tensorindex_list_is_valid must be TensorIndex "
248 : "types.");
249 : static constexpr bool value = tmpl::is_set<TensorIndices...>::value;
250 : };
251 :
252 : template <typename TensorIndexList1, typename TensorIndexList2,
253 : bool ListsSameSize>
254 : struct generic_indices_at_same_positions_impl;
255 :
256 : template <typename... TensorIndices1, typename... TensorIndices2>
257 : struct generic_indices_at_same_positions_impl<
258 : tmpl::list<TensorIndices1...>, tmpl::list<TensorIndices2...>, true> {
259 : static_assert((... and (tt::is_tensor_index<TensorIndices1>::value and
260 : tt::is_tensor_index<TensorIndices2>::value)),
261 : "Template parameters of generic_indices_at_same_positions_impl "
262 : "must be lists containing TensorIndex types.");
263 : using type = std::bool_constant<(
264 : ... and (std::is_same_v<TensorIndices1, TensorIndices2> or
265 : (tt::is_time_index<TensorIndices1>::value and
266 : tt::is_time_index<TensorIndices2>::value)))>;
267 : };
268 :
269 : template <typename... TensorIndices1, typename... TensorIndices2>
270 : struct generic_indices_at_same_positions_impl<
271 : tmpl::list<TensorIndices1...>, tmpl::list<TensorIndices2...>, false> {
272 : static_assert((... and (tt::is_tensor_index<TensorIndices1>::value)),
273 : "The first template parameter of "
274 : "generic_indices_at_same_positions_impl must be a list "
275 : "containing TensorIndex types.");
276 : static_assert((... and (tt::is_tensor_index<TensorIndices2>::value)),
277 : "The second template parameter of "
278 : "generic_indices_at_same_positions_impl must be a list "
279 : "containing TensorIndex types.");
280 : using type = std::bool_constant<false>;
281 : };
282 :
283 : template <typename TensorIndexList>
284 : struct remove_time_indices;
285 : } // namespace detail
286 :
287 : /*!
288 : * \ingroup TensorExpressionsGroup
289 : * \brief Determine whether or not a given list of TensorIndexs is valid
290 : * to be used with a tensor
291 : *
292 : * \details A list of TensorIndexs is considered valid if the subset of generic
293 : * indices are a set. Indices with opposite valences are unique, e.g. one
294 : * instance each of `ti::a` and `ti::A` is valid. An arbitrary number of
295 : * concrete time indices, regardless of valence, is also valid.
296 : *
297 : * @tparam TensorIndexList list of generic index types, e.g. the types of
298 : * `ti::a, ti::b`
299 : */
300 : template <typename TensorIndexList>
301 1 : struct tensorindex_list_is_valid;
302 :
303 : template <typename... TensorIndices>
304 0 : struct tensorindex_list_is_valid<tmpl::list<TensorIndices...>> {
305 0 : static constexpr bool value = detail::tensorindex_list_is_valid_impl<
306 : typename detail::remove_time_indices<
307 : tmpl::list<TensorIndices...>>::type>::value;
308 : };
309 :
310 : /*!
311 : * \ingroup TensorExpressionsGroup
312 : * \brief Determine whether or not two lists of TensorIndexs contain the same
313 : * generic indices at the same positions
314 : *
315 : * \tparam TensorIndexList1 the first TensorIndex list
316 : * \tparam TensorIndexList2 the second TensorIndex list
317 : */
318 : template <typename TensorIndexList1, typename TensorIndexList2>
319 1 : using generic_indices_at_same_positions =
320 : typename detail::generic_indices_at_same_positions_impl<
321 : TensorIndexList1, TensorIndexList2,
322 : tmpl::size<TensorIndexList1>::value ==
323 : tmpl::size<TensorIndexList2>::value>::type;
324 : } // namespace tenex
325 :
326 : /*!
327 : * \ingroup TensorExpressionsGroup
328 : * \brief Creates a TensorIndex type list from a list of TensorIndex objects
329 : *
330 : * @tparam TensorIndices list of generic index objects, e.g. `ti::a, ti::b`
331 : */
332 : template <auto&... TensorIndices>
333 1 : using make_tensorindex_list =
334 : typename tenex::detail::make_tensorindex_list_impl<TensorIndices...>::type;
|
