From db8b608c2a464870151b3b47eb8972cad9d6834b Mon Sep 17 00:00:00 2001 From: Paul Gannay Date: Tue, 28 Jan 2025 18:44:13 +0100 Subject: [PATCH] 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);