Skip to content

Commit

Permalink
kokkos#120: API/containers/DynRankView wip
Browse files Browse the repository at this point in the history
  • Loading branch information
@antoinemeyer5 @fnrizzi
antoinemeyer5 authored and fnrizzi committed Dec 10, 2023
1 parent e1efedc commit 8e7708c
Showing 1 changed file with 159 additions and 124 deletions.
283 changes: 159 additions & 124 deletions docs/source/API/containers/DynRankView.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,240 +6,275 @@

Header File: ``<Kokkos_DynRankView.hpp>``

Class Interface
---------------
Usage
-----

.. cppkokkos:class:: template <class DataType> 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 <class LayoutType> DynRankView
Interface
---------

.. cppkokkos:class:: template <class MemorySpace> DynRankView
.. code-block:: cpp
template <class DataType [, class LayoutType] [, class MemorySpace] [, class MemoryTraits]>
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 <class MemoryTraits> 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<execution_space,memory_space>``.

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<execution_space,memory_space>``.
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<DT, Prop...>& 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<RT,RP...> & rhs)
.. cppkokkos:function:: DynRankView(const DynRankView<DT, Prop...>& 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<RT,RP...> & 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<DT, Prop...>& 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<DT, Prop...>& rhs, Args ... args)
..
The subview constructor. See ``subview`` function for arguments.

.. rubric:: Data Access Functions

Expand Down

0 comments on commit 8e7708c

Please sign in to comment.