From fb1e77be58f1f993cf26f20f3f0d119c6842c1f9 Mon Sep 17 00:00:00 2001 From: meriadeg perrinel Date: Mon, 29 May 2023 09:11:45 +0200 Subject: [PATCH 1/7] Converted MD files to rst files --- .../algorithms/std-algorithms/all/StdFill.md | 77 ------------ .../algorithms/std-algorithms/all/StdFill.rst | 100 ++++++++++++++++ .../std-algorithms/all/StdFill_n.md | 73 ------------ .../std-algorithms/all/StdFill_n.rst | 88 ++++++++++++++ .../std-algorithms/all/StdReplace.md | 79 ------------- .../std-algorithms/all/StdReplace.rst | 102 ++++++++++++++++ .../std-algorithms/all/StdReplaceCopy.md | 84 ------------- .../std-algorithms/all/StdReplaceCopy.rst | 111 ++++++++++++++++++ .../std-algorithms/all/StdReplaceCopyIf.md | 85 -------------- .../std-algorithms/all/StdReplaceCopyIf.rst | 101 ++++++++++++++++ .../std-algorithms/all/StdReplaceIf.md | 93 --------------- .../std-algorithms/all/StdReplaceIf.rst | 110 +++++++++++++++++ 12 files changed, 612 insertions(+), 491 deletions(-) delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdFill.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdFill.rst delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdFill_n.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplace.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplace.rst delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst delete mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.md create mode 100644 docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst 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..22cb32c42 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst @@ -0,0 +1,100 @@ + +``fill`` +========= + +Header: ```` + +Description +----------- + +Copy-assigns ``value`` to each element in the range ``[first, last)`` (overloads 1,2) +or in ``view`` (overloads 3,4). + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +.. code-block:: cpp + + // + // overload set accepting execution space + // + 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); + + +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 search in + + - 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 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..cd0e23e49 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst @@ -0,0 +1,88 @@ + +``fill_n`` +=========== + +Header: ```` + +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). + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +.. code-block:: cpp + + // + // overload set accepting execution space + // + 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); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``, ``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" + +- ``n``: + + - number of elements to modify (must be non-negative) + + +Return Value +~~~~~~~~~~~~ + +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 +~~~~~~~~~~~~ + +.. 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..bb82409c3 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst @@ -0,0 +1,102 @@ + +``replace`` +============ + +Header: ```` + +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==``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +.. code-block:: cpp + + // + // overload set accepting execution space + // + 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); + + + +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 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..168c6ad8e --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst @@ -0,0 +1,111 @@ + +``replace_copy`` +================= + +Header: ```` + +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==``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +.. code-block:: cpp + + // + // overload set accepting execution space + // + 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); + +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 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..7ec48c358 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst @@ -0,0 +1,101 @@ + +``replace_copy_if`` +==================== + +Header: ```` + +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``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +.. code-block:: cpp + + // + // overload set accepting execution space + // + template < + class ExecutionSpace, + class InputIteratorType, class OutputIteratorType, + class 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); + + + + +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 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..8126ffcc3 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst @@ -0,0 +1,110 @@ + +``replace_if`` +================= + +Header: ```` + +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). + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +.. code-block:: cpp + + // + // overload set accepting execution space + // + 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); + + + +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: + + .. 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); From a66e55bca7bea5367d3e288bb72da5e718c75801 Mon Sep 17 00:00:00 2001 From: meriadeg perrinel Date: Mon, 29 May 2023 21:13:19 +0200 Subject: [PATCH 2/7] Added Team Level documentation --- .../algorithms/std-algorithms/all/StdFill.rst | 33 ++++++++++++----- .../std-algorithms/all/StdFill_n.rst | 27 +++++++++++--- .../std-algorithms/all/StdReplace.rst | 29 ++++++++++----- .../std-algorithms/all/StdReplaceCopy.rst | 35 +++++++++++++----- .../std-algorithms/all/StdReplaceCopyIf.rst | 36 +++++++++++++++---- .../std-algorithms/all/StdReplaceIf.rst | 23 +++++++++++- 6 files changed, 146 insertions(+), 37 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst index 22cb32c42..be21d9d33 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdFill.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst @@ -41,22 +41,39 @@ Interface const Kokkos::View& view, const T& value); + // + // overload set accepting a team handle + // Note: for now omit the overloads accepting a label + // since they cause issues on device because of the string allocation. + // + template + KOKKOS_FUNCTION + void fill(const TeamHandleType& th, + IteratorType first, IteratorType last, + const T& value); + + template + KOKKOS_FUNCTION + void fill(const TeamHandleType& th, + const Kokkos::View& view, + const T& value); + Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``exespace``: - - - execution space instance +- ``exespace``: execution space instance -- ``label``: +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy - - used to name the implementation kernels for debugging purposes +- ``label``: string forwarded to internal parallel kernels for debugging purposes - for 1, the default string is: "Kokkos::fill_iterator_api_default" - for 3, the default string is: "Kokkos::fill_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally + - ``first, last``: range of elements to search in - range of elements to assign to @@ -65,7 +82,7 @@ Parameters and Requirements - must represent a valid range, i.e., ``last >= first`` (checked in debug mode) - - must be accessible from ``exespace`` + - must be accessible from ``exespace`` or from the execution space associated with the team handle - ``view``: @@ -73,9 +90,7 @@ Parameters and Requirements - must be accessible from ``exespace`` -- ``value``: - - - value to assign to each element +- ``value``: value to assign to each element Return Value diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst index cd0e23e49..c4560559e 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst @@ -41,24 +41,43 @@ Interface const Kokkos::View& view, SizeType n, const T& value); + // + // overload set accepting a team handle + // + template + KOKKOS_FUNCTION + IteratorType fill_n(const TeamHandleType& th, + IteratorType first, SizeType n, + const T& value); + + template < + class TeamHandleType, class DataType, class... Properties, class SizeType, + class T, int> + KOKKOS_FUNCTION + IteratorType fill_n(const TeamHandleType& th, + const Kokkos::View& view, + SizeType n, + const T& value); + Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``exespace``, ``first``, ``view``, ``value``: same as in [``fill``](./StdFill): execution space instance -- ``label``: +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy - - used to name the implementation kernels for debugging purposes +- ``label``: used to name the implementation kernels for debugging purposes - for 1, the default string is: "Kokkos::fill_n_iterator_api_default" - for 3, the default string is: "Kokkos::fill_n_view_api_default" -- ``n``: + - NOTE: overloads accepting a team handle do not use a label internally - - number of elements to modify (must be non-negative) +- ``n``: number of elements to modify (must be non-negative) +- ``value``: value to assign to each element Return Value ~~~~~~~~~~~~ diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst index bb82409c3..739361ecf 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst @@ -42,23 +42,38 @@ Interface const Kokkos::View& view, const T& old_value, const T& new_value); + // + // overload set accepting a team handle + // + template + KOKKOS_FUNCTION + void replace(const TeamHandleType& teamHandle, + Iterator first, Iterator last, + const ValueType& old_value, const ValueType& new_value); + + template + KOKKOS_FUNCTION + void replace(const TeamHandleType& teamHandle, + const ::Kokkos::View& view, + const ValueType& old_value, const ValueType& new_value); Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``exespace``: +- ``exespace``: execution space instance - - execution space instance +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy -- ``label``: - - - used to name the implementation kernels for debugging purposes +- ``label``: used to name the implementation kernels for debugging purposes - for 1, the default string is: "Kokkos::replace_iterator_api_default" - for 3, the default string is: "Kokkos::replace_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally + - ``first, last``: - range of elements to search in @@ -75,9 +90,7 @@ Parameters and Requirements - must be accessible from ``exespace`` -- ``old_value``, ``new_value``: - - - self-explanatory +- ``old_value``, ``new_value``: self-explanatory Return Value diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst index 168c6ad8e..b616100ce 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst @@ -59,21 +59,42 @@ Interface const Kokkos::View& view_to, const T& old_value, const T& new_value); + // + // overload set accepting a team handle + // + template + KOKKOS_FUNCTION + OutputIterator replace_copy(const TeamHandleType& teamHandle, + InputIterator first_from, InputIterator last_from, + OutputIterator first_dest, + const ValueType& old_value, const ValueType& new_value); + + template < + class TeamHandleType, class DataType1, class... Properties1, + class DataType2, class... Properties2, class ValueType, int> + KOKKOS_FUNCTION + auto replace_copy(const TeamHandleType& teamHandle, + const Kokkos::View& view_from, + const Kokkos::View& view_dest, + const ValueType& old_value, const ValueType& new_value); + + Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``exespace``: - - - execution space instance +- ``exespace``: execution space instance -- ``label``: +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy - - used to name the implementation kernels for debugging purposes +- ``label``: used to name the implementation kernels for debugging purposes - for 1, the default string is: "Kokkos::replace_copy_iterator_api_default" - for 3, the default string is: "Kokkos::replace_copy_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally + - ``first_from, last_from``: - range of elements to copy from @@ -100,9 +121,7 @@ Parameters and Requirements - must be accessible from ``exespace`` -- ``old_value``, ``new_value``: - - - self-explanatory +- ``old_value``, ``new_value``: self-explanatory Return Value diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst index 7ec48c358..e482e4ab7 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst @@ -62,13 +62,31 @@ Interface class DataType2, class... Properties2, class UnaryPredicateType, class T > - auto replace_copy_if(const std::string& label, (4) - const ExecutionSpace& exespace, - const Kokkos::View& view_from, - const Kokkos::View& view_to, - UnaryPredicateType pred, const T& new_value); - + 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 + // + template + KOKKOS_FUNCTION + OutputIterator + replace_copy_if(const TeamHandleType& teamHandle, InputIterator first_from, + InputIterator last_from, OutputIterator first_dest, + PredicateType pred, const ValueType& new_value); + + template + KOKKOS_FUNCTION + auto replace_copy_if(const TeamHandleType& teamHandle, + const ::Kokkos::View& view_from, + const ::Kokkos::View& view_dest, + PredicateType pred, const ValueType& new_value); Parameters and Requirements @@ -78,12 +96,16 @@ Parameters and Requirements - same as in [``replace_copy``](./StdReplaceCopy) -- ``label``: +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes - for 1, the default string is: "Kokkos::replace_copy_if_iterator_api_default" - for 3, the default string is: "Kokkos::replace_copy_if_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally + - ``pred``: - unary predicate which returns ``true`` for the required element; ``pred(v)`` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst index 8126ffcc3..b0fa8666e 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst @@ -41,6 +41,22 @@ Interface const Kokkos::View& view, UnaryPredicateType pred, const T& new_value); + // + // overload set accepting a team handle + // + template + KOKKOS_FUNCTION + void replace_if(const TeamHandleType& teamHandle, + InputIterator first, InputIterator last, + Predicate pred, const ValueType& new_value); + + template + KOKKOS_FUNCTION + void replace_if(const TeamHandleType& teamHandle, + const ::Kokkos::View& view, + Predicate pred, const ValueType& new_value); Parameters and Requirements @@ -48,12 +64,16 @@ Parameters and Requirements - ``exespace``, ``first``, ``last``, ``view``, ``new_value``: same as in [``replace``](./StdReplace) -- ``label``: +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes - for 1, the default string is: "Kokkos::replace_if_iterator_api_default" - for 3, the default string is: "Kokkos::replace_if_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally + - ``pred``: - *unary* predicate returning ``true`` for the required element to replace; ``pred(v)`` @@ -78,6 +98,7 @@ Parameters and Requirements bool operator()(value_type v) const { return /* ... */; } }; + Return Value ~~~~~~~~~~~~ From 732fca4086cd2e172bc09733e09fe60da2c5ae3d Mon Sep 17 00:00:00 2001 From: Francesco Rizzi Date: Fri, 1 Dec 2023 17:54:54 +0100 Subject: [PATCH 3/7] finalize --- .../algorithms/std-algorithms/all/StdFill.rst | 32 ++++++------ .../std-algorithms/all/StdFill_n.rst | 51 ++++++++++--------- .../std-algorithms/all/StdReplace.rst | 30 ++++++----- .../std-algorithms/all/StdReplaceCopy.rst | 48 ++++++++--------- .../std-algorithms/all/StdReplaceCopyIf.rst | 46 ++++++++--------- .../std-algorithms/all/StdReplaceIf.rst | 35 +++++++------ 6 files changed, 126 insertions(+), 116 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst index be21d9d33..179d264c5 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdFill.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill.rst @@ -7,8 +7,8 @@ Header: ```` Description ----------- -Copy-assigns ``value`` to each element in the range ``[first, last)`` (overloads 1,2) -or in ``view`` (overloads 3,4). +Assigns a given ``value`` to each element in a given range or rank-1 ``View``. + Interface --------- @@ -16,11 +16,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template void fill(const ExecutionSpace& exespace, (1) IteratorType first, IteratorType last, @@ -41,20 +41,22 @@ Interface const Kokkos::View& view, const T& value); - // - // overload set accepting a team handle - // Note: for now omit the overloads accepting a label - // since they cause issues on device because of the string allocation. - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template KOKKOS_FUNCTION - void fill(const TeamHandleType& th, + void fill(const TeamHandleType& teamHandle, (5) IteratorType first, IteratorType last, const T& value); template KOKKOS_FUNCTION - void fill(const TeamHandleType& th, + void fill(const TeamHandleType& teamHandle, (6) const Kokkos::View& view, const T& value); @@ -74,13 +76,11 @@ Parameters and Requirements - NOTE: overloads accepting a team handle do not use a label internally -- ``first, last``: range of elements to search in - - - range of elements to assign to +- ``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`` (checked in debug mode) + - must represent a valid range, i.e., ``last >= first`` - must be accessible from ``exespace`` or from the execution space associated with the team handle diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst index c4560559e..e814b0aa2 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdFill_n.rst @@ -7,8 +7,8 @@ Header: ```` 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). +Assigns a given ``value`` to the first ``n`` elements in a given range or rank-1 ``View``. + Interface --------- @@ -16,11 +16,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template IteratorType fill_n(const ExecutionSpace& exespace, (1) IteratorType first, @@ -31,41 +31,46 @@ Interface IteratorType first, SizeType n, const T& value); - template + 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 + 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 - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + + +.. code-block:: cpp + template KOKKOS_FUNCTION - IteratorType fill_n(const TeamHandleType& th, - IteratorType first, SizeType n, - const T& value); + 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, int> + class TeamHandleType, class DataType, class... Properties, class SizeType, + class T> KOKKOS_FUNCTION - IteratorType fill_n(const TeamHandleType& th, - const Kokkos::View& view, - SizeType n, - const T& value); + auto fill_n(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + SizeType n, const T& value); Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``exespace``, ``first``, ``view``, ``value``: same as in [``fill``](./StdFill): execution space instance - -- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy +- ``exespace``, ``teamHandle``, ``first``, ``view``, ``value``: same as in [``fill``](./StdFill): execution space instance - ``label``: used to name the implementation kernels for debugging purposes @@ -84,7 +89,7 @@ Return Value 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). +Otherwise, it returns ``first`` (for 1,2,5) or ``Kokkos::begin(view)`` (for 3,4,6). Example diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst index 739361ecf..f30058e23 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst @@ -7,9 +7,8 @@ Header: ```` 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==``. +Replaces with ``new_value`` all elements that are equal to ``old_value`` in +a given range or rank-1 ``View``. Equality is checked using ``operator==``. Interface --------- @@ -17,11 +16,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template void replace(const ExecutionSpace& exespace, (1) IteratorType first, IteratorType last, @@ -42,19 +41,24 @@ Interface const Kokkos::View& view, const T& old_value, const T& new_value); - // - // overload set accepting a team handle - // + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template KOKKOS_FUNCTION - void replace(const TeamHandleType& teamHandle, + 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, + void replace(const TeamHandleType& teamHandle, (6) const ::Kokkos::View& view, const ValueType& old_value, const ValueType& new_value); @@ -74,9 +78,7 @@ Parameters and Requirements - NOTE: overloads accepting a team handle do not use a label internally -- ``first, last``: - - - range of elements to search in +- ``first, last``: range of elements to search in - must be *random access iterators*, e.g., ``Kokkos::Experimental::begin/end`` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst index b616100ce..54aaa1542 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst @@ -7,9 +7,9 @@ Header: ```` 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``. +Copies the elements from a given range ``[first_from, last_from)`` to another range +beginning at ``first_to`` or from ``view_from`` to ``view_to`` replacing +with ``new_value`` all elements that equal ``old_value``. Comparison between elements is done using ``operator==``. Interface @@ -18,20 +18,20 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template - OutputIteratorType replace_copy(const ExecutionSpace& exespace, (1) + 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) + OutputIteratorType replace_copy(const std::string& label, (2) const ExecutionSpace& exespace, OutputIteratorType first_to, const T& old_value, const T& new_value); @@ -42,7 +42,7 @@ Interface class DataType2, class... Properties2, class T > - auto replace_copy(const ExecutionSpace& exespace, (3) + 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); @@ -54,18 +54,22 @@ Interface class T > auto replace_copy(const std::string& label, - const ExecutionSpace& exespace, (4) + 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 - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template KOKKOS_FUNCTION - OutputIterator replace_copy(const TeamHandleType& teamHandle, + OutputIterator replace_copy(const TeamHandleType& teamHandle, (5) InputIterator first_from, InputIterator last_from, OutputIterator first_dest, const ValueType& old_value, const ValueType& new_value); @@ -74,7 +78,7 @@ Interface class TeamHandleType, class DataType1, class... Properties1, class DataType2, class... Properties2, class ValueType, int> KOKKOS_FUNCTION - auto replace_copy(const TeamHandleType& teamHandle, + 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); @@ -95,23 +99,19 @@ Parameters and Requirements - NOTE: overloads accepting a team handle do not use a label internally -- ``first_from, last_from``: - - - range of elements to copy from +- ``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``: + - must be accessible from ``exespace`` or from the execution space associated with the team handle - - beginning of the range to copy to +- ``first_to``: beginning of the range to copy to - must be a *random access iterator* - - must be accessible from ``exespace`` + - must be accessible from ``exespace`` or from the execution space associated with the team handle - ``view_from``, ``view_to``: @@ -119,7 +119,7 @@ Parameters and Requirements - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` - - must be accessible from ``exespace`` + - must be accessible from ``exespace`` or from the execution space associated with the team handle - ``old_value``, ``new_value``: self-explanatory diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst index e482e4ab7..2c1e994f5 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst @@ -17,17 +17,17 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class UnaryPredicateType, class T > - OutputIteratorType replace_copy_if(const ExecutionSpace& exespace, (1) + OutputIteratorType replace_copy_if(const ExecutionSpace& exespace, (1) InputIteratorType first_from, InputIteratorType last_from, OutputIteratorType first_to, @@ -38,7 +38,7 @@ Interface class InputIteratorType, class OutputIteratorType, class UnaryPredicateType, class T > - OutputIteratorType replace_copy_if(const std::string& label, (2) + OutputIteratorType replace_copy_if(const std::string& label, (2) const ExecutionSpace& exespace, InputIteratorType first_from, InputIteratorType last_from, @@ -51,7 +51,7 @@ Interface class DataType2, class... Properties2, class UnaryPredicateType, class T > - auto replace_copy_if(const ExecutionSpace& exespace, (3) + auto replace_copy_if(const ExecutionSpace& exespace, (3) const Kokkos::View& view_from, const Kokkos::View& view_to, UnaryPredicateType pred, const T& new_value); @@ -62,20 +62,24 @@ Interface class DataType2, class... Properties2, class UnaryPredicateType, class T > - auto replace_copy_if(const std::string& label, (4) + 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 - // +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, + replace_copy_if(const TeamHandleType& teamHandle, InputIterator first_from, (5) InputIterator last_from, OutputIterator first_dest, PredicateType pred, const ValueType& new_value); @@ -83,8 +87,8 @@ Interface class DataType2, class... Properties2, class PredicateType, class ValueType, int> KOKKOS_FUNCTION - auto replace_copy_if(const TeamHandleType& teamHandle, - const ::Kokkos::View& view_from, + auto replace_copy_if(const TeamHandleType& teamHandle, (6) + const ::Kokkos::View& view_from, const ::Kokkos::View& view_dest, PredicateType pred, const ValueType& new_value); @@ -92,12 +96,10 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- ``exespace``, ``first_from``, ``last_from``, ``first_to``, ``view_from``, ``view_to``, ``new_value``: +- ``exespace``, ``teamHandle``, ``first_from``, ``last_from``, ``first_to``, ``view_from``, ``view_to``, ``new_value``: - same as in [``replace_copy``](./StdReplaceCopy) -- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy - - ``label``: used to name the implementation kernels for debugging purposes - for 1, the default string is: "Kokkos::replace_copy_if_iterator_api_default" @@ -106,14 +108,12 @@ Parameters and Requirements - NOTE: overloads accepting a team handle do not use a label internally -- ``pred``: - - - unary predicate which returns ``true`` for the required element; ``pred(v)`` +- ``pred``: unary predicate returning ``true`` for the required element. - 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``. + ``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) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst index b0fa8666e..0358306fd 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst @@ -16,11 +16,11 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting execution space - // template void replace_if(const ExecutionSpace& exespace, (1) IteratorType first, IteratorType last, @@ -41,20 +41,24 @@ Interface const Kokkos::View& view, UnaryPredicateType pred, const T& new_value); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template KOKKOS_FUNCTION - void replace_if(const TeamHandleType& teamHandle, + 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, + void replace_if(const TeamHandleType& teamHandle, (6) const ::Kokkos::View& view, Predicate pred, const ValueType& new_value); @@ -74,18 +78,17 @@ Parameters and Requirements - 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)`` +- ``pred``: *unary* predicate returning ``true`` for the required element to replace. - 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``. + ``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 + .. code-block:: cpp struct Predicate { From 73e9895af58a7683952e7a209f8d4c546ee9372d Mon Sep 17 00:00:00 2001 From: JBludau <104908666+JBludau@users.noreply.github.com> Date: Thu, 5 Sep 2024 12:55:16 +0200 Subject: [PATCH 4/7] Update docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst --- .../API/algorithms/std-algorithms/all/StdReplaceCopy.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst index 54aaa1542..bc7cb9889 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopy.rst @@ -8,8 +8,9 @@ Description ----------- Copies the elements from a given range ``[first_from, last_from)`` to another range -beginning at ``first_to`` or from ``view_from`` to ``view_to`` replacing -with ``new_value`` all elements that equal ``old_value``. +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 From fdd27481d70c6ab0925455fec53d3182732f8321 Mon Sep 17 00:00:00 2001 From: JBludau <104908666+JBludau@users.noreply.github.com> Date: Thu, 5 Sep 2024 12:55:28 +0200 Subject: [PATCH 5/7] Update docs/source/API/algorithms/std-algorithms/all/StdReplace.rst --- docs/source/API/algorithms/std-algorithms/all/StdReplace.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst index f30058e23..389f89558 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplace.rst @@ -7,7 +7,7 @@ Header: ```` Description ----------- -Replaces with ``new_value`` all elements that are equal to ``old_value`` in +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 From 960e0eec92d72b29ddb6f0156329f298fe137584 Mon Sep 17 00:00:00 2001 From: JBludau <104908666+JBludau@users.noreply.github.com> Date: Thu, 5 Sep 2024 12:55:38 +0200 Subject: [PATCH 6/7] Update docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst --- .../API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst index 2c1e994f5..daa9d33b8 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceCopyIf.rst @@ -8,8 +8,8 @@ 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``. +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 --------- From e4b9b8a64fcf1dbea743d47530a7b9b91582119d Mon Sep 17 00:00:00 2001 From: JBludau <104908666+JBludau@users.noreply.github.com> Date: Thu, 5 Sep 2024 12:55:48 +0200 Subject: [PATCH 7/7] Update docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst --- .../API/algorithms/std-algorithms/all/StdReplaceIf.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst index 0358306fd..4641244bd 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdReplaceIf.rst @@ -7,8 +7,9 @@ Header: ```` 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). +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 ---------