From 9f4a9e1dbbdefcb8dd27b75e1fb44e6b1089a038 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcin=20Wr=C3=B3bel?= Date: Fri, 26 Aug 2022 09:04:11 +0200 Subject: [PATCH] #120: - API/core/view/subview transition from .md to .rst --- docs/source/API/core/view/subview.md | 74 ---------------------- docs/source/API/core/view/subview.rst | 91 +++++++++++++++++++++++++++ 2 files changed, 91 insertions(+), 74 deletions(-) delete mode 100644 docs/source/API/core/view/subview.md create mode 100644 docs/source/API/core/view/subview.rst diff --git a/docs/source/API/core/view/subview.md b/docs/source/API/core/view/subview.md deleted file mode 100644 index 2b12bdd64..000000000 --- a/docs/source/API/core/view/subview.md +++ /dev/null @@ -1,74 +0,0 @@ -# `subview` - -Header File: `Kokkos_Core.hpp` - -Usage: -```c++ -auto s = subview(view,std::pair(5,191),Kokkos::ALL,1); -``` - -Creates a `Kokkos::View` viewing a subset of another `Kokkos::View`. - -## Synopsis - -```c++ -template -IMPL_DETAIL subview(const ViewType& v, Args ... args); -``` - -## Description - -* ```c++ - template - IMPL_DETAIL subview(const ViewType& v, Args ... args); - ``` - Returns a new `Kokkos::View` `s` viewing a subset of `v` specified by `args...`. - The return type of subview is an implementation detail and is determined by - the types in `Args...`. - - Subset selection: - * For every integer argument in `args...` the rank of the returned view is - one smaller than the rank of `v` and the values referenced by `s` correspond to - the values associated with using the integer argument in the corresponding - position during indexing into `v`. - * Passing [`Kokkos::ALL`](KokkosALL) as the `r`th argument is equivalent to passing - `pair(0,v.extent(r))` as the `r`th argument. - * If the `r`th argument `arg_r` is the `d`th range (`std::pair`, `Kokkos::pair` or - [`Kokkos::ALL`](KokkosALL)) in the argument list than `s.extent(d) = arg_r.second-arg_r.first`, - and dimension `d` of `s` references the range `[arg_r.first,arg_r.second)` of - dimension `r` of `v`. - - Restrictions: - * `sizeof...(args)` is equal to `ViewType::rank`. - * Valid arguments are of type: - * `std::pair` with `std::is_integral::value` being true. - * `Kokkos::pair` with `std::is_integral::value` being true. - * `iType` with `std::is_integral::value` being true. - * `decltype(`[`Kokkos::ALL`](KokkosALL)`)` - * If the `r`th argument `arg_r` is of type `std::pair` or `Kokkos::pair` it must meet: - * `arg_r.first >= 0` - * `arg_r.second <= v.extent(r)` - * `arg_r.first <= arg_r.second` - * If the `r`th argument `arg_r` is an integral it must meet: - * `arg_r >= 0` - * `arg_r < v.extent(r)` - -## Examples - -```c++ -Kokkos::View a("A",N0,N1,N2); - -auto s = Kokkos::subview(a, - std::pair(3,15), - 5, - Kokkos::ALL, - Kokkos::ALL); -for(int i0 = 0; i0 < s.extent(0); i0++) -for(int i1 = 0; i1 < s.extent(1); i1++) -for(int i2 = 0; i2 < s.extent(2); i2++) { - assert(s(i0,i1,i2) == a(i0+3,5,i1,i2)); -} - -auto s3415 = Kokkos::subview(a,3,4,1,5); -assert(s3415() == a(3,4,1,5)); -``` diff --git a/docs/source/API/core/view/subview.rst b/docs/source/API/core/view/subview.rst new file mode 100644 index 000000000..3aa930ab4 --- /dev/null +++ b/docs/source/API/core/view/subview.rst @@ -0,0 +1,91 @@ +``subview`` +=========== + +.. role:: cpp(code) + :language: cpp + +Header File: ``Kokkos_Core.hpp`` + +Usage: + +.. code-block:: cpp + + auto s = subview(view,std::pair(5,191),Kokkos::ALL,1); + +Creates a ``Kokkos::View`` viewing a subset of another ``Kokkos::View``. + +Synopsis +-------- + +.. code-block:: cpp + + template + IMPL_DETAIL subview(const ViewType& v, Args ... args); + +Description +----------- + +* + .. code-block:: cpp + + template + IMPL_DETAIL subview(const ViewType& v, Args ... args); + + Returns a new ``Kokkos::View`` ``s`` viewing a subset of ``v`` specified by ``args...``. + The return type of subview is an implementation detail and is determined by + the types in ``Args...``. + + .. rubric:: Subset selection: + + * For every integer argument in ``args...`` the rank of the returned view is + one smaller than the rank of ``v`` and the values referenced by ``s`` correspond to + the values associated with using the integer argument in the corresponding + position during indexing into ``v``. + * Passing `Kokkos::ALL <../utilities/all.html#kokkosall>`_ as the ``r``\ th argument is equivalent to passing + ``pair(0,v.extent(r))`` as the ``r``\ th argument. + * If the ``r``\ th argument ``arg_r`` is the ``d``\ th range (\ ``std::pair``\ , ``Kokkos::pair`` or + `Kokkos::ALL <../utilities/all.html#kokkosall>`_ ) in the argument list than ``s.extent(d) = arg_r.second-arg_r.first``\ , + and dimension ``d`` of ``s`` references the range ``[arg_r.first,arg_r.second)`` of + dimension ``r`` of ``v``. + + .. rubric:: Restrictions: + + * ``sizeof...(args)`` is equal to ``ViewType::rank``. + * Valid arguments are of type: + + * ``std::pair`` with ``std::is_integral::value`` being true. + * ``Kokkos::pair`` with ``std::is_integral::value`` being true. + * ``iType`` with ``std::is_integral::value`` being true. + * ``decltype(``\ `Kokkos::ALL <../utilities/all.html#kokkosall>`_ ``)`` + + * If the ``r``\ th argument ``arg_r`` is of type ``std::pair`` or ``Kokkos::pair`` it must meet: + + * ``arg_r.first >= 0`` + * ``arg_r.second <= v.extent(r)`` + * ``arg_r.first <= arg_r.second`` + + * If the ``r``\ th argument ``arg_r`` is an integral it must meet: + + * ``arg_r >= 0`` + * ``arg_r < v.extent(r)`` + +Examples +-------- + +.. code-block:: cpp + + Kokkos::View a("A",N0,N1,N2); + + auto s = Kokkos::subview(a, + std::pair(3,15), + 5, + Kokkos::ALL, + Kokkos::ALL); + for(int i0 = 0; i0 < s.extent(0); i0++) + for(int i1 = 0; i1 < s.extent(1); i1++) + for(int i2 = 0; i2 < s.extent(2); i2++) { + assert(s(i0,i1,i2) == a(i0+3,5,i1,i2)); + } + + auto s3415 = Kokkos::subview(a,3,4,1,5); + assert(s3415() == a(3,4,1,5));