From 5967b1f382a30d6a2de742f78ea2b1e1ff25f237 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 11:19:13 +0200 Subject: [PATCH 01/13] Convert StdPartitionPoint from md to rst: init --- .../std-algorithms/all/StdPartitionPoint.md | 56 ------------- .../std-algorithms/all/StdPartitionPoint.rst | 83 +++++++++++++++++++ 2 files changed, 83 insertions(+), 56 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.md b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.md deleted file mode 100644 index f0705c9cc..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.md +++ /dev/null @@ -1,56 +0,0 @@ - -# `partition_point` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -IteratorType partition_point(const ExecutionSpace& exespace, (1) - IteratorType first, IteratorType last, - PredicateType pred); - -template -IteratorType partition_point(const std::string& label, (2) - const ExecutionSpace& exespace, - IteratorType first, IteratorType last, - PredicateType pred); - -template -auto partition_point(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (3) - PredicateType pred); - -template -auto partition_point(const std::string& label, (4) - const ExecutionSpace& exespace, - const ::Kokkos::View& view, - PredicateType pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Examines the range `[first, last)` or `view` and locates the -first element that does not satisfy `pred`. - -Assumes the range (or the view) already to be partitioned. - - -## Parameters and Requirements - -- `exespace`, `first`, `last`, `view`, `pred`: same as in [`is_partioned`](./StdIsPartitioned) - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::partition_point_iterator_api_default" - - for 3, the default string is: "Kokkos::partition_point_view_api_default" - -## Return - -Iterator to the elment *after* the last element in the first partition, -or `last` if all elements satisfy `pred`. \ No newline at end of file diff --git a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst new file mode 100644 index 000000000..b28593b63 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst @@ -0,0 +1,83 @@ +``partition_point`` +=================== + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +Examines a range or ``view`` and locates the first element that does not satisfy ``pred``. Assumes the range (or the view) already to be partitioned. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set accepting execution space + // + template + IteratorType partition_point(const ExecutionSpace& exespace, (1) + IteratorType first, IteratorType last, + UnaryPredicate pred); + + template + IteratorType partition_point(const std::string& label, (2) + const ExecutionSpace& exespace, + IteratorType first, IteratorType last, + UnaryPredicate pred); + + template < + class ExecutionSpace, class UnaryPredicate, + class DataType, class... Properties> + auto partition_point(const std::string& label, (3) + const ExecutionSpace& exespace, + const Kokkos::View& view, + UnaryPredicate pred); + + template < + class ExecutionSpace, class UnaryPredicate, + class DataType, class... Properties> + auto partition_point(const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + UnaryPredicate pred); + + // + // overload set accepting a team handle + // + template + KOKKOS_FUNCTION + IteratorType partition_point(const TeamHandleType& teamHandle, (5) + IteratorType first, IteratorType last, + UnaryPredicate pred); + + template < + class TeamHandleType, class UnaryPredicate, + class DataType, class... Properties> + KOKKOS_FUNCTION + auto partition_point(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + UnaryPredicate pred); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |IsPartioned| replace:: ``is_partioned`` +.. _IsPartioned: ./StdIsPartitioned.html + +- ``exespace``, ``first``, ``last``, ``view``, ``pred``: same as in |IsPartioned|_ + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1: The default string is "Kokkos::partitioned_point_iterator_api_default" + + - 4: The default string is "Kokkos::partition_point_view_api_default" + +Return Value +~~~~~~~~~~~~ + +Iterator to the elment *after* the last element in the first partition, or ``last`` if all elements satisfy ``pred``. \ No newline at end of file From 30c5738ce9db7449dd0bea5ee9123278e5f4ae46 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 11:24:11 +0200 Subject: [PATCH 02/13] Convert StdPartitionPoint from md to rst: fix --- .../algorithms/std-algorithms/all/StdPartitionPoint.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst index b28593b63..d0129307f 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst @@ -64,10 +64,10 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. |IsPartioned| replace:: ``is_partioned`` -.. _IsPartioned: ./StdIsPartitioned.html +.. |IsPartitioned| replace:: ``is_partitioned`` +.. _IsPartitioned: ./StdIsPartitioned.html -- ``exespace``, ``first``, ``last``, ``view``, ``pred``: same as in |IsPartioned|_ +- ``exespace``, ``first``, ``last``, ``view``, ``pred``: same as in |IsPartitioned|_ - ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy @@ -80,4 +80,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -Iterator to the elment *after* the last element in the first partition, or ``last`` if all elements satisfy ``pred``. \ No newline at end of file +Iterator to the element *after* the last element in the first partition, or ``last`` if all elements satisfy ``pred``. \ No newline at end of file From f3eccfeb29dac21dd218cdb6b96b3e610dd3cc8a Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 11:59:23 +0200 Subject: [PATCH 03/13] Convert StdPartitionPoint from md to rst: fix --- .../API/algorithms/std-algorithms/all/StdPartitionPoint.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst index d0129307f..57c089980 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst @@ -77,6 +77,8 @@ Parameters and Requirements - 4: The default string is "Kokkos::partition_point_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally + Return Value ~~~~~~~~~~~~ From 48254d622bbe9ec5b07a3cc20228cb76b32d1c45 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 12:44:59 +0200 Subject: [PATCH 04/13] Convert StdAdjacentDifference from md to rst: init --- .../all/StdAdjacentDifference.md | 143 ------------- .../all/StdAdjacentDifference.rst | 201 ++++++++++++++++++ 2 files changed, 201 insertions(+), 143 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.md b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.md deleted file mode 100644 index 56bdd1d82..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.md +++ /dev/null @@ -1,143 +0,0 @@ - -# `adjacent_difference` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -OutputIteratorType adjacent_difference(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest); - -template -OutputIteratorType adjacent_difference(const ExecutionSpace& exespace, (2) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOp bin_op); - -template -OutputIteratorType adjacent_difference(const std::string& label, (3) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest); - -template -OutputIteratorType adjacent_difference(const std::string& label, (4) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOp bin_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2> -auto adjacent_difference(const ExecutionSpace& exespace, (5) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOp> -auto adjacent_difference(const ExecutionSpace& exespace, (6) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOp bin_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2> -auto adjacent_difference(const std::string& label, (7) - const ExecutionSpace& exespace, - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOp> -auto adjacent_difference(const std::string& label, (8) - const ExecutionSpace& exespace, - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOp bin_op); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- (1,3,5,7): First, a copy of `*first_from` is written to `*first_dest` for (1,3), - or a copy of `view_from(0)` is written to `view_dest(0)` for (5,7). - Second, it computes the *difference* between the second and the first - of each adjacent pair of elements of the range `[first_from, last_from)` for (1,3) - or in `view_from` for (5,7), and writes them to the range beginning at `first_dest + 1` for (1,3), - or `view_dest` for (5,7). - -- (2,4,6,8): First, a copy of `*first_from` is written to `*first_dest` for (2,4), - or a copy of `view_from(0)` is written to `view_dest(0)` for (6,8). - Second, it calls the binary functor with the second and the first elements - of each adjacent pair of elements of the range `[first_from, last_from)` for (2,4) - or in `view_from` for (6,8), and writes them to the range beginning at `first_dest + 1` for (2,4), - or `view_dest` for (6,8). - - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,2 the default string is: "Kokkos::adjacent_difference_iterator_api_default" - - for 5,6 the default string is: "Kokkos::adjacent_difference_view_api_default" -- `first_from`, `last_from`, `first_dest`: - - range of elements to read from `*_from` and write to `first_dest` - - must be *random access iterators* - - must represent a valid range, i.e., `last_from >= first_from` (checked in debug mode) - - must be accessible from `exespace` -- `view_from`, `view_dest`: - - views to read elements from `view_from` and write to `view_dest` - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `bin_op`: - - *binary* functor representing the operation to apply to each pair of elements. - Must be valid to be called from the execution space passed, and callable with - two arguments `a,b` of type (possible const) `value_type`, where `value_type` - is the value type of `InputIteratorType` (for 1,2,3,4) or the value type - of `view_from` (for 5,6,7,8), and must not modify `a,b`. - - must conform to: - ```c++ - struct BinaryOp - { - KOKKOS_INLINE_FUNCTION - return_type operator()(const value_type & a, - const value_type & b) const { - return /* ... */; - } - - // or, also valid - return_type operator()(value_type a, - value_type b) const { - return /* ... */; - } - }; - ``` - The return type `return_type` must be such that an object of type `OutputIteratorType` for (1,2,3,4) - or an object of type `value_type` where `value_type` is the value type of `view_dest` for (5,6,7,8) - can be dereferenced and assigned a value of type `return_type`. - -## Return - -Iterator to the element *after* the last element written. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst new file mode 100644 index 000000000..aa27fe2f9 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst @@ -0,0 +1,201 @@ +``adjacent_difference`` +======================= + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +First, a copy of ``*first_from`` is written to ``*first_dest``, or a copy of ``view_from(0)`` is written to ``view_dest(0)``. +Second, it computes the *difference* or calls the binary functor between the second and the first of each adjacent pair of elements of a range or in ``view_from``, and writes them to the range beginning at ``first_dest + 1``, or ``view_dest``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set accepting execution space + // + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType> + OutputIteratorType adjacent_difference(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest); + + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType, + class BinaryOp> + OutputIteratorType adjacent_difference(const ExecutionSpace& exespace, (2) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp bin_op); + + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType> + OutputIteratorType adjacent_difference(const std::string& label, (3) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest); + + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType, + class BinaryOp> + OutputIteratorType adjacent_difference(const std::string& label, (4) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp bin_op); + + // + // overload set accepting views + // + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + auto adjacent_difference(const ExecutionSpace& exespace, (5) + const Kokkos::View& view_from, + const Kokkos::View& view_dest); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + auto adjacent_difference(const ExecutionSpace& exespace, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp bin_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + auto adjacent_difference(const std::string& label, (7) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + auto adjacent_difference(const std::string& label, (8) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp bin_op); + + // + // overload set accepting a team handle + // + template < + class TeamHandleType, + class InputIteratorType, class OutputIteratorType> + KOKKOS_FUNCTION + OutputIteratorType adjacent_difference(const TeamHandleType& teamHandle, (9) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest); + + template < + class TeamHandleType, + class InputIteratorType, class OutputIteratorType, + class BinaryOp> + KOKKOS_FUNCTION + OutputIteratorType adjacent_difference(const TeamHandleType& teamHandle, (10) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp bin_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + KOKKOS_FUNCTION + auto adjacent_difference(const TeamHandleType& teamHandle, (11) + const Kokkos::View& view_from, + const Kokkos::View& view_dest); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + KOKKOS_FUNCTION + auto adjacent_difference(const TeamHandleType& teamHandle, (12) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp bin_op); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1 & 2: The default string is "Kokkos::adjacent_difference_iterator_api" + + - 5 & 6: The default string is "Kokkos::adjacent_difference_view_api" + +- ``first_from``, ``last_from``, ``first_dest``: range of elements to read from ``*_from`` and write to ``first_dest`` + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last_from >= first_from`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view_from``, ``view_dest``: views to read elements from ``view_from`` and write to ``view_dest`` + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``bin_op``: + + - *binary* functor representing the operation to apply to each pair of elements. Must be valid to be called from the execution space passed, and callable with two arguments ``a,b`` of type (possible const) ``value_type``, where ``value_type`` is the value type of ``InputIteratorType`` (for 1,2,3,4) or the value type of ``view_from`` (for 5,6,7,8), and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + struct BinaryOp + { + KOKKOS_INLINE_FUNCTION + return_type operator()(const value_type & a, + const value_type & b) const { + return /* ... */; + } + + // or, also valid + return_type operator()(value_type a, + value_type b) const { + return /* ... */; + } + }; + + The return type ``return_type`` must be such that an object of type ``OutputIteratorType`` for (1,2,3,4) + or an object of type ``value_type`` where ``value_type`` is the value type of ``view_dest`` for (5,6,7,8) + can be dereferenced and assigned a value of type ``return_type``. + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element written. \ No newline at end of file From 7b7066026745e15f1d7713648f2513f609097f95 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 14:06:40 +0200 Subject: [PATCH 05/13] Convert StdAdjacentDifference from md to rst: fix --- .../API/algorithms/std-algorithms/all/StdAdjacentDifference.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst index aa27fe2f9..dd0ff7f46 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst @@ -154,6 +154,8 @@ Parameters and Requirements - 5 & 6: The default string is "Kokkos::adjacent_difference_view_api" + - NOTE: overloads accepting a team handle do not use a label internally + - ``first_from``, ``last_from``, ``first_dest``: range of elements to read from ``*_from`` and write to ``first_dest`` - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` From 949a971855e43d58a6e40dc63f7b2dee4620ce78 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 14:16:53 +0200 Subject: [PATCH 06/13] Convert StdReduce from md to rst: init --- .../std-algorithms/all/StdReduce.md | 148 ------------- .../std-algorithms/all/StdReduce.rst | 207 ++++++++++++++++++ 2 files changed, 207 insertions(+), 148 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReduce.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReduce.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReduce.md b/docs/source/API/algorithms/std-algorithms/all/StdReduce.md deleted file mode 100644 index 5020a8cb8..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdReduce.md +++ /dev/null @@ -1,148 +0,0 @@ - -# `reduce` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -// -// overload set A -// -template -typename IteratorType::value_type reduce(const ExecutionSpace& exespace, (1) - IteratorType first, - IteratorType last); - -template -typename IteratorType::value_type reduce(const std::string& label, (2) - const ExecutionSpace& exespace, - IteratorType first, - IteratorType last); - -template -auto reduce(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& view); - -template -auto reduce(const std::string& label, const ExecutionSpace& exespace, (4) - const ::Kokkos::View& view); - -// -// overload set B -// -template -ValueType reduce(const ExecutionSpace& exespace, (5) - IteratorType first, IteratorType last, - ValueType init_reduction_value); - -template -ValueType reduce(const std::string& label, const ExecutionSpace& exespace, (6) - IteratorType first, IteratorType last, - ValueType init_reduction_value); - -template -ValueType reduce(const ExecutionSpace& exespace, (7) - const ::Kokkos::View& view, - ValueType init_reduction_value); - -template -ValueType reduce(const std::string& label, (8) - const ExecutionSpace& exespace, - const ::Kokkos::View& view, - ValueType init_reduction_value); - -// -// overload set C -// -template < - class ExecutionSpace, class IteratorType, class ValueType, - class BinaryOp> -ValueType reduce(const ExecutionSpace& exespace, (9) - IteratorType first, IteratorType last, - ValueType init_reduction_value, - BinaryOp joiner); - -template < - class ExecutionSpace, class IteratorType, class ValueType, - class BinaryOp> -ValueType reduce(const std::string& label, const ExecutionSpace& exespace, (10) - IteratorType first, IteratorType last, - ValueType init_reduction_value, - BinaryOp joiner); - -template < - class ExecutionSpace, class DataType, class... Properties, - class ValueType, class BinaryOp> -ValueType reduce(const ExecutionSpace& exespace, (11) - const ::Kokkos::View& view, - ValueType init_reduction_value, - BinaryOp joiner); - -template < - class ExecutionSpace, class DataType, class... Properties, - class ValueType, class BinaryOp> -ValueType reduce(const std::string& label, const ExecutionSpace& exespace, (12) - const ::Kokkos::View& view, - ValueType init_reduction_value, - BinaryOp joiner); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- Overload set A (1,2,3,4): performs a reduction of the elements - in the range `[first, last)` (1,2) or in `view` (3,4). - -- Overload set B (5,6,7,8): performs a reduction of the elements - in the range `[first, last)` (5,6) or in `view` (7,8) accounting for - the initial value `init_reduction_value`. - -- Overload set C (9,10,11,12): performs a reduction of the elements - in the range `[first, last)` (9,10) - or in `view` (11,12) accounting for the initial value `init_reduction_value` - using the functor `joiner` to join operands during the reduction operation. - - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,5,9 the default string is: "Kokkos::reduce_iterator_api_default" - - for 3,7,11 the default string is: "Kokkos::reduce_view_api_default" -- `first`, `last`: - - range of elements to reduce over - - must be *random access iterators* - - must represent a valid range, i.e., `last >= first` (checked in debug mode) - - must be accessible from `exespace` -- `view`: - - view to reduce - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `init_reduction_value`: - - initial reduction value to use -- `joiner`: - - *binary* functor performing the desired operation to join two elements. - Must be valid to be called from the execution space passed, and callable with - two arguments `a,b` of type (possible const) `ValueType`, and must not modify `a,b`. - - Must conform to: - ```c++ - struct JoinFunctor { - KOKKOS_FUNCTION - constexpr ValueType operator()(const ValueType& a, const ValueType& b) const { - return /* ... */ - } - }; - ``` - - The behavior is non-deterministic if the `joiner` operation - is not associative or not commutative. - - -## Return - -The reduction result. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst new file mode 100644 index 000000000..c850b8524 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst @@ -0,0 +1,207 @@ +``reduce`` +========== + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +- Overload set A: performs a reduction of the elements in a range or in ``view``. + +- Overload set B: performs a reduction of the elements in a range or in ``view`` accounting for the initial value ``init_reduction_value``. + +- Overload set C: performs a reduction of the elements in a range or in ``view`` accounting for the initial value ``init_reduction_value`` using the functor ``joiner`` to join operands during the reduction operation. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set A + // + template + typename IteratorType::value_type reduce(const ExecutionSpace& exespace, (1) + IteratorType first, + IteratorType last); + + template + typename IteratorType::value_type reduce(const std::string& label, (2) + const ExecutionSpace& exespace, + IteratorType first, + IteratorType last); + + template + KOKKOS_FUNCTION + typename IteratorType::value_type reduce(const TeamHandleType& teamHandle, (3) + IteratorType first, + IteratorType last); + + template + auto reduce(const ExecutionSpace& exespace, (4) + const Kokkos::View& view) + + template + auto reduce(const std::string& label, const ExecutionSpace& exespace, (5) + const Kokkos::View& view); + + template + KOKKOS_FUNCTION + auto reduce(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view) + + // + // overload set B + // + template + ValueType reduce(const ExecutionSpace& exespace, (7) + IteratorType first, IteratorType last, + ValueType init_reduction_value); + + template + ValueType reduce(const std::string& label, (8) + const ExecutionSpace& exespace, + IteratorType first, IteratorType last, + ValueType init_reduction_value); + + template + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (9) + IteratorType first, IteratorType last, + ValueType init_reduction_value); + + template < + class ExecutionSpace, class DataType, + class... Properties, class ValueType> + ValueType reduce(const ExecutionSpace& exespace, (10) + const Kokkos::View& view, + ValueType init_reduction_value); + + template < + class ExecutionSpace, class DataType, + class... Properties, class ValueType> + ValueType reduce(const std::string& label, (11) + const ExecutionSpace& exespace, + const Kokkos::View& view, + ValueType init_reduction_value); + + template < + class TeamHandleType, class DataType, + class... Properties, class ValueType> + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (12) + const Kokkos::View& view, + ValueType init_reduction_value); + + // + // overload set C + // + template < + class ExecutionSpace, class IteratorType, + class ValueType, class BinaryOp> + ValueType reduce(const ExecutionSpace& exespace, (13) + IteratorType first, IteratorType last, + ValueType init_reduction_value, + BinaryOp joiner); + + template < + class ExecutionSpace, class IteratorType, + class ValueType, class BinaryOp> + ValueType reduce(const std::string& label, (14) + const ExecutionSpace& exespace, + IteratorType first, IteratorType last, + ValueType init_reduction_value, + BinaryOp joiner); + + template < + class TeamHandleType, class IteratorType, + class ValueType, class BinaryOp> + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (15) + IteratorType first, IteratorType last, + ValueType init_reduction_value, + BinaryOp joiner); + + template < + class ExecutionSpace, class DataType, + class... Properties, class ValueType, class BinaryOp> + ValueType reduce(const ExecutionSpace& exespace, (16) + const Kokkos::View& view, + ValueType init_reduction_value, + BinaryOp joiner); + + template < + class ExecutionSpace, class DataType, + class... Properties, class ValueType, class BinaryOp> + ValueType reduce(const std::string& label, (17) + const ExecutionSpace& exespace, + const Kokkos::View& view, + ValueType init_reduction_value, + BinaryOp joiner); + + template < + class TeamHandleType, class DataType, + class... Properties, class ValueType, class BinaryOp> + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (18) + const Kokkos::View& view, + ValueType init_reduction_value, + BinaryOp joiner); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1,7,13: The default string is "Kokkos::reduce_default_functors_iterator_api" + + - 3,10: The default string is "Kokkos::reduce_default_functors_view_api" + + - 16: The default string is "Kokkos::reduce_custom_functors_view_api" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first``, ``last``: range of elements to reduce over + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last_from >= first_from`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: view to reduce + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``init_reduction_value``: initial reduction value to use + +- ``joiner``: + + - *binary* functor performing the desired operation to join two elements. Must be valid to be called from the execution space passed, and callable with two arguments ``a,b`` of type (possible const) ``ValueType``, and must not modify ``a,b``. + + - Must conform to: + + .. code-block:: cpp + + struct JoinFunctor { + KOKKOS_FUNCTION + constexpr ValueType operator()(const ValueType& a, const ValueType& b) const { + return /* ... */ + } + }; + + - The behavior is non-deterministic if the ``joiner`` operation is not associative or not commutative. + +Return Value +~~~~~~~~~~~~ + +The reduction result. From f83ed52b5dd7d15aade72cee73ca9f84a7c1919c Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 15:11:59 +0200 Subject: [PATCH 07/13] Convert StdTransformReduce from md to rst: init --- .../std-algorithms/all/StdTransformReduce.md | 257 -------------- .../std-algorithms/all/StdTransformReduce.rst | 326 ++++++++++++++++++ 2 files changed, 326 insertions(+), 257 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.md b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.md deleted file mode 100644 index 703210228..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.md +++ /dev/null @@ -1,257 +0,0 @@ - -# `transform_reduce` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -// -// overload set A -// -template < - class ExecutionSpace, class IteratorType1, - class IteratorType2, class ValueType> -ValueType transform_reduce(const ExecutionSpace& exespace, (1) - IteratorType1 first1, IteratorType1 last1, - IteratorType2 first2, - ValueType init_reduction_value); - -template < - class ExecutionSpace, class IteratorType1, - class IteratorType2, class ValueType> -ValueType transform_reduce(const std::string& label, (2) - const ExecutionSpace& exespace, - IteratorType1 first1, IteratorType1 last1, - IteratorType2 first2, - ValueType init_reduction_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType> -ValueType transform_reduce(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& first_view, - const ::Kokkos::View& second_view, - ValueType init_reduction_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType> -ValueType transform_reduce(const std::string& label, (4) - const ExecutionSpace& exespace, - const ::Kokkos::View& first_view, - const ::Kokkos::View& second_view, - ValueType init_reduction_value); - -// -// overload set B -// -template < - class ExecutionSpace, - class IteratorType1, class IteratorType2, - class ValueType, - class BinaryJoinerType, class BinaryTransform> -ValueType transform_reduce(const ExecutionSpace& exespace, (5) - IteratorType1 first1, - IteratorType1 last1, IteratorType2 first2, - ValueType init_reduction_value, - BinaryJoinerType joiner, - BinaryTransform binary_transformer); - -template < - class ExecutionSpace, - class IteratorType1, class IteratorType2, - class ValueType, - class BinaryJoinerType, class BinaryTransform> -ValueType transform_reduce(const std::string& label, (6) - const ExecutionSpace& exespace, - IteratorType1 first1, IteratorType1 last1, - IteratorType2 first2, - ValueType init_reduction_value, - BinaryJoinerType joiner, - BinaryTransform binary_transformer); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType, - class BinaryJoinerType, class BinaryTransform> -ValueType transform_reduce(const ExecutionSpace& exespace, (7) - const ::Kokkos::View& first_view, - const ::Kokkos::View& second_view, - ValueType init_reduction_value, - BinaryJoinerType joiner, - BinaryTransform binary_transformer); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType, - class BinaryJoinerType, class BinaryTransform> -ValueType transform_reduce(const std::string& label, (8) - const ExecutionSpace& exespace, - const ::Kokkos::View& first_view, - const ::Kokkos::View& second_view, - ValueType init_reduction_value, - BinaryJoinerType joiner, - BinaryTransform binary_transformer); - -// -// overload set C -// -template < - class ExecutionSpace, - class IteratorType, class ValueType, - class BinaryJoinerType, class UnaryTransform> -ValueType transform_reduce(const ExecutionSpace& exespace, (9) - IteratorType first1, IteratorType last1, - ValueType init_reduction_value, - BinaryJoinerType joiner, - UnaryTransform unary_transformer); - -template < - class ExecutionSpace, - class IteratorType, class ValueType, - class BinaryJoinerType, class UnaryTransform> -ValueType transform_reduce(const std::string& label, - const ExecutionSpace& exespace, (10) - IteratorType first1, IteratorType last1, - ValueType init_reduction_value, - BinaryJoinerType joiner, - UnaryTransform unary_transformer); - -template < - class ExecutionSpace, - class DataType, class... Properties, class ValueType, - class BinaryJoinerType, class UnaryTransform> -ValueType transform_reduce(const ExecutionSpace& exespace, (11) - const ::Kokkos::View& first_view, - ValueType init_reduction_value, - BinaryJoinerType joiner, - UnaryTransform unary_transformer); - -template < - class ExecutionSpace, - class DataType, class... Properties, class ValueType, - class BinaryJoinerType, class UnaryTransform> -ValueType transform_reduce(const std::string& label, (12) - const ExecutionSpace& exespace, - const ::Kokkos::View& first_view, - ValueType init_reduction_value, - BinaryJoinerType joiner, - UnaryTransform unary_transformer); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- (1,2): performs the *product* (via `operator*`) between each pair - of elements in the range `[first1, last1)` and the range starting at `first2`, - and reduces the results along with the initial value `init_reduction_value` - -- (3,4): performs the *product* (via `operator*`) between each pair - of elements in `first_view` and `second_view`, - and reduces the results along with the initial value `init_reduction_value` - -- (5,6): applies the functor `binary_transformer` to each pair of elements - in the range `[first1, last1)` and the range starting at `first2`, - and reduces the results along with the initial value `init_reduction_value` - with the join operation done via the *binary* functor `joiner` - -- (7,8): applies the functor `binary_transformer` to each pair of elements - in `first_view` and `second_view`, - and reduces the result along with the initial value `init_reduction_value` - with the join operation done via the *binary* functor `joiner` - -- (9,10): applies the functor `unary_transformer` to each element - in the range `[first, last)`, and reduces the results along with - the initial value `init_reduction_value` - with the join operation done via the *binary* functor `joiner` - -- (11,12): applies the functor `unary_transformer` to each element - in `view`, and reduces the results along with - the initial value `init_reduction_value` - with the join operation done via the *binary* functor `joiner` - - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,5,9 the default string is: "Kokkos::transform_reduce_iterator_api_default" - - for 3,7,11 the default string is: "Kokkos::transform_reduce_view_api_default" -- `first1`, `last1`, `first2`: - - ranges of elements to transform and reduce - - must be *random access iterators* - - must represent a valid range, i.e., `last1 >= first1` (checked in debug mode) - - must be accessible from `exespace` -- `first_view`, `second_view`: - - views to transform and reduce - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `init_reduction_value`: - - initial reduction value to use -- `joiner`: - - *binary* functor performing the desired operation to join two elements. - Must be valid to be called from the execution space passed, and callable with - two arguments `a,b` of type (possible const) `ValueType`, and must not modify `a,b`. - - Must conform to: - ```c++ - struct JoinFunctor { - KOKKOS_FUNCTION - constexpr ValueType operator()(const ValueType& a, - const ValueType& b) const { - return /* ... */ - } - }; - ``` - - The behavior is non-deterministic if the `joiner` operation - is not associative or not commutative. - -- `binary_transformer`: - - *binary* functor applied to each pair of elements *before* doing the reduction. - Must be valid to be called from the execution space passed, and callable with - two arguments `a,b` of type (possible const) `value_type_a` and `value_type_b`, - where `value_type_{a,b}` are the value types of `first1` and `first2` (for 1,2,5,6) - or the value types of `first_view` and `second_view` (for 3,4,7,8), and must not modify `a,b`. - - Must conform to: - ```c++ - struct BinaryTransformer { - KOKKOS_FUNCTION - constexpr return_type operator()(const value_type_a & a, const value_type_b & b) const { - return /* ... */ - } - }; - ``` - - the `return_type` is such that it can be accepted by the `joiner` - -- `unary_transformer`: - - *unary* functor performing the desired operation to an element. - Must be valid to be called from the execution space passed, and callable with - an arguments `v` of type (possible const) `value_type`, - where `value_type` is the value type of `first1` (for 9,10) - or the value type of `first_view` (for 11,12), and must not modify `v`. - - Must conform to: - ```c++ - struct UnaryTransformer { - KOKKOS_FUNCTION - constexpr value_type operator()(const value_type & v) const { - return /* ... */ - } - }; - ``` - -## Return - -The reduction result. \ No newline at end of file diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst new file mode 100644 index 000000000..08a9d00ef --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst @@ -0,0 +1,326 @@ +``transform_reduce`` +==================== + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +Performs the *product* (via ``operator*``, the functor ``binary_transformer`` or the functor ``unary_transformer``) between each pair of elements in: + +- the range ``[first1, last1)`` and the range starting at ``first2``, or + +- ``first_view`` and ``second_view``, or + +- the range ``[first, last)``, or + +- ``view``, + +and reduces the results along with the initial value ``init_reduction_value`` and with the join operation done via the *binary* functor ``joiner`` if needed. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set A + // + template < + class ExecutionSpace, class IteratorType1, + class IteratorType2, class ValueType> + ValueType transform_reduce(const ExecutionSpace& exespace, (1) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value); + + template < + class ExecutionSpace, class IteratorType1, + class IteratorType2, class ValueType> + ValueType transform_reduce(const std::string& label, (2) + const ExecutionSpace& exespace, + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + ValueType transform_reduce(const ExecutionSpace& exespace, (3) + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + ValueType transform_reduce(const std::string& label, (4) + const ExecutionSpace& exespace, + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value); + + template < + class TeamHandleType, + class IteratorType1, class IteratorType2, + class ValueType> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (5) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (6) + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value); + + // + // overload set B + // + template < + class ExecutionSpace, + class IteratorType1, class IteratorType2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + ValueType transform_reduce(const ExecutionSpace& exespace, (7) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + template < + class ExecutionSpace, + class IteratorType1, class IteratorType2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + ValueType transform_reduce(const std::string& label, (8) + const ExecutionSpace& exespace, + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + ValueType transform_reduce(const ExecutionSpace& exespace, (9) + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + ValueType transform_reduce(const std::string& label, (10) + const ExecutionSpace& exespace, + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + template < + class TeamHandleType, + class IteratorType1, class IteratorType2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (11) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (12) + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + // + // overload set C + // + template < + class ExecutionSpace, + class IteratorType, class ValueType, + class BinaryJoinerType, class UnaryTransform> + ValueType transform_reduce(const ExecutionSpace& exespace, (13) + IteratorType first1, IteratorType last1, + ValueType init_reduction_value, + BinaryJoinerType joiner, + UnaryTransform unary_transformer); + + template < + class ExecutionSpace, + class IteratorType, class ValueType, + class BinaryJoinerType, class UnaryTransform> + ValueType transform_reduce(const std::string& label, (14) + const ExecutionSpace& exespace, + IteratorType first1, IteratorType last1, + ValueType init_reduction_value, + BinaryJoinerType joiner, + UnaryTransform unary_transformer); + + template < + class ExecutionSpace, + class DataType, class... Properties, class ValueType, + class BinaryJoinerType, class UnaryTransform> + ValueType transform_reduce(const ExecutionSpace& exespace, (15) + const Kokkos::View& view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + UnaryTransform unary_transformer); + + template < + class ExecutionSpace, + class DataType, class... Properties, class ValueType, + class BinaryJoinerType, class UnaryTransform> + ValueType transform_reduce(const std::string& label, (16) + const ExecutionSpace& exespace, + const Kokkos::View& view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + UnaryTransform unary_transformer); + + template < + class TeamHandleType, + class IteratorType, class ValueType, + class BinaryJoinerType, class UnaryTransform> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (17) + IteratorType first1, IteratorType last1, + ValueType init_reduction_value, + BinaryJoinerType joiner, + UnaryTransform unary_transformer); + + template < + class TeamHandleType, + class DataType, class... Properties, + class ValueType, + class BinaryJoinerType, class UnaryTransform> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (18) + const Kokkos::View& view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + UnaryTransform unary_transformer); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1 & 3: The default string is "Kokkos::transform_reduce_default_functors_iterator_api" + + - 7 & 13: The default string is "Kokkos::transform_reduce_custom_functors_iterator_api" + + - 9 & 15: The default string is "Kokkos::transform_reduce_custom_functors_view_api" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first1``, ``last1``, ``first2``: ranges of elements to transform and reduce + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last_from >= first_from`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``first_view``, ``second_view``: views to transform and reduce + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``init_reduction_value``: initial reduction value to use + +- ``joiner``: + + - *binary* functor performing the desired operation to join two elements. Must be valid to be called from the execution space passed, and callable with two arguments ``a,b`` of type (possible const) ``ValueType``, and must not modify ``a,b``. + + - Must conform to: + + .. code-block:: cpp + + struct JoinFunctor { + KOKKOS_FUNCTION + constexpr ValueType operator()(const ValueType& a, + const ValueType& b) const { + return /* ... */ + } + }; + + - The behavior is non-deterministic if the ``joiner`` operation is not associative or not commutative. + +- ``binary_transformer``: + + - *binary* functor applied to each pair of elements *before* doing the reduction. Must be valid to be called from the execution space passed, and callable with two arguments ``a,b`` of type (possible const) ``value_type_a`` and ``value_type_b``, where ``value_type_{a,b}`` are the value types of ``first1`` and ``first2`` or the value types of ``first_view`` and ``second_view``, and must not modify ``a,b``. + + - Must conform to: + + .. code-block:: cpp + + struct BinaryTransformer { + KOKKOS_FUNCTION + constexpr return_type operator()(const value_type_a & a, const value_type_b & b) const { + return /* ... */ + } + }; + + - the ``return_type`` is such that it can be accepted by the ``joiner`` + +- ``unary_transformer``: + + - *unary* functor performing the desired operation to an element. Must be valid to be called from the execution space passed, and callable with an arguments ``v`` of type (possible const) ``value_type``, where ``value_type`` is the value type of ``first1`` or the value type of ``first_view``, and must not modify ``v``. + + - Must conform to: + + .. code-block:: cpp + + struct UnaryTransformer { + KOKKOS_FUNCTION + constexpr value_type operator()(const value_type & v) const { + return /* ... */ + } + }; + +Return Value +~~~~~~~~~~~~ + +The reduction result. \ No newline at end of file From a7d763abf9bbc7a7c045382287f79ca17c72f2a7 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 15:46:47 +0200 Subject: [PATCH 08/13] Convert StdExclusiveScan from md to rst: init --- .../std-algorithms/all/StdExclusiveScan.md | 152 ------------- .../std-algorithms/all/StdExclusiveScan.rst | 212 ++++++++++++++++++ 2 files changed, 212 insertions(+), 152 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.md b/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.md deleted file mode 100644 index f05298de3..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.md +++ /dev/null @@ -1,152 +0,0 @@ - -# `exclusive_scan` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -// -// overload set A -// -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class ValueType> -OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (1) - InputIteratorType first, - InputIteratorType last, - OutputIteratorType first_dest, - ValueType init_value); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class ValueType> -OutputIteratorType exclusive_scan(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIteratorType first, - InputIteratorType last, - OutputIteratorType first_dest, - ValueType init_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType> -auto exclusive_scan(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - ValueType init_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType> -auto exclusive_scan(const std::string& label, const ExecutionSpace& exespace, (4) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - ValueType init_value); - -// -// overload set B -// -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class ValueType, class BinaryOpType - > -OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (5) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - ValueType init_value, BinaryOpType bin_op); - - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class ValueType, class BinaryOpType - > -OutputIteratorType exclusive_scan(const std::string& label, (6) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - ValueType init_value, BinaryOpType bin_op); - -template < - class ExecutionSpace, class DataType1, class... Properties1, - class DataType2, class... Properties2, class ValueType, - class BinaryOpType> -auto exclusive_scan(const ExecutionSpace& exespace, (7) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - ValueType init_value, BinaryOpType bin_op); - -template < - class ExecutionSpace, class DataType1, class... Properties1, - class DataType2, class... Properties2, class ValueType, - class BinaryOpType> -auto exclusive_scan(const std::string& label, const ExecutionSpace& exespace, (8) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - ValueType init_value, BinaryOpType bin_op); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- 1,2,3,4: computes an exclusive prefix *sum* for the range `[first_from, last_from)` (1,2) -or `view_from` (3,4), using `init` as the initial value, and writes -the results to the range beginning at `first_dest` (1,2) or to `view_dest` (3,4). - -- 5,6,7,8: computes an exclusive prefix scan using the binary functor `bin_op` -to combine two elements for the range `[first_from, last_from)` (5,6) -or `view_from` (7,8), using `init` as the initial value, and writes -the results to the range beginning at `first_dest` (5,6) or to `view_dest` (7,8). - -Exclusive means that the i-th input element is not included in the i-th sum. - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,2 the default string is: "Kokkos::exclusive_scan_iterator_api_default" - - for 5,6 the default string is: "Kokkos::exclusive_scan_view_api_default" -- `first_from`, `last_from`, `first_dest`: - - range of elements to read from (`*_from`) and write to (`first_dest`) - - must be *random access iterators* - - must represent a valid range, i.e., `last_from >= first_from` (checked in debug mode) - - must be accessible from `exespace` -- `view_from`, `view_dest`: - - views to read elements from `view_from` and write to `view_dest` - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `bin_op`: - - *binary* functor representing the operation to combine pair of elements. - Must be valid to be called from the execution space passed, and callable with - two arguments `a,b` of type (possible const) `value_type`, where `value_type` - is the value type of `InputIteratorType` (for 1,2,5,6) or the value type - of `view_from` (for 3,4,7,8), and must not modify `a,b`. - - must conform to: - ```c++ - struct BinaryOp - { - KOKKOS_INLINE_FUNCTION - return_type operator()(const value_type & a, - const value_type & b) const { - return /* ... */; - } - }; - ``` - The return type `return_type` must be such that an object of type `OutputIteratorType` - for (1,2,5,6) or an object of type `value_type` where `value_type` is the - value type of `view_dest` for (3,4,7,8) can be dereferenced and assigned a value of type `return_type`. - -## Return - -Iterator to the element *after* the last element written. \ No newline at end of file diff --git a/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst new file mode 100644 index 000000000..5c15e92df --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst @@ -0,0 +1,212 @@ +``exclusive_scan`` +================== + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +Computes an exclusive prefix: + +- *sum* for the range ``[first_from, last_from)`` + +- scan using the binary functor ``bin_op`` to combine two elements for the range ``[first_from, last_from)`` + +or ``view_from``, using ``init`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. + +Exclusive means that the i-th input element is not included in the i-th sum. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set A + // + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType> + OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (1) + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType> + OutputIteratorType exclusive_scan(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + auto exclusive_scan(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + auto exclusive_scan(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value); + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class ValueType> + KOKKOS_FUNCTION + OutputIteratorType exclusive_scan(const TeamHandleType& teamHandle, (5) + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + KOKKOS_FUNCTION + auto exclusive_scan(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value); + + // + // overload set B + // + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType, class BinaryOpType> + OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (7) + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value, BinaryOpType bop); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType, class BinaryOpType> + OutputIteratorType exclusive_scan(const std::string& label, (8) + const ExecutionSpace& exespace, + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value, + BinaryOpType bop); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, class BinaryOpType> + auto exclusive_scan(const ExecutionSpace& exespace, (9) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value, BinaryOpType bop); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, class BinaryOpType> + auto exclusive_scan(const std::string& label, (10) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value, BinaryOpType bop); + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class ValueType, class BinaryOpType> + KOKKOS_FUNCTION + OutputIteratorType exclusive_scan(const TeamHandleType& teamHandle, (11) + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value, + BinaryOpType bop); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, class BinaryOpType> + KOKKOS_FUNCTION + auto exclusive_scan(const TeamHandleType& teamHandle, (12) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value, BinaryOpType bop); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1: The default string is "Kokkos::exclusive_scan_default_functors_iterator_api" + + - 3: The default string is "Kokkos::exclusive_scan_default_functors_view_api" + + - 7: The default string is "Kokkos::exclusive_scan_custom_functors_iterator_api" + + - 9: The default string is "Kokkos::exclusive_scan_custom_functors_view_api" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first_from``, ``last_from``, ``first_dest``: range of elements to read from (``*_from``) and write to (``first_dest``) + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last_from >= first_from`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view_from``, ``view_dest``: views to read elements from ``view_from`` and write to ``view_dest`` + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``bin_op``: + + - *binary* functor representing the operation to combine pair of elements. Must be valid to be called from the execution space passed, and callable with two arguments ``a,b`` of type (possible const) ``value_type``, where ``value_type`` is the value type of ``InputIteratorType`` or the value type of ``view_from``, and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + struct BinaryOp + { + KOKKOS_INLINE_FUNCTION + return_type operator()(const value_type & a, + const value_type & b) const { + return /* ... */; + } + }; + + The return type ``return_type`` must be such that an object of type ``OutputIteratorType`` + or an object of type ``value_type`` where ``value_type`` is the + value type of ``view_dest`` can be dereferenced and assigned a value of type ``return_type``. + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element written. \ No newline at end of file From a9005a9d44b07095cb48584af14916e164ef79bf Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 18:10:44 +0200 Subject: [PATCH 09/13] Convert StdTransformExclusiveScan from md to rst: init --- .../all/StdTransformExclusiveScan.md | 98 ------------- .../all/StdTransformExclusiveScan.rst | 137 ++++++++++++++++++ 2 files changed, 137 insertions(+), 98 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.md b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.md deleted file mode 100644 index b2145ebcc..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.md +++ /dev/null @@ -1,98 +0,0 @@ -# `transform_exclusive_scan` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class ValueType, - class BinaryOpType, class UnaryOpType> -OutputIteratorType transform_exclusive_scan(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - ValueType init_value, - BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class ValueType, - class BinaryOpType, class UnaryOpType> -OutputIteratorType transform_exclusive_scan(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - ValueType init_value, - BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType, class BinaryOpType, class UnaryOpType> -auto transform_exclusive_scan(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - ValueType init_value, BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType, class BinaryOpType, class UnaryOpType> -auto transform_exclusive_scan(const std::string& label, (4) - const ExecutionSpace& exespace, - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - ValueType init_value, BinaryOpType binary_op, - UnaryOpType unary_op); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- 1,2: transforms each element in the range `[first_from, last_from)` -with `unary_op`, then computes an exclusive prefix scan operation using `binary_op` -over the resulting range, with `init` as the initial value, and writes -the results to the range beginning at `first_dest`. -"exclusive" means that the i-th input element is not included in the i-th sum - -- 3,4: same as (1,2) except that the elements are read from `view_from` -and written to `view_dest` - -## Parameters and Requirements - -- `exespace`, `first_from`, `first_last`, `first_dest`, `view_from`, `view_dest`: - - same as [`exclusive_scan`](./StdExclusiveScan) -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1 the default string is: "Kokkos::transform_exclusive_scan_iterator_api_default" - - for 3 the default string is: "Kokkos::transform_exclusive_scan_view_api_default" -- `unary_op`: - - *unary* functor performing the desired transformation operation to an element. - Must be valid to be called from the execution space passed, and callable with - an arguments `v` of type (possible const) `value_type`, - where `value_type` is the value type of `first_from` (for 1,2) - or the value type of `view_from` (for 3,4), and must not modify `v`. - - Must conform to: - ```c++ - struct UnaryOp { - KOKKOS_FUNCTION - constexpr value_type operator()(const value_type & v) const { - return /* ... */ - } - }; - ``` - -## Return - -Iterator to the element *after* the last element written. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst new file mode 100644 index 000000000..9c5561e52 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst @@ -0,0 +1,137 @@ +``transform_exclusive_scan`` +============================ + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +Transforms each element in a range or a ``view`` with ``unary_op`` then computes an exclusive prefix scan operation using ``binary_op`` over the resulting range, with ``init`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. +"exclusive" means that the i-th input element is not included in the i-th sum. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set accepting execution space + // + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType, + class BinaryOpType, class UnaryOpType> + OutputIteratorType transform_exclusive_scan(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + ValueType init_value, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType, + class BinaryOpType, class UnaryOpType> + OutputIteratorType transform_exclusive_scan(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + ValueType init_value, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, class BinaryOpType, class UnaryOpType> + auto transform_exclusive_scan(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, class BinaryOpType, class UnaryOpType> + auto transform_exclusive_scan(const std::string& label, (4) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value, + BinaryOpType binary_op, + UnaryOpType unary_op); + + // + // overload set accepting a team handle + // + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class ValueType, + class BinaryOpType, class UnaryOpType> + KOKKOS_FUNCTION + OutputIteratorType transform_exclusive_scan(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + ValueType init_value, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, class BinaryOpType, class UnaryOpType> + KOKKOS_FUNCTION + auto transform_exclusive_scan(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value, + BinaryOpType binary_op, + UnaryOpType unary_op); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |ExclusiveScan| replace:: ``exclusive_scan`` +.. _ExclusiveScan: ./StdExclusiveScan.html + +- ``exespace``, ``first_from``, ``first_last``, ``first_dest``, ``view_from``, ``view_dest``: same as |ExclusiveScan|_ + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1: The default string is "Kokkos::transform_exclusive_scan_custom_functors_iterator_api" + + - 3: The default string is "Kokkos::transform_exclusive_scan_custom_functors_view_api" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``unary_op``: + + - *unary* functor performing the desired transformation operation to an element. Must be valid to be called from the execution space passed, and callable with an arguments ``v`` of type (possible const) ``value_type``, where ``value_type`` is the value type of ``first_from`` or value type of ``view_from``, and must not modify ``v``. + + - Must conform to: + + .. code-block:: cpp + + struct UnaryOp { + KOKKOS_FUNCTION + constexpr value_type operator()(const value_type & v) const { + return /* ... */ + } + }; + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element written. From 711acaf6a7196ee7fa30e1b28743a5721e5bd49f Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 18:43:56 +0200 Subject: [PATCH 10/13] Convert StdInclusiveScan from md to rst: fix --- .../std-algorithms/all/StdInclusiveScan.md | 166 ------------- .../std-algorithms/all/StdInclusiveScan.rst | 228 ++++++++++++++++++ 2 files changed, 228 insertions(+), 166 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.md b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.md deleted file mode 100644 index e48d666ca..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.md +++ /dev/null @@ -1,166 +0,0 @@ - -# `inclusive_scan` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -// -// overload set A -// -template -OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest); - -template -OutputIteratorType inclusive_scan(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2> -auto inclusive_scan(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2> -auto inclusive_scan(const std::string& label, const ExecutionSpace& exespace, (4) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest); - -// -// overload set B -// -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType - > -OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (5) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType bin_op); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType - > -OutputIteratorType inclusive_scan(const std::string& label, (6) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType bin_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType> -auto inclusive_scan(const ExecutionSpace& exespace, (7) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType bin_op); - -template < - class ExecutionSpace, class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType> -auto inclusive_scan(const std::string& label, const ExecutionSpace& exespace, (8) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType bin_op); - -// -// overload set C -// -template < - class ExecutionSpace, - class InputIteratorType, class OutputIteratorType, - class BinaryOpType, class ValueType - > -OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (9) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType bin_op, - ValueType init_value); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType, class ValueType - > -OutputIteratorType inclusive_scan(const std::string& label, (10) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType bin_op, - ValueType init_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class ValueType> -auto inclusive_scan(const ExecutionSpace& exespace, (11) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType bin_op, - ValueType init_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class ValueType> -auto inclusive_scan(const std::string& label, const ExecutionSpace& exespace, (12) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType bin_op, - ValueType init_value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- 1,2,3,4: computes an inclusive prefix scan over the range `[first_from, last_from)` (1,2) -or for `view_from` (3,4) using the binary op `bin_op` to combine two elements, -and writes the results to the range beginning at `first_dest` (1,2) or to `view_dest` (3,4). - -- 5,6,7,8: computes an inclusive prefix scan over the range `[first_from, last_from)` (5,6) -or `view_from` (7,8) using the binary op `bin_op` to combine two elements, and writes -the results to the range beginning at `first_dest` (5,6) or to `view_dest` (7,8). - -- 9,10,11,12: computes an inclusive prefix scan over the range `[first_from, last_from)` (9,10) -or `view_from` (11,12) using the binary functor `bin_op` to combine two elements -and `init` as the initial value, and writes -the results to the range beginning at `first_dest` (9,10) or to `view_dest` (11,12). - -Inclusive means that the i-th input element is included in the i-th sum. - -## Parameters and Requirements - -- `exespace`, `first_from`, `first_last`, `first_dest`, `view_from`, `view_dest`, `bin_op`: - - same as in [`exclusive_scan`](./StdExclusiveScan) -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,5,9 the default string is: "Kokkos::inclusive_scan_iterator_api_default" - - for 3,7,11 the default string is: "Kokkos::inclusive_scan_view_api_default" - -## Return - -Iterator to the element *after* the last element written. \ No newline at end of file diff --git a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst new file mode 100644 index 000000000..662693adc --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst @@ -0,0 +1,228 @@ +``inclusive_scan`` +================== + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +Computes an inclusive prefix scan over a range or a ``view_from`` using the binary op ``bin_op`` to combine two elements, and ``init`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. +Inclusive means that the i-th input element is included in the i-th sum. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set A + // + template + OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest); + + template + OutputIteratorType inclusive_scan(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + auto inclusive_scan(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_dest); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + auto inclusive_scan(const std::string& label, (4) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest); + + template + KOKKOS_FUNCTION + OutputIteratorType inclusive_scan(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + KOKKOS_FUNCTION + auto inclusive_scan(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_dest); + + // + // overload set B + // + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOp> + OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (7) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOp> + OutputIteratorType inclusive_scan(const std::string& label, (8) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + auto inclusive_scan(const ExecutionSpace& exespace, (9) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + auto inclusive_scan(const std::string& label, (10) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op); + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class BinaryOp> + KOKKOS_FUNCTION + OutputIteratorType inclusive_scan(const TeamHandleType& teamHandle, (11) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + KOKKOS_FUNCTION + auto inclusive_scan(const TeamHandleType& teamHandle, (12) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op); + + // + // overload set C + // + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType, + class BinaryOp, class ValueType> + OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (13) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op, + ValueType init_value); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOp, class ValueType> + OutputIteratorType inclusive_scan(const std::string& label, (14) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op, + ValueType init_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp, class ValueType> + auto inclusive_scan(const ExecutionSpace& exespace, (15) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op, + ValueType init_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp, class ValueType> + auto inclusive_scan(const std::string& label, (16) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op, + ValueType init_value); + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class BinaryOp, class ValueType> + KOKKOS_FUNCTION + OutputIteratorType inclusive_scan(const TeamHandleType& teamHandle, (17) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op, + ValueType init_value); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp, class ValueType> + KOKKOS_FUNCTION + auto inclusive_scan(const TeamHandleType& teamHandle, (18) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op, + ValueType init_value); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |ExclusiveScan| replace:: ``exclusive_scan`` +.. _ExclusiveScan: ./StdExclusiveScan.html + +- ``exespace``, ``first_from``, ``first_last``, ``first_dest``, ``view_from``, ``view_dest``, ``bin_op``: same as in |ExclusiveScan|_ + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1: The default string is "Kokkos::inclusive_scan_default_functors_iterator_api" + + - 3: The default string is "Kokkos::inclusive_scan_default_functors_view_api" + + - 7, 13: The default string is "Kokkos::inclusive_scan_custom_functors_iterator_api" + + - 9, 15: The default string is "Kokkos::inclusive_scan_custom_functors_view_api" + + - NOTE: overloads accepting a team handle do not use a label internally + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element written. \ No newline at end of file From 85d8c2c1372abf018359917e5398355395235185 Mon Sep 17 00:00:00 2001 From: antoinemeyer5 Date: Mon, 17 Jul 2023 19:36:42 +0200 Subject: [PATCH 11/13] Convert StdTransformInclusiveScan from md to rst: init --- .../all/StdTransformInclusiveScan.md | 132 ------------ .../all/StdTransformInclusiveScan.rst | 188 ++++++++++++++++++ 2 files changed, 188 insertions(+), 132 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.md b/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.md deleted file mode 100644 index 552c829ae..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.md +++ /dev/null @@ -1,132 +0,0 @@ - -# `transform_inclusive_scan` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType, class UnaryOpType> -OutputIteratorType transform_inclusive_scan(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType, class UnaryOpType> -OutputIteratorType transform_inclusive_scan(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class UnaryOpType> -auto transform_inclusive_scan(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class UnaryOpType> -auto transform_inclusive_scan(const std::string& label, (4) - const ExecutionSpace& exespace, - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType binary_op, - UnaryOpType unary_op); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType, class UnaryOpType, - class ValueType> -OutputIteratorType transform_inclusive_scan(const ExecutionSpace& exespace, (5) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType binary_op, - UnaryOpType unary_op, - ValueType init_value); - -template < - class ExecutionSpace, class InputIteratorType, - class OutputIteratorType, class BinaryOpType, class UnaryOpType, - class ValueType> -OutputIteratorType transform_inclusive_scan(const std::string& label, (6) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType binary_op, - UnaryOpType unary_op, - ValueType init_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class UnaryOpType, class ValueType> -auto transform_inclusive_scan(const ExecutionSpace& exespace, (7) - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType binary_op, UnaryOpType unary_op, - ValueType init_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class UnaryOpType, class ValueType> -auto transform_inclusive_scan(const std::string& label, (8) - const ExecutionSpace& exespace, - const ::Kokkos::View& view_from, - const ::Kokkos::View& view_dest, - BinaryOpType binary_op, UnaryOpType unary_op, - ValueType init_value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- 1,2: transforms each element in the range `[first_from, last_from)` -with `unary_op`, then computes an inclusive prefix scan operation using `binary_op` -over the resulting range, and writes the results to the range beginning at `first_dest`. - -- 3,4: same as (1,2) except that the elements are read from `view_from` -and written to `view_dest` - -- 5,6: same as (1,2) but the scan accounts for the `init_value`. - -- 7,8: same as (3,4) but the scan accounts for the `init_value`. - -Inclusive means that the i-th input element is included in the i-th sum. - -## Parameters and Requirements - -- `exespace`, `first_from`, `first_last`, `first_dest`, `view_from`, `view_dest`, `init_value`, `bin_op`, `unary_op`: - - same as [`transform_exclusive_scan`](./StdTransformExclusiveScan) -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,5 the default string is: "Kokkos::transform_inclusive_scan_iterator_api_default" - - for 3,7 the default string is: "Kokkos::transform_inclusive_scan_view_api_default" - -## Return - -Iterator to the element *after* the last element written. \ No newline at end of file diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst new file mode 100644 index 000000000..d686aed5c --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst @@ -0,0 +1,188 @@ +``transform_inclusive_scan`` +============================ + +Header: ``Kokkos_StdAlgorithms.hpp`` + +Description +----------- + +Transforms each element in a range or ``view_from`` with ``unary_op``, then computes an inclusive prefix scan operation using ``binary_op`` over the resulting range, with ``init_value`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. + +Inclusive means that the i-th input element is included in the i-th sum. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +.. code-block:: cpp + + // + // overload set A: no init value + // + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType> + OutputIteratorType transform_inclusive_scan(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType> + OutputIteratorType transform_inclusive_scan(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType> + auto transform_inclusive_scan(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType> + auto transform_inclusive_scan(const std::string& label, (4) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType> + KOKKOS_FUNCTION + OutputIteratorType transform_inclusive_scan(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType> + KOKKOS_FUNCTION + auto transform_inclusive_scan(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + // + // overload set B: init value + // + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType, + class ValueType> + OutputIteratorType transform_inclusive_scan(const ExecutionSpace& exespace, (7) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op, + ValueType init_value); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType, + class ValueType> + OutputIteratorType transform_inclusive_scan(const std::string& label, (8) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op, + ValueType init_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType, class ValueType> + auto transform_inclusive_scan(const ExecutionSpace& exespace, (9) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op, + ValueType init_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType, class ValueType> + auto transform_inclusive_scan(const std::string& label, (10) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op, + ValueType init_value); + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType, + class ValueType> + KOKKOS_FUNCTION + OutputIteratorType transform_inclusive_scan(const TeamHandleType& teamHandle, (11) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op, + ValueType init_value); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType, class ValueType> + KOKKOS_FUNCTION + auto transform_inclusive_scan(const TeamHandleType& teamHandle, (12) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op, + ValueType init_value); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |TransformExclusiveScan| replace:: ``transform_exclusive_scan`` +.. _TransformExclusiveScan: ./StdTransformExclusiveScan.html + +- ``exespace``, ``first_from``, ``first_last``, ``first_dest``, ``view_from``, ``view_dest``, ``init_value``, ``bin_op``, ``unary_op``: same as |TransformExclusiveScan|_ + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1,7: The default string is "Kokkos::transform_inclusive_scan_custom_functors_iterator_api" + + - 3,9: The default string is "Kokkos::transform_inclusive_scan_custom_functors_view_api" + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element written. \ No newline at end of file From e0cef00193034ab6214ad3f13df30fe312da9510 Mon Sep 17 00:00:00 2001 From: Francesco Rizzi Date: Sat, 16 Dec 2023 12:19:52 +0100 Subject: [PATCH 12/13] progress --- .../all/StdAdjacentDifference.rst | 39 ++--- .../std-algorithms/all/StdExclusiveScan.rst | 70 ++++----- .../std-algorithms/all/StdInclusiveScan.rst | 73 +++++----- .../std-algorithms/all/StdPartitionPoint.rst | 24 ++-- .../std-algorithms/all/StdReduce.rst | 12 +- .../all/StdTransformExclusiveScan.rst | 16 ++- .../all/StdTransformInclusiveScan.rst | 76 +++++----- .../std-algorithms/all/StdTransformReduce.rst | 134 +++++++++--------- 8 files changed, 235 insertions(+), 209 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst index dd0ff7f46..e0c67411f 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst @@ -1,24 +1,28 @@ ``adjacent_difference`` ======================= -Header: ``Kokkos_StdAlgorithms.hpp`` +Header: ```` Description ----------- -First, a copy of ``*first_from`` is written to ``*first_dest``, or a copy of ``view_from(0)`` is written to ``view_dest(0)``. -Second, it computes the *difference* or calls the binary functor between the second and the first of each adjacent pair of elements of a range or in ``view_from``, and writes them to the range beginning at ``first_dest + 1``, or ``view_dest``. +This function performs the following two operations. +First, a copy of ``*first_from`` is written to ``*first_dest``, or a copy of ``view_from(0)`` +is written to ``view_dest(0)``. +Second, it computes the *difference* or calls the binary functor between the second and +the first of each adjacent pair of elements of a range or in ``view_from``, +and writes them to the range beginning at ``first_dest + 1``, or ``view_dest``. Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType> @@ -57,9 +61,6 @@ Interface OutputIteratorType first_dest, BinaryOp bin_op); - // - // overload set accepting views - // template < class ExecutionSpace, class DataType1, class... Properties1, @@ -98,9 +99,13 @@ Interface const Kokkos::View& view_dest, BinaryOp bin_op); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template < class TeamHandleType, class InputIteratorType, class OutputIteratorType> @@ -150,13 +155,13 @@ Parameters and Requirements - ``label``: string forwarded to internal parallel kernels for debugging purposes - - 1 & 2: The default string is "Kokkos::adjacent_difference_iterator_api" + - 1, 2: The default string is "Kokkos::adjacent_difference_iterator_api" - - 5 & 6: The default string is "Kokkos::adjacent_difference_view_api" + - 5, 6: The default string is "Kokkos::adjacent_difference_view_api" - NOTE: overloads accepting a team handle do not use a label internally -- ``first_from``, ``last_from``, ``first_dest``: range of elements to read from ``*_from`` and write to ``first_dest`` +- ``first_from``, ``last_from``, ``first_dest``: range of elements to read from and write to - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` @@ -164,7 +169,7 @@ Parameters and Requirements - must be accessible from ``exespace`` or from the execution space associated with the team handle -- ``view_from``, ``view_dest``: views to read elements from ``view_from`` and write to ``view_dest`` +- ``view_from``, ``view_dest``: views to read elements from and write to - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` @@ -200,4 +205,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -Iterator to the element *after* the last element written. \ No newline at end of file +Iterator to the element *after* the last element written. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst index 5c15e92df..a4f055743 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst @@ -21,11 +21,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set A - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class ValueType> @@ -65,34 +65,10 @@ Interface const Kokkos::View& view_dest, ValueType init_value); - template < - class TeamHandleType, class InputIteratorType, - class OutputIteratorType, class ValueType> - KOKKOS_FUNCTION - OutputIteratorType exclusive_scan(const TeamHandleType& teamHandle, (5) - InputIteratorType first, - InputIteratorType last, - OutputIteratorType first_dest, - ValueType init_value); - - template < - class TeamHandleType, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType> - KOKKOS_FUNCTION - auto exclusive_scan(const TeamHandleType& teamHandle, (6) - const Kokkos::View& view_from, - const Kokkos::View& view_dest, - ValueType init_value); - - // - // overload set B - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class ValueType, class BinaryOpType> - OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (7) + OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (5) InputIteratorType first, InputIteratorType last, OutputIteratorType first_dest, @@ -101,7 +77,7 @@ Interface template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class ValueType, class BinaryOpType> - OutputIteratorType exclusive_scan(const std::string& label, (8) + OutputIteratorType exclusive_scan(const std::string& label, (6) const ExecutionSpace& exespace, InputIteratorType first, InputIteratorType last, @@ -114,7 +90,7 @@ Interface class DataType1, class... Properties1, class DataType2, class... Properties2, class ValueType, class BinaryOpType> - auto exclusive_scan(const ExecutionSpace& exespace, (9) + auto exclusive_scan(const ExecutionSpace& exespace, (7) const Kokkos::View& view_from, const Kokkos::View& view_dest, ValueType init_value, BinaryOpType bop); @@ -124,12 +100,42 @@ Interface class DataType1, class... Properties1, class DataType2, class... Properties2, class ValueType, class BinaryOpType> - auto exclusive_scan(const std::string& label, (10) + auto exclusive_scan(const std::string& label, (8) const ExecutionSpace& exespace, const Kokkos::View& view_from, const Kokkos::View& view_dest, ValueType init_value, BinaryOpType bop); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class ValueType> + KOKKOS_FUNCTION + OutputIteratorType exclusive_scan(const TeamHandleType& teamHandle, (9) + InputIteratorType first, + InputIteratorType last, + OutputIteratorType first_dest, + ValueType init_value); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + KOKKOS_FUNCTION + auto exclusive_scan(const TeamHandleType& teamHandle, (10) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + ValueType init_value); + + template < class TeamHandleType, class InputIteratorType, class OutputIteratorType, class ValueType, class BinaryOpType> @@ -209,4 +215,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -Iterator to the element *after* the last element written. \ No newline at end of file +Iterator to the element *after* the last element written. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst index 662693adc..d2ce72ddd 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst @@ -14,11 +14,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set A - // template OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (1) InputIteratorType first_from, @@ -65,9 +65,6 @@ Interface const Kokkos::View& view_from, const Kokkos::View& view_dest); - // - // overload set B - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class BinaryOp> @@ -108,35 +105,11 @@ Interface const Kokkos::View& view_dest, BinaryOp binary_op); - template < - class TeamHandleType, class InputIteratorType, - class OutputIteratorType, class BinaryOp> - KOKKOS_FUNCTION - OutputIteratorType inclusive_scan(const TeamHandleType& teamHandle, (11) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOp binary_op); - - template < - class TeamHandleType, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOp> - KOKKOS_FUNCTION - auto inclusive_scan(const TeamHandleType& teamHandle, (12) - const Kokkos::View& view_from, - const Kokkos::View& view_dest, - BinaryOp binary_op); - - // - // overload set C - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class BinaryOp, class ValueType> - OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (13) + OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (11) InputIteratorType first_from, InputIteratorType last_from, OutputIteratorType first_dest, @@ -146,7 +119,7 @@ Interface template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class BinaryOp, class ValueType> - OutputIteratorType inclusive_scan(const std::string& label, (14) + OutputIteratorType inclusive_scan(const std::string& label, (12) const ExecutionSpace& exespace, InputIteratorType first_from, InputIteratorType last_from, @@ -159,7 +132,7 @@ Interface class DataType1, class... Properties1, class DataType2, class... Properties2, class BinaryOp, class ValueType> - auto inclusive_scan(const ExecutionSpace& exespace, (15) + auto inclusive_scan(const ExecutionSpace& exespace, (13) const Kokkos::View& view_from, const Kokkos::View& view_dest, BinaryOp binary_op, @@ -170,13 +143,43 @@ Interface class DataType1, class... Properties1, class DataType2, class... Properties2, class BinaryOp, class ValueType> - auto inclusive_scan(const std::string& label, (16) + auto inclusive_scan(const std::string& label, (14) const ExecutionSpace& exespace, const Kokkos::View& view_from, const Kokkos::View& view_dest, BinaryOp binary_op, ValueType init_value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class BinaryOp> + KOKKOS_FUNCTION + OutputIteratorType inclusive_scan(const TeamHandleType& teamHandle, (15) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOp binary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOp> + KOKKOS_FUNCTION + auto inclusive_scan(const TeamHandleType& teamHandle, (16) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOp binary_op); + + template < class TeamHandleType, class InputIteratorType, class OutputIteratorType, class BinaryOp, class ValueType> @@ -225,4 +228,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -Iterator to the element *after* the last element written. \ No newline at end of file +Iterator to the element *after* the last element written. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst index 57c089980..59d7cbd06 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst @@ -1,23 +1,24 @@ ``partition_point`` =================== -Header: ``Kokkos_StdAlgorithms.hpp`` +Header: ```` Description ----------- -Examines a range or ``view`` and locates the first element that does not satisfy ``pred``. Assumes the range (or the view) already to be partitioned. +Examines a range or ``view`` and locates the first element that does not satisfy ``pred``. +Assumes the range (or the view) already to be partitioned. Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template IteratorType partition_point(const ExecutionSpace& exespace, (1) IteratorType first, IteratorType last, @@ -44,9 +45,14 @@ Interface const Kokkos::View& view, UnaryPredicate pred); - // - // overload set accepting a team handle - // + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template KOKKOS_FUNCTION IteratorType partition_point(const TeamHandleType& teamHandle, (5) @@ -82,4 +88,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -Iterator to the element *after* the last element in the first partition, or ``last`` if all elements satisfy ``pred``. \ No newline at end of file +Iterator to the element *after* the last element in the first partition, or ``last`` if all elements satisfy ``pred``. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst index c850b8524..e3bc87549 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst @@ -17,11 +17,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set A - // template typename IteratorType::value_type reduce(const ExecutionSpace& exespace, (1) IteratorType first, @@ -52,9 +52,6 @@ Interface auto reduce(const TeamHandleType& teamHandle, (6) const Kokkos::View& view) - // - // overload set B - // template ValueType reduce(const ExecutionSpace& exespace, (7) IteratorType first, IteratorType last, @@ -95,9 +92,6 @@ Interface const Kokkos::View& view, ValueType init_reduction_value); - // - // overload set C - // template < class ExecutionSpace, class IteratorType, class ValueType, class BinaryOp> diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst index 9c5561e52..19956703b 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst @@ -14,11 +14,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class ValueType, @@ -69,9 +69,13 @@ Interface BinaryOpType binary_op, UnaryOpType unary_op); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template < class TeamHandleType, class InputIteratorType, class OutputIteratorType, class ValueType, diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst index d686aed5c..ec5594fdf 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst @@ -15,11 +15,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set A: no init value - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class BinaryOpType, class UnaryOpType> @@ -64,37 +64,11 @@ Interface BinaryOpType binary_op, UnaryOpType unary_op); - template < - class TeamHandleType, class InputIteratorType, - class OutputIteratorType, class BinaryOpType, class UnaryOpType> - KOKKOS_FUNCTION - OutputIteratorType transform_inclusive_scan(const TeamHandleType& teamHandle, (5) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_dest, - BinaryOpType binary_op, - UnaryOpType unary_op); - - template < - class TeamHandleType, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class BinaryOpType, class UnaryOpType> - KOKKOS_FUNCTION - auto transform_inclusive_scan(const TeamHandleType& teamHandle, (6) - const Kokkos::View& view_from, - const Kokkos::View& view_dest, - BinaryOpType binary_op, - UnaryOpType unary_op); - - // - // overload set B: init value - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class BinaryOpType, class UnaryOpType, class ValueType> - OutputIteratorType transform_inclusive_scan(const ExecutionSpace& exespace, (7) + OutputIteratorType transform_inclusive_scan(const ExecutionSpace& exespace, (5) InputIteratorType first_from, InputIteratorType last_from, OutputIteratorType first_dest, @@ -106,7 +80,7 @@ Interface class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class BinaryOpType, class UnaryOpType, class ValueType> - OutputIteratorType transform_inclusive_scan(const std::string& label, (8) + OutputIteratorType transform_inclusive_scan(const std::string& label, (6) const ExecutionSpace& exespace, InputIteratorType first_from, InputIteratorType last_from, @@ -120,7 +94,7 @@ Interface class DataType1, class... Properties1, class DataType2, class... Properties2, class BinaryOpType, class UnaryOpType, class ValueType> - auto transform_inclusive_scan(const ExecutionSpace& exespace, (9) + auto transform_inclusive_scan(const ExecutionSpace& exespace, (7) const Kokkos::View& view_from, const Kokkos::View& view_dest, BinaryOpType binary_op, @@ -132,7 +106,7 @@ Interface class DataType1, class... Properties1, class DataType2, class... Properties2, class BinaryOpType, class UnaryOpType, class ValueType> - auto transform_inclusive_scan(const std::string& label, (10) + auto transform_inclusive_scan(const std::string& label, (8) const ExecutionSpace& exespace, const Kokkos::View& view_from, const Kokkos::View& view_dest, @@ -140,12 +114,44 @@ Interface UnaryOpType unary_op, ValueType init_value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class BinaryOpType, class UnaryOpType> + KOKKOS_FUNCTION + OutputIteratorType transform_inclusive_scan(const TeamHandleType& teamHandle, (9) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class BinaryOpType, class UnaryOpType> + KOKKOS_FUNCTION + auto transform_inclusive_scan(const TeamHandleType& teamHandle, (10) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + BinaryOpType binary_op, + UnaryOpType unary_op); + + template < class TeamHandleType, class InputIteratorType, class OutputIteratorType, class BinaryOpType, class UnaryOpType, class ValueType> KOKKOS_FUNCTION - OutputIteratorType transform_inclusive_scan(const TeamHandleType& teamHandle, (11) + OutputIteratorType transform_inclusive_scan(const TeamHandleType& teamHandle, (11) InputIteratorType first_from, InputIteratorType last_from, OutputIteratorType first_dest, @@ -185,4 +191,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -Iterator to the element *after* the last element written. \ No newline at end of file +Iterator to the element *after* the last element written. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst index 08a9d00ef..ed178af2c 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst @@ -23,11 +23,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set A - // template < class ExecutionSpace, class IteratorType1, class IteratorType2, class ValueType> @@ -66,36 +66,12 @@ Interface const Kokkos::View& second_view, ValueType init_reduction_value); - template < - class TeamHandleType, - class IteratorType1, class IteratorType2, - class ValueType> - KOKKOS_FUNCTION - ValueType transform_reduce(const TeamHandleType& teamHandle, (5) - IteratorType1 first1, IteratorType1 last1, - IteratorType2 first2, - ValueType init_reduction_value); - - template < - class TeamHandleType, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType> - KOKKOS_FUNCTION - ValueType transform_reduce(const TeamHandleType& teamHandle, (6) - const Kokkos::View& first_view, - const Kokkos::View& second_view, - ValueType init_reduction_value); - - // - // overload set B - // template < class ExecutionSpace, class IteratorType1, class IteratorType2, class ValueType, class BinaryJoinerType, class BinaryTransform> - ValueType transform_reduce(const ExecutionSpace& exespace, (7) + ValueType transform_reduce(const ExecutionSpace& exespace, (5) IteratorType1 first1, IteratorType1 last1, IteratorType2 first2, ValueType init_reduction_value, @@ -107,7 +83,7 @@ Interface class IteratorType1, class IteratorType2, class ValueType, class BinaryJoinerType, class BinaryTransform> - ValueType transform_reduce(const std::string& label, (8) + ValueType transform_reduce(const std::string& label, (6) const ExecutionSpace& exespace, IteratorType1 first1, IteratorType1 last1, IteratorType2 first2, @@ -121,7 +97,7 @@ Interface class DataType2, class... Properties2, class ValueType, class BinaryJoinerType, class BinaryTransform> - ValueType transform_reduce(const ExecutionSpace& exespace, (9) + ValueType transform_reduce(const ExecutionSpace& exespace, (7) const Kokkos::View& first_view, const Kokkos::View& second_view, ValueType init_reduction_value, @@ -134,7 +110,7 @@ Interface class DataType2, class... Properties2, class ValueType, class BinaryJoinerType, class BinaryTransform> - ValueType transform_reduce(const std::string& label, (10) + ValueType transform_reduce(const std::string& label, (8) const ExecutionSpace& exespace, const Kokkos::View& first_view, const Kokkos::View& second_view, @@ -142,41 +118,11 @@ Interface BinaryJoinerType joiner, BinaryTransform binary_transformer); - template < - class TeamHandleType, - class IteratorType1, class IteratorType2, - class ValueType, - class BinaryJoinerType, class BinaryTransform> - KOKKOS_FUNCTION - ValueType transform_reduce(const TeamHandleType& teamHandle, (11) - IteratorType1 first1, IteratorType1 last1, - IteratorType2 first2, - ValueType init_reduction_value, - BinaryJoinerType joiner, - BinaryTransform binary_transformer); - - template < - class TeamHandleType, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class ValueType, - class BinaryJoinerType, class BinaryTransform> - KOKKOS_FUNCTION - ValueType transform_reduce(const TeamHandleType& teamHandle, (12) - const Kokkos::View& first_view, - const Kokkos::View& second_view, - ValueType init_reduction_value, - BinaryJoinerType joiner, - BinaryTransform binary_transformer); - - // - // overload set C - // template < class ExecutionSpace, class IteratorType, class ValueType, class BinaryJoinerType, class UnaryTransform> - ValueType transform_reduce(const ExecutionSpace& exespace, (13) + ValueType transform_reduce(const ExecutionSpace& exespace, (9) IteratorType first1, IteratorType last1, ValueType init_reduction_value, BinaryJoinerType joiner, @@ -186,7 +132,7 @@ Interface class ExecutionSpace, class IteratorType, class ValueType, class BinaryJoinerType, class UnaryTransform> - ValueType transform_reduce(const std::string& label, (14) + ValueType transform_reduce(const std::string& label, (10) const ExecutionSpace& exespace, IteratorType first1, IteratorType last1, ValueType init_reduction_value, @@ -197,7 +143,7 @@ Interface class ExecutionSpace, class DataType, class... Properties, class ValueType, class BinaryJoinerType, class UnaryTransform> - ValueType transform_reduce(const ExecutionSpace& exespace, (15) + ValueType transform_reduce(const ExecutionSpace& exespace, (11) const Kokkos::View& view, ValueType init_reduction_value, BinaryJoinerType joiner, @@ -207,13 +153,69 @@ Interface class ExecutionSpace, class DataType, class... Properties, class ValueType, class BinaryJoinerType, class UnaryTransform> - ValueType transform_reduce(const std::string& label, (16) + ValueType transform_reduce(const std::string& label, (12) const ExecutionSpace& exespace, const Kokkos::View& view, ValueType init_reduction_value, BinaryJoinerType joiner, UnaryTransform unary_transformer); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, + class IteratorType1, class IteratorType2, + class ValueType> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (13) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (14) + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value); + + template < + class TeamHandleType, + class IteratorType1, class IteratorType2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (15) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class ValueType, + class BinaryJoinerType, class BinaryTransform> + KOKKOS_FUNCTION + ValueType transform_reduce(const TeamHandleType& teamHandle, (16) + const Kokkos::View& first_view, + const Kokkos::View& second_view, + ValueType init_reduction_value, + BinaryJoinerType joiner, + BinaryTransform binary_transformer); + template < class TeamHandleType, class IteratorType, class ValueType, @@ -323,4 +325,4 @@ Parameters and Requirements Return Value ~~~~~~~~~~~~ -The reduction result. \ No newline at end of file +The reduction result. From 28ce9481138a426232a62d7efdf18fc4ebd13981 Mon Sep 17 00:00:00 2001 From: Francesco Rizzi Date: Tue, 19 Dec 2023 17:53:03 +0100 Subject: [PATCH 13/13] update , NOT final --- .../std-algorithms/all/StdInclusiveScan.rst | 3 +- .../std-algorithms/all/StdReduce.rst | 93 ++++++++++--------- .../all/StdTransformExclusiveScan.rst | 9 +- .../std-algorithms/all/StdTransformReduce.rst | 6 +- 4 files changed, 62 insertions(+), 49 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst index d2ce72ddd..35e4bbf7c 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst @@ -6,7 +6,8 @@ Header: ``Kokkos_StdAlgorithms.hpp`` Description ----------- -Computes an inclusive prefix scan over a range or a ``view_from`` using the binary op ``bin_op`` to combine two elements, and ``init`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. +Computes an inclusive prefix scan over a range or a ``view_from`` using the binary op ``bin_op`` to combine two elements, +and ``init`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. Inclusive means that the i-th input element is included in the i-th sum. Interface diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst index e3bc87549..ceaffb3f4 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst @@ -33,69 +33,44 @@ Overload set accepting execution space IteratorType first, IteratorType last); - template - KOKKOS_FUNCTION - typename IteratorType::value_type reduce(const TeamHandleType& teamHandle, (3) - IteratorType first, - IteratorType last); - template - auto reduce(const ExecutionSpace& exespace, (4) + auto reduce(const ExecutionSpace& exespace, (3) const Kokkos::View& view) template - auto reduce(const std::string& label, const ExecutionSpace& exespace, (5) + auto reduce(const std::string& label, const ExecutionSpace& exespace, (4) const Kokkos::View& view); - template - KOKKOS_FUNCTION - auto reduce(const TeamHandleType& teamHandle, (6) - const Kokkos::View& view) - template - ValueType reduce(const ExecutionSpace& exespace, (7) + ValueType reduce(const ExecutionSpace& exespace, (5) IteratorType first, IteratorType last, ValueType init_reduction_value); template - ValueType reduce(const std::string& label, (8) + ValueType reduce(const std::string& label, (6) const ExecutionSpace& exespace, IteratorType first, IteratorType last, ValueType init_reduction_value); - template - KOKKOS_FUNCTION - ValueType reduce(const TeamHandleType& teamHandle, (9) - IteratorType first, IteratorType last, - ValueType init_reduction_value); - template < class ExecutionSpace, class DataType, class... Properties, class ValueType> - ValueType reduce(const ExecutionSpace& exespace, (10) + ValueType reduce(const ExecutionSpace& exespace, (7) const Kokkos::View& view, ValueType init_reduction_value); template < class ExecutionSpace, class DataType, class... Properties, class ValueType> - ValueType reduce(const std::string& label, (11) + ValueType reduce(const std::string& label, (8) const ExecutionSpace& exespace, const Kokkos::View& view, ValueType init_reduction_value); - template < - class TeamHandleType, class DataType, - class... Properties, class ValueType> - KOKKOS_FUNCTION - ValueType reduce(const TeamHandleType& teamHandle, (12) - const Kokkos::View& view, - ValueType init_reduction_value); - template < class ExecutionSpace, class IteratorType, class ValueType, class BinaryOp> - ValueType reduce(const ExecutionSpace& exespace, (13) + ValueType reduce(const ExecutionSpace& exespace, (9) IteratorType first, IteratorType last, ValueType init_reduction_value, BinaryOp joiner); @@ -103,35 +78,67 @@ Overload set accepting execution space template < class ExecutionSpace, class IteratorType, class ValueType, class BinaryOp> - ValueType reduce(const std::string& label, (14) + ValueType reduce(const std::string& label, (10) const ExecutionSpace& exespace, IteratorType first, IteratorType last, ValueType init_reduction_value, BinaryOp joiner); template < - class TeamHandleType, class IteratorType, - class ValueType, class BinaryOp> - KOKKOS_FUNCTION - ValueType reduce(const TeamHandleType& teamHandle, (15) - IteratorType first, IteratorType last, + class ExecutionSpace, class DataType, + class... Properties, class ValueType, class BinaryOp> + ValueType reduce(const ExecutionSpace& exespace, (11) + const Kokkos::View& view, ValueType init_reduction_value, BinaryOp joiner); template < class ExecutionSpace, class DataType, class... Properties, class ValueType, class BinaryOp> - ValueType reduce(const ExecutionSpace& exespace, (16) + ValueType reduce(const std::string& label, (12) + const ExecutionSpace& exespace, const Kokkos::View& view, ValueType init_reduction_value, BinaryOp joiner); +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + typename IteratorType::value_type reduce(const TeamHandleType& teamHandle, (13) + IteratorType first, + IteratorType last); + + template + KOKKOS_FUNCTION + auto reduce(const TeamHandleType& teamHandle, (14) + const Kokkos::View& view) + + template + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (15) + IteratorType first, IteratorType last, + ValueType init_reduction_value); + template < - class ExecutionSpace, class DataType, - class... Properties, class ValueType, class BinaryOp> - ValueType reduce(const std::string& label, (17) - const ExecutionSpace& exespace, + class TeamHandleType, class DataType, + class... Properties, class ValueType> + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (16) const Kokkos::View& view, + ValueType init_reduction_value); + + template < + class TeamHandleType, class IteratorType, + class ValueType, class BinaryOp> + KOKKOS_FUNCTION + ValueType reduce(const TeamHandleType& teamHandle, (17) + IteratorType first, IteratorType last, ValueType init_reduction_value, BinaryOp joiner); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst index 19956703b..2b81aa150 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst @@ -6,7 +6,9 @@ Header: ``Kokkos_StdAlgorithms.hpp`` Description ----------- -Transforms each element in a range or a ``view`` with ``unary_op`` then computes an exclusive prefix scan operation using ``binary_op`` over the resulting range, with ``init`` as the initial value, and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. +Transforms each element in a range or a ``view`` with ``unary_op`` then computes an exclusive +prefix scan operation using ``binary_op`` over the resulting range, with ``init`` as the initial value, +and writes the results to the range beginning at ``first_dest`` or to ``view_dest``. "exclusive" means that the i-th input element is not included in the i-th sum. Interface @@ -122,7 +124,10 @@ Parameters and Requirements - ``unary_op``: - - *unary* functor performing the desired transformation operation to an element. Must be valid to be called from the execution space passed, and callable with an arguments ``v`` of type (possible const) ``value_type``, where ``value_type`` is the value type of ``first_from`` or value type of ``view_from``, and must not modify ``v``. + - *unary* functor performing the desired transformation operation to an element. + Must be valid to be called from the execution space passed, and callable with ``v`` of type + (possible const) ``value_type``, where ``value_type`` is the value type of ``first_from`` + or value type of ``view_from``, and must not modify ``v``. - Must conform to: diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst index ed178af2c..f1c7fc721 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst @@ -248,11 +248,11 @@ Parameters and Requirements - ``label``: string forwarded to internal parallel kernels for debugging purposes - - 1 & 3: The default string is "Kokkos::transform_reduce_default_functors_iterator_api" + - 1, 3: The default string is "Kokkos::transform_reduce_default_functors_iterator_api" - - 7 & 13: The default string is "Kokkos::transform_reduce_custom_functors_iterator_api" + - 7, 13: The default string is "Kokkos::transform_reduce_custom_functors_iterator_api" - - 9 & 15: The default string is "Kokkos::transform_reduce_custom_functors_view_api" + - 9, 15: The default string is "Kokkos::transform_reduce_custom_functors_view_api" - NOTE: overloads accepting a team handle do not use a label internally