Debian Codegraph @

src/atlas/array/native/NativeArrayView.h

raw
1 /*
2 * (C) Copyright 2013 ECMWF.
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 * In applying this licence, ECMWF does not waive the privileges and immunities
7 * granted to it by virtue of its status as an intergovernmental organisation
8 * nor does it submit to any jurisdiction.
9 */
10
11 /// @file ArrayView.h
12 /// This file contains the ArrayView class, a class that allows to wrap any
13 /// contiguous raw data into
14 /// a view which is accessible with multiple indices.
15 /// All it needs is the strides for each index, and the shape of each index.
16 /// ATTENTION: The last index is stride 1
17 ///
18 /// Bounds-checking can be turned ON by defining
19 /// "ATLAS_ARRAYVIEW_BOUNDS_CHECKING"
20 /// before including this header.
21 ///
22 /// Example 1:
23 /// int[] array = { 1, 2, 3, 4, 5, 6, 7, 8, 9};
24 /// int[2] strides = { 3, 1 };
25 /// int[2] shape = { 3, 3 };
26 /// ArrayView<int,2> matrix( array, shape, strides );
27 /// for( idx_t i=0; i<matrix.shape(0); ++i ) {
28 /// for( idx_t j=0; j<matrix.shape(1); ++j ) {
29 /// matrix(i,j) *= 10;
30 /// }
31 /// }
32 ///
33 /// Strides can also be omitted as for most common cases it can be inferred
34 /// from the shape.
35 ///
36 /// Example 2:
37 /// int[] array = { 1, 2, 3, 4, 5, 6, 7, 8, 9};
38 /// int[2] shape = { 3, 3 };
39 /// ArrayView<int,2> matrix( array, shape );
40 /// which is identical for this matrix to previous Example 1
41 ///
42 /// There is also an easier way to wrap Field and Array classes:
43 ///
44 /// Example 3:
45 /// ArrayView<int,3> fieldview( Field );
46 /// ArrayView<int,2> arrayview( Array );
47 ///
48 /// @author Willem Deconinck
49
50 #pragma once
51
52 #include <array>
53 #include <cstddef>
54 #include <initializer_list>
55 #include <iostream>
56 #include <type_traits>
57 #include <utility>
58
59 #include "atlas/array/ArrayDataStore.h"
60 #include "atlas/array/ArrayViewDefs.h"
61 #include "atlas/array/LocalView.h"
62 #include "atlas/array/Range.h"
63 #include "atlas/array/helpers/ArraySlicer.h"
64 #include "atlas/library/config.h"
65 #include "atlas/mdspan.h"
66
67 //------------------------------------------------------------------------------------------------------
68
69 namespace atlas {
70 namespace array {
71
72 //------------------------------------------------------------------------------------------------------
73
74 /// @brief Multi-dimensional access to a Array object or Field object
75 ///
76 /// An ArrayView enables access to the inner data-memory-storage of the Array.
77 /// It is required to create the view using the make_view helper functions.
78 ///
79 /// ### Example 1:
80 ///
81 /// @code{.cpp}
82 /// auto view = make_view<double,2>( Array );
83 /// double sum = 0;
84 /// for( idx_t i=0; i<view.shape(0); ++i ) {
85 /// for( idx_t j=0; j<view.shape(1); ++j ) {
86 /// sum += view(i,j);
87 /// }
88 /// }
89 /// @endcode
90 ///
91 /// ### Data storage
92 ///
93 /// Depending on whether atlas was compiled with the Feature `GRIDTOOLS_STORAGE`, the
94 /// internal data allocation of the Array object is managed by [GridTools](https://gridtools.github.io/)
95 /// (ATLAS_HAVE_GRIDTOOLS==1) or by Atlas itself (ATLAS_HAVE_GRIDTOOLS==0).
96 ///
97 /// The ArrayView class is therefore also compiled differently dependening on this feature.
98
99 template <typename Value, int Rank>
100 class ArrayView {
101 template <typename T>
102 using is_non_const_value_type = typename std::is_same<T, typename std::remove_const<Value>::type>;
103
104 #define ENABLE_IF_NON_CONST \
105 template <bool EnableBool = true, \
106 typename std::enable_if<(!std::is_const<Value>::value && EnableBool), int>::type* = nullptr>
107
108 #define ENABLE_IF_CONST_WITH_NON_CONST(T) \
109 template <typename T, typename std::enable_if<(std::is_const<Value>::value && is_non_const_value_type<T>::value), \
110 int>::type* = nullptr>
111
112 public:
113 // -- Type definitions
114 using value_type = Value;
115 using non_const_value_type = typename std::remove_const<Value>::type;
116 static constexpr bool is_const = std::is_const<Value>::value;
117 static constexpr bool is_non_const = !std::is_const<Value>::value;
118 static constexpr int RANK{Rank};
119
120 private:
121 using slicer_t = typename helpers::ArraySlicer<ArrayView<Value, Rank>>;
122 using const_slicer_t = typename helpers::ArraySlicer<const ArrayView<const Value, Rank>>;
123
124 template <typename... Args>
125 struct slice_t {
126 using type = typename slicer_t::template Slice<Args...>::type;
127 };
128
129 template <typename... Args>
130 struct const_slice_t {
131 using type = typename const_slicer_t::template Slice<Args...>::type;
132 };
133
134 using mdspan_extents_type = dextents<size_t,RANK>;
135 using mdspan_strides_type = std::array<size_t,RANK>;
136 using mdspan_type = mdspan<value_type, mdspan_extents_type, layout_stride>;
137 using const_mdspan_type = mdspan<const value_type, mdspan_extents_type, layout_stride>;
138
139 public:
140 // -- Constructors
141
142 template <typename ValueTp, typename = std::enable_if_t<std::is_convertible_v<ValueTp*,value_type*>>>
143 ArrayView(const ArrayView<ValueTp, Rank>& other): data_(other.data()), size_(other.size()) {
144 for (int j = 0; j < Rank; ++j) {
145 shape_[j] = other.shape_[j];
146 strides_[j] = other.strides_[j];
147 }
148 }
149
150 template <typename ValueTp, typename = std::enable_if_t<std::is_convertible_v<ValueTp*,value_type*>>>
151 ArrayView(ArrayView<ValueTp, Rank>&& other):data_(other.data()), size_(other.size()) {
152 for (int j = 0; j < Rank; ++j) {
153 shape_[j] = other.shape_[j];
154 strides_[j] = other.strides_[j];
155 }
156 }
157
158 #ifndef DOXYGEN_SHOULD_SKIP_THIS
159 // This constructor should not be used directly, but only through a array::make_view() function.
160 ArrayView(value_type* data, const ArrayShape& shape, const ArrayStrides& strides): data_(data) {
161 size_ = 1;
162 for (int j = 0; j < Rank; ++j) {
163 shape_[j] = shape[j];
164 strides_[j] = strides[j];
165 size_ *= size_t(shape_[j]);
166 }
167 }
168 #endif
169
170 mdspan_type as_mdspan() {
171 return mdspan_type{this->data(), {mdspan_extents(), mdspan_strides()}};
172 }
173
174 const_mdspan_type as_mdspan() const {
175 return const_mdspan_type{this->data(), {mdspan_extents(), mdspan_strides()}};
176 }
177
178 ENABLE_IF_CONST_WITH_NON_CONST(value_type)
179 operator const ArrayView<value_type, Rank>&() const { return *(const ArrayView<value_type, Rank>*)(this); }
180
181 // -- Access methods
182
183 /// @brief Multidimensional index operator: view(i,j,k,...)
184 template <typename... Idx, int Rank_ = Rank, typename = std::enable_if_t<sizeof...(Idx) == Rank_>>
185 ATLAS_HOST_DEVICE
186 value_type& operator()(Idx... idx) {
187 check_bounds(idx...);
188 return data_[index(idx...)];
189 }
190
191 /// @brief Multidimensional index operator: view(i,j,k,...)
192 template <typename... Idx, int Rank_ = Rank, typename = std::enable_if_t<sizeof...(Idx) == Rank_>>
193 ATLAS_HOST_DEVICE
194 const value_type& operator()(Idx... idx) const {
195 return data_[index(idx...)];
196 }
197
198 /// @brief Access to data using square bracket [idx] operator @m_class{m-label m-warning} **Rank==1**.
199 ///
200 /// Note that this function is only present when Rank == 1
201 #ifndef DOXYGEN_SHOULD_SKIP_THIS
202 template <typename Idx, int Rank_ = Rank, typename = std::enable_if_t<Rank_ == 1>>
203 ATLAS_HOST_DEVICE
204 const value_type& operator[](Idx idx) const {
205 #else
206 // Doxygen API is cleaner!
207 template <typename Int>
208 ATLAS_HOST_DEVICE
209 value_type operator[](Int idx) const {
210 #endif
211 check_bounds(idx);
212 return data_[idx * strides_[0]];
213 }
214
215 /// @brief Access to data using square bracket [idx] operator @m_class{m-label m-warning} **Rank==1**
216 ///
217 /// Note that this function is only present when Rank == 1
218 #ifndef DOXYGEN_SHOULD_SKIP_THIS
219 template <typename Idx, int Rank_ = Rank, typename = std::enable_if_t<Rank_ == 1>>
220 ATLAS_HOST_DEVICE
221 value_type& operator[](Idx idx) {
222 #else
223 // Doxygen API is cleaner!
224 template <typename Idx>
225 ATLAS_HOST_DEVICE
226 value_type operator[](Idx idx) {
227 #endif
228 check_bounds(idx);
229 return data_[idx * strides_[0]];
230 }
231
232 /// @brief Return number of values in dimension **Dim** (template argument)
233 ///
234 /// Example use:
235 /// @code{.cpp}
236 /// for( idx_t i=0; i<view.shape<0>(); ++i ) {
237 /// for( idx_t j=0; j<view.shape<1>(); +j ) {
238 /// ...
239 /// }
240 /// }
241 /// @endcode
242 template <unsigned int Dim>
243 ATLAS_HOST_DEVICE
244 idx_t shape() const {
245 return shape_[Dim];
246 }
247
248 /// @brief Return stride for values in dimension **Dim** (template argument)
249 template <unsigned int Dim>
250 ATLAS_HOST_DEVICE
251 idx_t stride() const {
252 return strides_[Dim];
253 }
254
255 /// @brief Return total number of values (accumulated over all dimensions)
256 ATLAS_HOST_DEVICE
257 size_t size() const { return size_; }
258
259 /// @brief Return the number of dimensions
260 ATLAS_HOST_DEVICE
261 static constexpr idx_t rank() { return Rank; }
262
263 ATLAS_HOST_DEVICE
264 const idx_t* strides() const { return strides_; }
265
266 ATLAS_HOST_DEVICE
267 const idx_t* shape() const { return shape_; }
268
269 /// @brief Return number of values in dimension idx
270 template <typename Int>
271 ATLAS_HOST_DEVICE
272 idx_t shape(Int idx) const {
273 return shape_[idx];
274 }
275
276 /// @brief Return stride for values in dimension idx
277 template <typename Int>
278 ATLAS_HOST_DEVICE
279 idx_t stride(Int idx) const {
280 return strides_[idx];
281 }
282
283 /// @brief Access to internal data. @m_class{m-label m-danger} **dangerous**
284 ATLAS_HOST_DEVICE
285 value_type const* data() const { return data_; }
286
287 /// @brief Access to internal data. @m_class{m-label m-danger} **dangerous**
288 ATLAS_HOST_DEVICE
289 value_type* data() { return data_; }
290
291 ATLAS_HOST_DEVICE
292 bool valid() const { return true; }
293
294 /// @brief Return true when all values are contiguous in memory.
295 ///
296 /// This means that if there is e.g. padding in the fastest dimension, or if
297 /// the ArrayView represents a slice, the returned value will be false.
298 ATLAS_HOST_DEVICE
299 bool contiguous() const { return (size_ == size_t(shape_[0]) * size_t(strides_[0]) ? true : false); }
300
301 ENABLE_IF_NON_CONST
302 void assign(const value_type& value);
303
304 ENABLE_IF_NON_CONST
305 void assign(const std::initializer_list<value_type>& list);
306
307 ENABLE_IF_NON_CONST
308 void assign(const ArrayView& other);
309
310 ENABLE_IF_NON_CONST
311 void assign(const LocalView<value_type,Rank>& other);
312
313 void dump(std::ostream& os) const;
314
315 /// @brief Obtain a slice from this view: view.slice( Range, Range, ... )
316 ///
317 /// The return type of this function is intentionally `auto` and is guaranteed to have
318 /// the same API as ArrayView, but is not necessarily this type.
319 ///
320 /// If the current view has Rank == 2, a Rank == 1 slice can be created in several ways:
321 ///
322 /// @code{.cpp}
323 /// auto slice1 = view.slice( Range(0,2), Range::all() );
324 /// auto slice2 = view.slice( Range::To(2), Range::all() );
325 /// @endcode
326 ///
327 /// Sometimes it may be required to extend the rank of the current view to cater for
328 /// certain algorithms requiring an extra rank.
329 ///
330 /// @code{.cpp}
331 /// auto slice3 = view.slice( Range::all(), Range::all(), Range::dummy() );
332 /// @endcode
333 template <typename... Args>
334 ATLAS_HOST_DEVICE
335 auto slice(Args... args) {
336 return slicer_t(*this).apply(args...);
337 }
338
339
340 /// @brief Obtain a slice from this view: view.slice( Range, Range, ... )
341 template <typename... Args>
342 ATLAS_HOST_DEVICE
343 auto slice(Args... args) const {
344 return const_slicer_t(*this).apply(args...);
345 }
346
347 template <typename... Ints>
348 ATLAS_HOST_DEVICE
349 constexpr idx_t index(Ints... idx) const {
350 return index_part<0>(idx...);
351 }
352
353 private:
354 // -- Private methods
355
356 template <int Dim, typename Int, typename... Ints>
357 ATLAS_HOST_DEVICE
358 constexpr idx_t index_part(Int idx, Ints... next_idx) const {
359 return idx * strides_[Dim] + index_part<Dim + 1>(next_idx...);
360 }
361
362 template <int Dim, typename Int>
363 ATLAS_HOST_DEVICE
364 constexpr idx_t index_part(Int last_idx) const {
365 return last_idx * strides_[Dim];
366 }
367
368 #if ATLAS_ARRAYVIEW_BOUNDS_CHECKING
369 template <typename... Ints>
370 ATLAS_HOST_DEVICE
371 void check_bounds(Ints... idx) const {
372 static_assert(sizeof...(idx) == Rank, "Expected number of indices is different from rank of array");
373 #if ATLAS_HOST_COMPILE
374 return check_bounds_part<0>(idx...);
375 #endif
376 }
377 #else
378 template <typename... Ints>
379 ATLAS_HOST_DEVICE
380 void check_bounds(Ints... idx) const {
381 static_assert(sizeof...(idx) == Rank, "Expected number of indices is different from rank of array");
382 }
383 #endif
384
385 template <typename... Ints>
386 ATLAS_HOST_DEVICE
387 void check_bounds_force(Ints... idx) const {
388 static_assert(sizeof...(idx) == Rank, "Expected number of indices is different from rank of array");
389 #if ATLAS_HOST_COMPILE
390 return check_bounds_part<0>(idx...);
391 #endif
392 }
393
394 template <int Dim, typename Int, typename... Ints>
395 ATLAS_HOST
396 void check_bounds_part(Int idx, Ints... next_idx) const {
397 if (idx_t(idx) >= shape_[Dim]) {
398 throw_OutOfRange("ArrayView", array_dim<Dim>(), idx, shape_[Dim]);
399 }
400 check_bounds_part<Dim + 1>(next_idx...);
401 }
402
403 template <int Dim, typename Int>
404 ATLAS_HOST
405 void check_bounds_part(Int last_idx) const {
406 if (idx_t(last_idx) >= shape_[Dim]) {
407 throw_OutOfRange("ArrayView", array_dim<Dim>(), last_idx, shape_[Dim]);
408 }
409 }
410
411
412 template<int... i>
413 ATLAS_HOST_DEVICE
414 mdspan_extents_type _get_mdspan_extents(std::integer_sequence<int, i...> = {}) const {
415 return mdspan_extents_type{(shape_[i])...};
416 }
417
418 ATLAS_HOST_DEVICE
419 mdspan_extents_type mdspan_extents() const {
420 return _get_mdspan_extents(std::make_integer_sequence<int,RANK>{});
421 }
422
423 template<int... i>
424 ATLAS_HOST_DEVICE
425 mdspan_strides_type _get_mdspan_strides(std::integer_sequence<int, i...> = {}) const {
426 return mdspan_strides_type{(static_cast<typename mdspan_strides_type::value_type>(strides_[i]))...};
427 }
428
429 ATLAS_HOST_DEVICE
430 mdspan_strides_type mdspan_strides() const {
431 return _get_mdspan_strides(std::make_integer_sequence<int,RANK>{});
432 }
433
434 // -- Private data
435
436 template<typename,int> friend class ArrayView;
437
438 value_type* data_;
439 size_t size_;
440 idx_t shape_[Rank];
441 idx_t strides_[Rank];
442 };
443
444 //------------------------------------------------------------------------------------------------------
445
446 #undef ENABLE_IF_NON_CONST
447 #undef ENABLE_IF_CONST_WITH_NON_CONST
448
449 } // namespace array
450 } // namespace atlas