From d2dde8e455d13d6bd308c0ca406972b746aa03cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcin=20Wr=C3=B3bel?= Date: Wed, 9 Nov 2022 17:42:07 +0100 Subject: [PATCH] #120: - API core view creat_mirror transition from md to rst --- docs/source/API/core/view/create_mirror.md | 190 ---------------- docs/source/API/core/view/create_mirror.rst | 232 ++++++++++++++++++++ 2 files changed, 232 insertions(+), 190 deletions(-) delete mode 100644 docs/source/API/core/view/create_mirror.md create mode 100644 docs/source/API/core/view/create_mirror.rst diff --git a/docs/source/API/core/view/create_mirror.md b/docs/source/API/core/view/create_mirror.md deleted file mode 100644 index 38d938875..000000000 --- a/docs/source/API/core/view/create_mirror.md +++ /dev/null @@ -1,190 +0,0 @@ -# `create_mirror[_view]` - -Header File: `Kokkos_Core.hpp` - -A common desired use case is to have a memory allocation in GPU memory and an identical memory allocation in CPU memory, such that copying from one to another is straightforward. To satisfy this use case and others, Kokkos has facilities for dealing with "mirrors" of View. A "mirror" of a View type `A` is loosely defined a View type `B` such that Views of type `B` are accessible from the CPU and [`deep_copy`](deep_copy) between Views of type `A` and `B` are direct. The most common functions for dealing with mirrors are `create_mirror`, `create_mirror_view` and `create_mirror_view_and_copy`. - -Usage: -```c++ -auto host_mirror = create_mirror(a_view); -auto host_mirror_view = create_mirror_view(a_view); - -auto host_mirror_space = create_mirror(ExecSpace(),a_view); -auto host_mirror_view_space = create_mirror_view(ExecSpace(),a_view); -``` - -## Synopsis - -```c++ -template -typename ViewType::HostMirror create_mirror(ViewType const&); - -template -typename ViewType::HostMirror create_mirror(decltype(Kokkos::WithoutInitializing), - ViewType const&); - -template -ImplMirrorType create_mirror(Space const& space, ViewType const&); - -template -ImplMirrorType create_mirror(decltype(Kokkos::WithoutInitializing), - Space const& space, ViewType const&); - -template -auto create_mirror(Impl::ViewCtorProp const& arg_prop, - ViewType const& v); - -template -typename ViewType::HostMirror create_mirror_view(ViewType const&); - -template -typename ViewType::HostMirror create_mirror_view(decltype(Kokkos::WithoutInitializing), - ViewType const&); - -template -ImplMirrorType create_mirror_view(Space const& space, ViewType const&); - -template -ImplMirrorType create_mirror_view(decltype(Kokkos::WithoutInitializing), - Space const& space, ViewType const&); - -template -auto create_mirror_view(Impl::ViewCtorProp const& arg_prop, - ViewType const& v); - -template -ImplMirrorType create_mirror_view_and_copy(Space const& space, ViewType const&); - -template -auto create_mirror_view_and_copy(Impl::ViewCtorProp const& arg_prop, - ViewType const& v); -``` - - -## Description - -* ```c++ - template - typename ViewType::HostMirror create_mirror(ViewType const& src); - ``` - Creates a new host accessible [`View`](view) with the same layout and padding as `src`. - * `src`: a `Kokkos::View`. - -* ```c++ - template - typename ViewType::HostMirror create_mirror(decltype(Kokkos::WithoutInitializing), - ViewType const& src); - ``` - Creates a new host accessible [`View`](view) with the same layout and padding as `src`. The new view will have uninitialized data. - * `src`: a `Kokkos::View`. - -* ```c++ - template - ImplMirrorType create_mirror(Space const& space, ViewType const&); - ``` - Creates a new [`View`](view) with the same layout and padding as `src` but with a device type of `Space::device_type`. - * `src`: a `Kokkos::View`. - * `Space`: a class meeting the requirements of [`ExecutionSpaceConcept`](ExecutionSpaceConcept) or [`MemorySpaceConcept`](MemorySpaceConcept) - * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. - -* ```c++ - template - ImplMirrorType create_mirror(decltype(Kokkos::WithoutInitializing), - Space const& space, ViewType const&); - ``` - Creates a new [`View`](view) with the same layout and padding as `src` but with a device type of `Space::device_type`. The new view will have uninitialized data. - * `src`: a `Kokkos::View`. - * `Space`: a class meeting the requirements of [`ExecutionSpaceConcept`](ExecutionSpaceConcept) or [`MemorySpaceConcept`](MemorySpaceConcept) - * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. - -* ```c++ - template - auto create_mirror(Impl::ViewCtorProp const& arg_prop, - ViewType const& v); - ``` - Creates a new [`View`](view) with the same layout and padding as `src` using the [`View`](view) constructor properties `arg_prop`, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. If `arg_prop` contains a memory space, a [`View`](view) in that space is created. Otherwise, a [`View`](view) in host-accessible memory is returned. - * `src`: a `Kokkos::View`. - * `arg_prop`: [`View`](view) constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. - - Restrictions: - * `arg_prop` must not include a pointer to memory, or a label, or allow padding. - -* ```c++ - template - typename ViewType::HostMirror create_mirror_view(ViewType const& src); - ``` - If `src` is not host accessible (i.e. if `SpaceAccessibility::accessible` is `false`) - it creates a new host accessible [`View`](view) with the same layout and padding as `src`. Otherwise returns `src`. - * `src`: a `Kokkos::View`. - -* ```c++ - template - typename ViewType::HostMirror create_mirror_view(decltype(Kokkos::WithoutInitializing), - ViewType const& src); - ``` - If `src` is not host accessible (i.e. if `SpaceAccessibility::accessible` is `false`) - it creates a new host accessible [`View`](view) with the same layout and padding as `src`. The new view will have uninitialized data. Otherwise returns `src`. - * `src`: a `Kokkos::View`. - -* ```c++ - template - ImplMirrorType create_mirror_view(Space const& space, ViewType const&); - ``` - If `std::is_same::value` is `false`, - creates a new [`View`](view) with the same layout and padding as `src` but with a device type of `Space::device_type`. - Otherwise returns `src`. - * `src`: a `Kokkos::View`. - * `Space`: a class meeting the requirements of [`ExecutionSpaceConcept`](ExecutionSpaceConcept) or [`MemorySpaceConcept`](MemorySpaceConcept) - * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. - -* ```c++ - template - ImplMirrorType create_mirror_view(decltype(Kokkos::WithoutInitializing), - Space const& space, ViewType const& src); - ``` - If `std::is_same::value` is `false`, - creates a new [`View`](view) with the same layout and padding as `src` but with a device type of `Space::device_type`. The new view will have uninitialized data. - Otherwise returns `src`. - * `src`: a `Kokkos::View`. - * `Space`: a class meeting the requirements of [`ExecutionSpaceConcept`](ExecutionSpaceConcept) or [`MemorySpaceConcept`](MemorySpaceConcept) - * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. - -* ```c++ - template - auto create_mirror_view(Impl::ViewCtorProp const& arg_prop, - ViewType const& src); - ``` - If the [`View`](view) constructor arguments `arg_prop` include a memory space and the memory space doesn't match the memory space of `src`, creates a new [`View`](view) in the specified memory_space. - If the `arg_prop` don't include a memory space and the memory space of `src` is not host-accessible, creates a new host-accessible [`View`](view). - Otherwise, `src` is returned. - If a new [`View`](view) is created, the implicitly called constructor respects `arg_prop` and uses the same layout and padding as `src`. - * `src`: a `Kokkos::View`. - * `arg_prop`: [`View`](view) constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. - - Restrictions: - * `arg_prop` must not include a pointer to memory, or a label, or allow padding. - -* ```c++ - template - ImplMirrorType create_mirror_view_and_copy(Space const& space, ViewType const&); - ``` - If `std::is_same::value` is `false`, - creates a new `Kokkos::View` with the same layout and padding as `src` but with a device type of `Space::device_type` and - conducts a `deep_copy` from `src` to the new view if one was created. Otherwise returns `src`. - * `src`: a `Kokkos::View`. - * `Space`: a class meeting the requirements of [`ExecutionSpaceConcept`](ExecutionSpaceConcept) or [`MemorySpaceConcept`](MemorySpaceConcept) - * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. - -* ```c++ - template - ImplMirrorType create_mirror_view_and_copy(Impl::ViewCtorProp const& arg_prop, - ViewType const& src); - ``` - If the memory space included in the [`View`](view) constructor arguments `arg_prop` matches the memory space of `src`, creates a new [`View`](view) in the specified memory space using `arg_prop` and the same layout andf padding as `src`. Additionally, a `deep_copy` from `src` to the new view is executed (using the execution space contained in `arg_prop` if provided). -Otherwise returns `src`. - * `src`: a `Kokkos::View`. - * `arg_prop`: [`View`](view) constructor properties, e.g., `Kokkos::view_alloc(Kokkos::HostSpace{}, Kokkos::WithoutInitializing)`. - - Restrictions: - * `arg_prop` must not include a pointer to memory, or a label, or allow padding. - * `arg_prop` must include a memory space. diff --git a/docs/source/API/core/view/create_mirror.rst b/docs/source/API/core/view/create_mirror.rst new file mode 100644 index 000000000..e080d29a7 --- /dev/null +++ b/docs/source/API/core/view/create_mirror.rst @@ -0,0 +1,232 @@ +``create_mirror[_view]`` +======================== + +Header File: ``Kokkos_Core.hpp`` + +A common desired use case is to have a memory allocation in GPU memory and an identical memory allocation in CPU memory, such that copying from one to another is straightforward. To satisfy this use case and others, Kokkos has facilities for dealing with "mirrors" of View. A "mirror" of a View type ``A`` is loosely defined a View type ``B`` such that Views of type ``B`` are accessible from the CPU and `deep_copy `_ between Views of type `A` and ``B`` are direct. The most common functions for dealing with mirrors are ``create_mirror`` , ``create_mirror_view`` and ``create_mirror_view_and_copy``. + +Usage: + +.. code-block:: cpp + + auto host_mirror = create_mirror(a_view); + auto host_mirror_view = create_mirror_view(a_view); + + auto host_mirror_space = create_mirror(ExecSpace(),a_view); + auto host_mirror_view_space = create_mirror_view(ExecSpace(),a_view); + +Synopsis +-------- + +.. code-block:: cpp + + template + typename ViewType::HostMirror create_mirror(ViewType const&); + + template + typename ViewType::HostMirror create_mirror(decltype(Kokkos::WithoutInitializing), + ViewType const&); + + template + ImplMirrorType create_mirror(Space const& space, ViewType const&); + + template + ImplMirrorType create_mirror(decltype(Kokkos::WithoutInitializing), + Space const& space, ViewType const&); + + template + auto create_mirror(Impl::ViewCtorProp const& arg_prop, + ViewType const& v); + + template + typename ViewType::HostMirror create_mirror_view(ViewType const&); + + template + typename ViewType::HostMirror create_mirror_view(decltype(Kokkos::WithoutInitializing), + ViewType const&); + + template + ImplMirrorType create_mirror_view(Space const& space, ViewType const&); + + template + ImplMirrorType create_mirror_view(decltype(Kokkos::WithoutInitializing), + Space const& space, ViewType const&); + + template + auto create_mirror_view(Impl::ViewCtorProp const& arg_prop, + ViewType const& v); + + template + ImplMirrorType create_mirror_view_and_copy(Space const& space, ViewType const&); + + template + auto create_mirror_view_and_copy(Impl::ViewCtorProp const& arg_prop, + ViewType const& v); + +Description +----------- + +* + .. code-block:: cpp + + template + typename ViewType::HostMirror create_mirror(ViewType const& src); + + Creates a new host accessible `View `_ with the same layout and padding as ``src``. + + * `src`: a `Kokkos::View`. + +* + .. code-block:: cpp + + template + typename ViewType::HostMirror create_mirror(decltype(Kokkos::WithoutInitializing), + ViewType const& src); + + Creates a new host accessible `View `_ with the same layout and padding as ``src``. The new view will have uninitialized data. + + * `src`: a `Kokkos::View`. + +* + .. code-block:: cpp + + template + ImplMirrorType create_mirror(Space const& space, ViewType const&); + + Creates a new `View `_ with the same layout and padding as ``src`` but with a device type of ``Space::device_type``. + + * `src`: a `Kokkos::View`. + * ``Space`` : a class meeting the requirements of `ExecutionSpaceConcept `_ or `MemorySpaceConcept `_ + * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. + +* + .. code-block:: cpp + + template + ImplMirrorType create_mirror(decltype(Kokkos::WithoutInitializing), + Space const& space, ViewType const&); + + Creates a new `View `_ with the same layout and padding as ``src`` but with a device type of ``Space::device_type``. The new view will have uninitialized data. + + * `src`: a `Kokkos::View`. + * ``Space`` : a class meeting the requirements of `ExecutionSpaceConcept `_ or `MemorySpaceConcept `_ + * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. + +* + .. code-block:: cpp + + template + auto create_mirror(Impl::ViewCtorProp const& arg_prop, + ViewType const& v); + + Creates a new `View `_ with the same layout and padding as ``src`` using the `View `_ constructor properties ``arg_prop`` , e.g., ``Kokkos::view_alloc(Kokkos::WithoutInitializing)``. If ``arg_prop`` contains a memory space, a `View `_ in that space is created. Otherwise, a `View `_ in host-accessible memory is returned. + + * `src`: a `Kokkos::View`. + * `arg_prop`: [`View`](view) constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. + + Restrictions: + + * ``arg_prop`` must not include a pointer to memory, or a label, or allow padding. + +* + .. code-block:: cpp + + template + typename ViewType::HostMirror create_mirror_view(ViewType const& src); + + If ``src`` is not host accessible (i.e. if ``SpaceAccessibility::accessible`` is ``false`` ) + it creates a new host accessible `View `_ with the same layout and padding as ``src``. Otherwise returns ``src``. + + * `src`: a `Kokkos::View`. + +* + .. code-block:: cpp + + template + typename ViewType::HostMirror create_mirror_view(decltype(Kokkos::WithoutInitializing), + ViewType const& src); + + If ``src`` is not host accessible (i.e. if ``SpaceAccessibility::accessible`` is ``false`` ) + it creates a new host accessible `View `_ with the same layout and padding as ``src``. The new view will have uninitialized data. Otherwise returns ``src``. + + * `src`: a `Kokkos::View`. + +* + .. code-block:: cpp + + template + ImplMirrorType create_mirror_view(Space const& space, ViewType const&); + + If ``std::is_same::value`` is ``false`` , + creates a new `View `_ with the same layout and padding as ``src`` but with a device type of ``Space::device_type``. + Otherwise returns ``src``. + + * `src`: a `Kokkos::View`. + * ``Space`` : a class meeting the requirements of `ExecutionSpaceConcept `_ or `MemorySpaceConcept `_ + * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. + +* + .. code-block:: cpp + + template + ImplMirrorType create_mirror_view(decltype(Kokkos::WithoutInitializing), + Space const& space, ViewType const& src); + + If ``std::is_same::value`` is ``false`` , + creates a new `View `_ with the same layout and padding as ``src`` but with a device type of ``Space::device_type``. The new view will have uninitialized data. + Otherwise returns ``src``. + + * `src`: a `Kokkos::View`. + * ``Space`` : a class meeting the requirements of `ExecutionSpaceConcept `_ or `MemorySpaceConcept `_ + * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. + +* + .. code-block:: cpp + + template + auto create_mirror_view(Impl::ViewCtorProp const& arg_prop, + ViewType const& src); + + If the `View `_ constructor arguments ``arg_prop`` include a memory space and the memory space doesn't match the memory space of ``src`` , creates a new `View `_ in the specified memory_space. + If the ``arg_prop`` don't include a memory space and the memory space of ``src`` is not host-accessible, creates a new host-accessible `View `_. + Otherwise, ``src`` is returned. + If a new `View `_ is created, the implicitly called constructor respects ``arg_prop`` and uses the same layout and padding as ``src``. + + * `src`: a `Kokkos::View`. + * `arg_prop`: [`View`](view) constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. + + Restrictions: + + * ``arg_prop`` must not include a pointer to memory, or a label, or allow padding. + +* + .. code-block:: cpp + + template + ImplMirrorType create_mirror_view_and_copy(Space const& space, ViewType const&); + + If ``std::is_same::value`` is ``false`` , + creates a new ``Kokkos::View`` with the same layout and padding as ``src`` but with a device type of ``Space::device_type`` and + conducts a ``deep_copy`` from ``src`` to the new view if one was created. Otherwise returns ``src``. + + * `src`: a `Kokkos::View`. + * ``Space`` : a class meeting the requirements of `ExecutionSpaceConcept `_ or `MemorySpaceConcept `_ + * `ImplMirrorType`: an implementation defined specialization of `Kokkos::View`. + +* + .. code-block:: cpp + + template + ImplMirrorType create_mirror_view_and_copy(Impl::ViewCtorProp const& arg_prop, + ViewType const& src); + + If the memory space included in the `View `_ constructor arguments ``arg_prop`` matches the memory space of ``src`` , creates a new `View `_ in the specified memory space using ``arg_prop`` and the same layout andf padding as ``src``. Additionally, a ``deep_copy`` from ``src`` to the new view is executed (using the execution space contained in ``arg_prop`` if provided). + Otherwise returns ``src``. + + * `src`: a `Kokkos::View`. + * `arg_prop`: [`View`](view) constructor properties, e.g., `Kokkos::view_alloc(Kokkos::HostSpace{}, Kokkos::WithoutInitializing)`. + + Restrictions: + + * ``arg_prop`` must not include a pointer to memory, or a label, or allow padding. + * ``arg_prop`` must include a memory space.