diff --git a/docs/source/API/core/view/view.md b/docs/source/API/core/view/view.md deleted file mode 100644 index 81b2a8015..000000000 --- a/docs/source/API/core/view/view.md +++ /dev/null @@ -1,351 +0,0 @@ -# `View` - -Header File: `Kokkos_Core.hpp` - -Usage: - -Kokkos View is a potentially reference counted multi dimensional array with compile time layouts and memory space. -Its semantics are similar to that of `std::shared_ptr`. - -## Interface - -```c++ -template -class View; -``` - -### Parameters - -Template parameters other than `DataType` are optional, but ordering is enforced. That means for example that `LayoutType` can be omitted but if both `MemorySpace` and `MemoryTraits` are specified, `MemorySpace` must come before `MemoryTraits`. - - * `DataType`: Defines the fundamental scalar type of the `View` and its dimensionality. The basic structure is `ScalarType STARS BRACKETS` where the number of STARS denotes the number of runtime length dimensions and the number of BRACKETS defines the compile time dimensions. Due to C++ type restrictions runtime dimensions must come first. Examples: - * `double**`: 2D View of `double` with 2 runtime dimensions - * `const int***[5][3]`: 5D View of `int` with 3 runtime and 2 compile dimensions. The data is `const`. - * `Foo[6][2]`: 2D View of a class `Foo` with 2 compile time dimensions. - * `LayoutType`: determines the mapping of indices into the underlying 1D memory storage. Custom Layouts can be implemented, but Kokkos comes with some built-in ones: - * [`LayoutRight`](layoutRight): strides increase from the right most to the left most dimension. The last dimension has a stride of one. This corresponds to how C multi dimensional arrays (`[][][]`) are laid out in memory. - * [`LayoutLeft`](layoutLeft): strides increase from the left most to the right most dimension. The first dimension has a stride of one. This is the layout Fortran uses for its arrays. - * [`LayoutStride`](layoutStride): strides can be arbitrary for each dimension. - * `MemorySpace`: Controls the storage location. If omitted the default memory space of the default execution space is used (i.e. `Kokkos::DefaultExecutionSpace::memory_space`) - * `MemoryTraits`: Sets access properties via enum parameters for the templated `Kokkos::MemoryTraits<>` class. Enums can be combined bit combined. Posible values: - * `Unmanaged`: The View will not be reference counted. The allocation has to be provided to the constructor. - * [`Atomic`](../atomics): All accesses to the view will use atomic operations. - * `RandomAccess`: Hint that the view is used in a random access manner. If the view is also `const` this will trigger special load operations on GPUs (i.e. texture fetches). - * `Restrict`: There is no aliasing of the view by other data structures in the current scope. - -### Requirements: - -## Public Class Members - -### Enums - - * `rank`: rank of the view (i.e. the dimensionality). - * `rank_dynamic`: number of runtime determined dimensions. - * `reference_type_is_lvalue_reference`: whether the reference type is a C++ lvalue reference. - -### Typedefs - -#### Data Types - - * `data_type`: The `DataType` of the View, note `data_type` contains the array specifiers (e.g. `int**[3]`) - * `const_data_type`: Const version of `DataType`, same as `data_type` if that is already const. - * `non_const_data_type`: Non-const version of `DataType`, same as `data_type` if that is already non-const. - - * `scalar_array_type`: If `DataType` represents some properly specialised array data type such as Sacado FAD types, `scalar_array_type` is the underlying fundamental scalar type. - * `const_scalar_array_type`: Const version of `scalar_array_type`, same as `scalar_array_type` if that is already const - * `non_const_scalar_array_type`: Non-Const version of `scalar_array_type`, same as `scalar_array_type` if that is already non-const. - -#### Scalar Types - * `value_type`: The `data_type` stripped of its array specifiers, i.e. the scalar type of the data the view is referencing (e.g. if `data_type` is `const int**[3]`, `value_type` is `const int`. - * `const_value_type`: const version of `value_type`. - * `non_const_value_type`: non-const version of `value_type`. - - - -#### Spaces - * `execution_space`: Execution Space associated with the view, will be used for performing view initialization, and certain deep_copy operations. - * `memory_space`: Data storage location type. - * `device_type`: the compound type defined by `Device` - * `memory_traits`: The memory traits of the view. - * `host_mirror_space`: Host accessible memory space used in `HostMirror`. - - - -#### ViewTypes - * `non_const_type`: this view type with all template parameters explicitly defined. - * `const_type`: this view type with all template parameters explicitly defined using a `const` data type. - * `HostMirror`: compatible view type with the same `DataType` and `LayoutType` stored in host accessible memory space. - -#### Data Handles - * `reference_type`: return type of the view access operators. - * `pointer_type`: pointer to scalar type. - -#### Other - * `array_layout`: The Layout of the View. - * `size_type`: index type associated with the memory space of this view. - * `dimension`: An integer array like type, able to represent the extents of the view. - * `specialize`: A specialization tag used for partial specialization of the mapping construct underlying a Kokkos View. - -### Constructors - - * `View()`: Default Constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is NULL. - * `View( const View& rhs)`: Copy constructor with compatible view. Follows View assignment rules. - * `View( View&& rhs)`: Move constructor - * `View( const std::string& name, const IntType& ... indices)`: Standard allocating constructor. The initialization is executed on the default instance of the execution space corresponding to `MemorySpace` and fences it. - * `name`: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique, - * `indices`: Runtime dimensions of the view. - * Requires: `sizeof(IntType...)==rank_dynamic()` - * Requires: `array_layout::is_regular == true`. - * `View( const std::string& name, const array_layout& layout)`: Standard allocating constructor. The initialization is executed on the default instance of the execution space corresponding to `MemorySpace` and fences it. - * `name`: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique, - * `layout`: an instance of a layout class. - * `View( const AllocProperties& prop, , const IntType& ... indices)`: Allocating constructor with allocation properties. If an execution space is specified in `prop`, the initialization uses it and does not fence. Otherwise, the View is initialized using the default execution space instance corresponding to `MemorySpace` and fences it. - * An allocation properties object is returned by the `view_alloc` function. - * `indices`: Runtime dimensions of the view. - * Requires: `sizeof(IntType...)==rank_dynamic()` - * Requires: `array_layout::is_regular == true`. - * `View( const AllocProperties& prop, const array_layout& layout)`: Allocating constructor with allocation properties and a layout object. If an execution space is specified in `prop`, the initialization uses it and does not fence. Otherwise, the View is initialized using the default execution space instance corresponding to `MemorySpace` and fences it. - * An allocation properties object is returned by the `view_alloc` function. - * `layout`: an instance of a layout class. - * `View( const pointer_type& ptr, const IntType& ... indices)`: Unmanaged data wrapping constructor. - * `ptr`: pointer to a user provided memory allocation. Must provide storage of size `View::required_allocation_size(n0,...,nR)` - * `indices`: Runtime dimensions of the view. - * Requires: `sizeof(IntType...)==rank_dynamic()` - * Requires: `array_layout::is_regular == true`. - * `View( const std::string& name, const array_layout& layout)`: Unmanaged data wrapper constructor. - * `ptr`: pointer to a user provided memory allocation. Must provide storage of size `View::required_allocation_size(layout)` (*NEEDS TO BE IMPLEMENTED*) - * `layout`: an instance of a layout class. - * `View( const ScratchSpace& space, const IntType& ... indices)`: Constructor which acquires memory from a Scratch Memory handle. - * `space`: scratch memory handle. Typically returned from `team_handles` in `TeamPolicy` kernels. - * `indices`: Runtime dimensions of the view. - * Requires: `sizeof(IntType...)==rank_dynamic()` - * Requires: `array_layout::is_regular == true`. - * `View( const ScratchSpace& space, const array_layout& layout)`: Constructor which acquires memory from a Scratch Memory handle. - * `space`: scratch memory handle. Typically returned from `team_handles` in `TeamPolicy` kernels. - * `layout`: an instance of a layout class. - * `View( const View& rhs, Args ... args)`: Subview constructor. See `subview` function for arguments. - -### Data Access Functions - - * ```c++ - reference_type operator() (const IntType& ... indices) const - ``` - Returns a value of `reference_type` which may or not be referenceable itself. The number of index arguments must match the `rank` of the view. - See notes on `reference_type` for properties of the return type. - * Requires: `sizeof(IntType...)==rank_dynamic()` - - * ```c++ - reference_type access (const IntType& i0=0, ... , const IntType& i7=0) const - ``` - Returns a value of `reference_type` which may or not be referenceable itself. The number of index arguments must be equal or larger than the `rank` of the view. - Index arguments beyond `rank` must be `0`, which will be enforced if `KOKKOS_DEBUG` is defined. - See notes on `reference_type` for properties of the return type. - -### Data Layout, Dimensions, Strides - - * ```c++ - constexpr array_layout layout() const - ``` - Returns the layout object. Can be used to to construct other views with the same dimensions. - * ```c++ - template - constexpr size_t extent( const iType& dim) const - ``` - Return the extent of the specified dimension. `iType` must be an integral type, and `dim` must be smaller than `rank`. - * ```c++ - template - constexpr int extent_int( const iType& dim) const - ``` - Return the extent of the specified dimension as an `int`. `iType` must be an integral type, and `dim` must be smaller than `rank`. - Compared to `extent` this function can be useful on architectures where `int` operations are more efficient than `size_t`. It also may eliminate the need for type casts in applications which otherwise perform all index operations with `int`. - * ```c++ - template - constexpr size_t stride(const iType& dim) const - ``` - Return the stride of the specified dimension. `iType` must be an integral type, and `dim` must be smaller than `rank`. - Example: `a.stride(3) == (&a(i0,i1,i2,i3+1,i4)-&a(i0,i1,i2,i3,i4))` - * ```c++ - constexpr size_t stride_0() const - ``` - Return the stride of dimension 0. - * ```c++ - constexpr size_t stride_1() const - ``` - Return the stride of dimension 1. - * ```c++ - constexpr size_t stride_2() const - ``` - Return the stride of dimension 2. - * ```c++ - constexpr size_t stride_3() const - ``` - Return the stride of dimension 3. - * ```c++ - constexpr size_t stride_4() const - ``` - Return the stride of dimension 4. - * ```c++ - constexpr size_t stride_5() const - ``` - Return the stride of dimension 5. - * ```c++ - constexpr size_t stride_6() const - ``` - Return the stride of dimension 6. - * ```c++ - constexpr size_t stride_7() const - ``` - Return the stride of dimension 7. - * ```c++ - template - void stride(iType* strides) const - ``` - Sets `strides[r]` to `stride(r)` for all `r` with `0<=r& rhs); - ``` - Returns true if the View can be assigned to rhs. See below for assignment rules. - - * ```c++ - void assign_data(pointer_type arg_data); - ``` - Decrement reference count of previously assigned data and set the underlying pointer to arg_data. Note that the effective result of this operation is that the view is now an unmanaged view; thus, the deallocation of memory associated with arg_data is not linked in anyway to the deallocation of the view. - - * ```c++ - constexpr bool is_allocated() const; - ``` - Returns true if the view points to a valid memory location. This function works for both managed and unmanaged views. With the unmanaged view, there is no guarantee that referenced address is valid, only that it is a non-null pointer. - -## NonMember Functions - - * ```c++ - template - bool operator==(ViewDst, ViewSrc); - ``` - Returns true if `value_type`, `array_layout`, `memory_space`, `rank`, `data()` and `extent(r)`, for `0<=r - bool operator!=(ViewDst, ViewSrc); - ``` - Returns true if any of `value_type`, `array_layout`, `memory_space`, `rank`, `data()` and `extent(r)`, for `0<=r::value == true` than `std::is_const::value == true`. - * `MemorySpaceAccess::assignable == true` - * If `DstType::dynamic_rank != DstType::rank` and `SrcType::dynamic_rank != SrcType::rank` than for each dimension `k` which is compile time for both it must be true that `dst_view.extent(k) == src_view.extent(k)` - -Additionally the following conditions must be met at runtime: - * If `DstType::dynamic_rank != DstType::rank` than for each compile time dimension `k` it must be true that `dst_view.extent(k) == src_view.extent(k)`. - -Furthermore there are rules which must be met if `DstType::array_layout` is not the same as `SrcType::array_layout`. -These rules only cover cases where both layouts are one of `LayoutLeft`, `LayoutRight` or `LayoutStride` - * If neither `DstType::array_layout` nor `SrcType::array_layout` is `LayoutStride`: - * If `DstType::rank > 1` than `DstType::array_layout` must be the same as `SrcType::array_layout`. - * If either `DstType::array_layout` or `SrcType::array_layout` is `LayoutStride` - * For each dimension `k` it must hold that `dst_view.extent(k) == src_view.extent(k)` - -### Assignment Examples - ```c++ - View a1 = View("A1",N); // OK - View a2 = View("A2",N); // OK - View a3 = View("A3",N,M); // OK if M == 10 otherwise runtime failure - View a4 = a1; // OK - View a5 = a4; // Error: const to non-const assignment - View a6 = a1; // Error: Ranks do not match - View a7 = a3; // Error: compile time dimensions do not match - View a8 = a3; // OK if N == 4 otherwise runtime failure - View a9 = a1; // OK since a1 is either LayoutLeft or LayoutRight - View a10 = a8; // OK - View a11 = a10; // OK - View a12 = View("A12",N); // Error: non-assignable memory spaces - View a13 = View("A13",N); // OK - ``` - -## Examples - - -```c++ -#include -#include - -int main(int argc, char* argv[]) { - Kokkos::initialize(argc,argv); - - int N0 = atoi(argv[1]); - int N1 = atoi(argv[2]); - - Kokkos::View a("A",N0); - Kokkos::View b("B",N1); - - Kokkos::parallel_for("InitA", N0, KOKKOS_LAMBDA (const int& i) { - a(i) = i; - }); - - Kokkos::parallel_for("InitB", N1, KOKKOS_LAMBDA (const int& i) { - b(i) = i; - }); - - Kokkos::View c("C",N0,N1); - { - Kokkos::View const_a(a); - Kokkos::View const_b(b); - Kokkos::parallel_for("SetC", Kokkos::MDRangePolicy>({0,0},{N0,N1}), - KOKKOS_LAMBDA (const int& i0, const int& i1) { - c(i0,i1) = a(i0) * b(i1); - }); - } - - Kokkos::finalize(); -} -``` diff --git a/docs/source/API/core/view/view.rst b/docs/source/API/core/view/view.rst new file mode 100644 index 000000000..eb949d4d8 --- /dev/null +++ b/docs/source/API/core/view/view.rst @@ -0,0 +1,505 @@ +``Kokkos::View`` +================ + +.. role:: cpp(code) + :language: cpp + +Header File: ``Kokkos_Core.hpp`` + +Class Interface +--------------- + +.. cpp:class:: template View + + A potentially reference counted multi dimensional array with compile time layouts and memory space. + Its semantics are similar to that of :cpp:`std::shared_ptr`. + + Template parameters other than :any:`DataType` are optional, but ordering is enforced. That means for example that :cpp:`LayoutType` can be omitted but if both :cpp:`MemorySpace` and :cpp:`MemoryTraits` are specified, :cpp:`MemorySpace` must come before :cpp:`MemoryTraits`. + + :tparam DataType: Defines the fundamental scalar type of the :any:`View` and its dimensionality. The basic structure is ``ScalarType STARS BRACKETS`` where the number of STARS denotes the number of runtime length dimensions and the number of BRACKETS defines the compile time dimensions. Due to C++ type restrictions runtime dimensions must come first. Examples: + + * :cpp:`double**`: 2D View of :cpp:`double` with 2 runtime dimensions + * :cpp:`const int***[5][3]`: 5D View of :cpp:`int` with 3 runtime and 2 compile dimensions. The data is :cpp:`const`. + * :cpp:`Foo[6][2]`: 2D View of a class :cpp:`Foo` with 2 compile time dimensions. + + :tparam LayoutType: Determines the mapping of indices into the underlying 1D memory storage. Custom Layouts can be implemented, but Kokkos comes with some built-in ones: + + * `LayoutRight `_: strides increase from the right most to the left most dimension. The last dimension has a stride of one. This corresponds to how C multi dimensional arrays (``[][][]``) are laid out in memory. + * `LayoutLeft `_: strides increase from the left most to the right most dimension. The first dimension has a stride of one. This is the layout Fortran uses for its arrays. + * `LayoutStride `_: strides can be arbitrary for each dimension. + + :tparam MemorySpace: Controls the storage location. If omitted the default memory space of the default execution space is used (i.e. :cpp:`Kokkos::DefaultExecutionSpace::memory_space`) + :tparam MemoryTraits: Sets access properties via enum parameters for the templated :cpp:`Kokkos::MemoryTraits<>` class. Enums can be combined bit combined. Posible values: + + * :cpp:`Unmanaged`: The View will not be reference counted. The allocation has to be provided to the constructor. + * `Atomic <../atomics.html>`_: All accesses to the view will use atomic operations. + * :cpp:`RandomAccess`: Hint that the view is used in a random access manner. If the view is also :cpp:`const` this will trigger special load operations on GPUs (i.e. texture fetches). + * :cpp:`Restrict`: There is no aliasing of the view by other data structures in the current scope. + + .. rubric:: Public Member Variables + + .. cpp:member:: static constexpr unsigned rank + + the rank of the view (i.e. the dimensionality). + + .. cpp:member:: static constexpr unsigned rank_dynamic + + the number of runtime determined dimensions. + + .. cpp:member:: static constexpr bool reference_type_is_lvalue_reference + + whether the reference type is a C++ lvalue reference. + + .. rubric:: Data Types + + .. cpp:type:: data_type + + The ``DataType`` of the View, note ``data_type`` contains the array specifiers (e.g. :cpp:`int**[3]`) + + .. cpp:type:: const_data_type + + The const version of ``DataType``, same as ``data_type`` if that is already const. + + .. cpp:type:: non_const_data_type + + The non-const version of ``DataType``, same as ``data_type`` if that is already non-const. + + .. cpp:type:: scalar_array_type + + If ``DataType`` represents some properly specialised array data type such as Sacado FAD types, ``scalar_array_type`` is the underlying fundamental scalar type. + + .. cpp:type:: const_scalar_array_type + + The const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already const + + .. cpp:type:: non_const_scalar_array_type + + The non-Const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already non-const. + + .. rubric:: Scalar Types + + .. cpp:type:: value_type + + The ``data_type`` stripped of its array specifiers, i.e. the scalar type of the data the view is referencing (e.g. if ``data_type`` is :cpp:`const int**[3]`, ``value_type`` is ``const int``. + + .. cpp:type:: const_value_type + + The const version of ``value_type``. + + .. cpp:type:: non_const_value_type + + The non-const version of ``value_type``. + + .. rubric:: Spaces + + .. cpp:type:: execution_space + + The Execution Space associated with the view, will be used for performing view initialization, and certain ``deep_copy`` operations. + + .. cpp:type:: memory_space + + The data storage location type. + + .. cpp:type:: device_type + + The compound type defined by :cpp:`Device` + + .. cpp:type:: memory_traits + + The memory traits of the view. + + .. cpp:type:: host_mirror_space + + The host accessible memory space used in `HostMirror`. + + .. rubric:: View Types + + .. cpp:type:: non_const_type + + The view type with all template parameters explicitly defined. + + .. cpp:type:: const_type + + The view type with all template parameters explicitly defined using a :cpp:`const` data type. + + .. cpp:type:: HostMirror + + A compatible view type with the same ``DataType`` and ``LayoutType`` stored in host accessible memory space. + + .. rubric:: Data Handle Types + + .. cpp:type:: reference_type + + The return type of the view access operators. + + .. cpp:type:: pointer_type + + The pointer to scalar type. + + .. rubric:: Other Types + + .. cpp:type:: array_layout + + The Layout of the View. + + .. cpp:type:: size_type + + The index type associated with the memory space of this view. + + .. cpp:type:: dimension + + An integer array like type, able to represent the extents of the view. + + .. cpp:type:: specialize + + A specialization tag used for partial specialization of the mapping construct underlying a Kokkos View. + + .. rubric:: Constructors + + .. cpp:function:: View() + + The default constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is :cpp:`nullptr`. + + .. cpp:function:: View(const View& rhs) + + The copy constructor with compatible view. Follows View assignment :ref:`rules `. + + .. cpp:function:: View(View&& rhs) + + The move constructor. + + .. cpp:function:: View(const std::string& name, const IntType& ... indices) + + *Requires:* :cpp:`sizeof(IntType...)==rank_dynamic()` *and* :cpp:`array_layout::is_regular == true`. + + Standard allocating constructor. The initialization is executed on the default instance of the execution space corresponding to ``MemorySpace`` and fences it. + + :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique. + :param indices: the runtime dimensions of the view. + + .. cpp:function:: View(const std::string& name, const array_layout& layout) + + Standard allocating constructor. The initialization is executed on the default instance of the execution space corresponding to ``MemorySpace`` and fences it. + + :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique. + :param layout: an instance of a layout class. + + .. cpp:function:: View(const AllocProperties& prop, const IntType& ... indices) + + *Requires:* :cpp:`sizeof(IntType...)==rank_dynamic()` *and* :cpp:`array_layout::is_regular == true`. + + Allocating constructor with allocation properties. If an execution space is specified in ``prop``, the initialization uses it and does not fence. Otherwise, the View is initialized using the default execution space instance corresponding to ``MemorySpace`` and fences it. + + :param prop: an allocation properties object returned by the `view_alloc` function. + :param indices: the runtime dimensions of the view. + + .. cpp:function:: View( const AllocProperties& prop, const array_layout& layout) + + Allocating constructor with allocation properties and a layout object. If an execution space is specified in ``prop``, the initialization uses it and does not fence. Otherwise, the View is initialized using the default execution space instance corresponding to ``MemorySpace`` and fences it. + + :param prop: an allocation properties object returned by the `view_alloc` function. + :param layout: an instance of a layout class. + + .. cpp:function:: View( const pointer_type& ptr, const IntType& ... indices) + + *Requires:* :cpp:`sizeof(IntType...)==rank_dynamic()` *and* :cpp:`array_layout::is_regular == true`. + + An unmanaged data wrapping constructor. + + :param ptr: a pointer to a user provided memory allocation. Must provide storage of size :func:`View::required_allocation_size(n0,...,nR)` + :param indices: the runtime dimensions of the view. + + .. cpp:function:: View( const pointer_type& ptr, const array_layout& layout) + + An unmanaged data wrapper constructor. + + :param ptr: a pointer to a user provided memory allocation. Must provide storage of size :func:`View::required_allocation_size(n0,...,nR)` (*NEEDS TO BE IMPLEMENTED*) + :param layout: an instance of a layout class. + + .. cpp:function:: View( const ScratchSpace& space, const IntType& ... indices) + + *Requires:* :cpp:`sizeof(IntType...)==rank_dynamic()` *and* :cpp:`array_layout::is_regular == true`. + + A constructor which acquires memory from a Scratch Memory handle. + + :param space: a scratch memory handle. Typically returned from :cpp:`team_handles` in :cpp:`TeamPolicy` kernels. + :param indices: the runtime dimensions of the view. + + .. cpp:function:: View( const ScratchSpace& space, const array_layout& layout) + + A constructor which acquires memory from a Scratch Memory handle. + + :param space: a scratch memory handle. Typically returned from :cpp:`team_handles` in :cpp:`TeamPolicy` kernels. + :param layout: an instance of a layout class. + + .. cpp:function:: View( const View& rhs, Args ... args) + + The subview constructor. + + .. seealso:: + + The :func:`subview` free function. + + .. ........................................................................... + + .. rubric:: Data Access Functions + + .. cpp:function:: reference_type operator() (const IntType& ... indices) const + + *Requires:* :cpp:`sizeof(IntType...)==rank_dynamic()`. + + :param indices: The index to access the view at. The number of index arguments must match the :any:`rank` of the view. + :return: a value of :any:`reference_type` which may or not be referenceable itself. + + .. cpp:function:: reference_type access(const IntType& i0=0, const IntType& i1=0, const IntType& i2=0, const IntType& i3=0, const IntType& i4=0, const IntType& i5=0, const IntType& i6=0, const IntType& i7=0) + + :param i...: The index arguments to access the view at. Index arguments beyond :any:`rank` must be ``0``, which will be enforced if :c:macro:`KOKKOS_DEBUG` is defined. + + :return: a value of `reference_type` which may or not be referenceable itself. + + .. rubric:: Data Layout, Dimensions, Strides + + .. cpp:function:: constexpr array_layout layout() const + + :return: the layout object that be used to to construct other views with the same dimensions. + + .. cpp:function:: template constexpr size_t extent( const iType& dim) const + + *Requires:* :any:`iType` *must be integral.* + + *Preconditions:* :any:`dim` *must be less than* :any:`rank`. + + :return: the extent of the specified dimension. + + .. cpp:function:: template constexpr int extent_int( const iType& dim) const + + *Requires:* :any:`iType` *must be integral.* + + *Preconditions:* :any:`dim` *must be less than* :any:`rank`. + + :return: the extent of the specified dimension as an :cpp:`int`. + + Compared to :cpp:`extent` this function can be useful on architectures where :cpp:`int` operations are more efficient than :cpp:`size_t`. It also may eliminate the need for type casts in applications which otherwise perform all index operations with :cpp:`int`. + + .. cpp:function:: template constexpr size_t stride(const iType& dim) const + + *Requires:* :any:`iType` *must be integral.* + + *Preconditions:* :any:`dim` *must be less than* :any:`rank`. + + :return: the stride of the specified dimension. + + .. code-block:: cpp + :caption: Example of using :any:`stride`. + + a.stride(3) == (&a(i0,i1,i2,i3+1,i4)-&a(i0,i1,i2,i3,i4)) + + .. cpp:function:: constexpr size_t stride_0() const + + :return: the stride of dimension 0. + + .. cpp:function:: constexpr size_t stride_1() const + + :return: the stride of dimension 1. + + .. cpp:function:: constexpr size_t stride_2() const + + :return: the stride of dimension 2. + + .. cpp:function:: constexpr size_t stride_3() const + + :return: the stride of dimension 3. + + .. cpp:function:: constexpr size_t stride_4() const + + :return: the stride of dimension 4. + + .. cpp:function:: constexpr size_t stride_5() const + + :return: the stride of dimension 5. + + .. cpp:function:: constexpr size_t stride_6() const + + :return: the stride of dimension 6. + + .. cpp:function:: constexpr size_t stride_7() const + + :return: the stride of dimension 7. + + .. cpp:function:: template void stride(iType* strides) const + + *Requires:* :any:`iType` *must be integral.* + + *Preconditions:* :any:`strides` *must be an array of length* :any:`rank` + 1. + + :param strides: an array of length :any:`rank` + 1 that will be used to store the stride + + Sets ``strides[r]`` to ``stride(r)`` for all ``r`` with :cpp:`0<=r& rhs); + + :return: true if the View can be assigned to rhs. + + .. seealso:: + :ref:`Assignment Rules` + + .. cpp:function:: void assign_data(pointer_type arg_data); + + :param arg_data: the new data pointer + + Decrement reference count of previously assigned data and set the underlying pointer to arg_data. Note that the effective result of this operation is that the view is now an unmanaged view; thus, the deallocation of memory associated with arg_data is not linked in anyway to the deallocation of the view. + + .. cpp:function:: constexpr bool is_allocated() const + + :return: true if the view points to a valid memory location. This function works for both managed and unmanaged views. With the unmanaged view, there is no guarantee that referenced address is valid, only that it is a non-null pointer. + +Non-Member Functions +-------------------- + +.. cpp:function:: template bool operator==(ViewDst, ViewSrc); + + :tparam ViewDst: the first view type + :tparam ViewSrc: the second view type + + :return: true if :cpp:type:`~View::value_type`, :cpp:type:`~View::array_layout`, :cpp:any:`~View::memory_space`, :cpp:any:`~View::rank`, :cpp:any:`~View::data()` and :cpp:any:`~View::extent` (r), for :cpp:`0<=r bool operator!=(ViewDst, ViewSrc); + + :tparam ViewDst: the first view type + :tparam ViewSrc: the second view type + + :return: true if :cpp:type:`~View::value_type`, :cpp:type:`~View::array_layout`, :cpp:any:`~View::memory_space`, :cpp:any:`~View::rank`, :cpp:any:`~View::data()` and :cpp:any:`~View::extent` (r), for :cpp:`0<=r::value == true` than :cpp:`std::is_const::value == true`. + * :cpp:`MemorySpaceAccess::assignable == true` + * If :cpp:`DstType::dynamic_rank != DstType::rank` and :cpp:`SrcType::dynamic_rank != SrcType::rank` than for each dimension :cpp:`k` which is compile time for both it must be true that :cpp:`dst_view.extent(k) == src_view.extent(k)` + +Additionally the following conditions must be met at runtime: + + * If :cpp:`DstType::dynamic_rank != DstType::rank` than for each compile time dimension :cpp:`k` it must be true that :cpp:`dst_view.extent(k) == src_view.extent(k)`. + +Furthermore there are rules which must be met if :cpp:`DstType::array_layout` is not the same as :cpp:`SrcType::array_layout`. +These rules only cover cases where both layouts are one of :cpp:`LayoutLeft`, :cpp:`LayoutRight` or :cpp:`LayoutStride` + + * If neither :cpp:`DstType::array_layout` nor :cpp:`SrcType::array_layout` is `LayoutStride`: + + * If :cpp:`DstType::rank > 1` than :cpp:`DstType::array_layout` must be the same as :cpp:`SrcType::array_layout`. + + * If either :cpp:`DstType::array_layout` or :cpp:`SrcType::array_layout` is :cpp:`LayoutStride` + + * For each dimension :cpp:`k` it must hold that :cpp:`dst_view.extent(k) == src_view.extent(k)` + +Assignment Examples +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cpp + + View a1 = View("A1",N); // OK + View a2 = View("A2",N); // OK + View a3 = View("A3",N,M); // OK if M == 10 otherwise runtime failure + View a4 = a1; // OK + View a5 = a4; // Error: const to non-const assignment + View a6 = a1; // Error: Ranks do not match + View a7 = a3; // Error: compile time dimensions do not match + View a8 = a3; // OK if N == 4 otherwise runtime failure + View a9 = a1; // OK since a1 is either LayoutLeft or LayoutRight + View a10 = a8; // OK + View a11 = a10; // OK + View a12 = View("A12",N); // Error: non-assignable memory spaces + View a13 = View("A13",N); // OK + +Examples +-------- + +.. code-block:: cpp + + #include + #include + + int main(int argc, char* argv[]) { + Kokkos::initialize(argc,argv); + + int N0 = atoi(argv[1]); + int N1 = atoi(argv[2]); + + Kokkos::View a("A",N0); + Kokkos::View b("B",N1); + + Kokkos::parallel_for("InitA", N0, KOKKOS_LAMBDA (const int& i) { + a(i) = i; + }); + + Kokkos::parallel_for("InitB", N1, KOKKOS_LAMBDA (const int& i) { + b(i) = i; + }); + + Kokkos::View c("C",N0,N1); + { + Kokkos::View const_a(a); + Kokkos::View const_b(b); + Kokkos::parallel_for("SetC", Kokkos::MDRangePolicy>({0,0},{N0,N1}), + KOKKOS_LAMBDA (const int& i0, const int& i1) { + c(i0,i1) = a(i0) * b(i1); + }); + } + + Kokkos::finalize(); + }