diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopy.md b/docs/source/API/algorithms/std-algorithms/all/StdCopy.md deleted file mode 100644 index d046a74c7..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopy.md +++ /dev/null @@ -1,76 +0,0 @@ - -# `copy` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -OutputIteratorType copy(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to); - -template -OutputIteratorType copy(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2 -> -auto copy(const ExecutionSpace& exespace, (3) - const Kokkos::View& view_from, - const Kokkos::View& view_to); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2 -> -auto copy(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view_from, - const Kokkos::View& view_to); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Copies the elements from range `[first_from, last_from)` to another -range beginning at `first_to` (overloads 1,2) or from -a source view `view_from` to a destination view `view_to` (overloads 3,4). - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::copy_iterator_api_default" - - for 3, the default string is: "Kokkos::copy_view_api_default" -- `first_from, last_from`: - - range of elements to copy from - - 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` -- `first_to`: - - beginning of the range to copy to - - must be a *random access iterator* - - must be accessible from `exespace` -- `view_from`, `view_to`: - - source and destination views to copy elements from and to - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` - - -## Return - -Iterator to the destination element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst new file mode 100644 index 000000000..07567105d --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst @@ -0,0 +1,109 @@ + +``copy`` +======== + +Header: ```` + +Description +----------- + +Copies the elements from a source range or rank-1 ``View`` to a destination range or rank-1 ``View``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + OutputIteratorType copy(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to); + + template + OutputIteratorType copy(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to); + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2 + > + auto copy(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_to); + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2 + > + auto copy(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view_from, + const Kokkos::View& view_to); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + OutputIteratorType copy(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to); + + template < + class TeamHandleType, class DataType1, class... Properties1, + class DataType2, class... Properties2> + KOKKOS_FUNCTION + auto copy(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view_from, + ::Kokkos::View& view_to); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::copy_iterator_api_default" + + - for 3, the default string is: "Kokkos::copy_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first_from, last_from``: range of elements to copy from + + - must be *random access iterators* + + - 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_to``: beginning of the range to copy to + + - must be a *random access iterator* and must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view_from``, ``view_to``: source and destination views to copy elements from and 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 + +Return Value +~~~~~~~~~~~~ + +Iterator to the destination element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.md b/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.md deleted file mode 100644 index 67c823818..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.md +++ /dev/null @@ -1,77 +0,0 @@ - -# `copy_backward` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -OutputIteratorType copy_backward(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType last_to); - -template -OutputIteratorType copy_backward(const std::string& label, - const ExecutionSpace& exespace, (2) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType last_to); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2 -> -auto copy_backward(const ExecutionSpace& exespace, (3) - const Kokkos::View& view_from, - const Kokkos::View& view_to); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2 -> -auto copy_backward(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view_from, - const Kokkos::View& view_to); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Copies the elements in reverse order from range `[first_from, last_from)` to another -range *ending* at `last_to` (overloads 1,2) or from -a source view `view_from` to a destination view `view_to` (overloads 3,4). -The relative order is preserved. - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::copy_backward_iterator_api_default" - - for 3, the default string is: "Kokkos::copy_backward_view_api_default" -- `first_from, last_from`: - - range of elements to copy from - - 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` -- `last_to`: - - iterator past the last element of the range to copy to - - must be a *random access iterator* - - must be accessible from `exespace` -- `view_from`, `view_to`: - - source and destination views to copy elements from and to - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` - - -## Return - -Iterator to the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst new file mode 100644 index 000000000..75662ceda --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst @@ -0,0 +1,116 @@ + +``copy_backward`` +================= + +Header: ```` + +Description +----------- + +Copies the elements in reverse order from range ``[first_from, last_from)`` to another +range *ending* at ``last_to`` or from a source view ``view_from`` to a destination +view ``view_to``. The relative order is preserved. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + OutputIteratorType copy_backward(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType last_to); + + template + OutputIteratorType copy_backward(const std::string& label, + const ExecutionSpace& exespace, (2) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType last_to); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2 + > + auto copy_backward(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_to); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2 + > + auto copy_backward(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view_from, + const Kokkos::View& view_to); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + OutputIteratorType copy_backward(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType last_to); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2> + KOKKOS_FUNCTION + auto copy_backward(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view_from, + ::Kokkos::View& view_to); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::copy_backward_iterator_api_default" + + - for 3, the default string is: "Kokkos::copy_backward_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first_from, last_from``: range of elements to copy from + + - 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`` or from the execution space associated with the team handle + +- ``last_to``: iterator past the last element of the range to copy to + + - must be a *random access iterator* + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view_from``, ``view_to``: source and destination views to copy elements from and 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 + +Return Value +~~~~~~~~~~~~ + +Iterator to the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.md b/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.md deleted file mode 100644 index 1e5d41763..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.md +++ /dev/null @@ -1,80 +0,0 @@ - -# `copy_if` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template < - class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class UnaryPredicateType -> -OutputIteratorType copy_if(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to, - UnaryPredicateType pred); - -template < - class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class UnaryPredicateType -> -OutputIteratorType copy_if(const std::string& label, - const ExecutionSpace& exespace, (2) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to, - UnaryPredicateType pred); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class UnaryPredicateType -> -auto copy_if(const ExecutionSpace& exespace, (3) - const Kokkos::View& view_from, - const Kokkos::View& view_to, - UnaryPredicateType pred); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class UnaryPredicateType -> -auto copy_if(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view_from, - const Kokkos::View& view_to, - UnaryPredicateType pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Copies the elements for which `pred` returns `true` from range `[first_from, last_from)` -to another range beginning at `first_to` (overloads 1,2) or from `view_from` to `view_to` -(overloads 3,4). - - -## Parameters and Requirements - -- `exespace`, `first_from`, `last_from`, `first_to`, `view_from`, `view_to`: - - same as in [`copy`](./StdCopy) -- `label`: - - for 1, the default string is: "Kokkos::copy_if_iterator_api_default" - - for 3, the default string is: "Kokkos::copy_if_view_api_default" -- `pred`: - - unary predicate which returns `true` for the required element; `pred(v)` - must be valid to be called from the execution space passed, and convertible to bool for every - argument `v` of type (possible const) `value_type`, where `value_type` - is the value type of `InputIteratorType` (for 1,2) or of `view_from` (for 3,4), - and must not modify `v`. - - should have the same API as the unary predicate in [`replace_if`](./StdReplaceIf) - - -## Return - -Iterator to the destination element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst new file mode 100644 index 000000000..fb78fc9d6 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst @@ -0,0 +1,134 @@ + +``copy_if`` +=========== + +Header: ```` + +Description +----------- + +Copies the elements for which a predicate returns ``true`` from source range or ``View`` to +another range or ``View`` + +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 UnaryPredicateType> + OutputIteratorType copy_if(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to, + UnaryPredicateType pred); + + template < + class ExecutionSpace, class InputIteratorType, + class OutputIteratorType, class UnaryPredicateType> + OutputIteratorType copy_if(const std::string& label, + const ExecutionSpace& exespace, (2) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to, + UnaryPredicateType pred); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryPredicateType + > + auto copy_if(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_to, + UnaryPredicateType pred); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryPredicateType + > + auto copy_if(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view_from, + const Kokkos::View& view_to, + UnaryPredicateType pred); + + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, class InputIteratorType, + class OutputIteratorType, class UnaryPredicateType> + KOKKOS_FUNCTION + OutputIteratorType copy_if(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to, + UnaryPredicateType pred); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryPredicateType> + KOKKOS_FUNCTION + auto copy_if(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_to, + UnaryPredicateType pred); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |copy| replace:: ``copy`` +.. _copy: ./StdCopy.html + +- ``exespace``, ``teamHandle``, ``first_from``, ``last_from``, ``first_to``, ``view_from``, ``view_to``: same as in |copy|_ + +- ``label``: + + - for 1, the default string is: "Kokkos::copy_if_iterator_api_default" + + - for 3, the default string is: "Kokkos::copy_if_view_api_default" + +- ``pred``: unary predicate which returns ``true`` for the required element to copy + + - ``pred(v)`` must be valid to be called from the execution space passed or the execution + space associated with the team handle, and convertible to bool for every + argument ``v`` of type (possible const) ``value_type``, where ``value_type`` + is the value type of ``InputIteratorType`` or of ``view_from``, and must not modify ``v``. + + - must conform to: + + .. code-block:: cpp + + struct Predicate + { + KOKKOS_INLINE_FUNCTION + bool operator()(const value_type & v) const { return /* ... */; } + + // or, also valid + + KOKKOS_INLINE_FUNCTION + bool operator()(value_type v) const { return /* ... */; } + }; + + +Return Value +~~~~~~~~~~~~ + +Iterator to the destination element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.md b/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.md deleted file mode 100644 index 944d6175f..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.md +++ /dev/null @@ -1,70 +0,0 @@ - -# `copy_n` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -OutputIteratorType copy_n(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - SizeType n, - OutputIteratorType first_to); - -template -OutputIteratorType copy_n(const std::string & label, - const ExecutionSpace& exespace, (2) - InputIteratorType first_from, - SizeType n, - OutputIteratorType first_to); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class SizeType, - class DataType2, class... Properties2 -> -auto copy_n(const ExecutionSpace& exespace, (3) - const Kokkos::View& view_from, - SizeType n, - const Kokkos::View& view_to); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class SizeType, - class DataType2, class... Properties2 -> -auto copy_n(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view_from, - SizeType n, - const Kokkos::View& view_to); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -Copies the first `n` elements starting at `first_from` to -another range starting at `first_to` (overloads 1,2) or the first `n` elements -from `view_from` to `view_to` (overloads 3,4). - - -## Parameters and Requirements - -- `exespace`, `first_from`, `first_to`, `view_from`, `view_to`: - - same as in [`copy`](./StdCopy) -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::copy_n_if_iterator_api_default" - - for 3, the default string is: "Kokkos::copy_n_if_view_api_default" -- `n`: - - number of elements to copy (must be non-negative) - - -## Return - -If `n>0`, returns an iterator to the destination element *after* the last element copied. - -Otherwise, returns `first_to` (for 1,2) or `Kokkos::begin(view_to)` (for 3,4). diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst new file mode 100644 index 000000000..7c8106b28 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst @@ -0,0 +1,109 @@ +``copy_n`` +========== + +Header: ```` + +Description +----------- + +Copies the first ``n`` elements from a source range or rank-1 ``View`` to another range or rank-1 ``View``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template < + class ExecutionSpace, class InputIteratorType, + class SizeType, class OutputIteratorType> + OutputIteratorType copy_n(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + SizeType n, + OutputIteratorType first_to); + + template < + class ExecutionSpace, class InputIteratorType, + class SizeType, class OutputIteratorType> + OutputIteratorType copy_n(const std::string & label, + const ExecutionSpace& exespace, (2) + InputIteratorType first_from, + SizeType n, + OutputIteratorType first_to); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class SizeType, + class DataType2, class... Properties2> + auto copy_n(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + SizeType n, + const Kokkos::View& view_to); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class SizeType, + class DataType2, class... Properties2> + auto copy_n(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view_from, + SizeType n, + const Kokkos::View& view_to); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, class InputIteratorType, + class SizeType, class OutputIteratorType> + KOKKOS_FUNCTION + OutputIteratorType copy_n(const TeamHandleType& teamHandle, (5) + InputIteratorType first_from, + SizeType n, + OutputIteratorType first_to); + + template < + class TeamHandleType, + class DataType1, class... Properties1, class SizeType, + class DataType2, class... Properties2> + KOKKOS_FUNCTION + auto copy_n(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view_from, + SizeType n, + ::Kokkos::View& view_to); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. |copy| replace:: ``copy`` +.. _copy: ./StdCopy.html + + +- ``exespace``, ``teamHandle``, ``first_from``, ``first_to``, ``view_from``, ``view_to``: same as in |copy|_ + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::copy_n_if_iterator_api_default" + + - for 3, the default string is: "Kokkos::copy_n_if_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``n``: number of elements to copy (must be non-negative) + + +Return Value +~~~~~~~~~~~~ + +If ``n>0``, returns an iterator to the destination element *after* the last element copied. + +Otherwise, returns ``first_to`` (for 1,2,5) or ``Kokkos::begin(view_to)`` (for 3,4,6). diff --git a/docs/source/API/algorithms/std-algorithms/all/StdGenerate.md b/docs/source/API/algorithms/std-algorithms/all/StdGenerate.md deleted file mode 100644 index b0bf9cb27..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdGenerate.md +++ /dev/null @@ -1,72 +0,0 @@ - -# `generate` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -void generate(const ExecutionSpace& exespace, (1) - IteratorType first, IteratorType last, - GeneratorType g); - -template -void generate(const std::string& label, const ExecutionSpace& exespace, (2) - IteratorType first, IteratorType last, - GeneratorType g); - -template -void generate(const ExecutionSpace& exespace, (3) - const Kokkos::View& view, - GeneratorType g); - -template -void generate(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view, - GeneratorType g); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Assigns the value generated by the functor `g` to each elements in the -range `[first, last)` (overloads 1,2) or in the `view` (overloads 3,4). - - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::generate_iterator_api_default" - - for 3, the default string is: "Kokkos::generate_view_api_default" -- `first, last`: - - range of elements to modify - - 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 modify - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `g`: - - functor of the form: - ```c++ - struct Generate - { - KOKKOS_INLINE_FUNCTION - return_type operator()() const{ return /* ... */; } - }; - ``` - where `return_type` must be assignable to `value_type`, with `value_type` - being the value type of `IteratorType` (for 1,2) or of `view` (for 3,4). - - -## Return - -None diff --git a/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst b/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst new file mode 100644 index 000000000..496ae646a --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst @@ -0,0 +1,107 @@ + +``generate`` +============ + +Header: ```` + +Description +----------- + +Assigns the value generated by the functor ``g`` to each elements in the +range ``[first, last)`` (overloads 1,2,5) or in the ``view`` (overloads 3,4,6). + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + void generate(const ExecutionSpace& exespace, (1) + IteratorType first, IteratorType last, + GeneratorType g); + + template + void generate(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType first, IteratorType last, + GeneratorType g); + + template + void generate(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + GeneratorType g); + + template + void generate(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + GeneratorType g); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + void generate(const TeamHandleType& teamHandle, (5) + IteratorType first, IteratorType last, + GeneratorType g); + + template + KOKKOS_FUNCTION + void generate(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + GeneratorType g); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::generate_iterator_api_default" + + - for 3, the default string is: "Kokkos::generate_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to modify + + - must be *random access iterators* + + - must represent a valid range, i.e., ``last >= first`` (checked in debug mode) + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: view to modify + + - 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 + +- ``g``: + + - functor of the following form, where ``return_type`` must be assignable to ``value_type``, with ``value_type`` being the value type of ``IteratorType`` or of ``view``: + + .. code-block:: cpp + + struct Generate + { + KOKKOS_INLINE_FUNCTION + return_type operator()() const{ return /* ... */; } + }; + + +Return Value +~~~~~~~~~~~~ + +None diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransform.md b/docs/source/API/algorithms/std-algorithms/all/StdTransform.md deleted file mode 100644 index ec43d1b2a..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransform.md +++ /dev/null @@ -1,139 +0,0 @@ - -# `transform` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -OutputIterator transform(const ExecutionSpace& exespace, (1) - InputIterator first_from, InputIterator last_from, - OutputIterator first_to, - UnaryOperation unary_op); - -template -OutputIterator transform(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIterator first_from, InputIterator last_from, - OutputIterator d_first, - UnaryOperation unary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class UnaryOperation -> -auto transform(const ExecutionSpace& exespace, (3) - const Kokkos::View& source, - Kokkos::View& dest, - UnaryOperation unary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class UnaryOperation -> -auto transform(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& source, - Kokkos::View& dest, - UnaryOperation unary_op); - -template < - class ExecutionSpace, - class InputIterator1, class InputIterator2, class OutputIterator, - class BinaryOperation -> -OutputIterator transform(const ExecutionSpace& exespace, (5) - InputIterator1 first_from1, InputIterator1 last_from1, - InputIterator2 first_from2, OutputIterator first_to, - BinaryOperation binary_op); - -template < - class ExecutionSpace, - class InputIterator1, class InputIterator2, class OutputIterator, - class BinaryOperation -> -OutputIterator transform(const std::string& label, (6) - const ExecutionSpace& exespace, - InputIterator1 first_from1, InputIterator1 last_from1, - InputIterator2 first_from2, OutputIterator first_to, - BinaryOperation binary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class DataType3, class... Properties3, - class BinaryOperation -> -auto transform(const ExecutionSpace& exespace, (7) - const Kokkos::View& source1, - const Kokkos::View& source2, - Kokkos::View& dest, - BinaryOperation binary_op); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class DataType3, class... Properties3, - class BinaryOperation -> -auto transform(const std::string& label, const ExecutionSpace& exespace, (8) - const Kokkos::View& source1, - const Kokkos::View& source2, - Kokkos::View& dest, - BinaryOperation binary_op); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- Overloads (1,2): applies the given *unary* operation to all elements in the -range `[first_from, last_from)` stores the result in the range starting at `first_to` - -- Overloads (3,4): applies the given *unary* operation to all elements in -the `source` view and stores the result in the `dest` view. - -- Overloads (5,6): applies the given *binary* operation to pair of elements -from the ranges `[first_from1, last_from1)` and `[first_from2, last_from2]` -and stores the result in range starting at `first_to` - -- Overloads (7,8): applies the given *binary* operation to pair of elements -from the views `source1, source2` and stores the result in `dest` view - - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1,3,5,7, the default string is: "Kokkos::transform_iterator_api_default" - - for 2,4,6,8, the default string is: "Kokkos::transform_view_api_default" -- `first_from, last_from, first_from1, first_from2`: - - ranges of elements to tranform - - must be *random access iterators* - - must be valid ranges, i.e., `first_from >= last_from`, `first_from1 >= last_from2` - - must be accessible from `exespace` -- `first_to`: - - beginning of the range to write to - - must be a *random access iterator* - - must be accessible from `exespace` -- `source, source1, source2`: - - source views to transform - - must be accessible from `exespace` -- `dest`: - - destination view to write to - - must be accessible from `exespace` - - -## Return - -Iterator to the element *after* the last element transformed. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst new file mode 100644 index 000000000..119d71b05 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst @@ -0,0 +1,205 @@ + +``transform`` +============= + +Header: ```` + +Description +----------- + +- Overloads (1,2,9): applies the given *unary* operation to all elements in the range ``[first_from, last_from)`` stores the result in the range starting at ``first_to`` + +- Overloads (3,4,10): applies the given *unary* operation to all elements in the ``source`` view and stores the result in the ``dest`` view. + +- Overloads (5,6,11): applies the given *binary* operation to pair of elements from the ranges ``[first_from1, last_from1)`` and ``[first_from2, last_from2]`` and stores the result in range starting at ``first_to`` + +- Overloads (7,8,12): applies the given *binary* operation to pair of elements from the views ``source1, source2`` and stores the result in ``dest`` view + + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template < + class ExecutionSpace, class InputIterator, + class OutputIterator, class UnaryOperation> + OutputIterator transform(const ExecutionSpace& exespace, (1) + InputIterator first_from, InputIterator last_from, + OutputIterator first_to, + UnaryOperation unary_op); + + template < + class ExecutionSpace, class InputIterator, + class OutputIterator, class UnaryOperation> + OutputIterator transform(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIterator first_from, InputIterator last_from, + OutputIterator first_to, + UnaryOperation unary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryOperation + > + auto transform(const ExecutionSpace& exespace, (3) + const Kokkos::View& source, + Kokkos::View& dest, + UnaryOperation unary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryOperation + > + auto transform(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& source, + Kokkos::View& dest, + UnaryOperation unary_op); + + template < + class ExecutionSpace, + class InputIterator1, class InputIterator2, class OutputIterator, + class BinaryOperation + > + OutputIterator transform(const ExecutionSpace& exespace, (5) + InputIterator1 first_from1, InputIterator1 last_from1, + InputIterator2 first_from2, OutputIterator first_to, + BinaryOperation binary_op); + + template < + class ExecutionSpace, + class InputIterator1, class InputIterator2, class OutputIterator, + class BinaryOperation + > + OutputIterator transform(const std::string& label, (6) + const ExecutionSpace& exespace, + InputIterator1 first_from1, InputIterator1 last_from1, + InputIterator2 first_from2, OutputIterator first_to, + BinaryOperation binary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class DataType3, class... Properties3, + class BinaryOperation + > + auto transform(const ExecutionSpace& exespace, (7) + const Kokkos::View& source1, + const Kokkos::View& source2, + Kokkos::View& dest, + BinaryOperation binary_op); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class DataType3, class... Properties3, + class BinaryOperation + > + auto transform(const std::string& label, const ExecutionSpace& exespace, (8) + const Kokkos::View& source1, + const Kokkos::View& source2, + Kokkos::View& dest, + BinaryOperation binary_op); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template < + class TeamHandleType, class InputIterator, + class OutputIterator, class UnaryOperation> + KOKKOS_FUNCTION + OutputIterator transform(const TeamHandleType& teamHandle, (9) + InputIterator first_from, + InputIterator last_from, + OutputIterator first_to, + UnaryOperation unary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryOperation> + KOKKOS_FUNCTION + auto transform(const TeamHandleType& teamHandle, (10) + const ::Kokkos::View& source, + ::Kokkos::View& dest, + UnaryOperation unary_op); + + template < + class TeamHandleType, class InputIterator1, + class InputIterator2, class OutputIterator, + class BinaryOperation> + KOKKOS_FUNCTION + OutputIterator transform(const TeamHandleType& teamHandle, (11) + InputIterator1 first_from1, + InputIterator1 last_from1, + InputIterator2 first_from2, + OutputIterator first_to, + BinaryOperation binary_op); + + template < + class TeamHandleType, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class DataType3, class... Properties3, + class BinaryOperation> + KOKKOS_FUNCTION + auto transform(const TeamHandleType& teamHandle, (12) + const ::Kokkos::View& source1, + const ::Kokkos::View& source2, + ::Kokkos::View& dest, + BinaryOperation binary_op); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1,3,5,7, the default string is: "Kokkos::transform_iterator_api_default" + + - for 2,4,6,8, the default string is: "Kokkos::transform_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first_from, last_from, first_from1, first_from2``: ranges of elements to transform + + - must be *random access iterators* + + - must be valid ranges, i.e., ``first_from >= last_from``, ``first_from1 >= last_from2`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``first_to``: beginning of the range to write to + + - must be a *random access iterator* + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``source, source1, source2, dest``: source and destination views + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element transformed.