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..e0c67411f --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdAdjacentDifference.rst @@ -0,0 +1,208 @@ +``adjacent_difference`` +======================= + +Header: ```` + +Description +----------- + +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 + + 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); + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + 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" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``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`` + + - 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 and write to + + - 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. 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..a4f055743 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdExclusiveScan.rst @@ -0,0 +1,218 @@ +``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. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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 ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class ValueType, class BinaryOpType> + OutputIteratorType exclusive_scan(const ExecutionSpace& exespace, (5) + 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, (6) + 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, (7) + 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, (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> + 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. 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..35e4bbf7c --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdInclusiveScan.rst @@ -0,0 +1,232 @@ +``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. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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); + + 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 ExecutionSpace, + class InputIteratorType, class OutputIteratorType, + class BinaryOp, class ValueType> + OutputIteratorType inclusive_scan(const ExecutionSpace& exespace, (11) + 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, (12) + 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, (13) + 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, (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> + 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. 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..59d7cbd06 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdPartitionPoint.rst @@ -0,0 +1,91 @@ +``partition_point`` +=================== + +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. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |IsPartitioned| replace:: ``is_partitioned`` +.. _IsPartitioned: ./StdIsPartitioned.html + +- ``exespace``, ``first``, ``last``, ``view``, ``pred``: same as in |IsPartitioned|_ + +- ``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" + + - NOTE: overloads accepting a team handle do not use a label internally + +Return Value +~~~~~~~~~~~~ + +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.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..ceaffb3f4 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReduce.rst @@ -0,0 +1,208 @@ +``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. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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); + + template + ValueType reduce(const ExecutionSpace& exespace, (5) + IteratorType first, IteratorType last, + ValueType init_reduction_value); + + template + ValueType reduce(const std::string& label, (6) + const ExecutionSpace& exespace, + IteratorType first, IteratorType last, + ValueType init_reduction_value); + + template < + class ExecutionSpace, class DataType, + class... Properties, class ValueType> + 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, (8) + const ExecutionSpace& exespace, + const Kokkos::View& view, + ValueType init_reduction_value); + + 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, (10) + const ExecutionSpace& exespace, + 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, (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 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); + + 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. 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..2b81aa150 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformExclusiveScan.rst @@ -0,0 +1,146 @@ +``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. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + 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 ``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. 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..ec5594fdf --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformInclusiveScan.rst @@ -0,0 +1,194 @@ +``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. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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); + + +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) + 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. 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..f1c7fc721 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransformReduce.rst @@ -0,0 +1,328 @@ +``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. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + 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 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); + + 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, (10) + 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, (11) + 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, (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, + 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.