diff --git a/docs/source/API/algorithms-index.rst b/docs/source/API/algorithms-index.rst index 2efd63d19..034949b25 100644 --- a/docs/source/API/algorithms-index.rst +++ b/docs/source/API/algorithms-index.rst @@ -5,5 +5,5 @@ API: Algorithms :maxdepth: 1 ./algorithms/Random-Number - ./algorithms/Sort + ./algorithms/sorting-index ./algorithms/std-algorithms-index diff --git a/docs/source/API/algorithms/sorting-index.rst b/docs/source/API/algorithms/sorting-index.rst new file mode 100644 index 000000000..a883309cd --- /dev/null +++ b/docs/source/API/algorithms/sorting-index.rst @@ -0,0 +1,9 @@ +Sorting +####### + +.. toctree:: + :maxdepth: 1 + + ./sorting/sort-freefnc-standard-policies + ./sorting/sort-freefnc-nested-policies + ./sorting/binsort diff --git a/docs/source/API/algorithms/sorting/binsort.rst b/docs/source/API/algorithms/sorting/binsort.rst new file mode 100644 index 000000000..9c375c894 --- /dev/null +++ b/docs/source/API/algorithms/sorting/binsort.rst @@ -0,0 +1,122 @@ + +.. role:: cppkokkos(code) + :language: cppkokkos + +``BinSort`` +=========== + +Header File: ````. + +This page describes the Kokkos' ``BinSort`` API. + +API +^^^ + +BinSort Class +------------- + +.. cpp:class:: template BinSort + + :tparam KeyViewType: View for the keys + + :tparam BinSortOp: TBD + + :tparam Space: TBD + + :tparam SizeType: TBD + + .. rubric:: Constructors + + .. cppkokkos:function:: template BinSort(const ExecutionSpace& exec, const_key_view_type keys, int range_begin, int range_end, BinSortOp bin_op, bool sort_within_bins = false) + + :param exec: execution space + :param keys: dfkdfd + :param range_begin: tbd + :param range_end: tbd + :param bin_op: dfdv + :param sort_within_bins: dfdfd + + .. cppkokkos:function:: template BinSort(const ExecutionSpace& exec, const_key_view_type keys, BinSortOp bin_op, bool sort_within_bins = false) + + :param exec: execution space + :param keys: dfkdfd + :param bin_op: dfdv + :param sort_within_bins: dfdfd + + .. cppkokkos:function:: BinSort(const_key_view_type keys, int range_begin, int range_end, BinSortOp bin_op, bool sort_within_bins = false) + + Constructor that takes the keys, the binning_operator and optionally whether to sort within bins (default false) + + :param keys: dfkdfd + :param range_begin: tbd + :param range_end: tbd + :param bin_op: dfdv + + + .. cppkokkos:function:: BinSort(const_key_view_type keys, BinSortOp bin_op, bool sort_within_bins = false) + + Another constructor + + :param keys: dfkdfd + :param bin_op: dfdv + :param sort_within_bins: dfdfd + + + .. rubric:: Public Methods + + .. cppkokkos:function:: template void create_permute_vector(const ExecutionSpace& exec) + + Create the permutation vector, the bin_offset array and the bin_count array. + Can be called again if keys changed + + .. cppkokkos:function:: void create_permute_vector(const ExecutionSpace& exec) + + Create the permutation vector, the bin_offset array and the bin_count array. + Can be called again if keys changed + + .. cppkokkos:function:: template void sort(const ExecutionSpace& exec, ValuesViewType const& values, int values_range_begin, int values_range_end) const + + Sort a subset of a view with respect to the first dimension using the + permutation array + + + .. cppkokkos:function:: template void sort(ValuesViewType const& values, int values_range_begin, int values_range_end) const + + Sort a subset of a view with respect to the first dimension using the permutation array + + + .. cppkokkos:function:: template void sort(ExecutionSpace const& exec, ValuesViewType const& values) const + + .. cppkokkos:function:: template void sort(ValuesViewType const& values) const + + + +| +| + +Bin Op classes +-------------- + +.. cpp:class:: template BinOp1D + + :tparam KeyViewType: View for the keys + + .. rubric:: Constructors + + .. cppkokkos:function:: BinOp1D(int max_bins, typename KeyViewType::const_value_type min, typename KeyViewType::const_value_type max) + + Construct BinOp with number of bins, minimum value and maximum value + + +.. cpp:class:: template BinOp3D + + :tparam KeyViewType: View for the keys + + .. rubric:: Constructors + + .. cppkokkos:function:: BinOp3D(int max_bins[], typename KeyViewType::const_value_type min[], typename KeyViewType::const_value_type max[]) + + Construct BinOp with number of bins, minimum values and maximum values + +| +| diff --git a/docs/source/API/algorithms/Sort.rst b/docs/source/API/algorithms/sorting/sort-freefnc-nested-policies.rst similarity index 54% rename from docs/source/API/algorithms/Sort.rst rename to docs/source/API/algorithms/sorting/sort-freefnc-nested-policies.rst index 383999f3d..cb0fe4b6b 100644 --- a/docs/source/API/algorithms/Sort.rst +++ b/docs/source/API/algorithms/sorting/sort-freefnc-nested-policies.rst @@ -1,74 +1,44 @@ -Sort -==== .. role:: cppkokkos(code) :language: cppkokkos -.. code-block:: cpp +Sort with nested policies (team- and thread-level) +================================================== - template - struct copy_functor { } +Header File: ````. - template - struct copy_permute_functor { } - class BinSort { - template struct copy_functor { } - template struct copy_permute_functor { } - template void sort( ValuesViewType const & values, int values_range_begin, int values_range_end ) const { } - template void sort( ValuesViewType const & values ) const { } - } +Parallel sort functions to use within ``TeamPolicy`` kernels. +These perform sorting using team-level (``TeamThreadRange``) or thread-level (``ThreadVectorRange``) parallelism. - template struct BinOp1D { } - template struct BinOp3D { } - template void sort( ViewType const & view ) { } - template void sort( ViewType view, size_t const begin, size_t const end ) { } +API +--- -Sorting with nested policies (team- and thread-level) -===================================================== +.. warning:: The following functions are currently inside the ``Kokkos::Experimental`` namespace. -Parallel sort functions for use within ``TeamPolicy`` kernels. These perform sorting using team-level (``TeamThreadRange``) or thread-level (``ThreadVectorRange``) parallelism. -Header: ```` +.. cppkokkos:kokkosinlinefunction:: template void sort_team(const TeamMember& t, const ViewType& view); -Synopsis --------- +.. cppkokkos:kokkosinlinefunction:: template void sort_team(const TeamMember& t, const ViewType& view, const Comparator& comp); -.. code-block:: cpp - - //namespace Kokkos::Experimental +.. cppkokkos:kokkosinlinefunction:: template void sort_by_key_team(const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); - template - KOKKOS_INLINE_FUNCTION void sort_team(const TeamMember& t, const ViewType& view); +.. cppkokkos:kokkosinlinefunction:: template void sort_by_key_team(const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView, const Comparator& comp); - template - KOKKOS_INLINE_FUNCTION void sort_team(const TeamMember& t, const ViewType& view, const Comparator& comp); +.. cppkokkos:kokkosinlinefunction:: template void sort_thread(const TeamMember& t, const ViewType& view); - template - KOKKOS_INLINE_FUNCTION void sort_by_key_team( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); +.. cppkokkos:kokkosinlinefunction:: template void sort_thread(const TeamMember& t, const ViewType& view); - template - KOKKOS_INLINE_FUNCTION void sort_by_key_team( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView, const Comparator& comp); +.. cppkokkos:kokkosinlinefunction:: template void sort_thread(const TeamMember& t, const ViewType& view, const Comparator& comp); - template - KOKKOS_INLINE_FUNCTION void sort_thread(const TeamMember& t, const ViewType& view); +.. cppkokkos:kokkosinlinefunction:: template void sort_by_key_thread(const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); - template - KOKKOS_INLINE_FUNCTION void sort_thread(const TeamMember& t, const ViewType& view); +.. cppkokkos:kokkosinlinefunction:: template void sort_by_key_thread(const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView, const Comparator& comp); - template - KOKKOS_INLINE_FUNCTION void sort_thread(const TeamMember& t, const ViewType& view, const Comparator& comp); - template - KOKKOS_INLINE_FUNCTION void sort_by_key_thread( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); +| - template - KOKKOS_INLINE_FUNCTION void sort_by_key_thread( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView, const Comparator& comp); ``sort_team`` and ``sort_by_key_team`` internally use the entire team, so they may be called inside the top level of ``TeamPolicy`` lambdas and functors. ``sort_thread`` and ``sort_by_key_thread`` use the vector lanes of a thread, so they may be called within either ``TeamPolicy`` or ``TeamThreadRange`` loops. @@ -97,7 +67,7 @@ Example ------- .. code-block:: cpp - + #include #include #include @@ -158,27 +128,27 @@ Sample output ~~~~~~~~~~~~~ .. code-block:: cpp - + A, with each row sorted: - 0 9 38 68 74 76 83 89 91 95 - 19 41 41 55 65 68 78 92 99 99 - 2 13 16 17 19 40 44 54 96 99 - 17 18 65 68 77 80 82 94 94 95 - 0 14 34 35 45 46 47 52 58 96 - 2 6 9 13 25 32 37 51 80 81 - 3 5 14 16 20 25 33 39 60 97 - 7 8 15 31 33 38 40 40 42 86 - 4 19 20 29 42 56 60 63 68 90 - 1 16 16 17 33 39 60 64 78 94 + 0 9 38 68 74 76 83 89 91 95 + 19 41 41 55 65 68 78 92 99 99 + 2 13 16 17 19 40 44 54 96 99 + 17 18 65 68 77 80 82 94 94 95 + 0 14 34 35 45 46 47 52 58 96 + 2 6 9 13 25 32 37 51 80 81 + 3 5 14 16 20 25 33 39 60 97 + 7 8 15 31 33 38 40 40 42 86 + 4 19 20 29 42 56 60 63 68 90 + 1 16 16 17 33 39 60 64 78 94 A, with each column sorted: - 0 5 9 13 19 25 33 39 42 81 - 0 6 14 16 20 32 37 40 58 86 - 1 8 15 17 25 38 40 51 60 90 - 2 9 16 17 33 39 44 52 68 94 - 2 13 16 29 33 40 47 54 78 95 - 3 14 20 31 42 46 60 63 80 95 - 4 16 34 35 45 56 60 64 91 96 - 7 18 38 55 65 68 78 89 94 97 - 17 19 41 68 74 76 82 92 96 99 - 19 41 65 68 77 80 83 94 99 99 + 0 5 9 13 19 25 33 39 42 81 + 0 6 14 16 20 32 37 40 58 86 + 1 8 15 17 25 38 40 51 60 90 + 2 9 16 17 33 39 44 52 68 94 + 2 13 16 29 33 40 47 54 78 95 + 3 14 20 31 42 46 60 63 80 95 + 4 16 34 35 45 56 60 64 91 96 + 7 18 38 55 65 68 78 89 94 97 + 17 19 41 68 74 76 82 92 96 99 + 19 41 65 68 77 80 83 94 99 99 diff --git a/docs/source/API/algorithms/sorting/sort-freefnc-standard-policies.rst b/docs/source/API/algorithms/sorting/sort-freefnc-standard-policies.rst new file mode 100644 index 000000000..157b00226 --- /dev/null +++ b/docs/source/API/algorithms/sorting/sort-freefnc-standard-policies.rst @@ -0,0 +1,193 @@ + +.. role:: cppkokkos(code) + :language: cppkokkos + +Sort +==== + +Header File: ````. + +This page describes the Kokkos' sorting API to use with standard host-based dispatching. + +API +^^^ + +Overload set using ``operator<`` for comparing elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cppkokkos:function:: template void sort(const ExecutionSpace& exec, const Kokkos::View& view); + + Sort the elements in ``view`` in non-discending order using the provided ``exespace``. + Elements are compared using ``operator<``. + + :param exec: execution space instance + :param view: view to sort + + Semantics: + + - this function is potentially asynchronous. If needed, you can block either using + a `global fence <../core/parallel-dispatch/fence.html>`_ or you can just use `fence + the execution space instance <../core/execution_spaces.html>`_ argument + you pass to the function + + Constraints: + + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - ``view`` must be accessible from ``exespace`` + + +.. cppkokkos:function:: template void sort(const Kokkos::View& view); + + Sort the elements in ``view`` in non-discending order using the view's associated execution space. + Elements are compared using ``operator<``. + + :param view: view to sort + + Constraints + + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + Semantics: + + - This is a blocking function. Before the sorting is executed, the function internally + calls ``Kokkos::fence("Kokkos::sort: before")``, and after the sort is completed + the execution space is fenced with message ``exec.fence("Kokkos::sort: fence after sorting")``. + + Possible implementation: + + .. code-block:: cpp + + template + void sort(const Kokkos::View& view){ + using ViewType = Kokkos::View; + typename ViewType::execution_space exec; + sort(exec, view); + } + +Overload set accepting a custom comparison object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2.0 + +.. cppkokkos:function:: template void sort(const ExecutionSpace& exec, const Kokkos::View& view, const ComparatorType& comparator) + + Sort the elements in ``view`` in non-discending order using the view's associated execution space. + Elements are compared using the comparison functor ``comparator``. + + :param exec: execution space instance + :param view: view to sort + :param comparator: comparison functor + + Constraints: + + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - ``view`` must be accessible from ``exespace`` + + - ``comparator``: comparison function object returning ``true`` if the first + argument is less than the second. Must be valid to be called from the execution space passed, + and callable with two arguments ``a,b`` of type (possible const-qualified) ``value_type``, + where ``value_type`` is the non-const value type of the view. Must conform to: + + .. code-block:: cpp + + template + struct CustomComparison { + KOKKOS_FUNCTION bool operator()(T a, T b) const{ + // return true if a is less than b + } + }; + + Semantics: + + - this function is potentially asynchronous. If needed, you can block either using + a `global fence <../core/parallel-dispatch/fence.html>`_ or you can just use `fence + the execution space instance <../core/execution_spaces.html>`_ argument + you pass to the function + + +.. cppkokkos:function:: template void sort(const Kokkos::View& view, const ComparatorType& comparator) + + Sort the elements in ``view`` in non-discending order using the view's associated execution space. + Elements are compared using the comparison functor ``comparator``. + + :param view: view to sort + :param comparator: comparison functor + + Constraints: + + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - ``comparator``: same requirements as overload above + + Semantics: + + - This is a blocking function. Before the actual sorting is executed, the function + calls ``Kokkos::fence("Kokkos::sort with comparator: before)"``; after the sort is completed + the execution space is fenced with + message ``exec.fence("Kokkos::sort with comparator: fence after sorting")``. + + Possible implementation: + + .. code-block:: cpp + + template + void sort(const Kokkos::View& view, + const ComparatorType& comparator) + { + using ViewType = Kokkos::View; + typename ViewType::execution_space exec; + sort(exec, view, comparator); + } + +Overload set to sort a View's subrange +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. cppkokkos:function:: template void sort(const ExecutionSpace& exec, ViewType view, size_t const startIndex, size_t const endIndex) + + Sort a subrange of elements of ``view`` in non-discending order using the given execution space. + + :param exec: execution space instance + :param view: view to sort + :param startIndex, endIndex: indices representing the range of elements to sort (``endIndex`` is exclusive) + + Constraints: + + - ``view`` must be rank-1 + + Preconditions: + + - ``startIndex, endIndex`` must represent a valid range, i.e., ``endIndex >= startIndex``, and be admissible for the given ``view``, i.e., ``endIndex < view.extent(0)`` + + Semantics: + + - this function is potentially asynchronous. If needed, you can block either using + a `global fence <../core/parallel-dispatch/fence.html>`_ or you can just use `fence + the execution space instance <../core/execution_spaces.html>`_ argument + you pass to the function + + +.. cppkokkos:function:: template void sort(ViewType view, size_t const startIndex, size_t const endIndex) + + Sort a subrange of elements of ``view`` in non-discending order using the view's associated execution space. + + :param view: view to sort + :param startIndex, endIndex: indices representing the range of elements to sort (``endIndex`` is exclusive) + + Constraints: same as overload above + + Semantics: + + - This is a blocking function. ``Kokkos::fence("Kokkos::sort: before")`` is called before sorting, + and the execution space is fenced after the sort with message ``Kokkos::Sort: fence after sorting``. + + Possible implementation: + + .. code-block:: cpp + + template + void sort(ViewType view, size_t const startIndex, size_t const endIndex) { + typename ViewType::execution_space exec; + sort(exec, view, startIndex, endIndex); + }