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 all 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
112 changes: 79 additions & 33 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,60 +11,74 @@ 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<...>(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.
// 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.

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( index_type work_begin
, index_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( index_type work_begin
, index_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
, index_type work_begin
, index_type work_end );

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

// retrieve chunk_size
inline member_type chunk_size() const;
index_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;
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
Expand Down Expand Up @@ -97,26 +111,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).

* The actual constructors are templated so we can check that they are converted to ``index_type`` safely (see `#6754 <https://github.com/kokkos/kokkos/pull/6754>`_).

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