diff --git a/docs/source/API/containers/DynRankView.rst b/docs/source/API/containers/DynRankView.rst index bcc3be880..0d249d57d 100644 --- a/docs/source/API/containers/DynRankView.rst +++ b/docs/source/API/containers/DynRankView.rst @@ -6,240 +6,275 @@ Header File: ```` -Class Interface ---------------- +Usage +----- -.. cppkokkos:class:: template DynRankView +``DynRankView`` is a potential reference counted multidimensional array with compile time layouts and memory space. Its semantics are similar to that of ``std::shared_ptr``. The ``DynRankView`` differs from the [[View|Kokkos::View]] in that its rank is not provided with the ``DataType`` template parameter; it is determined dynamically based on the number of extent arguments passed to the constructor. The rank has an upper bound of 7 dimensions. -.. cppkokkos:class:: template DynRankView +Interface +--------- -.. cppkokkos:class:: template DynRankView +.. code-block:: cpp + + template + class DynRankView; + +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``. + +.. cppkokkos:type:: DataType + + Defines the fundamental scalar type of the ``DynRankView``. The basic structure is ``ScalarType``. Examples: + + * ``double``: a ``DynRankView`` of ``double``, dimensions are passed as arguments to the constructor, the number of which determine the rank. + +.. cppkokkos:type:: 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. + +.. cppkokkos:type:: MemorySpace + + Controls the storage location. If omitted, the default memory space of the default execution space is used (i.e. ``Kokkos::DefaultExecutionSpace::memory_space``) + +.. cppkokkos:type:: [[ MemoryTraits | Kokkos::MemoryTraits ]] -.. cppkokkos:class:: template DynRankView + * ``Unmanaged``: The DynRankView will not be reference counted. The allocation has to be provided to the constructor. + * ``Atomic``: 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. - A potentially reference counted multidimensional array with compile time layouts and memory space. Its semantics are similar to that of ``std::shared_ptr``. The ``DynRankView`` differs from the ``Kokkos::View`` in that its rank is not provided with the ``DataType`` template parameter; it is determined dynamically based on the number of extent arguments passed to the constructor. The rank has an upper bound of 7 dimensions. +Requirements +~~~~~~~~~~~~ - 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``. +Public Class Members +-------------------- - :tparam DataType: Defines the fundamental scalar type of the ``DynRankView``. The basic structure is ``ScalarType``. Examples: +Enums +~~~~~ - * ``double``: a ``DynRankView`` of ``double``, dimensions are passed as arguments to the constructor, the number of which determine the rank. +.. cppkokkos:type:: rank - :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: + Rank of the view (i.e. the dimensionality). - * ``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. +.. cppkokkos:type:: rank_dynamic - :tparam MemorySpace: Controls the storage location. If omitted, the default memory space of the default execution space is used (i.e. ``Kokkos::DefaultExecutionSpace::memory_space``) - :tparam MemoryTraits: Sets access properties via enum parameters for the templated ``Kokkos::MemoryTraits<>`` class. Enums can be bit combined. Possible values: + Number of runtime determined dimensions. - * ``Unmanaged``: The DynRankView will not be reference counted. The allocation has to be provided to the constructor. - * ``Atomic``: 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. +.. cppkokkos:type:: reference_type_is_lvalue_reference - .. rubric:: Public Member Variables + Whether the reference type is a C++ lvalue reference. - .. cppkokkos:member:: static constexpr unsigned rank +Typedefs +~~~~~~~~ - The rank of the view (i.e. the dimensionality). +Data Types +^^^^^^^^^^ - .. cppkokkos:member:: static constexpr unsigned rank_dynamic +.. cppkokkos:type:: data_type - The number of runtime determined dimensions. + The ``DataType`` of the DynRankView. - .. cppkokkos:member:: static constexpr bool reference_type_is_lvalue_reference +.. cppkokkos:type:: const_data_type - Whether the reference type is a C++ lvalue reference. + Const version of ``DataType``, same as ``data_type`` if that is already const. - .. rubric:: Data Types +.. cppkokkos:type:: non_const_data_type - .. cppkokkos:type:: data_type + Non-const version of ``DataType``, same as ``data_type`` if that is already non-const. - The ``DataType`` of the DynRankView. +.. cppkokkos:type:: scalar_array_type - .. cppkokkos:type:: const_data_type + If ``DataType`` represents some properly specialised array data type such as Sacado FAD types, ``scalar_array_type`` is the underlying fundamental scalar type. - The const version of ``DataType``, same as ``data_type`` if that is already const. +.. cppkokkos:type:: const_scalar_array_type - .. cppkokkos:type:: non_const_data_type + The const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already const - The non-const version of ``DataType``, same as ``data_type`` if that is already non-const. +.. cppkokkos:type:: non_const_scalar_array_type - .. cppkokkos:type:: scalar_array_type + The non-Const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already non-const. - If ``DataType`` represents some properly specialised array data type such as Sacado FAD types, ``scalar_array_type`` is the underlying fundamental scalar type. +Scalar Types +^^^^^^^^^^^^ - .. cppkokkos:type:: const_scalar_array_type +.. cppkokkos:type:: value_type - The const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already const + 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*******``, ``value_type`` is ``const int``). - .. cppkokkos:type:: non_const_scalar_array_type +.. cppkokkos:type:: const_value_type - The non-Const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already non-const. + Const version of ``value_type``. - .. rubric:: Scalar Types +.. cppkokkos:type:: non_const_value_type - .. cppkokkos:type:: value_type + Non-const version of ``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*******``, ``value_type`` is ``const int``). +Spaces +^^^^^^ - .. cppkokkos:type:: const_value_type +.. cppkokkos:type:: execution_space - The const version of ``value_type``. + Execution space associated with the view, will be used for performing view initialization, and certain deep_copy operations. - .. cppkokkos:type:: non_const_value_type +.. cppkokkos:type:: memory_space - The non-const version of ``value_type``. + Data storage location type. - .. rubric:: Spaces +.. cppkokkos:type:: device_type - .. cppkokkos:type:: execution_space + The compound type defined by ``Device``. - The Execution Space associated with the view, will be used for performing view initialization, and certain ``deep_copy`` operations. +.. cppkokkos:type:: memory_traits - .. cppkokkos:type:: memory_space + The memory traits of the view. - The data storage location type. +.. cppkokkos:type:: host_mirror_space - .. cppkokkos:type:: device_type + Host accessible memory space used in ``HostMirror``. - The compound type defined by ``Device``. +ViewTypes +^^^^^^^^^ - .. cppkokkos:type:: memory_traits +.. cppkokkos:type:: non_const_type - The memory traits of the view. + This view type with all template parameters explicitly defined. - .. cppkokkos:type:: host_mirror_space +.. cppkokkos:type:: const_type - The host accessible memory space used in ``HostMirror``. + This view type with all template parameters explicitly defined using a ``const`` data type. - .. rubric:: View Types +.. cppkokkos:type:: HostMirror - .. cppkokkos:type:: non_const_type + Compatible view type with the same ``DataType`` and ``LayoutType`` stored in host accessible memory space. - The view type with all template parameters explicitly defined. +Data Handles +^^^^^^^^^^^^ - .. cppkokkos:type:: const_type +.. cppkokkos:type:: reference_type - The view type with all template parameters explicitly defined using a ``const`` data type. + Return type of the view access operators. - .. cppkokkos:type:: HostMirror +.. cppkokkos:type:: pointer_type - A compatible view type with the same ``DataType`` and ``LayoutType`` stored in host accessible memory space. + Pointer to scalar type. - .. rubric:: Data Handle Types +Other +^^^^^ - .. cppkokkos:type:: reference_type +.. cppkokkos:type:: array_layout - The return type of the view access operators. + The layout of the ``DynRankView``. - .. cppkokkos:type:: pointer_type +.. cppkokkos:type:: size_type - The pointer to scalar type. + Index type associated with the memory space of this view. - .. rubric:: Other Types +.. cppkokkos:type:: dimension - .. cppkokkos:type:: array_layout + An integer array like type, able to represent the extents of the view. - The layout of the ``DynRankView``. +.. cppkokkos:type:: specialize - .. cppkokkos:type:: size_type + A specialization tag used for partial specialization of the mapping construct underlying a Kokkos ``DynRankView``. - The index type associated with the memory space of this view. +Constructors +~~~~~~~~~~~~ - .. cppkokkos:type:: dimension +.. cppkokkos:function:: DynRankView() - An integer array like type, able to represent the extents of the view. + Default constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is ``nullptr`` and its rank is set to 0. - .. cppkokkos:type:: specialize +.. cppkokkos:function:: DynRankView(const DynRankView& rhs) - A specialization tag used for partial specialization of the mapping construct underlying a Kokkos ``DynRankView``. + Copy constructor with compatible DynRankViews. Follows DynRankView assignment rules. - .. rubric:: Constructors +.. cppkokkos:function:: DynRankView(DynRankView&& rhs) - .. cppkokkos:function:: DynRankView() + Move constructor. - The default constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is ``nullptr`` and its rank is set to 0. +.. cppkokkos:function:: DynRankView(const View & rhs) - .. cppkokkos:function:: DynRankView(const DynRankView& rhs) + Copy constructor taking View as input. - The copy constructor with compatible DynRankViews. Follows DynRankView assignment rules. +.. cppkokkos:function:: DynRankView(const std::string& name, const IntType& ... indices) - .. cppkokkos:function:: DynRankView(DynRankView&& rhs) + Requires: ``array_layout::is_regular == true`` - The move constructor. + Standard allocating constructor. - .. cppkokkos:function:: DynRankView(const View & rhs) + * ``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. - The copy constructor taking View as input. +.. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout) - .. cppkokkos:function:: DynRankView(const std::string& name, const IntType& ... indices) + Standard allocating constructor. - *Requires:* ``array_layout::is_regular == true`` + * ``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. - The standard allocating constructor. +.. cppkokkos:function:: DynRankView(const AllocProperties& prop, const IntType& ... indices) - :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 + Requires: ``array_layout::is_regular == true`` - .. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout) + Allocating constructor with allocation properties. An allocation properties object is returned by the ``view_alloc`` function. - The standard allocating constructor. + * ``indices``: runtime dimensions of the view. - :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique - :param layout: the instance of a layout class +.. cppkokkos:function:: DynRankView(const AllocProperties& prop, const array_layout& layout) - .. cppkokkos:function:: DynRankView(const AllocProperties& prop, const IntType& ... indices) + Allocating constructor with allocation properties and a layout object. - *Requires:* ``array_layout::is_regular == true`` + * ``layout``: an instance of a layout class. - The allocating constructor with allocation properties. An allocation properties object is returned by the ``view_alloc`` function. +.. cppkokkos:function:: DynRankView(const pointer_type& ptr, const IntType& ... indices) - :param indices: the runtime dimensions of the view + Requires: ``array_layout::is_regular == true`` - .. cppkokkos:function:: DynRankView(const AllocProperties& prop, const array_layout& layout) + Unmanaged data wrapping constructor. - The allocating constructor with allocation properties and a layout object. + * ``ptr``: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(n0,...,nR)``. + * ``indices``: runtime dimensions of the view. - :param layout: the instance of a layout class +.. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout) - .. cppkokkos:function:: DynRankView(const pointer_type& ptr, const IntType& ... indices) + Unmanaged data wrapper constructor. - *Requires:* ``array_layout::is_regular == true`` + * ``ptr``: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(layout)`` (\ *NEEDS TO BE IMPLEMENTED*\ ) + * ``layout``: an instance of a layout class. - The unmanaged data wrapping constructor. +.. cppkokkos:function:: DynRankView(const ScratchSpace& space, const IntType& ... indices) - :param ptr: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(n0,...,nR)`` - :param indices: the runtime dimensions of the view + Requires: ``sizeof(IntType...)==rank_dynamic()`` and ``array_layout::is_regular == true`` - .. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout) + Constructor which acquires memory from a Scratch Memory handle. - The unmanaged data wrapper constructor. + * ``space``: scratch memory handle. Typically returned from ``team_handles`` in ``TeamPolicy`` kernels. + * ``indices``: runtime dimensions of the view. - :param ptr: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(layout)`` (\ *NEEDS TO BE IMPLEMENTED*\ ) - :param layout: the instance of a layout class +.. cppkokkos:function:: DynRankView(const ScratchSpace& space, const array_layout& layout) - .. cppkokkos:function:: DynRankView( const ScratchSpace& space, const IntType& ... indices) + Constructor which acquires memory from a Scratch Memory handle. - The 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. - *Requires:* ``sizeof(IntType...)==rank_dynamic()`` *and* ``array_layout::is_regular == true``. +.. cppkokkos:function:: DynRankView(const DynRankView& rhs, Args ... args) - :param space: scratch memory handle. Typically returned from ``team_handles`` in ``TeamPolicy`` kernels - :param indices: the runtime dimensions of the view + Subview constructor. See ``subview`` function for arguments. - .. cppkokkos:function:: DynRankView(const ScratchSpace& space, const array_layout& layout) +Data Access Functions +~~~~~~~~~~~~~~~~~~~~~ - The constructor which acquires memory from a Scratch Memory handle. - :param space: scratch memory handle. Typically returned from ``team_handles`` in ``TeamPolicy`` kernels. - :param layout: the instance of a layout class - .. cppkokkos:function:: DynRankView(const DynRankView& rhs, Args ... args) +.. - The subview constructor. See ``subview`` function for arguments. .. rubric:: Data Access Functions