diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill.md b/docs/source/API/algorithms/std-algorithms/all/StdFill.md deleted file mode 100644 index dbeef0870..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFill.md +++ /dev/null @@ -1,77 +0,0 @@ - -# `fill` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -void fill(const ExecutionSpace& exespace, (1) - IteratorType first, IteratorType last, - const T& value); - -template -void fill(const std::string& label, const ExecutionSpace& exespace, (2) - IteratorType first, IteratorType last, - const T& value); - -template -void fill(const ExecutionSpace& exespace, (3) - const Kokkos::View& view, - const T& value); - -template -void fill(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view, - const T& value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Copy-assigns `value` to each element in the range `[first, last)` (overloads 1,2) -or in `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::fill_iterator_api_default" - - for 3, the default string is: "Kokkos::fill_view_api_default" -- `first, last`: - - range of elements to assign to - - must be *random access iterators*, e.g., `Kokkos::Experimental::begin/end` - - must represent a valid range, i.e., `last >= first` (checked in debug mode) - - must be accessible from `exespace` -- `view`: - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `value`: - - value to assign to each element - - -## Return - -None - -## Example - -```c++ -namespace KE = Kokkos::Experimental; -Kokkos::View a("a", 13); - -KE::fill(Kokkos::DefaultExecutionSpace(), KE::begin(a), KE::end(a), 4.); - -// passing the view directly -KE::fill(Kokkos::DefaultExecutionSpace(), a, 22.); - -// explicitly set execution space (assuming active) -KE::fill(Kokkos::OpenMP(), KE::begin(a), KE::end(a), 14.); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst new file mode 100644 index 000000000..179d264c5 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst @@ -0,0 +1,115 @@ + +``fill`` +========= + +Header: ```` + +Description +----------- + +Assigns a given ``value`` to each element in a given range or rank-1 ``View``. + + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + void fill(const ExecutionSpace& exespace, (1) + IteratorType first, IteratorType last, + const T& value); + + template + void fill(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType first, IteratorType last, + const T& value); + + template + void fill(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + const T& value); + + template + void fill(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + const T& value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + void fill(const TeamHandleType& teamHandle, (5) + IteratorType first, IteratorType last, + const T& value); + + template + KOKKOS_FUNCTION + void fill(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + const T& value); + + +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 + + - for 1, the default string is: "Kokkos::fill_iterator_api_default" + + - for 3, the default string is: "Kokkos::fill_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to modify + + - must be *random access iterators*, e.g., ``Kokkos::Experimental::begin/end`` + + - must represent a valid range, i.e., ``last >= first`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` + +- ``value``: value to assign to each element + + +Return Value +~~~~~~~~~~~~ + +None + +Example +~~~~~~~~~~~~ + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + Kokkos::View a("a", 13); + + KE::fill(Kokkos::DefaultExecutionSpace(), KE::begin(a), KE::end(a), 4.); + + // passing the view directly + KE::fill(Kokkos::DefaultExecutionSpace(), a, 22.); + + // explicitly set execution space (assuming active) + KE::fill(Kokkos::OpenMP(), KE::begin(a), KE::end(a), 14.); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.md b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.md deleted file mode 100644 index 50af52934..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.md +++ /dev/null @@ -1,73 +0,0 @@ - -# `fill_n` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -IteratorType fill_n(const ExecutionSpace& exespace, (1) - IteratorType first, - SizeType n, const T& value); - -template -IteratorType fill_n(const std::string& label, const ExecutionSpace& exespace, (2) - IteratorType first, - SizeType n, const T& value); - -template -auto fill_n(const ExecutionSpace& exespace, (3) - const Kokkos::View& view, - SizeType n, const T& value); - -template -auto fill_n(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view, - SizeType n, const T& value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Copy-assigns `value` to the first `n` elements in the range starting at `first` (overloads 1,2) -or the first `n` elements in `view` (overloads 3,4). - -## Parameters and Requirements - -- `exespace`, `first`, `view`, `value`: same as in [`fill`](./StdFill) -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::fill_n_iterator_api_default" - - for 3, the default string is: "Kokkos::fill_n_view_api_default" -- `n`: - - number of elements to modify (must be non-negative) - - -## Return - -If `n > 0`, returns an iterator to the element *after* the last element assigned. - -Otherwise, it returns `first` (for 1,2) or `Kokkos::begin(view)` (for 3,4). - - -## Example - -```c++ -namespace KE = Kokkos::Experimental; -Kokkos::View a("a", 13); -// do something with a -// ... - -const double newValue{4}; -KE::fill_n(Kokkos::DefaultExecutionSpace(), KE::begin(a), 10, newValue); - -// passing the view directly -KE::fill_n(Kokkos::DefaultExecutionSpace(), a, 10, newValue); - -// explicitly set execution space (assuming active) -KE::fill_n(Kokkos::OpenMP(), KE::begin(a), 10, newValue); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst new file mode 100644 index 000000000..e814b0aa2 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst @@ -0,0 +1,112 @@ + +``fill_n`` +=========== + +Header: ```` + +Description +----------- + +Assigns a given ``value`` to the first ``n`` elements in a given range or rank-1 ``View``. + + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + IteratorType fill_n(const ExecutionSpace& exespace, (1) + IteratorType first, + SizeType n, const T& value); + + template + IteratorType fill_n(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType first, + SizeType n, const T& value); + + template < + class ExecutionSpace, class DataType, class... Properties, + class SizeType, class T> + auto fill_n(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + SizeType n, const T& value); + + template < + class ExecutionSpace, class DataType, class... Properties, + class SizeType, class T> + auto fill_n(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + SizeType n, const T& value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + IteratorType fill_n(const TeamHandleType& teamHandle, (5) + IteratorType first, SizeType n, const T& value); + + template < + class TeamHandleType, class DataType, class... Properties, class SizeType, + class T> + KOKKOS_FUNCTION + auto fill_n(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + SizeType n, const T& value); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``, ``teamHandle``, ``first``, ``view``, ``value``: same as in [``fill``](./StdFill): execution space instance + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::fill_n_iterator_api_default" + + - for 3, the default string is: "Kokkos::fill_n_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``n``: number of elements to modify (must be non-negative) + +- ``value``: value to assign to each element + +Return Value +~~~~~~~~~~~~ + +If ``n > 0``, returns an iterator to the element *after* the last element assigned. + +Otherwise, it returns ``first`` (for 1,2,5) or ``Kokkos::begin(view)`` (for 3,4,6). + + +Example +~~~~~~~~~~~~ + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + Kokkos::View a("a", 13); + // do something with a + // ... + + const double newValue{4}; + KE::fill_n(Kokkos::DefaultExecutionSpace(), KE::begin(a), 10, newValue); + + // passing the view directly + KE::fill_n(Kokkos::DefaultExecutionSpace(), a, 10, newValue); + + // explicitly set execution space (assuming active) + KE::fill_n(Kokkos::OpenMP(), KE::begin(a), 10, newValue); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplace.md b/docs/source/API/algorithms/std-algorithms/all/StdReplace.md deleted file mode 100644 index d6500379c..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplace.md +++ /dev/null @@ -1,79 +0,0 @@ - -# `replace` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -void replace(const ExecutionSpace& exespace, (1) - IteratorType first, IteratorType last, - const T& old_value, const T& new_value); - -template -void replace(const std::string& label, const ExecutionSpace& exespace, (2) - IteratorType first, IteratorType last, - const T& old_value, const T& new_value); - -template -void replace(const ExecutionSpace& exespace, (3) - const Kokkos::View& view, - const T& old_value, const T& new_value); - -template -void replace(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view, - const T& old_value, const T& new_value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Replaces with `new_value` all elements that are equal to `old_value` in the -range `[first, last)` (overloads 1,2) or in `view` (overloads 3,4). -Equality is checked using `operator==`. - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::replace_iterator_api_default" - - for 3, the default string is: "Kokkos::replace_view_api_default" -- `first, last`: - - range of elements to search in - - must be *random access iterators*, e.g., `Kokkos::Experimental::begin/end` - - must represent a valid range, i.e., `last >= first` (this condition is checked in debug mode) - - must be accessible from `exespace` -- `view`: - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `old_value`, `new_value`: - - self-explanatory - - -## Return - -None - - -## Example - -```c++ -namespace KE = Kokkos::Experimental; -Kokkos::View a("a", 13); -// do something with a -// ... - -const double oldValue{2}; -const double newValue{34}; -KE::replace(Kokkos::DefaultExecutionSpace(), KE::begin(a), KE::end(a), oldValue, newValue); - -// explicitly set label and execution space (assuming active) -KE::replace("mylabel", Kokkos::OpenMP(), a, oldValue, newValue); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst new file mode 100644 index 000000000..389f89558 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst @@ -0,0 +1,117 @@ + +``replace`` +============ + +Header: ```` + +Description +----------- + +Replaces all elements that are equal to ``old_value`` with ``new_value`` in +a given range or rank-1 ``View``. Equality is checked using ``operator==``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + void replace(const ExecutionSpace& exespace, (1) + IteratorType first, IteratorType last, + const T& old_value, const T& new_value); + + template + void replace(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType first, IteratorType last, + const T& old_value, const T& new_value); + + template + void replace(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + const T& old_value, const T& new_value); + + template + void replace(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + const T& old_value, const T& new_value); + + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + void replace(const TeamHandleType& teamHandle, (5) + Iterator first, Iterator last, + const ValueType& old_value, const ValueType& new_value); + + template + KOKKOS_FUNCTION + void replace(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view, + const ValueType& old_value, const ValueType& new_value); + + +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::replace_iterator_api_default" + + - for 3, the default string is: "Kokkos::replace_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to search in + + - must be *random access iterators*, e.g., ``Kokkos::Experimental::begin/end`` + + - must represent a valid range, i.e., ``last >= first`` (this condition is checked in debug mode) + + - must be accessible from ``exespace`` + +- ``view``: + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` + +- ``old_value``, ``new_value``: self-explanatory + + +Return Value +~~~~~~~~~~~~ + +None + +Example +~~~~~~~~~~~~ + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + Kokkos::View a("a", 13); + + KE::fill(Kokkos::DefaultExecutionSpace(), KE::begin(a), KE::end(a), 4.); + + // passing the view directly + KE::fill(Kokkos::DefaultExecutionSpace(), a, 22.); + + // explicitly set execution space (assuming active) + KE::fill(Kokkos::OpenMP(), KE::begin(a), KE::end(a), 14.); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.md b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.md deleted file mode 100644 index 1a1628981..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.md +++ /dev/null @@ -1,84 +0,0 @@ - -# `replace_copy` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -OutputIteratorType replace_copy(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to, - const T& old_value, const T& new_value); - -template -OutputIteratorType replace_copy(const std::string& label, (2) - const ExecutionSpace& exespace, - OutputIteratorType first_to, - const T& old_value, const T& new_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class T -> -auto replace_copy(const ExecutionSpace& exespace, (3) - const Kokkos::View& view_from, - const Kokkos::View& view_to, - const T& old_value, const T& new_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class T -> -auto replace_copy(const std::string& label, - const ExecutionSpace& exespace, (4) - const Kokkos::View& view_from, - const Kokkos::View& view_to, - const T& old_value, const T& new_value); - -} //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 `view_from` to `view_to` -(overloads 3,4) replacing with `new_value` all elements that equal `old_value`. -Comparison between elements is done using `operator==`. - -## Parameters and Requirements - -- `exespace`: - - execution space instance -- `label`: - - used to name the implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::replace_copy_iterator_api_default" - - for 3, the default string is: "Kokkos::replace_copy_view_api_default" -- `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 - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `old_value`, `new_value`: - - self-explanatory - - -## Return - -Iterator to the element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst new file mode 100644 index 000000000..bc7cb9889 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst @@ -0,0 +1,131 @@ + +``replace_copy`` +================= + +Header: ```` + +Description +----------- + +Copies the elements from a given range ``[first_from, last_from)`` to another range +beginning at ``first_to``, while replacing all elements that equal ``old_value`` +with ``new_value``. +The overload taking a ``View`` uses the ``begin`` and ``end`` iterators of the ``View``. +Comparison between elements is done using ``operator==``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + OutputIteratorType replace_copy(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to, + const T& old_value, const T& new_value); + + template + OutputIteratorType replace_copy(const std::string& label, (2) + const ExecutionSpace& exespace, + OutputIteratorType first_to, + const T& old_value, const T& new_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class T + > + auto replace_copy(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_to, + const T& old_value, const T& new_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class T + > + auto replace_copy(const std::string& label, + const ExecutionSpace& exespace, (4) + const Kokkos::View& view_from, + const Kokkos::View& view_to, + const T& old_value, const T& new_value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + OutputIterator replace_copy(const TeamHandleType& teamHandle, (5) + InputIterator first_from, InputIterator last_from, + OutputIterator first_dest, + const ValueType& old_value, const ValueType& new_value); + + template < + class TeamHandleType, class DataType1, class... Properties1, + class DataType2, class... Properties2, class ValueType, int> + KOKKOS_FUNCTION + auto replace_copy(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + const ValueType& old_value, const ValueType& new_value); + + +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::replace_copy_iterator_api_default" + + - for 3, the default string is: "Kokkos::replace_copy_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first_from, last_from``: range of elements to copy from + + - 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 + +- ``first_to``: beginning 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 + + - 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 + +- ``old_value``, ``new_value``: self-explanatory + + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.md b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.md deleted file mode 100644 index 21e7e9a4f..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.md +++ /dev/null @@ -1,85 +0,0 @@ - -# `replace_copy_if` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template < - class ExecutionSpace, - class InputIteratorType, class OutputIteratorType, - class UnaryPredicateType, class T -> -OutputIteratorType replace_copy_if(const ExecutionSpace& exespace, (1) - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to, - UnaryPredicateType pred, const T& new_value); - -template < - class ExecutionSpace, - class InputIteratorType, class OutputIteratorType, - class UnaryPredicateType, class T -> -OutputIteratorType replace_copy_if(const std::string& label, (2) - const ExecutionSpace& exespace, - InputIteratorType first_from, - InputIteratorType last_from, - OutputIteratorType first_to, - UnaryPredicateType pred, const T& new_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class UnaryPredicateType, class T -> -auto replace_copy_if(const ExecutionSpace& exespace, (3) - const Kokkos::View& view_from, - const Kokkos::View& view_to, - UnaryPredicateType pred, const T& new_value); - -template < - class ExecutionSpace, - class DataType1, class... Properties1, - class DataType2, class... Properties2, - class UnaryPredicateType, class T -> -auto replace_copy_if(const std::string& label, (4) - const ExecutionSpace& exespace, - const Kokkos::View& view_from, - const Kokkos::View& view_to, - UnaryPredicateType pred, const T& new_value); - -} //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 `view_from` to `view_to` -(overloads 3,4) replacing with `new_value` all elements for which `pred` returns `true`. - - -## Parameters and Requirements - -- `exespace`, `first_from`, `last_from`, `first_to`, `view_from`, `view_to`, `new_value`: - - same as in [`replace_copy`](./StdReplaceCopy) -- `label`: - - for 1, the default string is: "Kokkos::replace_copy_if_iterator_api_default" - - for 3, the default string is: "Kokkos::replace_copy_if_view_api_default" -- `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 that shown for [`replace_if`](./StdReplaceIf) - - -## Return - -Iterator to the element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst new file mode 100644 index 000000000..daa9d33b8 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst @@ -0,0 +1,123 @@ + +``replace_copy_if`` +==================== + +Header: ```` + +Description +----------- + +Copies the elements from range ``[first_from, last_from)`` to another range +beginning at ``first_to`` while replacing all elements for which ``pred`` returns ``true`` with ``new_value``. +The overload taking a ``View`` uses the ``begin`` and ``end`` iterators of the ``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, class T + > + OutputIteratorType replace_copy_if(const ExecutionSpace& exespace, (1) + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to, + UnaryPredicateType pred, const T& new_value); + + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType, + class UnaryPredicateType, class T + > + OutputIteratorType replace_copy_if(const std::string& label, (2) + const ExecutionSpace& exespace, + InputIteratorType first_from, + InputIteratorType last_from, + OutputIteratorType first_to, + UnaryPredicateType pred, const T& new_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryPredicateType, class T + > + auto replace_copy_if(const ExecutionSpace& exespace, (3) + const Kokkos::View& view_from, + const Kokkos::View& view_to, + UnaryPredicateType pred, const T& new_value); + + template < + class ExecutionSpace, + class DataType1, class... Properties1, + class DataType2, class... Properties2, + class UnaryPredicateType, class T + > + auto replace_copy_if(const std::string& label, (4) + const ExecutionSpace& exespace, + const Kokkos::View& view_from, + const Kokkos::View& view_to, + UnaryPredicateType pred, const T& new_value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + OutputIterator + replace_copy_if(const TeamHandleType& teamHandle, InputIterator first_from, (5) + InputIterator last_from, OutputIterator first_dest, + PredicateType pred, const ValueType& new_value); + + template + KOKKOS_FUNCTION + auto replace_copy_if(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view_from, + const ::Kokkos::View& view_dest, + PredicateType pred, const ValueType& new_value); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``, ``teamHandle``, ``first_from``, ``last_from``, ``first_to``, ``view_from``, ``view_to``, ``new_value``: + + - same as in [``replace_copy``](./StdReplaceCopy) + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::replace_copy_if_iterator_api_default" + + - for 3, the default string is: "Kokkos::replace_copy_if_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``pred``: unary predicate returning ``true`` for the required element. + + ``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``. + + - should have the same API as that shown for [``replace_if``](./StdReplaceIf) + +Return Value +~~~~~~~~~~~~ + +Iterator to the element *after* the last element copied. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.md b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.md deleted file mode 100644 index f4e98564a..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.md +++ /dev/null @@ -1,93 +0,0 @@ - -# `replace_if` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```c++ -namespace Kokkos{ -namespace Experimental{ - -template -void replace_if(const ExecutionSpace& exespace, (1) - IteratorType first, IteratorType last, - UnaryPredicateType pred, const T& new_value); - -template -void replace_if(const std::string& label, const ExecutionSpace& exespace, (2) - IteratorType first, IteratorType last, - UnaryPredicateType pred, const T& new_value); - -template -void replace_if(const ExecutionSpace& exespace, (3) - const Kokkos::View& view, - UnaryPredicateType pred, const T& new_value); - -template -void replace_if(const std::string& label, const ExecutionSpace& exespace, (4) - const Kokkos::View& view, - UnaryPredicateType pred, const T& new_value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Replaces with `new_value` all the elements for which `pred` is `true` in -the range `[first, last)` (overloads 1,2) or in `view` (overloads 3,4). - -## Parameters and Requirements - -- `exespace`, `first`, `last`, `view`, `new_value`: same as in [`replace`](./StdReplace) -- `label`: - - for 1, the default string is: "Kokkos::replace_if_iterator_api_default" - - for 3, the default string is: "Kokkos::replace_if_view_api_default" -- `pred`: - - *unary* predicate returning `true` for the required element to replace; `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 `IteratorType` (for 1,2) or the value type of `view` (for 3,4), - and must not modify `v`. - - must conform to: - ```c++ - 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 - -None - -## Example - -```c++ -template -struct IsPositiveFunctor { - KOKKOS_INLINE_FUNCTION - bool operator()(const ValueType val) const { return (val > 0); } -}; -// --- - -namespace KE = Kokkos::Experimental; -Kokkos::View a("a", 13); -// do something with a -// ... - -const double oldValue{2}; -const double newValue{34}; -KE::replace_if(Kokkos::DefaultExecutionSpace(), KE::begin(a), KE::end(a), - IsPositiveFunctor(), newValue); - -// explicitly set label and execution space (assuming active) -KE::replace_if("mylabel", Kokkos::OpenMP(), a, - IsPositiveFunctor(), newValue); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst new file mode 100644 index 000000000..4641244bd --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst @@ -0,0 +1,135 @@ + +``replace_if`` +================= + +Header: ```` + +Description +----------- + +Replaces all the elements in +the range ``[first, last)`` for which ``pred`` is ``true`` with with ``new_value``. +The overload taking a ``View`` uses the ``begin`` and ``end`` iterators of the ``View``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + void replace_if(const ExecutionSpace& exespace, (1) + IteratorType first, IteratorType last, + UnaryPredicateType pred, const T& new_value); + + template + void replace_if(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType first, IteratorType last, + UnaryPredicateType pred, const T& new_value); + + template + void replace_if(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + UnaryPredicateType pred, const T& new_value); + + template + void replace_if(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + UnaryPredicateType pred, const T& new_value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + void replace_if(const TeamHandleType& teamHandle, (5) + InputIterator first, InputIterator last, + Predicate pred, const ValueType& new_value); + + template + KOKKOS_FUNCTION + void replace_if(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view, + Predicate pred, const ValueType& new_value); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``, ``first``, ``last``, ``view``, ``new_value``: same as in [``replace``](./StdReplace) + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + + - for 1, the default string is: "Kokkos::replace_if_iterator_api_default" + + - for 3, the default string is: "Kokkos::replace_if_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``pred``: *unary* predicate returning ``true`` for the required element to replace. + + ``pred(v)`` 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 ``IteratorType`` or the value type + of ``view``, 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 +~~~~~~~~~~~~ + +None + +Example +~~~~~~~~~~~~ + +.. code-block:: cpp + + template + struct IsPositiveFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType val) const { return (val > 0); } + }; + // --- + + namespace KE = Kokkos::Experimental; + Kokkos::View a("a", 13); + // do something with a + // ... + + const double oldValue{2}; + const double newValue{34}; + KE::replace_if(Kokkos::DefaultExecutionSpace(), KE::begin(a), KE::end(a), + IsPositiveFunctor(), newValue); + + // explicitly set label and execution space (assuming active) + KE::replace_if("mylabel", Kokkos::OpenMP(), a, + IsPositiveFunctor(), newValue);