diff --git a/docs/source/API/algorithms/std-algorithms/all/StdForEach.md b/docs/source/API/algorithms/std-algorithms/all/StdForEach.md deleted file mode 100644 index bb549ed22..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdForEach.md +++ /dev/null @@ -1,109 +0,0 @@ - -# `for_each` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -void for_each(const ExecutionSpace& exespace, (1) - InputIterator first, InputIterator last, - UnaryFunctorType functor); - -template -void for_each(const std::string& label, const ExecutionSpace& exespace, (2) - InputIterator first, InputIterator last, - UnaryFunctorType functor); - -template -void for_each(const ExecutionSpace& exespace, - const Kokkos::View& view, (3) - UnaryFunctorType functor); - -template -void for_each(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view, (4) - UnaryFunctorType func); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Applies the UnaryFunctorType `func` to the result of dereferencing each iterator in `[first,last)` for (1,2) and to the view elements in (3,4). - -## Parameters and Requirements - -- `exespace`: - - execution space instance - -- `label`: - - for 1, the default string is: "Kokkos::for_each_iterator_api_default" - - for 3, the default string is: "Kokkos::for_each_view_api_default" - -- `first, last`: - - range of elements to operate on - - must be *random access iterators* - - 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` - -- `func`: - - function object called on the all the elements; - - The signature of the function should be `func(v)`. - - Must be valid to be called from the execution space passed, and must accept every argument `v` of type (possible const) `value_type`, where `value_type` is the value type of `InputIterator`, and must not modify `v`. - - must conform to: - ```cpp - struct func - { - KOKKOS_INLINE_FUNCTION - void operator()(const /*type needed */ & operand) const { /* ... */; } - - // or, also valid - - KOKKOS_INLINE_FUNCTION - void operator()(/*type needed */ operand) const { /* ... */; } - }; - ``` - -## Return - -(nothing) - - -## Example -```cpp -namespace KE = Kokkos::Experimental; - -template -struct IncrementValsFunctor -{ - const ValueType m_value; - IncrementValsFunctor(ValueType value) : m_value(value){} - - KOKKOS_INLINE_FUNCTION - void operator()(const ValueType & operand) const { - operand += m_value; - } -}; - -auto exespace = Kokkos::DefaultExecutionSpace; -using view_type = Kokkos::View; -view_type a("a", 15); -// fill "a" somehow - -// create functor -IncrementValsFunctor p(5); - -// Increment each element in "a" by 5. -KE::for_each(exespace, KE::begin(a), KE::end(a), p); - -// assuming OpenMP is enabled, then you can also explicitly call -KE::for_each(Kokkos::OpenMP(), KE::begin(a), KE::end(a), p); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdForEach.rst b/docs/source/API/algorithms/std-algorithms/all/StdForEach.rst new file mode 100644 index 000000000..ad1cef735 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdForEach.rst @@ -0,0 +1,148 @@ + +``for_each`` +============ + +Header: ```` + +Description +----------- + +Applies a unary functor to the result of dereferencing each iterator in a range or each element in a rank-1 ``View``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + UnaryFunctorType for_each(const ExecutionSpace& exespace, (1) + InputIterator first, InputIterator last, + UnaryFunctorType func); + + template + UnaryFunctorType for_each(const std::string& label, const ExecutionSpace& exespace, (2) + InputIterator first, InputIterator last, + UnaryFunctorType func); + + template + UnaryFunctorType for_each(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + UnaryFunctorType func); + + template + UnaryFunctorType for_each(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + UnaryFunctorType func); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + UnaryFunctorType for_each(const TeamHandleType& teamHandle, (5) + InputIterator first, InputIterator last, + UnaryFunctorType func); + + template + KOKKOS_FUNCTION + UnaryFunctorType for_each(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + UnaryFunctorType func); + +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::for_each_iterator_api_default" + + - for 3, the default string is: "Kokkos::for_each_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: iterators defining the ranges to operate on + + - must be *random access iterators* + + - 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`` or from the execution space associated with the team handle + +- ``func``: function object called on the all the elements; + + - The signature of the function should be ``func(v)`` and must be valid to be called from the execution space passed, + or the execution space associated with the team handle, and must accept every argument ``v`` of type + ``value_type``, where ``value_type`` is the value type of ``InputIterator`` or ``view`` + + - must conform to: + + .. code-block:: cpp + + struct func + { + KOKKOS_INLINE_FUNCTION + void operator()(const /*type needed */ & operand) const { /* ... */; } + + // or, also valid + + KOKKOS_INLINE_FUNCTION + void operator()(/*type needed */ & operand) const { /* ... */; } + }; + +Return +~~~~~~ + +``func`` + +Example +------- + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + + template + struct IncrementValFunctor + { + const ValueType m_value; + IncrementValFunctor(ValueType value) : m_value(value){} + + KOKKOS_INLINE_FUNCTION + void operator()(ValueType & operand) const { + operand += m_value; + } + }; + + auto exespace = Kokkos::DefaultExecutionSpace; + using view_type = Kokkos::View; + view_type a("a", 15); + // fill "a" somehow + + // create functor + IncrementValFunctor p(5); + + // Increment each element in "a" by 5. + KE::for_each(exespace, KE::begin(a), KE::end(a), p); + + // assuming OpenMP is enabled, then you can also explicitly call + // To run explicitly on the host (assuming a and b are accessible on Host) + KE::equal(Kokkos::DefaultHostExecutionSpace(), KE::begin(a), KE::end(a), diff --git a/docs/source/API/algorithms/std-algorithms/all/StdForEachN.md b/docs/source/API/algorithms/std-algorithms/all/StdForEachN.md deleted file mode 100644 index cf468521d..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdForEachN.md +++ /dev/null @@ -1,54 +0,0 @@ - -# `for_each_n` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -UnaryFunctorType for_each_n(const ExecutionSpace& exespace, - InputIterator first, SizeType n, - UnaryFunctorType functor); (1) - -template -UnaryFunctorType for_each_n(const std::string& label, const ExecutionSpace& exespace, - InputIterator first, SizeType n - UnaryFunctorType functor); (2) - -template -UnaryFunctorType for_each_n(const ExecutionSpace& exespace, - const Kokkos::View& view, SizeType n, - UnaryFunctorType functor); (3) - -template -UnaryFunctorType for_each_n(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view, SizeType n, - UnaryFunctorType func); (4) - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Applies the UnaryFunctorType `func` to the result of dereferencing each iterator in `[first,first+n]` for (1,2) and in (3,4) the functor is applied to the first `n` elements of the view. - -- (1,2): overload set accepting iterators -- (3,4): overload set accepting views - -## Parameters and Requirements - -- `exespace`, `first`, `view`, `func` : same as in [`for_each`](./StdForEach) - -- `label`: - - for 1, the default string is: "Kokkos::for_each_n_iterator_api_default" - - for 3, the default string is: "Kokkos::for_each_n_view_api_default" - -- `n`: - - number of elements to operate on - -## Return - -`func` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdForEachN.rst b/docs/source/API/algorithms/std-algorithms/all/StdForEachN.rst new file mode 100644 index 000000000..3747b4486 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdForEachN.rst @@ -0,0 +1,122 @@ + +``for_each_n`` +============== + +Header: ```` + +Description +----------- + +Applies a unary functor to the result of dereferencing each iterator in a range of ``n`` iterators +or each of the first ``n`` elements in a rank-1 ``View``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + IteratorType for_each_n(const ExecutionSpace& exespace, (1) + IteratorType first, SizeType n, + UnaryFunctorType func); + + template + IteratorType for_each_n(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType first, SizeType n + UnaryFunctorType func); + + template + auto for_each_n(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, SizeType n, + UnaryFunctorType func); + + template + auto for_each_n(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, SizeType n, + UnaryFunctorType func); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + IteratorType for_each_n(const TeamHandleType& teamHandle, (5) + IteratorType first, SizeType n, + UnaryFunctorType func); + + template + KOKKOS_FUNCTION + auto for_each_n(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, SizeType n, + UnaryFunctorType func); + +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::for_each_n_iterator_api_default" + + - for 3, the default string is: "Kokkos::for_each_n_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``n``: number of elements to operate on + +- ``first``: iterator defining the beginning of range + + - must be *random access iterator* + + - ``[first, first+n)`` must represent a valid range + + - 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`` or from the execution space associated with the team handle + +- ``func``: function object called on the all the elements; + + - The signature of the function should be ``func(v)`` and must be valid to be called from the execution space passed, + or the execution space associated with the team handle, and must accept every argument ``v`` of type + ``value_type``, where ``value_type`` is the value type of ``IteratorType`` or ``view`` + + - must conform to: + + .. code-block:: cpp + + struct func + { + KOKKOS_INLINE_FUNCTION + void operator()(const /*type needed */ & operand) const { /* ... */; } + + // or, also valid + + KOKKOS_INLINE_FUNCTION + void operator()(/*type needed */ & operand) const { /* ... */; } + }; + +Return +~~~~~~ + +- 1,2,5: an iterator equal to ``first + n`` + +- 3,4,6: an iterator equal to ``Kokkos::begin(view) + n`` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdLexicographicalCompare.md b/docs/source/API/algorithms/std-algorithms/all/StdLexicographicalCompare.md deleted file mode 100644 index c985d4576..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdLexicographicalCompare.md +++ /dev/null @@ -1,95 +0,0 @@ - -# `lexicographical_compare` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -bool lexicographical_compare(const ExecutionSpace& exespace, IteratorType1 first1, - IteratorType1 last1, IteratorType2 first2, (1) - IteratorType2 last2); - -template -bool lexicographical_compare(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first1, IteratorType1 last1, (2) - IteratorType2 first2, IteratorType2 last2); - -template -bool lexicographical_compare( - const ExecutionSpace& exespace, - const ::Kokkos::View& view1, (3) - ::Kokkos::View& view2); - -template -bool lexicographical_compare( - const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view1, (4) - ::Kokkos::View& view2); - -template -bool lexicographical_compare(const ExecutionSpace& exespace, IteratorType1 first1, - IteratorType1 last1, IteratorType2 first2, (5) - IteratorType2 last2, ComparatorType comp); - -template -bool lexicographical_compare(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first1, IteratorType1 last1, (6) - IteratorType2 first2, IteratorType2 last2, - ComparatorType comp); - -template -bool lexicographical_compare( - const ExecutionSpace& exespace, - const ::Kokkos::View& view1, - ::Kokkos::View& view2, ComparatorType comp); (7) - - -template -bool lexicographical_compare( - const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view1, (8) - ::Kokkos::View& view2, ComparatorType comp); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Returns `true` for (1,2,5,6) if the first range [first1, last1) is lexicographically less than the second range [first2, last2). -Returns `true` for (3,4,7,8) if elements in `view1` are lexicographically less than elements in `view2`. -Elements (1,2,3,4) are compared using the `<` operator. -Elements (5,6,7,8) are compared using `comp`. - -## Parameters and Requirements - -- `exespace`: - - execution space instance - -- `label`: - - 1,5: The default string is "Kokkos::lexicographical_compare_iterator_api_default". - - 3,7: The default string is "Kokkos::lexicographical_compare_view_api_default". - -- `first1`, `last1`, `first2`, `last2`: - - range of elements to compare - - must be *random access iterators* - - must represent valid ranges, i.e., `last1 >= first1` and `last2 >= first2` - - must be accessible from `exespace` - -- `view1`, `view2`: - - views to compare - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` - -- `pred` - similar to [`equal`](./StdEqual) - - diff --git a/docs/source/API/algorithms/std-algorithms/all/StdLexicographicalCompare.rst b/docs/source/API/algorithms/std-algorithms/all/StdLexicographicalCompare.rst new file mode 100644 index 000000000..b128356cc --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdLexicographicalCompare.rst @@ -0,0 +1,156 @@ + +``lexicographical_compare`` +=========================== + +Header: ```` + +Description +----------- + +Returns ``true`` if the first range (or view) is lexicographically less than the second range (or view). + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + bool lexicographical_compare(const ExecutionSpace& exespace, IteratorType1 first1, + IteratorType1 last1, IteratorType2 first2, (1) + IteratorType2 last2); + + template + bool lexicographical_compare(const std::string& label, const ExecutionSpace& exespace, + IteratorType1 first1, IteratorType1 last1, (2) + IteratorType2 first2, IteratorType2 last2); + + template + bool lexicographical_compare(const ExecutionSpace& exespace, (3) + const ::Kokkos::View& view1, + ::Kokkos::View& view2); + + template + bool lexicographical_compare(const std::string& label, (4) + const ExecutionSpace& exespace, + const ::Kokkos::View& view1, + ::Kokkos::View& view2); + + template + bool lexicographical_compare(const ExecutionSpace& exespace, IteratorType1 first1, + IteratorType1 last1, IteratorType2 first2, (5) + IteratorType2 last2, ComparatorType comp); + + template + bool lexicographical_compare(const std::string& label, const ExecutionSpace& exespace, + IteratorType1 first1, IteratorType1 last1, (6) + IteratorType2 first2, IteratorType2 last2, + ComparatorType comp); + + template + bool lexicographical_compare(const ExecutionSpace& exespace, (7) + const ::Kokkos::View& view1, + ::Kokkos::View& view2, + ComparatorType comp); + + + template + bool lexicographical_compare(const std::string& label, (8) + const ExecutionSpace& exespace, + const ::Kokkos::View& view1, + ::Kokkos::View& view2, + ComparatorType comp); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + bool lexicographical_compare(const TeamHandleType& teamHandle, IteratorType1 first1, + IteratorType1 last1, IteratorType2 first2, (9) + IteratorType2 last2); + + template + KOKKOS_FUNCTION + bool lexicographical_compare(const TeamHandleType& teamHandle, (10) + const ::Kokkos::View& view1, + ::Kokkos::View& view2); + + template + KOKKOS_FUNCTION + bool lexicographical_compare(const TeamHandleType& teamHandle, IteratorType1 first1, + IteratorType1 last1, IteratorType2 first2, (11) + IteratorType2 last2, ComparatorType comp); + + template + KOKKOS_FUNCTION + bool lexicographical_compare(const TeamHandleType& teamHandle, (12) + const ::Kokkos::View& view1, + ::Kokkos::View& view2, + ComparatorType comp); + +Detailed Description +~~~~~~~~~~~~~~~~~~~~ + +Returns ``true`` for if the first range ``[first1, last1)`` (or ``view1``) is lexicographically +less than the second range ``[first2, last2)`` (or ``view2``). + +Elements are compared using the ``<`` operator for all overloads not accepting a comparison object ``comp``. + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: + + - 1,5: The default string is "Kokkos::lexicographical_compare_iterator_api_defaul". + + - 3,7: The default string is "Kokkos::lexicographical_compare_view_api_default". + +- ``first1``, ``last1``, ``first2``, ``last2``: range of elements to compare + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent valid ranges, i.e., ``last1 >= first1`` and ``last2 >= first2`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view1``, ``view2``: views to compare + + - 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 + +- ``pred``: comparison function object returning ``true`` if the first agument is less than the second + + - must conform to: + + .. code-block:: cpp + + template + struct Comp { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return ...; + } + }; diff --git a/docs/source/API/algorithms/std-algorithms/all/StdMismatch.md b/docs/source/API/algorithms/std-algorithms/all/StdMismatch.md deleted file mode 100644 index 6f55b77fa..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdMismatch.md +++ /dev/null @@ -1,143 +0,0 @@ - -# `mismatch` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -Kokkos::pair mismatch(const ExecutionSpace& exespace, - IteratorType1 first1, - IteratorType1 last1, (1) - IteratorType2 first2, - IteratorType2 last2); - -template -Kokkos::pair mismatch( - const std::string& label, - const ExecutionSpace& exespace, - IteratorType1 first1, - IteratorType1 last1, (2) - IteratorType2 first2, - IteratorType2 last2) - -template -Kokkos::pair mismatch(const ExecutionSpace& exespace, - IteratorType1 first1, - IteratorType1 last1, (3) - IteratorType2 first2, - IteratorType2 last2, BinaryPredicate pred); - -template -Kokkos::pair mismatch(const std::string& label, - const ExecutionSpace& exespace, - IteratorType1 first1, - IteratorType1 last1, (4) - IteratorType2 first2, - IteratorType2 last2, BinaryPredicate pred); - -template -auto mismatch(const ExecutionSpace& exespace, - const Kokkos::View& view1, (5) - const Kokkos::View& view2); - -template -auto mismatch(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view1, (6) - const Kokkos::View& view2); - -template -auto mismatch(const ExecutionSpace& exespace, - const Kokkos::View& view1, (7) - const Kokkos::View& view2, - BinaryPredicateType&& predicate); - -template -auto mismatch(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view1, (8) - const Kokkos::View& view2, - BinaryPredicateType&& predicate); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Returns the first mismatching pair of elements from two ranges: one defined by [first1, last1) and another defined by [first2,last2) for (1,2,3,4). -Returns the first mismatching pair of elements from the two views `view1` and `view2` in (5,6,7,8). -The elements are compared using `operator==` in (1,2,5,6). -The elements in (3,4,7,8) are compared using a BinaryPredicate `pred`. - -## Parameters and Requirements - -- `exespace`: - - execution space instance - -- `label`: - - for 1,3, the default string is: "Kokkos::mismatch_iterator_api_default" - - for 5,7, the default string is: "Kokkos::mismatch_view_api_default" - -- `first1`, `last1`, `first2`, `last2`: - - range of elements to compare - - must be *random access iterators* - - must represent valid ranges, i.e., `last1 >= first1` and `last2 >= first2` - - must be accessible from `exespace` - -- `view1`, `view2`: - - views to compare - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` - -- `pred` - ```cpp - template - struct IsEqualFunctor { - - KOKKOS_INLINE_FUNCTION - Kokkos::pair operator()(const ValueType1& a, const ValueType2& b) const { - return (a == b); - } - }; - ``` - -## Return - -- (1,2) - Kokkos::pair, where the `.first` and `.second` are the IteratorType1 and IteratorType2 instances where the `operator==` evaluates to false -- (3,4) - Kokkos::pair, where the `.first` and `.second` are the IteratorType1 and IteratorType2 instances where the `pred` evaluates to false - -## Example - -```cpp -namespace KE = Kokkos::Experimental; - -template -struct MismatchFunctor { - - KOKKOS_INLINE_FUNCTION - Kokkos::pair operator()(const ValueType1& a, const ValueType2& b) const { - if(a != b) - return (Kokkos::pair (a,b)); - } -}; - -auto exespace = Kokkos::DefaultExecutionSpace; -using view_type = Kokkos::View; -view_type a("a", 15); -view_type b("b", 15); -// fill a,b somehow - -// create functor -MismatchFunctor p(); - -Kokkos::pair mismatch_index = KE::mismatch(exespace, KE::begin(a), KE::end(a), KE::begin(b), KE::end(b) p); - -// assuming OpenMP is enabled, then you can also explicitly call -Kokkos::pair mismatch_index = KE::mismatch(Kokkos::OpenMP(), KE::begin(a), KE::end(a), KE::begin(b), KE::end(b), p); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdMismatch.rst b/docs/source/API/algorithms/std-algorithms/all/StdMismatch.rst new file mode 100644 index 000000000..3c1ffab40 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdMismatch.rst @@ -0,0 +1,213 @@ + +``mismatch`` +============ + +Header: ```` + +Description +----------- + +Returns the first mismatching pair of elements from two ranges or two views. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + Kokkos::pair mismatch(const ExecutionSpace& exespace, (1) + IteratorType1 first1, + IteratorType1 last1, + IteratorType2 first2, + IteratorType2 last2); + + template + Kokkos::pair mismatch(const std::string& label, (2) + const ExecutionSpace& exespace, + IteratorType1 first1, + IteratorType1 last1, + IteratorType2 first2, + IteratorType2 last2) + + template + Kokkos::pair mismatch(const ExecutionSpace& exespace, (3) + IteratorType1 first1, + IteratorType1 last1, + IteratorType2 first2, + IteratorType2 last2, + BinaryPredicate pred); + + template + Kokkos::pair mismatch(const std::string& label, (4) + const ExecutionSpace& exespace, + IteratorType1 first1, + IteratorType1 last1, + IteratorType2 first2, + IteratorType2 last2, + BinaryPredicate pred); + + template + auto mismatch(const ExecutionSpace& exespace, + const Kokkos::View& view1, (5) + const Kokkos::View& view2); + + template + auto mismatch(const std::string& label, const ExecutionSpace& exespace, + const Kokkos::View& view1, (6) + const Kokkos::View& view2); + + template + auto mismatch(const ExecutionSpace& exespace, + const Kokkos::View& view1, (7) + const Kokkos::View& view2, + BinaryPredicateType&& predicate); + + template + auto mismatch(const std::string& label, const ExecutionSpace& exespace, + const Kokkos::View& view1, (8) + const Kokkos::View& view2, + BinaryPredicateType&& predicate); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + Kokkos::pair mismatch(const TeamHandleType& teamHandle, (9) + IteratorType1 first1, + IteratorType1 last1, + IteratorType2 first2, + IteratorType2 last2); + + template + KOKKOS_FUNCTION + Kokkos::pair mismatch(const TeamHandleType& teamHandle, (10) + IteratorType1 first1, + IteratorType1 last1, + IteratorType2 first2, + IteratorType2 last2, + BinaryPredicate pred); + + template + KOKKOS_FUNCTION + auto mismatch(const TeamHandleType& teamHandle, + const Kokkos::View& view1, (11) + const Kokkos::View& view2); + + template + KOKKOS_FUNCTION + auto mismatch(const TeamHandleType& teamHandle, + const Kokkos::View& view1, (12) + const Kokkos::View& view2, + BinaryPredicateType&& predicate); + +Detailed Description +~~~~~~~~~~~~~~~~~~~~ + +- 1,2,3,4,9,10: Returns the first mismatching pair of elements from two ranges: one defined + by ``[first1, last1)`` and another defined by ``[first2,last2)`` + +- 5,6,7,8,11,12: Returns the first mismatching pair of elements from the two views ``view1`` and ``view2`` + +Comparison of elements is done via the BinaryPredicate, ``pred``, where provided, otherwise +using ``operator==``. + + +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,3, the default string is: "Kokkos::mismatch_iterator_api_default" + + - for 5,7, the default string is: "Kokkos::mismatch_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first1``, ``last1``, ``first2``, ``last2``: range of elements to compare + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent valid ranges, i.e., ``last1 >= first1`` and ``last2 >= first2`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view1``, ``view2``: views to compare + - 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 + +- ``pred`` + + - must conform to: + + .. code-block:: cpp + + template + struct IsEqualFunctor { + + KOKKOS_INLINE_FUNCTION + Kokkos::pair operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + }; + +Return Value +~~~~~~~~~~~~ + +- a Kokkos::pair, where the ``.first`` and ``.second`` are the iterator instances + where the ``operator==`` evaluates to false, or ``pred`` evaluates to false + +Example +~~~~~~~ + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + + template + struct MismatchFunctor { + + KOKKOS_INLINE_FUNCTION + Kokkos::pair operator()(const ValueType1& a, const ValueType2& b) const { + if(a != b) + return (Kokkos::pair (a,b)); + } + }; + + auto exespace = Kokkos::DefaultExecutionSpace; + using view_type = Kokkos::View; + view_type a("a", 15); + view_type b("b", 15); + // fill a,b somehow + + // create functor + MismatchFunctor p(); + + Kokkos::pair mismatch_index = KE::mismatch(exespace, KE::begin(a), KE::end(a), KE::begin(b), KE::end(b), p); + + // assuming OpenMP is enabled, then you can also explicitly call + // To run explicitly on the Host, (assuming a and b are accessible on Host) + + Kokkos::pair mismatch_index = KE::mismatch(Kokkos::DefaultHostExecutionSpace(), KE::begin(a), KE::end(a), KE::begin(b), KE::end(b), p); + diff --git a/docs/source/API/algorithms/std-algorithms/all/StdSearch.md b/docs/source/API/algorithms/std-algorithms/all/StdSearch.md deleted file mode 100644 index 1574f560d..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdSearch.md +++ /dev/null @@ -1,78 +0,0 @@ - -# `search` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -IteratorType1 search(const ExecutionSpace& exespace, IteratorType1 first, - IteratorType1 last, IteratorType2 s_first, (1) - IteratorType2 s_last); - -template -IteratorType1 search(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first, IteratorType1 last, (2) - IteratorType2 s_first, IteratorType2 s_last); - -template -auto search(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (3) - const ::Kokkos::View& s_view); - -template -auto search(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (4) - const ::Kokkos::View& s_view); - -// overload set 2: binary predicate passed -template -IteratorType1 search(const ExecutionSpace& exespace, IteratorType1 first, (5) - IteratorType1 last, IteratorType2 s_first, - IteratorType2 s_last, const BinaryPredicateType& pred); - -template -IteratorType1 search(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first, IteratorType1 last, (6) - IteratorType2 s_first, IteratorType2 s_last, - const BinaryPredicateType& pred); - -template -auto search(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (7) - const ::Kokkos::View& s_view, - const BinaryPredicateType& pred); - -template -auto search(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (8) - const ::Kokkos::View& s_view, - const BinaryPredicateType& pred) - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Searches for the first occurrence of the sequence of elements `[s_first, s_last)` in the range `[first, last)` in (1,2,5,6). -Searches for the first occurrence of the sequence of elements `s_view` in `view` in (3,4,7,8). -Elements in (1,2,3,4) are compared using `==` and elements in (5,6,7,8) are compared using `pred`. - -## Parameters and Requirements - -- `exespace`, `s_first`, `s_last`, `first`, `last`, `s_view` and `view` similar to [`mismatch`](./StdMismatch). - -- `label`: - - 1,5: The default string is "Kokkos::search_iterator_api_default". - - 3,7: The default string is "Kokkos::search_view_api_default". - -- `pred` - similar to [`equal`](./StdEqual) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdSearch.rst b/docs/source/API/algorithms/std-algorithms/all/StdSearch.rst new file mode 100644 index 000000000..0ea9b42f9 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdSearch.rst @@ -0,0 +1,184 @@ + +``search`` +========== + +Header: ```` + +Description +----------- + +Searches in a range or a ``View`` for the first occurrence of a target sequence of elements. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + IteratorType1 search(const ExecutionSpace& exespace, (1) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + IteratorType1 search(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + auto search(const ExecutionSpace& exespace, (3) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + template + auto search(const std::string& label, const ExecutionSpace& exespace, (4) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + // overload set 2: binary predicate passed + template + IteratorType1 search(const ExecutionSpace& exespace, (5) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + IteratorType1 search(const std::string& label, const ExecutionSpace& exespace, (6) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + auto search(const ExecutionSpace& exespace, (7) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + + template + auto search(const std::string& label, const ExecutionSpace& exespace, (8) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred) + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + IteratorType1 search(const TeamHandleType& teamHandle, (9) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + KOKKOS_FUNCTION + auto search(const TeamHandleType& teamHandle, (10) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + // overload set 2: binary predicate passed + template + KOKKOS_FUNCTION + IteratorType1 search(const TeamHandleType& teamHandle, (11) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + KOKKOS_FUNCTION + auto search(const TeamHandleType& teamHandle, (12) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + + +Detailed Description +~~~~~~~~~~~~~~~~~~~~ + +- 1,2,5,6,9,11: Searches for the first occurrence of the sequence of elements ``[s_first, s_last)`` in the range ``[first, last)`` + +- 3,4,7,8,10,12: Searches for the first occurrence of the sequence of elements ``s_view`` in ``view`` + +Elements are compared using ``pred`` (where accepted), otherwise via ``operator ==``. + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1,5: The default string is "Kokkos::search_iterator_api_default". + + - 3,7: The default string is "Kokkos::search_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., returned from ``Kokkos::Experimental::(c)begin/(c)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 + +- ``s_first, s_last``: range of elements that you want to search for + + - same requirements as ``first, last`` + +- ``view``, ``s_view``: views to search in and for, respectively + + - 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 + +- ``pred``: *binary* functor returning ``true`` if two arguments should be considered "equal". + + ``pred(a,b)`` 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 pair of arguments ``a,b`` of type ``ValueType1`` and ``ValueType2``, + respectively, where ``ValueType1`` and ``ValueType{1,2}`` are the value types of + ``IteratorType{1,2}`` or ``(s_)view``, and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + template + struct IsEqualFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + }; + + +Return Value +~~~~~~~~~~~~ + +- for overloads accepting iterators: returns a ``IteratorType1`` instance pointing to the beginning + of the sequence ``[s_first, s_last)`` in the range ``[first, last)``, or ``last`` if no such element is found. + If the sequence ``[s_first, s_last)`` is empty, ``first`` is returend. + +- for overloads accepting Views: returns a Kokkos iterator to the first element in ``view`` that marks the beginning of ``s_view`` + or ``Kokkos::Experimental::end(view)`` if no such element is found. + If the sequence ``[s_first, s_last)`` is empty, ``Kokkos::Experimental::begin(view)`` is returend. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdSearchN.md b/docs/source/API/algorithms/std-algorithms/all/StdSearchN.md deleted file mode 100644 index a06bd62d9..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdSearchN.md +++ /dev/null @@ -1,80 +0,0 @@ - -# `search_n` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -IteratorType search_n(const ExecutionSpace& exespace, IteratorType first, - IteratorType last, SizeType count, (1) - const ValueType& value); - -template -IteratorType search_n(const std::string& label, const ExecutionSpace& exespace, - IteratorType first, IteratorType last, SizeType count, (2) - const ValueType& value); - -template -auto search_n(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (3) - SizeType count, const ValueType& value); - -template -auto search_n(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (4) - SizeType count, const ValueType& value); - -// overload set 2: binary predicate passed -template -IteratorType search_n(const ExecutionSpace& exespace, IteratorType first, - IteratorType last, SizeType count, const ValueType& value, (5) - const BinaryPredicateType& pred); - -template -IteratorType search_n(const std::string& label, const ExecutionSpace& exespace, - IteratorType first, IteratorType last, SizeType count, (6) - const ValueType& value, const BinaryPredicateType& pred); - -template -auto search_n(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (7) - SizeType count, const ValueType& value, - const BinaryPredicateType& pred); - -template -auto search_n(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (8) - SizeType count, const ValueType& value, - const BinaryPredicateType& pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Searches the range [first, last) for a range of `count` elements each comparing equal to `value` (1,2). -Searches the `view` for `count` elements each comparing equal to `value` (3,4). -Searches the range [first, last) for a range of `count` elements for which the `pred` returns true for `value` in (5,6). -Searches the `view` for a range of `count` elements for which the `pred` returns true for `value` in (7,8). - -## Parameters and Requirements - -- `exespace`, `first`, `last`, `view` and `count` similar to [`for_each_n`](./StdForEachN). - -- `label`: - - 1,5: The default string is "Kokkos::search_n_iterator_api_default". - - 3,7: The default string is "Kokkos::search_n_view_api_default". - -- `pred` - similar to [`equal`](./StdEqual) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdSearchN.rst b/docs/source/API/algorithms/std-algorithms/all/StdSearchN.rst new file mode 100644 index 000000000..3d8c6bb75 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdSearchN.rst @@ -0,0 +1,173 @@ + +``search_n`` +============ + +Header: ```` + +Description +----------- + +Searches a range or a ``View`` for the first sequence of ``count`` identical elements each equal to the given value. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + IteratorType search_n(const ExecutionSpace& exespace, IteratorType first, + IteratorType last, SizeType count, (1) + const ValueType& value); + + template + IteratorType search_n(const std::string& label, const ExecutionSpace& exespace, + IteratorType first, IteratorType last, SizeType count, (2) + const ValueType& value); + + template + auto search_n(const ExecutionSpace& exespace, + const ::Kokkos::View& view, (3) + SizeType count, const ValueType& value); + + template + auto search_n(const std::string& label, const ExecutionSpace& exespace, + const ::Kokkos::View& view, (4) + SizeType count, const ValueType& value); + + // overload set 2: binary predicate passed + template + IteratorType search_n(const ExecutionSpace& exespace, IteratorType first, + IteratorType last, SizeType count, const ValueType& value, (5) + const BinaryPredicateType& pred); + + template + IteratorType search_n(const std::string& label, const ExecutionSpace& exespace, + IteratorType first, IteratorType last, SizeType count, (6) + const ValueType& value, const BinaryPredicateType& pred); + + template + auto search_n(const ExecutionSpace& exespace, + const ::Kokkos::View& view, (7) + SizeType count, const ValueType& value, + const BinaryPredicateType& pred); + + template + auto search_n(const std::string& label, const ExecutionSpace& exespace, + const ::Kokkos::View& view, (8) + SizeType count, const ValueType& value, + const BinaryPredicateType& pred); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + IteratorType search_n(const TeamHandleType& teamHandle, IteratorType first, + IteratorType last, SizeType count, (9) + const ValueType& value); + + template + KOKKOS_FUNCTION + auto search_n(const TeamHandleType& teamHandle, + const ::Kokkos::View& view, (10) + SizeType count, const ValueType& value); + + // overload set 2: binary predicate passed + template + KOKKOS_FUNCTION + IteratorType search_n(const TeamHandleType& teamHandle, IteratorType first, + IteratorType last, SizeType count, const ValueType& value, (11) + const BinaryPredicateType& pred); + + template + KOKKOS_FUNCTION + auto search_n(const TeamHandleType& teamHandle, + const ::Kokkos::View& view, (12) + SizeType count, const ValueType& value, + const BinaryPredicateType& pred); + +Detailed Description +~~~~~~~~~~~~~~~~~~~~ + +- Searches the range ``[first, last)`` for a range of ``count`` elements + each comparing equal to ``value`` (1,2,9). + +- Searches the ``view`` for ``count`` elements each comparing equal to ``value`` (3,4,10). + +- Searches the range [first, last) for a range of ``count`` elements + for which the ``pred`` returns true for ``value`` in (5,6,11). + +- Searches the ``view`` for a range of ``count`` elements for which + the ``pred`` returns true for ``value`` in (7,8,12). + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1,5: The default string is "Kokkos::search_n_iterator_api_default". + + - 3,7: The default string is "Kokkos::search_n_view_api_default". + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``n``: number of elements to operate on + +- ``first``: iterator defining the beginning of range + + - must be *random access iterator* + + - ``[first, first+count)`` must represent a valid range + + - 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`` or from the execution space associated with the team handle + +- ``pred``: *binary* functor returning ``true`` if two arguments should be considered "equal". + + ``pred(a,b)`` 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 pair of arguments ``a,b`` of type ``ValueType1`` and ``ValueType``, + respectively, where ``ValueType1`` is the value type of ``IteratorType`` or ``view``, + and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + template + struct IsEqualFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + };