diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst index aae40206d..72a68942f 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopy.rst @@ -2,25 +2,23 @@ ``copy`` ======== -Header: `` +Header: ```` Description ----------- -Copies the elements from range `[first_from, last_from)` to another -range beginning at `first_to` (overloads 1,2,5) or from -a source view `view_from` to a destination view `view_to` (overloads 3,4,6). +Copies the elements from a source range or rank-1 ``View`` to destination range or rank-1 ``View``. Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting an execution space - // template OutputIteratorType copy(const ExecutionSpace& exespace, (1) InputIteratorType first_from, @@ -49,16 +47,22 @@ Interface const Kokkos::View& view_from, const Kokkos::View& view_to); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template + KOKKOS_FUNCTION OutputIterator copy(const TeamHandleType& teamHandle, InputIterator first, (5) InputIterator last, OutputIterator d_first); template < class TeamHandleType, class DataType1, class... Properties1, class DataType2, class... Properties2> + KOKKOS_FUNCTION auto copy( (6) const TeamHandleType& teamHandle, const ::Kokkos::View& source, @@ -68,29 +72,35 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `exespace`: - - execution space instance -- `teamHandle`: - - team handle instance given inside a parallel region when using a TeamPolicy -- `label`: - - used to name the implementation kernels for debugging purposes +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + - for 1, the default string is: "Kokkos::copy_iterator_api_default" + - for 3, the default string is: "Kokkos::copy_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally -- `first_from, last_from`: - - range of elements to copy from + +- ``first_from, last_from``: range of elements to copy from + - must be *random access iterators* - - must represent a valid range, i.e., `last_from >= first_from` (checked in debug mode) - - must be accessible from `exespace` -- `first_to`: - - beginning of the range to copy to - - must be a *random access iterator* - - must be accessible from `exespace` -- `view_from`, `view_to`: - - source and destination views to copy elements from and to - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` + - must represent a valid range, i.e., ``last_from >= first_from`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``first_to``: beginning of the range to copy to + + - must be a *random access iterator* and must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view_from``, ``view_to``: source and destination views to copy elements from and to + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle Return Value ~~~~~~~~~~~~ diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst index 3b6d0237d..be38c708b 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst @@ -2,26 +2,25 @@ ``copy_backward`` ================= -Header: `` +Header: ```` Description ----------- -Copies the elements in reverse order from range `[first_from, last_from)` to another -range *ending* at `last_to` (overloads 1,2,5) or from -a source view `view_from` to a destination view `view_to` (overloads 3,4,6). -The relative order is preserved. +Copies the elements in reverse order from range ``[first_from, last_from)`` to another +range *ending* at ``last_to`` or from a source view ``view_from`` to a destination +view ``view_to``. The relative order is preserved. Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting an execution space - // template OutputIteratorType copy_backward(const ExecutionSpace& exespace, (1) InputIteratorType first_from, @@ -53,10 +52,15 @@ Interface const Kokkos::View& view_from, const Kokkos::View& view_to); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template + KOKKOS_FUNCTION IteratorType2 copy_backward(const TeamHandleType& teamHandle, (5) IteratorType1 first, IteratorType1 last, IteratorType2 d_last); @@ -64,6 +68,7 @@ Interface template < class TeamHandleType, class DataType1, class... Properties1, class DataType2, class... Properties2> + KOKKOS_FUNCTION auto copy_backward( (6) const TeamHandleType& teamHandle, const ::Kokkos::View& source, @@ -72,29 +77,37 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `exespace`: - - execution space instance -- `teamHandle`: - - team handle instance given inside a parallel region when using a TeamPolicy -- `label`: - - used to name the implementation kernels for debugging purposes +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + - for 1, the default string is: "Kokkos::copy_backward_iterator_api_default" + - for 3, the default string is: "Kokkos::copy_backward_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally -- `first_from, last_from`: - - range of elements to copy from + +- ``first_from, last_from``: range of elements to copy from + - must be *random access iterators* - - must represent a valid range, i.e., `last_from >= first_from` (checked in debug mode) - - must be accessible from `exespace` -- `last_to`: - - iterator past the last element of the range to copy to + + - must represent a valid range, i.e., ``last_from >= first_from`` (checked in debug mode) + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``last_to``: iterator past the last element of the range to copy to + - must be a *random access iterator* - - must be accessible from `exespace` -- `view_from`, `view_to`: - - source and destination views to copy elements from and to - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view_from``, ``view_to``: source and destination views to copy elements from and to + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle Return Value ~~~~~~~~~~~~ diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst index aff175196..f0f26935d 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst @@ -2,25 +2,24 @@ ``copy_if`` =========== -Header: `` +Header: ```` Description ----------- -Copies the elements for which `pred` returns `true` from range `[first_from, last_from)` -to another range beginning at `first_to` (overloads 1,2,5) or from `view_from` to `view_to` -(overloads 3,4,6). +Copies the elements for which a predicate returns ``true`` from source range or ``View`` to +another range or ``View`` Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting an execution space - // template < class ExecutionSpace, class InputIteratorType, class OutputIteratorType, class UnaryPredicateType > @@ -62,17 +61,24 @@ Interface const Kokkos::View& view_to, UnaryPredicateType pred); - // - // overload set accepting a team handle - // + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template + KOKKOS_FUNCTION OutputIterator copy_n(const TeamHandleType& teamHandle, InputIterator first, (5) Size count, OutputIterator result); template < class TeamHandleType, class DataType1, class... Properties1, class Size, class DataType2, class... Properties2> + KOKKOS_FUNCTION auto copy_n( (6) const TeamHandleType& teamHandle, const ::Kokkos::View& source, Size count, @@ -82,21 +88,36 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `exespace`, `first_from`, `last_from`, `first_to`, `view_from`, `view_to`: - - same as in [`copy`](./StdCopy) -- `teamHandle`: - - team handle instance given inside a parallel region when using a TeamPolicy - - NOTE: overloads accepting a team handle do not use a label internally -- `label`: +- ``exespace``, ``teamHandle``, ``first_from``, ``last_from``, ``first_to``, ``view_from``, ``view_to``: + - same as in [``copy``](./StdCopy) + +- ``label``: + - for 1, the default string is: "Kokkos::copy_if_iterator_api_default" + - for 3, the default string is: "Kokkos::copy_if_view_api_default" -- `pred`: - - unary predicate which returns `true` for the required element; `pred(v)` - must be valid to be called from the execution space passed, and convertible to bool for every - argument `v` of type (possible const) `value_type`, where `value_type` - is the value type of `InputIteratorType` (for 1,2) or of `view_from` (for 3,4), - and must not modify `v`. - - should have the same API as the unary predicate in [`replace_if`](./StdReplaceIf) + +- ``pred``: unary predicate which returns ``true`` for the required element to copy + + - ``pred(v)`` must be valid to be called from the execution space passed or the execution + space associated with the team handle, and convertible to bool for every + argument ``v`` of type (possible const) ``value_type``, where ``value_type`` + is the value type of ``InputIteratorType`` or of ``view_from``, and must not modify ``v``. + + - must conform to: + + .. code-block:: cpp + + struct Predicate + { + KOKKOS_INLINE_FUNCTION + bool operator()(const value_type & v) const { return /* ... */; } + + // or, also valid + + KOKKOS_INLINE_FUNCTION + bool operator()(value_type v) const { return /* ... */; } + }; Return Value diff --git a/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst b/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst index d205b3afd..d8fe732ba 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdCopy_n.rst @@ -1,25 +1,23 @@ ``copy_n`` ========== -Header: `` +Header: ```` Description ----------- -Copies the first `n` elements starting at `first_from` to -another range starting at `first_to` (overloads 1,2,5) or the first `n` elements -from `view_from` to `view_to` (overloads 3,4,6). +Copies the first ``n`` elements from a source range or ``View`` to another range or ``View`` Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting an execution space - // template OutputIteratorType copy_n(const ExecutionSpace& exespace, (1) InputIteratorType first_from, @@ -55,17 +53,23 @@ Interface SizeType n, const Kokkos::View& view_to); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template + KOKKOS_FUNCTION OutputIterator copy_n(const TeamHandleType& teamHandle, InputIterator first, (5) Size count, OutputIterator result); template < class TeamHandleType, class DataType1, class... Properties1, class Size, class DataType2, class... Properties2> + KOKKOS_FUNCTION auto copy_n( (6) const TeamHandleType& teamHandle, const ::Kokkos::View& source, Size count, @@ -75,22 +79,23 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `exespace`, `first_from`, `first_to`, `view_from`, `view_to`: - - same as in [`copy`](./StdCopy) -- `teamHandle`: - - team handle instance given inside a parallel region when using a TeamPolicy - - NOTE: overloads accepting a team handle do not use a label internally -- `label`: - - used to name the implementation kernels for debugging purposes +- ``exespace``, ``teamHandle``, ``first_from``, ``first_to``, ``view_from``, ``view_to``: + - same as in [``copy``](./StdCopy) + +- ``label``: used to name the implementation kernels for debugging purposes + - for 1, the default string is: "Kokkos::copy_n_if_iterator_api_default" + - for 3, the default string is: "Kokkos::copy_n_if_view_api_default" -- `n`: - - number of elements to copy (must be non-negative) + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``n``: number of elements to copy (must be non-negative) Return Value ~~~~~~~~~~~~ -If `n>0`, returns an iterator to the destination element *after* the last element copied. +If ``n>0``, returns an iterator to the destination element *after* the last element copied. -Otherwise, returns `first_to` (for 1,2) or `Kokkos::begin(view_to)` (for 3,4). +Otherwise, returns ``first_to`` (for 1,2,5) or ``Kokkos::begin(view_to)`` (for 3,4,6). diff --git a/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst b/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst index 9304fbd52..afcafbed3 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdGenerate.rst @@ -2,24 +2,24 @@ ``generate`` ============ -Header: `` +Header: ```` Description ----------- -Assigns the value generated by the functor `g` to each elements in the -range `[first, last)` (overloads 1,2,5) or in the `view` (overloads 3,4,6). +Assigns the value generated by the functor ``g`` to each elements in the +range ``[first, last)`` (overloads 1,2,5) or in the ``view`` (overloads 3,4,6). Interface --------- .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting an execution space - // template void generate(const ExecutionSpace& exespace, (1) IteratorType first, IteratorType last, @@ -40,16 +40,22 @@ Interface const Kokkos::View& view, GeneratorType g); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template + KOKKOS_FUNCTION IteratorType generate_n(const TeamHandleType& teamHandle, (5) IteratorType first, Size count, Generator g); template < class TeamHandleType, class DataType, class... Properties, class Size, class Generator> + KOKKOS_FUNCTION auto generate_n( (6) const TeamHandleType& teamHandle, const ::Kokkos::View& view, Size count, @@ -59,28 +65,37 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `exespace`: - - execution space instance -- `teamHandle`: - - team handle instance given inside a parallel region when using a TeamPolicy -- `label`: - - used to name the implementation kernels for debugging purposes +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + - for 1, the default string is: "Kokkos::generate_iterator_api_default" + - for 3, the default string is: "Kokkos::generate_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally -- `first, last`: - - range of elements to modify + +- ``first, last``: range of elements to modify + - must be *random access iterators* - - must represent a valid range, i.e., `last >= first` (checked in debug mode) - - must be accessible from `exespace` -- `view`: - - view to modify - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` -- `g`: - - functor of the following form, where `return_type` must be assignable to - `value_type`, with `value_type` being the value type of `IteratorType` - (for 1,2) or of `view` (for 3,4): + + - must represent a valid range, i.e., ``last >= first`` (checked in debug mode) + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: view to modify + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``g``: + + - functor of the following form, where ``return_type`` must be assignable to + ``value_type``, with ``value_type`` being the value type of ``IteratorType`` + or of ``view``: .. code-block:: cpp diff --git a/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst b/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst index d3d140879..954b00c1a 100644 --- a/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst +++ b/docs/source/API/algorithms/std-algorithms/all/StdTransform.rst @@ -2,23 +2,23 @@ ``transform`` ============= -Header: `` +Header: ```` Description ----------- - Overloads (1,2,9): applies the given *unary* operation to all elements in the -range `[first_from, last_from)` stores the result in the range starting at `first_to` +range ``[first_from, last_from)`` stores the result in the range starting at ``first_to`` - Overloads (3,4,10): applies the given *unary* operation to all elements in -the `source` view and stores the result in the `dest` view. +the ``source`` view and stores the result in the ``dest`` view. - Overloads (5,6,11): applies the given *binary* operation to pair of elements -from the ranges `[first_from1, last_from1)` and `[first_from2, last_from2]` -and stores the result in range starting at `first_to` +from the ranges ``[first_from1, last_from1)`` and ``[first_from2, last_from2]`` +and stores the result in range starting at ``first_to`` - Overloads (7,8,12): applies the given *binary* operation to pair of elements -from the views `source1, source2` and stores the result in `dest` view +from the views ``source1, source2`` and stores the result in ``dest`` view Interface @@ -26,11 +26,12 @@ Interface .. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: cpp - // - // overload set accepting an execution space - // template OutputIterator transform(const ExecutionSpace& exespace, (1) InputIterator first_from, InputIterator last_from, @@ -113,11 +114,16 @@ Interface Kokkos::View& dest, BinaryOperation binary_op); - // - // overload set accepting a team handle - // +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + template + KOKKOS_FUNCTION OutputIterator transform(const TeamHandleType& teamHandle, (9) InputIterator first1, InputIterator last1, OutputIterator d_first, @@ -126,6 +132,7 @@ Interface template < class TeamHandleType, class DataType1, class... Properties1, class DataType2, class... Properties2, class UnaryOperation> + KOKKOS_FUNCTION auto transform( (10) const TeamHandleType& teamHandle, const ::Kokkos::View& source, @@ -133,6 +140,7 @@ Interface template + KOKKOS_FUNCTION OutputIterator transform(const TeamHandleType& teamHandle, (11) InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, OutputIterator d_first, @@ -142,6 +150,7 @@ Interface class TeamHandleType, class DataType1, class... Properties1, class DataType2, class... Properties2, class DataType3, class... Properties3, class BinaryOperation> + KOKKOS_FUNCTION auto transform(const TeamHandleType& teamHandle, (12) const ::Kokkos::View& source1, const ::Kokkos::View& source2, @@ -151,31 +160,35 @@ Interface Parameters and Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `exespace`: - - execution space instance -- `teamHandle`: - - team handle instance given inside a parallel region when using a TeamPolicy -- `label`: - - used to name the implementation kernels for debugging purposes +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: used to name the implementation kernels for debugging purposes + - for 1,3,5,7, the default string is: "Kokkos::transform_iterator_api_default" + - for 2,4,6,8, the default string is: "Kokkos::transform_view_api_default" + - NOTE: overloads accepting a team handle do not use a label internally -- `first_from, last_from, first_from1, first_from2`: - - ranges of elements to tranform + +- ``first_from, last_from, first_from1, first_from2``: ranges of elements to transform + - must be *random access iterators* - - must be valid ranges, i.e., `first_from >= last_from`, `first_from1 >= last_from2` - - must be accessible from `exespace` -- `first_to`: - - beginning of the range to write to + + - must be valid ranges, i.e., ``first_from >= last_from``, ``first_from1 >= last_from2`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``first_to``: beginning of the range to write to + - must be a *random access iterator* - - must be accessible from `exespace` -- `source, source1, source2`: - - source views to transform - - must be accessible from `exespace` -- `dest`: - - destination view to write to - - must be accessible from `exespace` + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``source, source1, source2, dest``: source and destination views + + - must be accessible from ``exespace`` or from the execution space associated with the team handle Return Value ~~~~~~~~~~~~