Added Team Level documentation

kokkos · May 29, 2023 · 97d5192 · 97d5192
1 parent 0a9b92a
commit 97d5192
Show file tree

Hide file tree

Showing 6 changed files with 146 additions and 37 deletions.
diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst
@@ -41,22 +41,39 @@ Interface
              const Kokkos::View<DataType, Properties...>& view,
              const T& value);
 
+   //
+   // overload set accepting a team handle
+   // Note: for now omit the overloads accepting a label
+   // since they cause issues on device because of the string allocation.
+   //
+   template <class TeamHandleType, class IteratorType, class T>
+   KOKKOS_FUNCTION
+   void fill(const TeamHandleType& th,
+             IteratorType first, IteratorType last,
+             const T& value);
+
+   template <class TeamHandleType, class DataType, class... Properties, class T>
+   KOKKOS_FUNCTION
+   void fill(const TeamHandleType& th,
+             const Kokkos::View<DataType, Properties...>& view,
+             const T& value);
+
 
 Parameters and Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- ``exespace``:
-
-  - execution space instance
+- ``exespace``: execution space instance
 
-- ``label``:
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
 
-  - used to name the implementation kernels for debugging purposes
+- ``label``: string forwarded to internal parallel kernels for debugging purposes
 
   - for 1, the default string is: "Kokkos::fill_iterator_api_default"
 
   - for 3, the default string is: "Kokkos::fill_view_api_default"
 
+  - NOTE: overloads accepting a team handle do not use a label internally
+
 - ``first, last``: range of elements to search in
 
   - range of elements to assign to
@@ -65,17 +82,15 @@ Parameters and Requirements
 
   - must represent a valid range, i.e., ``last >= first`` (checked in debug mode)
 
-  - must be accessible from ``exespace``
+  - must be accessible from ``exespace`` or from the execution space associated with the team handle
 
 - ``view``:
 
   - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride``
 
   - must be accessible from ``exespace``
 
-- ``value``:
-
-  - value to assign to each element
+- ``value``: value to assign to each element
 
 
 Return Value

diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst
@@ -41,24 +41,43 @@ Interface
                const Kokkos::View<DataType, Properties...>& view,
                SizeType n, const T& value);
 
+   //
+   // overload set accepting a team handle
+   //
+   template <class TeamHandleType, class IteratorType, class SizeType, class T>
+   KOKKOS_FUNCTION
+   IteratorType fill_n(const TeamHandleType& th,
+                       IteratorType first, SizeType n,
+                       const T& value);
+
+   template <
+       class TeamHandleType, class DataType, class... Properties, class SizeType,
+       class T, int>
+   KOKKOS_FUNCTION
+   IteratorType fill_n(const TeamHandleType& th,
+                       const Kokkos::View<DataType, Properties...>& view,
+                       SizeType n,
+                       const T& value);
+
 
 Parameters and Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - ``exespace``, ``first``, ``view``, ``value``: same as in [``fill``](./StdFill): execution space instance
 
-- ``label``:
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
 
-  - used to name the implementation kernels for debugging purposes
+- ``label``: used to name the implementation kernels for debugging purposes
 
   - for 1, the default string is: "Kokkos::fill_n_iterator_api_default"
 
   - for 3, the default string is: "Kokkos::fill_n_view_api_default"
 
-- ``n``:
+  - NOTE: overloads accepting a team handle do not use a label internally
 
-  - number of elements to modify (must be non-negative)
+- ``n``: number of elements to modify (must be non-negative)
 
+- ``value``: value to assign to each element
 
 Return Value
 ~~~~~~~~~~~~

diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst
@@ -42,23 +42,38 @@ Interface
                 const Kokkos::View<DataType, Properties...>& view,
                 const T& old_value, const T& new_value);
 
+   //
+   // overload set accepting a team handle
+   //
+   template <class TeamHandleType, class Iterator, class ValueType>
+   KOKKOS_FUNCTION
+   void replace(const TeamHandleType& teamHandle,
+                Iterator first, Iterator last,
+                const ValueType& old_value, const ValueType& new_value);
+
+   template <class TeamHandleType, class DataType1, class... Properties1,
+             class ValueType>
+   KOKKOS_FUNCTION
+   void replace(const TeamHandleType& teamHandle,
+                const ::Kokkos::View<DataType1, Properties1...>& view,
+                const ValueType& old_value, const ValueType& new_value);
 
 
 Parameters and Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- ``exespace``:
+- ``exespace``: execution space instance
 
-  - execution space instance
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
 
-- ``label``:
-
-  - used to name the implementation kernels for debugging purposes
+- ``label``: used to name the implementation kernels for debugging purposes
 
   - for 1, the default string is: "Kokkos::replace_iterator_api_default"
 
   - for 3, the default string is: "Kokkos::replace_view_api_default"
 
+  - NOTE: overloads accepting a team handle do not use a label internally
+
 - ``first, last``:
 
   - range of elements to search in
@@ -75,9 +90,7 @@ Parameters and Requirements
 
   - must be accessible from ``exespace``
 
-- ``old_value``, ``new_value``:
-
-  - self-explanatory
+- ``old_value``, ``new_value``: self-explanatory
 
 
 Return Value

diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst
@@ -59,21 +59,42 @@ Interface
                      const Kokkos::View<DataType2, Properties2...>& view_to,
                      const T& old_value, const T& new_value);
 
