diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index a4690122a..c77b470cd 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -6,14 +6,75 @@ Header File: ```` +.. warning:: + + ``ScatterView`` is still in the namespace ``Kokkos::Experimental`` + + .. _parallelReduce: ../core/parallel-dispatch/parallel_reduce.html .. |parallelReduce| replace:: :cpp:func:`parallel_reduce` +.. _View: ../core/view/view.html + +.. |View| replace:: ``View`` + +.. |reset| replace:: ``reset()`` + +.. |access| replace:: ``access()`` + +.. |contribute| replace:: ``contribute()`` + +.. |create_scatter_view| replace:: ``create_scatter_view()`` + +Usage +----- + +A Kokkos ScatterView serves as an interface for a standard Kokkos::|View|_ implementing a scatter-add pattern either via atomics or data replication. + +Construction of a ScatterView can be expensive, so you should try to reuse the same one if possible, in which case, you should call |reset|_ between uses. + +ScatterView can not be addressed directly: each thread inside a parallel region needs to make a call to |access|_ and access the underlying View through the return value of |access|_. + +Following the parallel region, a call to the free function Kokkos::Experimental::|contribute|_ should be made to perform the final reduction. + +Interface +--------- +.. code-block:: cpp + + template + class ScatterView + +Parameters +~~~~~~~~~~ +Template parameters other than ``DataType`` are optional, but if one is specified, preceding ones must also be specified. +That means for example that ``Operation`` can be omitted but if it is specified, ``Layout`` and ``ExecSpace`` must also be specified. + +* ``DataType``, ``Layout`` and ``ExecSpace`` need to be the same types as the one from the Kokkos::View this ScatterView is interfacing. + +* ``Operation``: + Can take the values: + + - ``Kokkos::Experimental::ScatterSum``: performs a Sum. It is the default value. + + - ``Kokkos::Experimental::ScatterProd``: performs a Multiplication. + + - ``Kokkos::Experimental::ScatterMin``: takes the min. + + - ``Kokkos::Experimental::ScatterMax``: takes the max. + +* ``Duplication``: + Whether to duplicate the grid or not; defaults to ``Kokkos::Experimental::ScatterDuplicated``, other option is ``Kokkos::Experimental::ScatterNonDuplicated``. + +* ``Contribution``: + Whether to contribute to use atomics; defaults to ``Kokkos::Experimental::ScatterAtomics``, other option is ``Kokkoss::Experimental::ScatterNonAtomic``. + +Creating a ScatterView with non default ``Operation``, ``Duplication`` or ``Contribution`` using this interface can become complicated, because you need to specify the exact type for ``DataType``, ``Layout`` and ``ExecSpace``. This is why it is advised that you instead use the function Kokkos::Experimental::|create_scatter_view|_. + Description ----------- -.. cppkokkos:class:: template ScatterView +.. cppkokkos:class:: template ScatterView .. rubric:: Public Member Variables @@ -67,6 +128,8 @@ Description :return: true if the ``internal_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. + .. _access: + .. cppkokkos:function:: access() const use within a kernel to return a ``ScatterAccess`` member; this member accumulates a given thread's contribution to the reduction. @@ -79,6 +142,8 @@ Description contribute ``ScatterView`` array's results into the input View ``dest`` + .. _reset: + .. cppkokkos:function:: reset() performs reset on destination array @@ -104,6 +169,15 @@ Description .. rubric:: Free Functions +.. _create_scatter_view: + +.. cppkokkos:function:: template create_scatter_view(const View& view) + + create a new ScatterView interfacing the View ``view``. + Default value for ``Operation`` is ``Kokkos::Experimental::ScatterSum``, ``Duplication`` and ``Contribution`` are chosen to make the ScatterView as efficient as possible when running on its ``ExecSpace``. + +.. _contribute: + .. cppkokkos:function:: contribute(View& dest, Kokkos::Experimental::ScatterView const& src) convenience function to perform final reduction of ScatterView @@ -115,15 +189,23 @@ Example .. code-block:: cpp + + #include + #include + KOKKOS_INLINE_FUNCTION int foo(int i) { return i; } KOKKOS_INLINE_FUNCTION double bar(int i) { return i*i; } - Kokkos::View results("results", 1); - Kokkos::Experimental::ScatterView scatter(results); - Kokkos::parallel_for(1, KOKKOS_LAMBDA(int input_i) { - auto access = scatter.access(); - auto result_i = foo(input_i); - auto contribution = bar(input_i); - access(result_i) += contribution; - }); - Kokkos::Experimental::contribute(results, scatter); + int main (int argc, char* argv[]) { + Kokkos::ScopeGuard guard(argc, argv); + + Kokkos::View results("results", 1); + auto scatter = Kokkos::Experimental::create_scatter_view(results); + Kokkos::parallel_for(1, KOKKOS_LAMBDA(int input_i) { + auto access = scatter.access(); + auto result_i = foo(input_i); + auto contribution = bar(input_i); + access(result_i) += contribution; + }); + Kokkos::Experimental::contribute(results, scatter); + }