Debian Codegraph @

src/atlas/array/helpers/ArrayForEach.h

raw
1 /*
2 * (C) Crown Copyright 2024 Met Office
3 *
4 * This software is licensed under the terms of the Apache Licence Version 2.0
5 * which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
6 */
7
8 #pragma once
9
10 #include <string_view>
11 #include <tuple>
12 #include <type_traits>
13 #include <utility>
14
15 #include "atlas/array/ArrayView.h"
16 #include "atlas/array/Range.h"
17 #include "atlas/array/helpers/ArraySlicer.h"
18 #include "atlas/parallel/omp/omp.h"
19 #include "atlas/runtime/Exception.h"
20 #include "atlas/util/Config.h"
21
22 namespace atlas {
23
24 namespace execution {
25
26 // As in C++17 std::execution namespace. Note: unsequenced_policy is a C++20
27 // addition.
28 class sequenced_policy {};
29 class unsequenced_policy {};
30 class parallel_unsequenced_policy {};
31 class parallel_policy {};
32
33 // execution policy objects as in C++ std::execution namespace. Note: unseq is a
34 // C++20 addition.
35 inline constexpr sequenced_policy seq{/*unspecified*/};
36 inline constexpr parallel_policy par{/*unspecified*/};
37 inline constexpr parallel_unsequenced_policy par_unseq{/*unspecified*/};
38 inline constexpr unsequenced_policy unseq{/*unspecified*/};
39
40 // Type names for execution policy (Not in C++ standard)
41 template <typename execution_policy>
42 constexpr std::string_view policy_name() {
43 return "unsupported";
44 };
45 template <>
46 constexpr std::string_view policy_name<sequenced_policy>() {
47 return "sequenced_policy";
48 };
49 template <>
50 constexpr std::string_view policy_name<unsequenced_policy>() {
51 return "unsequenced_policy";
52 };
53 template <>
54 constexpr std::string_view policy_name<parallel_unsequenced_policy>() {
55 return "parallel_unsequenced_policy";
56 };
57 template <>
58 constexpr std::string_view policy_name<parallel_policy>() {
59 return "parallel_policy";
60 };
61
62 template <typename execution_policy>
63 constexpr std::string_view policy_name(execution_policy) {
64 return policy_name<std::decay_t<execution_policy>>();
65 }
66
67 // Type check for execution policy (Not in C++ standard)
68 template <typename execution_policy>
69 constexpr auto is_execution_policy() {
70 return std::is_same_v<execution_policy, sequenced_policy> ||
71 std::is_same_v<execution_policy, parallel_policy> ||
72 std::is_same_v<execution_policy, parallel_unsequenced_policy> ||
73 std::is_same_v<execution_policy, unsequenced_policy>;
74 }
75
76 template <typename ExecutionPolicy>
77 constexpr auto demote_policy() {
78 if constexpr (std::is_same_v<ExecutionPolicy, parallel_unsequenced_policy>) {
79 return unseq;
80 } else if constexpr (std::is_same_v<ExecutionPolicy, parallel_policy>) {
81 return seq;
82 } else {
83 return ExecutionPolicy{};
84 }
85 ATLAS_UNREACHABLE();
86 }
87
88 template <typename execution_policy>
89 constexpr auto is_omp_policy() {
90 return std::is_same_v<execution_policy, parallel_policy> ||
91 std::is_same_v<execution_policy, parallel_unsequenced_policy>;
92 }
93
94 template <typename ExecutionPolicy>
95 using demote_policy_t = decltype(demote_policy<ExecutionPolicy>());
96
97 } // namespace execution
98
99 namespace option {
100
101 // Convert execution_policy objects to a util::Config
102
103 template <typename T>
104 util::Config execution_policy() {
105 return util::Config("execution_policy",
106 execution::policy_name<std::decay_t<T>>());
107 }
108
109 template <typename T>
110 util::Config execution_policy(T) {
111 return execution_policy<std::decay_t<T>>();
112 }
113
114 } // namespace option
115
116 namespace array {
117 namespace helpers {
118
119 namespace detail {
120
121 struct NoMask {
122 template <typename... Args>
123 constexpr bool operator()(Args...) const {
124 return 0;
125 }
126 };
127
128 inline constexpr NoMask no_mask;
129
130 template <typename... Ts, typename T>
131 constexpr auto tuplePushBack(const std::tuple<Ts...>& tuple, T value) {
132 return std::tuple_cat(tuple, std::make_tuple(value));
133 }
134
135 template <typename ExecutionPolicy, typename Functor>
136 void forEach(idx_t idxMax, const Functor& functor) {
137 if constexpr (execution::is_omp_policy<ExecutionPolicy>()) {
138 atlas_omp_parallel_for(auto idx = idx_t{}; idx < idxMax; ++idx) {
139 functor(idx);
140 }
141 } else {
142 // Simple for-loop for sequenced or unsequenced execution policies.
143 for (auto idx = idx_t{}; idx < idxMax; ++idx) {
144 functor(idx);
145 }
146 }
147 }
148
149 template <int NPad>
150 constexpr auto argPadding() {
151 if constexpr (NPad > 0) {
152 return std::tuple_cat(std::make_tuple(Range::all()),
153 argPadding<NPad - 1>());
154 } else {
155 return std::make_tuple();
156 }
157 ATLAS_UNREACHABLE();
158 }
159
160 template <size_t ViewIdx = 0, typename... SlicerArgs, typename ArrayViewTuple>
161 auto makeSlices(const std::tuple<SlicerArgs...>& slicerArgs,
162 ArrayViewTuple&& arrayViews) {
163 constexpr auto nb_views = std::tuple_size_v<ArrayViewTuple>;
164
165 auto&& arrayView = std::get<ViewIdx>(arrayViews);
166 using ArrayView = std::decay_t<decltype(arrayView)>;
167
168 constexpr auto Dim = sizeof...(SlicerArgs);
169 constexpr auto Rank = ArrayView::rank();
170
171 static_assert(
172 Dim <= Rank,
173 "Error: number of slicer arguments exceeds the rank of ArrayView.");
174 const auto paddedArgs = std::tuple_cat(slicerArgs, argPadding<Rank - Dim>());
175
176 const auto slicer = [&arrayView](const auto&... args) {
177 return std::make_tuple(arrayView.slice(args...));
178 };
179
180 if constexpr (ViewIdx == nb_views - 1) {
181 return std::apply(slicer, paddedArgs);
182 } else {
183 // recurse
184 return std::tuple_cat(
185 std::apply(slicer, paddedArgs),
186 makeSlices<ViewIdx + 1>(slicerArgs,
187 std::forward<ArrayViewTuple>(arrayViews)));
188 }
189 ATLAS_UNREACHABLE();
190 }
191
192 template <typename ExecutionPolicy, int Dim, int... ItrDims>
193 struct ArrayForEachImpl;
194
195 template <typename ExecutionPolicy, int Dim, int ItrDim, int... ItrDims>
196 struct ArrayForEachImpl<ExecutionPolicy, Dim, ItrDim, ItrDims...> {
197 template <typename ArrayViewTuple, typename Mask, typename Function,
198 typename... SlicerArgs, typename... MaskArgs>
199 static void apply(ArrayViewTuple&& arrayViews, const Mask& mask,
200 const Function& function,
201 const std::tuple<SlicerArgs...>& slicerArgs,
202 const std::tuple<MaskArgs...>& maskArgs) {
203 // Iterate over this dimension.
204 if constexpr (Dim == ItrDim) {
205 // Get size of iteration dimenion from first view argument.
206 const auto idxMax = std::get<0>(arrayViews).shape(ItrDim);
207
208 forEach<ExecutionPolicy>(idxMax, [&](idx_t idx) {
209 // Demote parallel execution policy to a non-parallel one in further
210 // recursion
211 ArrayForEachImpl<
212 execution::demote_policy_t<ExecutionPolicy>, Dim + 1,
213 ItrDims...>::apply(std::forward<ArrayViewTuple>(arrayViews), mask,
214 function, tuplePushBack(slicerArgs, idx),
215 tuplePushBack(maskArgs, idx));
216 });
217 }
218 // Add a RangeAll to arguments.
219 else {
220 ArrayForEachImpl<ExecutionPolicy, Dim + 1, ItrDim, ItrDims...>::apply(
221 std::forward<ArrayViewTuple>(arrayViews), mask, function,
222 tuplePushBack(slicerArgs, Range::all()), maskArgs);
223 }
224 }
225 };
226
227 template <typename...>
228 struct is_applicable : std::false_type {};
229
230 template <typename Function, typename... Args>
231 struct is_applicable<Function, std::tuple<Args...>>
232 : std::is_invocable<Function, Args...> {};
233
234 template <typename Function, typename Tuple>
235 inline constexpr bool is_applicable_v = is_applicable<Function, Tuple>::value;
236
237 template <typename ExecutionPolicy, int Dim>
238 struct ArrayForEachImpl<ExecutionPolicy, Dim> {
239 template <typename ArrayViewTuple, typename Mask, typename Function,
240 typename... SlicerArgs, typename... MaskArgs>
241 static void apply(ArrayViewTuple&& arrayViews, const Mask& mask,
242 const Function& function,
243 const std::tuple<SlicerArgs...>& slicerArgs,
244 const std::tuple<MaskArgs...>& maskArgs) {
245 constexpr auto maskPresent = !std::is_same_v<Mask, NoMask>;
246
247 if constexpr (maskPresent) {
248 constexpr auto invocableMask =
249 std::is_invocable_r_v<int, Mask, MaskArgs...>;
250 static_assert(
251 invocableMask,
252 "Cannot invoke mask function with given arguments.\n"
253 "Make sure you arguments are N integers (or auto...) "
254 "where N == sizeof...(ItrDims). Function must return an int.");
255
256 if (std::apply(mask, maskArgs)) {
257 return;
258 }
259 }
260
261 auto slices =
262 makeSlices(slicerArgs, std::forward<ArrayViewTuple>(arrayViews));
263
264 constexpr auto applicable = is_applicable_v<Function, decltype(slices)>;
265 static_assert(
266 applicable,
267 "Cannot invoke function with given arguments. "
268 "Make sure you the arguments are rvalue references (Slice&&) or const "
269 "references (const Slice&) or regular value (Slice)");
270 std::apply(function, std::move(slices));
271 }
272 };
273 } // namespace detail
274
275 /// brief Array "For-Each" helper struct.
276 ///
277 /// detail Iterates over dimensions given in ItrDims. Slices over full range
278 /// of other dimensions.
279 /// Note: ItrDims must be given in ascending numerical order. TODO: Static
280 /// checking for this.
281 template <int... ItrDims>
282 struct ArrayForEach {
283 /// brief Apply "For-Each" method.
284 ///
285 /// details Visits all elements indexed by ItrDims and creates a slice from
286 /// each ArrayView in arrayViews. Slices are sent to function
287 /// which is executed with the signature f(slice1, slice2,...).
288 /// Iterations are skipped when mask evaluates to "true"
289 /// and is executed with signature g(idx_i, idx_j,...), where the idxs
290 /// are indices of ItrDims.
291 /// When a config is supplied containing "execution_policy" =
292 /// "sequenced_policy" (default). All loops are then executed in
293 /// sequential (row-major) order. With "execution_policy" =
294 /// "parallel_unsequenced" the first loop is executed using OpenMP.
295 /// The remaining loops are executed in serial. Note: The lowest
296 /// ArrayView.rank() must be greater than or equal to the highest dim
297 /// in ItrDims. TODO: static checking for this.
298 template <typename... ArrayView, typename Mask, typename Function>
299 static void apply(const eckit::Parametrisation& conf,
300 std::tuple<ArrayView...>&& arrayViews, const Mask& mask,
301 const Function& function) {
302 auto execute = [&](auto execution_policy) {
303 apply(execution_policy, std::move(arrayViews), mask, function);
304 };
305
306 using namespace execution;
307 std::string execution_policy;
308 if (conf.get("execution_policy", execution_policy)) {
309 if (execution_policy == policy_name(par_unseq)) {
310 execute(par_unseq);
311 } else if (execution_policy == policy_name(par)) {
312 execute(par);
313 } else if (execution_policy == policy_name(unseq)) {
314 execute(unseq);
315 } else if (execution_policy == policy_name(seq)) {
316 execute(seq);
317 } else {
318 throw_Exception("Unrecognized execution policy " + execution_policy,
319 Here());
320 }
321 } else {
322 execute(seq);
323 }
324 }
325
326 /// brief Apply "For-Each" method.
327 ///
328 /// details As above, but Execution policy is determined at compile-time.
329 template <typename ExecutionPolicy, typename... ArrayView, typename Mask,
330 typename Function,
331 typename = std::enable_if_t<
332 execution::is_execution_policy<ExecutionPolicy>()>>
333 static void apply(ExecutionPolicy, std::tuple<ArrayView...>&& arrayViews,
334 const Mask& mask, const Function& function) {
335 detail::ArrayForEachImpl<ExecutionPolicy, 0, ItrDims...>::apply(
336 std::move(arrayViews), mask, function, std::make_tuple(),
337 std::make_tuple());
338 }
339
340 /// brief Apply "For-Each" method
341 ///
342 /// details Apply ForEach with default execution policy.
343 template <typename... ArrayView, typename Mask, typename Function>
344 static void apply(std::tuple<ArrayView...>&& arrayViews, const Mask& mask,
345 const Function& function) {
346 apply(std::move(arrayViews), mask, function);
347 }
348
349 /// brief Apply "For-Each" method
350 ///
351 /// details Apply ForEach with run-time determined execution policy and no
352 /// mask.
353 template <typename... ArrayView, typename Function>
354 static void apply(const eckit::Parametrisation& conf,
355 std::tuple<ArrayView...>&& arrayViews,
356 const Function& function) {
357 apply(conf, std::move(arrayViews), detail::no_mask, function);
358 }
359
360 /// brief Apply "For-Each" method
361 ///
362 /// details Apply ForEach with compile-time determined execution policy and no
363 /// mask.
364 template <typename ExecutionPolicy, typename... ArrayView, typename Function,
365 typename = std::enable_if_t<
366 execution::is_execution_policy<ExecutionPolicy>()>>
367 static void apply(ExecutionPolicy executionPolicy,
368 std::tuple<ArrayView...>&& arrayViews,
369 const Function& function) {
370 apply(executionPolicy, std::move(arrayViews), detail::no_mask, function);
371 }
372
373 /// brief Apply "For-Each" method
374 ///
375 /// details Apply ForEach with default execution policy and no mask.
376 template <typename... ArrayView, typename Function>
377 static void apply(std::tuple<ArrayView...>&& arrayViews,
378 const Function& function) {
379 apply(execution::seq, std::move(arrayViews), function);
380 }
381 };
382
383 /// brief Construct ArrayForEach and call apply
384 ///
385 /// details Construct an ArrayForEach<ItrDims...> using std::integer_sequence
386 /// <int, ItrDims...>. Remaining arguments are forwarded to apply
387 /// method.
388 template <int... ItrDims, typename... Args>
389 void arrayForEachDim(std::integer_sequence<int, ItrDims...>, Args&&... args) {
390 ArrayForEach<ItrDims...>::apply(std::forward<Args>(args)...);
391 }
392
393 } // namespace helpers
394 } // namespace array
395 } // namespace atlas