Merge pull request #386 from cz4rs/std-teamlevel-copy

stdalgos (5/10): team-level API, and rst update for release 4.2

docs/source/API/algorithms/std-algorithms/all/StdCopy.rst

@@ -0,0 +1,109 @@
+
+``copy``
+========
+
+Header: ``<Kokkos_StdAlgorithms.hpp>``
+
+Description
+-----------
+
+Copies the elements from a source range or rank-1 ``View`` to a destination range or rank-1 ``View``.
+
+Interface
+---------
+
+.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace.
+
+Overload set accepting execution space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: cpp
+
+  template <class ExecutionSpace, class InputIteratorType, class OutputIteratorType>
+  OutputIteratorType copy(const ExecutionSpace& exespace,                      (1)
+                          InputIteratorType first_from,
+                          InputIteratorType last_from,
+                          OutputIteratorType first_to);
+
+  template <class ExecutionSpace, class InputIteratorType, class OutputIteratorType>
+  OutputIteratorType copy(const std::string& label,                            (2)
+                          const ExecutionSpace& exespace,
+                          InputIteratorType first_from,
+                          InputIteratorType last_from,
+                          OutputIteratorType first_to);
+  template <
+    class ExecutionSpace,
+    class DataType1, class... Properties1,
+    class DataType2, class... Properties2
+  >
+  auto copy(const ExecutionSpace& exespace,                                    (3)
+            const Kokkos::View<DataType1, Properties1...>& view_from,
+            const Kokkos::View<DataType2, Properties2...>& view_to);
+  template <
+    class ExecutionSpace,
+    class DataType1, class... Properties1,
+    class DataType2, class... Properties2
+  >
+  auto copy(const std::string& label, const ExecutionSpace& exespace,          (4)
+            const Kokkos::View<DataType1, Properties1...>& view_from,
+            const Kokkos::View<DataType2, Properties2...>& view_to);
+
+Overload set accepting a team handle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.2
+
+.. code-block:: cpp
+
+  template <class TeamHandleType, class InputIteratorType, class OutputIteratorType>
+  KOKKOS_FUNCTION
+  OutputIteratorType copy(const TeamHandleType& teamHandle,                    (5)
+                          InputIteratorType first_from,
+			  InputIteratorType last_from,
+			  OutputIteratorType first_to);
+
+  template <
+    class TeamHandleType, class DataType1, class... Properties1,
+    class DataType2, class... Properties2>
+  KOKKOS_FUNCTION
+  auto copy(const TeamHandleType& teamHandle,                                  (6)
+            const ::Kokkos::View<DataType1, Properties1...>& view_from,
+            ::Kokkos::View<DataType2, Properties2...>& view_to);
+
+Parameters and Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``exespace``: execution space instance
+
+- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy
+
+- ``label``:  used to name the implementation kernels for debugging purposes
+
+  - for 1, the default string is: "Kokkos::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
+
+  - must be *random access iterators*
+
+  - 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
+~~~~~~~~~~~~
+
+Iterator to the destination element *after* the last element copied.

docs/source/API/algorithms/std-algorithms/all/StdCopyBackward.rst

@@ -0,0 +1,116 @@
+
+``copy_backward``
+=================
+
+Header: ``<Kokkos_StdAlgorithms.hpp>``
+
+Description
+-----------
+
+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
+
+  template <class ExecutionSpace, class InputIteratorType, class OutputIteratorType>
+  OutputIteratorType copy_backward(const ExecutionSpace& exespace,                (1)
+                                   InputIteratorType first_from,
+                                   InputIteratorType last_from,
+                                   OutputIteratorType last_to);
+
+  template <class ExecutionSpace, class InputIteratorType, class OutputIteratorType>
+  OutputIteratorType copy_backward(const std::string& label,
+                                   const ExecutionSpace& exespace,                (2)
+                                   InputIteratorType first_from,
+                                   InputIteratorType last_from,
+                                   OutputIteratorType last_to);
+
+  template <
+    class ExecutionSpace,
+    class DataType1, class... Properties1,
+    class DataType2, class... Properties2
+  >
+  auto copy_backward(const ExecutionSpace& exespace,                              (3)
+                     const Kokkos::View<DataType1, Properties1...>& view_from,
+                     const Kokkos::View<DataType2, Properties2...>& view_to);
+
+  template <
+    class ExecutionSpace,
+    class DataType1, class... Properties1,
+    class DataType2, class... Properties2
+  >
+  auto copy_backward(const std::string& label, const ExecutionSpace& exespace,    (4)
+                     const Kokkos::View<DataType1, Properties1...>& view_from,
+                     const Kokkos::View<DataType2, Properties2...>& view_to);
+
+Overload set accepting a team handle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.2
+
+.. code-block:: cpp
+
+  template <class TeamHandleType, class InputIteratorType, class OutputIteratorType>
+  KOKKOS_FUNCTION
+  OutputIteratorType copy_backward(const TeamHandleType& teamHandle,             (5)
+                                   InputIteratorType first_from,
+                                   InputIteratorType last_from,
+			           OutputIteratorType last_to);
+
+  template <
+    class TeamHandleType,
+    class DataType1, class... Properties1,
+    class DataType2, class... Properties2>
+  KOKKOS_FUNCTION
+  auto copy_backward(const TeamHandleType& teamHandle,                           (6)
+                     const ::Kokkos::View<DataType1, Properties1...>& view_from,
+                     ::Kokkos::View<DataType2, Properties2...>& view_to);
+
+Parameters and Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ``exespace``: execution space instance
+
+- ``teamHandle``:  team handle instance given inside a parallel region when using a TeamPolicy
+
+- ``label``: used to name the implementation kernels for debugging purposes
+
+  - for 1, the default string is: "Kokkos::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
+
+  - must be *random access iterators*
+
+  - must represent a valid range, i.e., ``last_from >= first_from`` (checked in debug mode)
+
+  - must be accessible from ``exespace`` or from the execution space associated with the team handle
+
+- ``last_to``: iterator past the last element of the range to copy to
+
+  - must be a *random access iterator*
+
+  - must be accessible from ``exespace`` or from the execution space associated with the team handle
+
+- ``view_from``, ``view_to``: source and destination views 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
+~~~~~~~~~~~~
+
+Iterator to the last element copied.