+   //
+   // overload set accepting a team handle
+   //
+   template <class TeamHandleType, class InputIterator, class OutputIterator,
+             class ValueType>
+   KOKKOS_FUNCTION
+   OutputIterator replace_copy(const TeamHandleType& teamHandle,
+                               InputIterator first_from, InputIterator last_from,
+                               OutputIterator first_dest,
+                               const ValueType& old_value, const ValueType& new_value);
+
+   template <
+       class TeamHandleType, class DataType1, class... Properties1,
+       class DataType2, class... Properties2, class ValueType, int>
+   KOKKOS_FUNCTION
+   auto replace_copy(const TeamHandleType& teamHandle,
+                     const Kokkos::View<DataType1, Properties1...>& view_from,
+                     const Kokkos::View<DataType2, Properties2...>& view_dest,
+                     const ValueType& old_value, const ValueType& new_value);
+
+
 Parameters and Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- ``exespace``:
-
-  - execution space instance
+- ``exespace``: execution space instance
 
-- ``label``:
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
 
-  - used to name the implementation kernels for debugging purposes
+- ``label``: used to name the implementation kernels for debugging purposes
 
   - for 1, the default string is: "Kokkos::replace_copy_iterator_api_default"
 
   - for 3, the default string is: "Kokkos::replace_copy_view_api_default"
 
+  - NOTE: overloads accepting a team handle do not use a label internally
+
 - ``first_from, last_from``:
 
   - range of elements to copy from
@@ -100,9 +121,7 @@ Parameters and Requirements
 
   - must be accessible from ``exespace``
 
-- ``old_value``, ``new_value``:
-
-  - self-explanatory
+- ``old_value``, ``new_value``: self-explanatory
 
 
 Return Value

diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst
@@ -62,13 +62,31 @@ Interface
      class DataType2, class... Properties2,
      class UnaryPredicateType, class T
    >
-   auto replace_copy_if(const std::string& label,                                  (4)
-                        const ExecutionSpace& exespace,
-                        const Kokkos::View<DataType1, Properties1...>& view_from,
-                        const Kokkos::View<DataType2, Properties2...>& view_to,
-                        UnaryPredicateType pred, const T& new_value);
-
+     auto replace_copy_if(const std::string& label,                                  (4)
+                          const ExecutionSpace& exespace,
+                          const Kokkos::View<DataType1, Properties1...>& view_from,
+                          const Kokkos::View<DataType2, Properties2...>& view_to,
+                          UnaryPredicateType pred, const T& new_value);
 
+   //
+   // overload set accepting a team handle
+   //
+   template <class TeamHandleType, class InputIterator, class OutputIterator,
+             class PredicateType, class ValueType>
+   KOKKOS_FUNCTION
+   OutputIterator
+   replace_copy_if(const TeamHandleType& teamHandle, InputIterator first_from,
+                   InputIterator last_from, OutputIterator first_dest,
+                   PredicateType pred, const ValueType& new_value);
+
+   template <class TeamHandleType, class DataType1, class... Properties1,
+             class DataType2, class... Properties2, class PredicateType,
+             class ValueType, int>
+   KOKKOS_FUNCTION
+   auto replace_copy_if(const TeamHandleType& teamHandle,
+                        const ::Kokkos::View<DataType1, Properties1...>& view_from,
+                        const ::Kokkos::View<DataType2, Properties2...>& view_dest,
+                        PredicateType pred, const ValueType& new_value);
 
 
 Parameters and Requirements
@@ -78,12 +96,16 @@ Parameters and Requirements
 
   - same as in [``replace_copy``](./StdReplaceCopy)
 
-- ``label``:
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
+
+- ``label``: used to name the implementation kernels for debugging purposes
 
   - for 1, the default string is: "Kokkos::replace_copy_if_iterator_api_default"
 
   - for 3, the default string is: "Kokkos::replace_copy_if_view_api_default"
 
+  - NOTE: overloads accepting a team handle do not use a label internally
+
 - ``pred``:
 
   - unary predicate which returns ``true`` for the required element; ``pred(v)``

diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst
@@ -41,19 +41,39 @@ Interface
                    const Kokkos::View<DataType, Properties...>& view,
                    UnaryPredicateType pred, const T& new_value);
 
+   //
+   // overload set accepting a team handle
+   //
+   template <class TeamHandleType, class InputIterator, class Predicate,
+             class ValueType>
+   KOKKOS_FUNCTION
+   void replace_if(const TeamHandleType& teamHandle,
+                   InputIterator first, InputIterator last,
+                   Predicate pred, const ValueType& new_value);
+
+   template <class TeamHandleType, class DataType1, class... Properties1,
+             class Predicate, class ValueType>
+   KOKKOS_FUNCTION
+   void replace_if(const TeamHandleType& teamHandle,
+                   const ::Kokkos::View<DataType1, Properties1...>& view,
+                   Predicate pred, const ValueType& new_value);
 
 
 Parameters and Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - ``exespace``, ``first``, ``last``, ``view``, ``new_value``: same as in [``replace``](./StdReplace)
 
-- ``label``:
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
+
+- ``label``: used to name the implementation kernels for debugging purposes
 
   - for 1, the default string is: "Kokkos::replace_if_iterator_api_default"
 
   - for 3, the default string is: "Kokkos::replace_if_view_api_default"
 
+  - NOTE: overloads accepting a team handle do not use a label internally
+
 - ``pred``:
 
   - *unary* predicate returning ``true`` for the required element to replace; ``pred(v)``
@@ -78,6 +98,7 @@ Parameters and Requirements
       bool operator()(value_type v) const { return /* ... */; }
    };
 
+
 Return Value
 ~~~~~~~~~~~~