From 3479a45e87a882ae1886812bfac6a3698e9e3205 Mon Sep 17 00:00:00 2001 From: Paul Gannay Date: Tue, 21 Jan 2025 14:20:08 +0100 Subject: [PATCH 1/6] Correct ScatterViews template parameters order Also added a small description on how to use ScatterView and added a description for the templates parameters (copied from the cheatsheet one). --- docs/source/API/containers/ScatterView.rst | 54 +++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index a4690122a..99b500285 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -10,10 +10,62 @@ Header File: ```` .. |parallelReduce| replace:: :cpp:func:`parallel_reduce` +.. _View: ../core/view/view.html + +.. |View| replace:: ``View`` + +Usage +----- +A Kokkos ScatterView wraps a standard Kokkos::|View|_ and allow access to it either via Atomic or Data Replication based scatter algorithms, choosing the strategy that should be the fastest for the ScatterView Execution Space. + +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 ``contribute`` should be made to perform the final reduction. + +It is part of the Experimental namespace. + +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 ``Op`` can be omitted but if it is specified, ``Layout`` and ``ExecSpace`` must also be specified. + +* ``DataType``: + Works the same as a |View|_'s DataType. + +* ``Layout``: + +* ``ExecSpace``: Defaults to ``Kokkos::DefaultExecutionSpace`` + +* ``Op``: + Can take the values: + + - ``Kokkos::Experimental::ScatterSum``: performs a Sum. + + - ``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``. + Description ----------- -.. cppkokkos:class:: template ScatterView +.. cppkokkos:class:: template ScatterView .. rubric:: Public Member Variables From 27fd1844b959a31b61ca015dfb5d14af1160db4d Mon Sep 17 00:00:00 2001 From: Paul Gannay Date: Mon, 27 Jan 2025 14:45:45 +0100 Subject: [PATCH 2/6] Improvement after review Created hyperlinks to function from usage section Ensured example compile without change Moved Warning about namespace to the top of the file --- docs/source/API/containers/ScatterView.rst | 52 ++++++++++++++++------ 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index 99b500285..a81e83f5a 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -6,6 +6,11 @@ Header File: ```` +.. warning:: + + Currently ``ScatterView`` is still in the namespace ``Kokkos::Experimental`` + + .. _parallelReduce: ../core/parallel-dispatch/parallel_reduce.html .. |parallelReduce| replace:: :cpp:func:`parallel_reduce` @@ -14,17 +19,22 @@ Header File: ```` .. |View| replace:: ``View`` +.. |reset| replace:: ``reset()`` + +.. |access| replace:: ``access()`` + +.. |contribute| replace:: ``contribute()`` + Usage ----- -A Kokkos ScatterView wraps a standard Kokkos::|View|_ and allow access to it either via Atomic or Data Replication based scatter algorithms, choosing the strategy that should be the fastest for the ScatterView Execution Space. -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. +A Kokkos ScatterView wraps a standard Kokkos::|View|_ and allow access to it either via Atomic or Data Replication based scatter algorithms, choosing the strategy that should be the fastest for the ScatterView Execution Space. -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()``. +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. -Following the parallel region, a call to the free function ``contribute`` should be made to perform the final reduction. +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|_. -It is part of the Experimental namespace. +Following the parallel region, a call to the free function |contribute|_ should be made to perform the final reduction. Interface --------- @@ -119,6 +129,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. @@ -131,6 +143,8 @@ Description contribute ``ScatterView`` array's results into the input View ``dest`` + .. _reset: + .. cppkokkos:function:: reset() performs reset on destination array @@ -156,6 +170,8 @@ Description .. rubric:: Free Functions +.. _contribute: + .. cppkokkos:function:: contribute(View& dest, Kokkos::Experimental::ScatterView const& src) convenience function to perform final reduction of ScatterView @@ -167,15 +183,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); + 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); + } From db8b608c2a464870151b3b47eb8972cad9d6834b Mon Sep 17 00:00:00 2001 From: Paul Gannay Date: Tue, 28 Jan 2025 18:44:13 +0100 Subject: [PATCH 3/6] Update doc with info on create_scatter_view() --- docs/source/API/containers/ScatterView.rst | 34 +++++++++++++--------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index a81e83f5a..4e465c193 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -25,40 +25,39 @@ Header File: ```` .. |contribute| replace:: ``contribute()`` +.. |create_scatter_view| replace:: ``create_scatter_view()`` + Usage ----- -A Kokkos ScatterView wraps a standard Kokkos::|View|_ and allow access to it either via Atomic or Data Replication based scatter algorithms, choosing the strategy that should be the fastest for the ScatterView Execution Space. +A Kokkos ScatterView serves as an interface for a standard Kokkos::|View|_ and allow access to it either via Atomic or Data Replication based scatter algorithms, choosing the strategy that should be the fastest for the ScatterView Execution Space. + +The best option to create a ScatterView is to make a call to the free function Kokkos::Experimental::|create_scatter_view|_. 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 |contribute|_ should be made to perform the final reduction. +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 + 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 ``Op`` can be omitted but if it is specified, ``Layout`` and ``ExecSpace`` must also be specified. - -* ``DataType``: - Works the same as a |View|_'s DataType. - -* ``Layout``: +That means for example that ``Operation`` can be omitted but if it is specified, ``Layout`` and ``ExecSpace`` must also be specified. -* ``ExecSpace``: Defaults to ``Kokkos::DefaultExecutionSpace`` +* ``DataType``, ``Layout`` and ``ExecSpace`` need to be the same types as the one from the Kokkos::View this ScatterView is interfacing. -* ``Op``: +* ``Operation``: Can take the values: - - ``Kokkos::Experimental::ScatterSum``: performs a Sum. + - ``Kokkos::Experimental::ScatterSum``: performs a Sum. It is the default value. - ``Kokkos::Experimental::ScatterProd``: performs a Multiplication. @@ -72,6 +71,8 @@ That means for example that ``Op`` can be omitted but if it is specified, ``Layo * ``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 explicit 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 ----------- @@ -170,6 +171,13 @@ 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) @@ -194,7 +202,7 @@ Example Kokkos::ScopeGuard guard(argc, argv); Kokkos::View results("results", 1); - Kokkos::Experimental::ScatterView scatter(results); + 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); From a4998b5e7e8095785df4576eca5a1355b0a828de Mon Sep 17 00:00:00 2001 From: PaulGannay Date: Tue, 4 Feb 2025 09:17:15 +0100 Subject: [PATCH 4/6] Update docs/source/API/containers/ScatterView.rst Co-authored-by: Thomas Padioleau --- docs/source/API/containers/ScatterView.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index 4e465c193..a01da480f 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -71,7 +71,7 @@ That means for example that ``Operation`` can be omitted but if it is specified, * ``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 explicit 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|_. +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 ----------- From 463d3403d713844658b28a7012a02dc388910d8c Mon Sep 17 00:00:00 2001 From: PaulGannay Date: Tue, 18 Feb 2025 16:29:30 +0100 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Daniel Arndt --- docs/source/API/containers/ScatterView.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index a01da480f..dd0a65607 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -8,7 +8,7 @@ Header File: ```` .. warning:: - Currently ``ScatterView`` is still in the namespace ``Kokkos::Experimental`` + ``ScatterView`` is still in the namespace ``Kokkos::Experimental`` .. _parallelReduce: ../core/parallel-dispatch/parallel_reduce.html @@ -30,7 +30,7 @@ Header File: ```` Usage ----- -A Kokkos ScatterView serves as an interface for a standard Kokkos::|View|_ and allow access to it either via Atomic or Data Replication based scatter algorithms, choosing the strategy that should be the fastest for the ScatterView Execution Space. +A Kokkos ScatterView serves as an interface for a standard Kokkos::|View|_ implementing a scatter-add pattern either via atomics or data replication. The best option to create a ScatterView is to make a call to the free function Kokkos::Experimental::|create_scatter_view|_. From a914f78bd2468ff222e2517547f41d84e1837270 Mon Sep 17 00:00:00 2001 From: PaulGannay Date: Wed, 19 Feb 2025 10:25:04 +0100 Subject: [PATCH 6/6] Update docs/source/API/containers/ScatterView.rst Co-authored-by: Daniel Arndt --- docs/source/API/containers/ScatterView.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/API/containers/ScatterView.rst b/docs/source/API/containers/ScatterView.rst index dd0a65607..c77b470cd 100644 --- a/docs/source/API/containers/ScatterView.rst +++ b/docs/source/API/containers/ScatterView.rst @@ -32,8 +32,6 @@ Usage A Kokkos ScatterView serves as an interface for a standard Kokkos::|View|_ implementing a scatter-add pattern either via atomics or data replication. -The best option to create a ScatterView is to make a call to the free function Kokkos::Experimental::|create_scatter_view|_. - 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|_.