Skip to content

Commit

Permalink
wip, need to do more checking
Browse files Browse the repository at this point in the history
  • Loading branch information
@fnrizzi
fnrizzi committed Dec 10, 2023
1 parent e4cca33 commit cbbb67c
Show file tree
Hide file tree
Showing 6 changed files with 235 additions and 158 deletions.
66 changes: 38 additions & 28 deletions docs/source/API/algorithms/std-algorithms/all/StdCopy.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,23 @@
``copy``
========

Header: `<Kokkos_StdAlgorithms.hpp>`
Header: ``<Kokkos_StdAlgorithms.hpp>``

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 <class ExecutionSpace, class InputIteratorType, class OutputIteratorType>
OutputIteratorType copy(const ExecutionSpace& exespace, (1)
InputIteratorType first_from,
Expand Down Expand Up @@ -49,16 +47,22 @@ Interface
const Kokkos::View<DataType1, Properties1...>& view_from,
const Kokkos::View<DataType2, Properties2...>& view_to);
//
// overload set accepting a team handle
//
Overload set accepting a team handle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 4.2

.. code-block:: cpp
template <class TeamHandleType, class InputIterator, class OutputIterator>
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<DataType1, Properties1...>& source,
Expand All @@ -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
~~~~~~~~~~~~
Expand Down
69 changes: 41 additions & 28 deletions docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,25 @@
``copy_backward``
=================

Header: `<Kokkos_StdAlgorithms.hpp>`
Header: ``<Kokkos_StdAlgorithms.hpp>``

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 <class ExecutionSpace, class InputIteratorType, class OutputIteratorType>
OutputIteratorType copy_backward(const ExecutionSpace& exespace, (1)
InputIteratorType first_from,
Expand Down Expand Up @@ -53,17 +52,23 @@ Interface
const Kokkos::View<DataType1, Properties1...>& view_from,
const Kokkos::View<DataType2, Properties2...>& view_to);
//
// overload set accepting a team handle
//
Overload set accepting a team handle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 4.2

.. code-block:: cpp
template <class TeamHandleType, class IteratorType1, class IteratorType2>
KOKKOS_FUNCTION
IteratorType2 copy_backward(const TeamHandleType& teamHandle, (5)
IteratorType1 first,
IteratorType1 last, IteratorType2 d_last);
template <
class TeamHandleType, class DataType1, class... Properties1,
class DataType2, class... Properties2>
KOKKOS_FUNCTION
auto copy_backward( (6)
const TeamHandleType& teamHandle,
const ::Kokkos::View<DataType1, Properties1...>& source,
Expand All @@ -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
~~~~~~~~~~~~
Expand Down
67 changes: 44 additions & 23 deletions docs/source/API/algorithms/std-algorithms/all/StdCopyIf.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,24 @@
``copy_if``
===========

Header: `<Kokkos_StdAlgorithms.hpp>`
Header: ``<Kokkos_StdAlgorithms.hpp>``

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
>
Expand Down Expand Up @@ -62,17 +61,24 @@ Interface
const Kokkos::View<DataType2, Properties2...>& view_to,
UnaryPredicateType pred);
//
// overload set accepting a team handle
//
Overload set accepting a team handle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 4.2

.. code-block:: cpp
template <class TeamHandleType, class InputIterator, class Size,
class OutputIterator>
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<DataType1, Properties1...>& source, Size count,
Expand All @@ -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
Expand Down
Loading

0 comments on commit cbbb67c

Please sign in to comment.