Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

RangePolicy constructor updates from Release 4.3 #523

Merged
merged 8 commits into from
May 24, 2024
Merged

RangePolicy constructor updates from Release 4.3 #523

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
eba5ba8
Cleanup of RangePolicy
nliber May 9, 2024
1c11b25
Updated RangePolicy constructors
nliber May 9, 2024
dfcd601
Added CTAD Ctors to RangePolicy
nliber May 9, 2024
a5bd047
Changed RangePolicy Usage to just have ... as the template parameters
nliber May 17, 2024
daa13e3
Removed pre-4.3 interface. The only difference was that the
nliber May 17, 2024
81d0e35
Minor fixes to longstanding documentation bugs in RangePolicy
nliber May 17, 2024
a363a60
Made some minor edits based on P/R #428 (now superseded by this P/R)
nliber May 24, 2024
460045f
Addressing various changes requested by dalg24
nliber May 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 68 additions & 29 deletions docs/source/API/core/policies/RangePolicy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ Usage

.. code-block:: cppkokkos

Kokkos::RangePolicy<>(begin, end, args...)
Kokkos::RangePolicy<ARGS>(begin, end, args...)
Kokkos::RangePolicy<>(Space(), begin, end, args...)
Kokkos::RangePolicy<ARGS>(Space(), begin, end, args...)
Kokkos::RangePolicy<...>(begin, end)
Kokkos::RangePolicy<...>(begin, end, chunk_size)
Kokkos::RangePolicy<...>(Space(), begin, end)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Kokkos::RangePolicy<...>(Space(), begin, end)
Kokkos::RangePolicy(exec, begin, end)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to have both template parameters and CTAD constructors, as I don't want the usage to imply this is not a templated class.

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.

Expand All @@ -23,41 +23,49 @@ Synopsis

.. code-block:: cpp

struct Kokkos::ChunkSize {
ChunkSize(int value_);
};

template<class ... Args>
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<Args...>::index_type;

//Inherited from PolicyTraits<Args...>
// Inherited from PolicyTraits<Args...>
using execution_space = PolicyTraits<Args...>::execution_space;
using schedule_type = PolicyTraits<Args...>::schedule_type;
using work_tag = PolicyTraits<Args...>::work_tag;
using index_type = PolicyTraits<Args...>::index_type;
using iteration_pattern = PolicyTraits<Args...>::iteration_pattern;
using launch_bounds = PolicyTraits<Args...>::launch_bounds;

//Constructors
// Constructors
RangePolicy(const RangePolicy&) = default;
RangePolicy(RangePolicy&&) = default;
Comment on lines 50 to 51
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would have gotten rid of these guys but I suppose we can do that later


inline RangePolicy();
RangePolicy();

RangePolicy( member_type work_begin
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say index_type
I think using member type was an attempt to have genericity between exec policy but it clearly does not work with MDRangePolicy.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to index_type.

, member_type work_end );

template<class ... Args>
inline RangePolicy( const execution_space & work_space
, const member_type work_begin
, const member_type work_end
, Args ... args);
RangePolicy( member_type work_begin
, member_type work_end
, ChunkSize chunk_size );

template<class ... Args>
inline RangePolicy( 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 );

RangePolicy( const execution_space & work_space
, member_type work_begin
, member_type work_end
, ChunkSize chunk_size );

// 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;
nliber marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -97,27 +105,58 @@ 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.

.. cppkokkos:function:: template<class ... InitArgs> RangePolicy(const int64_t& begin, const int64_t& end, const InitArgs ... init_args)
.. cppkokkos:function:: RangePolicy(int64_t begin, int64_t end)

Provide a start and end index as well as optional arguments to control certain behavior (see below).
Provide a start and end index.

.. cppkokkos:function:: template<class ... InitArgs> RangePolicy(const ExecutionSpace& space, const int64_t& begin, const int64_t& end, const InitArgs ... init_args)
.. cppkokkos:function:: RangePolicy(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 optional arguments to control certain behavior (see below).
Provide a start and end index as well as a ``ChunkSize``.

Optional ``InitArgs``:
^^^^^^^^^^^^^^^^^^^^^^
.. cppkokkos:function:: RangePolicy(const ExecutionSpace& space, int64_t begin, int64_t end)

* ``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.
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``.

Preconditions:
^^^^^^^^^^^^^^

* The start index must not be greater than the end index.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You referred to the PR that check that the indices arguments are representable as index_type.
Maybe that would be confusing because we pretend that the constructors take member_type/index_type by value when in reality they are templated.
Can we really pretend it is QOI?
(this does not need to be resolved here)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a sentence under "Preconditions" (I might move it, though).


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<SomeExecutionSpace>
RangePolicy rp5(ses, work_begin, work_end);
RangePolicy rp6(ses, work_begin, work_end, cs);

Examples
--------

Expand Down
Loading