From eba5ba8212e4bbe3c68e577626ffe3468b482fab Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 9 May 2024 15:08:36 -0500 Subject: [PATCH 1/8] Cleanup of RangePolicy Get rid of extraneous inline, const, etc. Fix parameters passed to ctors Fix return type of set_chunk_size() --- docs/source/API/core/policies/RangePolicy.rst | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index 31a2a4811..15b4ca13f 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -26,7 +26,7 @@ Synopsis template class Kokkos::RangePolicy { typedef RangePolicy execution_policy; - typedef typename traits::index_type member_type ; + typedef typename traits::index_type member_type; typedef typename traits::index_type index_type; //Inherited from PolicyTraits @@ -41,23 +41,23 @@ Synopsis RangePolicy(const RangePolicy&) = default; RangePolicy(RangePolicy&&) = default; - inline RangePolicy(); + RangePolicy(); template - inline RangePolicy( const execution_space & work_space - , const member_type work_begin - , const member_type work_end - , Args ... args); + RangePolicy( const execution_space & work_space + , member_type work_begin + , member_type work_end + , Args ... args ); template - inline RangePolicy( const member_type work_begin - , const member_type work_end - , Args ... args); + RangePolicy( member_type work_begin + , member_type work_end + , Args ... args ); // retrieve chunk_size - inline member_type chunk_size() const; + member_type chunk_size() const; // set chunk_size to a discrete value - inline RangePolicy set_chunk_size(int chunk_size_); + RangePolicy& set_chunk_size(int chunk_size_); // return ExecSpace instance provided to the constructor KOKKOS_INLINE_FUNCTION const execution_space & space() const; @@ -101,11 +101,11 @@ Constructors Default Constructor uninitialized policy. -.. cppkokkos:function:: template RangePolicy(const int64_t& begin, const int64_t& end, const InitArgs ... init_args) +.. cppkokkos:function:: template RangePolicy(int64_t begin, int64_t end, InitArgs ... init_args) Provide a start and end index as well as optional arguments to control certain behavior (see below). -.. cppkokkos:function:: template RangePolicy(const ExecutionSpace& space, const int64_t& begin, const int64_t& end, const InitArgs ... init_args) +.. cppkokkos:function:: template RangePolicy(const ExecutionSpace& space, int64_t begin, int64_t end, InitArgs ... init_args) Provide a start and end index and an ``ExecutionSpace`` instance to use as the execution resource, as well as optional arguments to control certain behavior (see below). From 1c11b251462a59300a34cef9b3da4e684376b9c0 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 9 May 2024 15:49:12 -0500 Subject: [PATCH 2/8] Updated RangePolicy constructors --- docs/source/API/core/policies/RangePolicy.rst | 72 +++++++++++++++++-- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index 15b4ca13f..de6f9534e 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -11,10 +11,14 @@ Usage .. code-block:: cppkokkos - Kokkos::RangePolicy<>(begin, end, args...) - Kokkos::RangePolicy(begin, end, args...) - Kokkos::RangePolicy<>(Space(), begin, end, args...) - Kokkos::RangePolicy(Space(), begin, end, args...) + Kokkos::RangePolicy<>(begin, end) + Kokkos::RangePolicy(begin, end) + Kokkos::RangePolicy<>(begin, end, chunk_size) + Kokkos::RangePolicy(begin, end, chunk_size) + Kokkos::RangePolicy<>(Space(), begin, end) + Kokkos::RangePolicy(Space(), begin, end) + Kokkos::RangePolicy<>(Space(), begin, end, chunk_size) + Kokkos::RangePolicy(Space(), begin, end, chunk_size) RangePolicy defines an execution policy for a 1D iteration space starting at begin and going to end with an open interval. @@ -23,6 +27,10 @@ Synopsis .. code-block:: cpp + struct Kokkos::ChunkSize { + ChunkSize(int value_); + }; + template class Kokkos::RangePolicy { typedef RangePolicy execution_policy; @@ -43,12 +51,34 @@ Synopsis RangePolicy(); + // since 4.3 + RangePolicy( member_type work_begin + , member_type work_end ); + + // since 4.3 + RangePolicy( member_type work_begin + , member_type work_end + , ChunkSize chunk_size ); + + // since 4.3 + RangePolicy( const execution_space & work_space + , member_type work_begin + , member_type work_end ); + + // since 4.3 + RangePolicy( const execution_space & work_space + , member_type work_begin + , member_type work_end + , ChunkSize chunk_size ); + + // until 4.3 template RangePolicy( const execution_space & work_space , member_type work_begin , member_type work_end , Args ... args ); + // until 4.3 template RangePolicy( member_type work_begin , member_type work_end @@ -97,10 +127,37 @@ Public Class Members Constructors ~~~~~~~~~~~~ +.. cppkokkos:function:: ChunkSize(int value_) + + Provide a hint for optimal chunk-size to be used during scheduling. + For the SYCL backend, the workgroup size used in a ``parallel_for`` kernel can be set via this passed to ``RangePolicy``. + .. cppkokkos:function:: RangePolicy() Default Constructor uninitialized policy. +Since 4.3: +^^^^^^^^^^ + +.. cppkokkos:function:: RangePolicy(int64_t begin, int64_t end) + + Provide a start and end index. + +.. cppkokkos:function:: RangePolicy(int64_t begin, int64_t end, ChunkSize chunk_size) + + Provide a start and end index as well as a ``ChunkSize``. + +.. cppkokkos:function:: RangePolicy(const ExecutionSpace& space, int64_t begin, int64_t end) + + Provide a start and end index and an ``ExecutionSpace`` instance to use as the execution resource. + +.. cppkokkos:function:: RangePolicy(const ExecutionSpace& space, int64_t begin, int64_t end, ChunkSize chunk_size) + + Provide a start and end index and an ``ExecutionSpace`` instance to use as the execution resource, as well as a ``ChunkSize``. + +Until 4.3: +^^^^^^^^^^ + .. cppkokkos:function:: template RangePolicy(int64_t begin, int64_t end, InitArgs ... init_args) Provide a start and end index as well as optional arguments to control certain behavior (see below). @@ -109,12 +166,13 @@ Constructors Provide a start and end index and an ``ExecutionSpace`` instance to use as the execution resource, as well as optional arguments to control certain behavior (see below). -Optional ``InitArgs``: -^^^^^^^^^^^^^^^^^^^^^^ +Optional ``InitArgs`` (until 4.3): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* ``ChunkSize`` : Provide a hint for optimal chunk-size to be used during scheduling. For the SYCL backend, the workgroup size used in a ``parallel_for`` kernel can be set via this variable. +* ``ChunkSize`` Preconditions: +^^^^^^^^^^^^^^ * The start index must not be greater than the end index. From dfcd60181599d4ab86666fc0ed067b19956d0973 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 9 May 2024 16:07:07 -0500 Subject: [PATCH 3/8] Added CTAD Ctors to RangePolicy --- docs/source/API/core/policies/RangePolicy.rst | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index de6f9534e..a7f6244d9 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -176,6 +176,28 @@ Preconditions: * The start index must not be greater than the end index. +CTAD Constructors (since 4.3): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cppkokkos + + int64_t work_begin = /* ... */; // conversions as well + int64_t work_end = /* ... */; // conversions as well + ChunkSize cs = /* ... */; // conversions as well + DefaultExecutionSpace des; // conversions as well + SomeExecutionSpace ses; // different from DefaultExecutionSpace + + // Deduces to RangePolicy<> + RangePolicy rp0; + RangePolicy rp1(work_begin, work_end); + RangePolicy rp2(work_begin, work_end, cs); + RangePolicy rp3(des, work_begin, work_end); + RangePolicy rp4(des, work_begin, work_end, cs); + + // Deduces to RangePolicy + RangePolicy rp5(ses, work_begin, work_end); + RangePolicy rp6(ses, work_begin, work_end, cs); + Examples -------- From a5bd04790deb8dc442896814ae94f1c911617a28 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 16 May 2024 20:31:14 -0500 Subject: [PATCH 4/8] Changed RangePolicy Usage to just have ... as the template parameters --- docs/source/API/core/policies/RangePolicy.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index a7f6244d9..958842d99 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -11,14 +11,10 @@ Usage .. code-block:: cppkokkos - Kokkos::RangePolicy<>(begin, end) - Kokkos::RangePolicy(begin, end) - Kokkos::RangePolicy<>(begin, end, chunk_size) - Kokkos::RangePolicy(begin, end, chunk_size) - Kokkos::RangePolicy<>(Space(), begin, end) - Kokkos::RangePolicy(Space(), begin, end) - Kokkos::RangePolicy<>(Space(), begin, end, chunk_size) - Kokkos::RangePolicy(Space(), begin, end, chunk_size) + Kokkos::RangePolicy<...>(begin, end) + Kokkos::RangePolicy<...>(begin, end, chunk_size) + Kokkos::RangePolicy<...>(Space(), begin, end) + Kokkos::RangePolicy<...>(Space(), begin, end, chunk_size) RangePolicy defines an execution policy for a 1D iteration space starting at begin and going to end with an open interval. From daa13e3c4bffe57a2a894058cee6bd1b5bbdeccf Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 16 May 2024 20:37:21 -0500 Subject: [PATCH 5/8] Removed pre-4.3 interface. The only difference was that the ctors were templated, but that only allowed passing ChunkSize multiple times --- docs/source/API/core/policies/RangePolicy.rst | 36 ------------------- 1 file changed, 36 deletions(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index 958842d99..c89c4abd4 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -47,39 +47,22 @@ Synopsis RangePolicy(); - // since 4.3 RangePolicy( member_type work_begin , member_type work_end ); - // since 4.3 RangePolicy( member_type work_begin , member_type work_end , ChunkSize chunk_size ); - // since 4.3 RangePolicy( const execution_space & work_space , member_type work_begin , member_type work_end ); - // since 4.3 RangePolicy( const execution_space & work_space , member_type work_begin , member_type work_end , ChunkSize chunk_size ); - // until 4.3 - template - RangePolicy( const execution_space & work_space - , member_type work_begin - , member_type work_end - , Args ... args ); - - // until 4.3 - template - RangePolicy( member_type work_begin - , member_type work_end - , Args ... args ); - // retrieve chunk_size member_type chunk_size() const; // set chunk_size to a discrete value @@ -132,9 +115,6 @@ Constructors Default Constructor uninitialized policy. -Since 4.3: -^^^^^^^^^^ - .. cppkokkos:function:: RangePolicy(int64_t begin, int64_t end) Provide a start and end index. @@ -151,22 +131,6 @@ Since 4.3: Provide a start and end index and an ``ExecutionSpace`` instance to use as the execution resource, as well as a ``ChunkSize``. -Until 4.3: -^^^^^^^^^^ - -.. cppkokkos:function:: template RangePolicy(int64_t begin, int64_t end, InitArgs ... init_args) - - Provide a start and end index as well as optional arguments to control certain behavior (see below). - -.. cppkokkos:function:: template RangePolicy(const ExecutionSpace& space, int64_t begin, int64_t end, InitArgs ... init_args) - - Provide a start and end index and an ``ExecutionSpace`` instance to use as the execution resource, as well as optional arguments to control certain behavior (see below). - -Optional ``InitArgs`` (until 4.3): -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* ``ChunkSize`` - Preconditions: ^^^^^^^^^^^^^^ From 81d0e35fd22995bdba014d2d1c9f415c6ac8c751 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 16 May 2024 20:47:11 -0500 Subject: [PATCH 6/8] Minor fixes to longstanding documentation bugs in RangePolicy --- docs/source/API/core/policies/RangePolicy.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index c89c4abd4..c2baac525 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -28,12 +28,11 @@ Synopsis }; template - class Kokkos::RangePolicy { - typedef RangePolicy execution_policy; - typedef typename traits::index_type member_type; - typedef typename traits::index_type index_type; + struct Kokkos::RangePolicy { + using execution_policy = RangePolicy; + using member_type = PolicyTraits::index_type; - //Inherited from PolicyTraits + // Inherited from PolicyTraits using execution_space = PolicyTraits::execution_space; using schedule_type = PolicyTraits::schedule_type; using work_tag = PolicyTraits::work_tag; @@ -41,7 +40,7 @@ Synopsis using iteration_pattern = PolicyTraits::iteration_pattern; using launch_bounds = PolicyTraits::launch_bounds; - //Constructors + // Constructors RangePolicy(const RangePolicy&) = default; RangePolicy(RangePolicy&&) = default; From a363a6028c5212407258447988eae1bd549589a0 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 23 May 2024 21:10:03 -0500 Subject: [PATCH 7/8] Made some minor edits based on P/R #428 (now superseded by this P/R) --- docs/source/API/core/policies/RangePolicy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index c2baac525..457fb209b 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -16,7 +16,7 @@ Usage Kokkos::RangePolicy<...>(Space(), begin, end) Kokkos::RangePolicy<...>(Space(), begin, end, chunk_size) -RangePolicy defines an execution policy for a 1D iteration space starting at begin and going to end with an open interval. +RangePolicy defines an execution policy for a 1D iteration space starting at ``begin`` and going to ``end`` with an open interval. Synopsis -------- From 460045f3191d3bd05b9d06fbcfea7d81d20bc922 Mon Sep 17 00:00:00 2001 From: "Nevin \":-)\" Liber" Date: Thu, 23 May 2024 21:31:16 -0500 Subject: [PATCH 8/8] Addressing various changes requested by dalg24 --- docs/source/API/core/policies/RangePolicy.rst | 35 +++++++++++-------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/source/API/core/policies/RangePolicy.rst b/docs/source/API/core/policies/RangePolicy.rst index 457fb209b..1fe2fe242 100644 --- a/docs/source/API/core/policies/RangePolicy.rst +++ b/docs/source/API/core/policies/RangePolicy.rst @@ -13,8 +13,14 @@ Usage Kokkos::RangePolicy<...>(begin, end) Kokkos::RangePolicy<...>(begin, end, chunk_size) - Kokkos::RangePolicy<...>(Space(), begin, end) - Kokkos::RangePolicy<...>(Space(), begin, end, chunk_size) + Kokkos::RangePolicy<...>(exec, begin, end) + Kokkos::RangePolicy<...>(exec, begin, end, chunk_size) + + // CTAD Constructors (since 4.3) + Kokkos::RangePolicy(begin, end) + Kokkos::RangePolicy(begin, end, chunk_size) + Kokkos::RangePolicy(exec, begin, end) + Kokkos::RangePolicy(exec, begin, end, chunk_size) RangePolicy defines an execution policy for a 1D iteration space starting at ``begin`` and going to ``end`` with an open interval. @@ -46,33 +52,33 @@ Synopsis RangePolicy(); - RangePolicy( member_type work_begin - , member_type work_end ); + RangePolicy( index_type work_begin + , index_type work_end ); - RangePolicy( member_type work_begin - , member_type work_end + RangePolicy( index_type work_begin + , index_type work_end , ChunkSize chunk_size ); RangePolicy( const execution_space & work_space - , member_type work_begin - , member_type work_end ); + , index_type work_begin + , index_type work_end ); RangePolicy( const execution_space & work_space - , member_type work_begin - , member_type work_end + , index_type work_begin + , index_type work_end , ChunkSize chunk_size ); // retrieve chunk_size - member_type chunk_size() const; + index_type chunk_size() const; // set chunk_size to a discrete value RangePolicy& set_chunk_size(int chunk_size_); // return ExecSpace instance provided to the constructor - KOKKOS_INLINE_FUNCTION const execution_space & space() const; + KOKKOS_FUNCTION const execution_space & space() const; // return Range begin - KOKKOS_INLINE_FUNCTION member_type begin() const; + KOKKOS_FUNCTION member_type begin() const; // return Range end - KOKKOS_INLINE_FUNCTION member_type end() const; + KOKKOS_FUNCTION member_type end() const; }; Parameters @@ -134,6 +140,7 @@ Preconditions: ^^^^^^^^^^^^^^ * The start index must not be greater than the end index. +* The actual constructors are templated so we can check that they are converted to ``index_type`` safely (see `#6754 `_). CTAD Constructors (since 4.3): ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^