From 1ad9fd8092d1c57a567672b88859a12a48d37cf1 Mon Sep 17 00:00:00 2001 From: Francesco Rizzi Date: Wed, 16 Aug 2023 12:24:13 +0200 Subject: [PATCH 1/3] WIP --- docs/source/API/algorithms-index.rst | 3 +- docs/source/API/algorithms/Sort.rst | 308 +++++++++--------- .../API/algorithms/sort-nested-policies.rst | 154 +++++++++ 3 files changed, 317 insertions(+), 148 deletions(-) create mode 100644 docs/source/API/algorithms/sort-nested-policies.rst diff --git a/docs/source/API/algorithms-index.rst b/docs/source/API/algorithms-index.rst index 2efd63d19..e3aa1bd1a 100644 --- a/docs/source/API/algorithms-index.rst +++ b/docs/source/API/algorithms-index.rst @@ -5,5 +5,6 @@ API: Algorithms :maxdepth: 1 ./algorithms/Random-Number - ./algorithms/Sort + ./algorithms/sort + ./algorithms/sort-nested-policies ./algorithms/std-algorithms-index diff --git a/docs/source/API/algorithms/Sort.rst b/docs/source/API/algorithms/Sort.rst index 383999f3d..0efabdd0c 100644 --- a/docs/source/API/algorithms/Sort.rst +++ b/docs/source/API/algorithms/Sort.rst @@ -1,184 +1,198 @@ -Sort -==== .. role:: cppkokkos(code) :language: cppkokkos -.. code-block:: cpp +Sort +==== - template - struct copy_functor { } +Header File: ````. - template - struct copy_permute_functor { } +This page describes the Kokkos' sorting API to use with standard host-based dispatching. - 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 { } - } +API +^^^ - template struct BinOp1D { } - template struct BinOp3D { } +.. cppkokkos:function:: template void sort(const ExecutionSpace& exec, const Kokkos::View& view); - template void sort( ViewType const & view ) { } - template void sort( ViewType view, size_t const begin, size_t const end ) { } + Sort the elements in ``view`` in non-discending order using the provided ``exespace``. + Elements are compared using ``operator<``. -Sorting with nested policies (team- and thread-level) -===================================================== + :param exec: execution space instance + :param view: view to sort -Parallel sort functions for use within ``TeamPolicy`` kernels. These perform sorting using team-level (``TeamThreadRange``) or thread-level (``ThreadVectorRange``) parallelism. + Semantics: -Header: ```` + - this function is potentially asynchronous -Synopsis --------- + Constraints: -.. code-block:: cpp - - //namespace Kokkos::Experimental + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` - template - KOKKOS_INLINE_FUNCTION void sort_team(const TeamMember& t, const ViewType& view); + - ``view`` must be accessible from ``exespace`` - template - KOKKOS_INLINE_FUNCTION void sort_team(const TeamMember& t, const ViewType& view, const Comparator& comp); - template - KOKKOS_INLINE_FUNCTION void sort_by_key_team( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); +.. cppkokkos:function:: template void sort(const Kokkos::View& view); - template - KOKKOS_INLINE_FUNCTION void sort_by_key_team( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView, const Comparator& comp); + Sort the elements in ``view`` in non-discending order using the view's associated execution space. + Elements are compared using ``operator<``. - template - KOKKOS_INLINE_FUNCTION void sort_thread(const TeamMember& t, const ViewType& view); + :param view: view to sort - template - KOKKOS_INLINE_FUNCTION void sort_thread(const TeamMember& t, const ViewType& view); + Constraints - template - KOKKOS_INLINE_FUNCTION void sort_thread(const TeamMember& t, const ViewType& view, const Comparator& comp); + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` - template - KOKKOS_INLINE_FUNCTION void sort_by_key_thread( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); + Semantics: - template - KOKKOS_INLINE_FUNCTION void sort_by_key_thread( - const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView, const Comparator& comp); + - Before the actual sorting is executed, the function calls ``Kokkos::fence("Kokkos::sort: before")``; after the sort is completed the execution space is fenced with message ``exec.fence("Kokkos::sort: fence after sorting")``. -``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. + Possible implementation: -The ``sort_by_key`` functions sort ``keyView``, while simultaneously applying the same permutation to the elements of ``valueView``. It is equivalent to sorting ``(key[i], value[i])`` tuples according to key. An example of where this is commonly used is to sort the entries and values in each row of a CRS (compressed row sparse) matrix. These functions require that ``keyView.extent(0) == valueView.extent(0)``. + .. code-block:: cpp -Versions taking a ``Comparator`` object will use it to order the keys. ``Comparator::operator()`` should be a const member function that accepts two keys ``a`` and ``b``, and returns a bool that is true if and only if ``a`` goes before ``b`` in the sorted list. For versions not taking a ``Comparator`` object, keys are sorted into ascending order (according to ``operator<``). For example, this comparator will sort a view of ``int`` in *descending* order: + template + void sort(const Kokkos::View& view){ + using ViewType = Kokkos::View; + typename ViewType::execution_space exec; + sort(exec, view); + } -.. code-block:: cpp - struct IntComparator { - KOKKOS_FUNCTION constexpr bool operator()(const int& a, const int& b) const { - return a > b; //a precedes b if a is larger - } - }; +.. cppkokkos:function:: template void sort(const ExecutionSpace& exec, const Kokkos::View& view, const ComparatorType& comparator) -Additional Information ----------------------- + Sort the elements in ``view`` in non-discending order using the view's associated execution space. + Elements are compared using the comparison functor ``comparator``. -* All functions include a final barrier at their level of parallelism, so all elements of ``view`` / ``keyView`` / ``valueView`` may be accessed immediately after they return. + .. versionadded:: 4.2.0 -* These functions can operate on views in both global and scratch memory spaces. + :param exec: execution space instance + :param view: view to sort + :param comparator: comparison functor -* These functions use the bitonic sorting algorithm, which is not stable. This means if a key is repeated in the input, then the values corresponding to that key might be in any order after doing a sort by key. + Constraints: -Example -------- + - ``view`` must be rank-1 with ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` -.. code-block:: cpp - - #include - #include - #include - - int main(int argc, char* argv[]) { - using ExecSpace = Kokkos::DefaultExecutionSpace; - using TeamPol = Kokkos::TeamPolicy; - using TeamMem = typename TeamPol::member_type; - Kokkos::initialize(argc, argv); - { - int n = 10; - Kokkos::Random_XorShift64_Pool rand_pool(13718); - Kokkos::View A("A", n, n); - Kokkos::fill_random(A, rand_pool, 100); - Kokkos::parallel_for( - TeamPol(n, Kokkos::AUTO()), - KOKKOS_LAMBDA(const TeamMem& t) - { - //Sort a row of A using the whole team. - auto A_row_i = Kokkos::subview(A, t.league_rank(), Kokkos::ALL()); - Kokkos::Experimental::sort_team(t, A_row_i); - }); - auto Ahost = Kokkos::create_mirror_view_and_copy(Kokkos::HostSpace(), A); - std::cout << "A, with each row sorted:\n"; - for(int i = 0; i < n; i++) { - for(int j = 0; j < n; j++) { - std::cout << Ahost(i, j) << ' '; - } - std::cout << '\n'; - } - int vectorLen = TeamPol::vector_length_max(); - Kokkos::parallel_for( - TeamPol(1, Kokkos::AUTO(), vectorLen), - KOKKOS_LAMBDA(const TeamMem& t) - { - Kokkos::parallel_for(Kokkos::TeamThreadRange(t, n), - [=](int i) - { - //Now sort a column of A by using just this thread. - auto A_col_i = Kokkos::subview(A, Kokkos::ALL(), i); - Kokkos::Experimental::sort_thread(t, A_col_i); - }); - }); - Kokkos::deep_copy(Ahost, A); - std::cout << "\nA, with each column sorted:\n"; - for(int i = 0; i < n; i++) { - for(int j = 0; j < n; j++) { - std::cout << Ahost(i, j) << ' '; - } - std::cout << '\n'; - } - } - Kokkos::finalize(); - return 0; - } + - ``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 + + +.. 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``. + + .. versionadded:: 4.2.0 + + :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: + + - 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 -Sample output -~~~~~~~~~~~~~ + template + void sort(const Kokkos::View& view, + const ComparatorType& comparator) + { + using ViewType = Kokkos::View; + typename ViewType::execution_space exec; + sort(exec, view, comparator); + } + + +.. cppkokkos:function:: template void sort(const ExecutionSpace& exec, ViewType view, size_t const begin, size_t const end) + + 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 begin,end: indices representing the range of elements to sort (end is exclusive) + + Constraints: + + - ``view`` must be rank-1 + + Preconditions: + + - ``begin, end`` must represent a valid range, i.e., ``end >= begin``, and be admissible for the given ``view``, i.e., ``end < view.extent(0)`` + + Semantics: + + - this function is potentially asynchronous + + +.. cppkokkos:function:: template void sort(ViewType view, size_t const begin, size_t const end) + + Sort a subrange of elements of ``view`` in non-discending order using the view's associated execution space. + + :param view: view to sort + :param begin,end: indices representing the range of elements to sort (end is exclusive) + + Constraints: same as overload above + + Semantics: + + - ``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 begin, size_t const end) { + typename ViewType::execution_space exec; + sort(exec, view, begin, end); + } + +| +| +| + +BinSort +^^^^^^^ .. 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 - - 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 + + template + struct copy_functor { } + + 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 { } + } + + template struct BinOp1D { } + template struct BinOp3D { } diff --git a/docs/source/API/algorithms/sort-nested-policies.rst b/docs/source/API/algorithms/sort-nested-policies.rst new file mode 100644 index 000000000..e481a9327 --- /dev/null +++ b/docs/source/API/algorithms/sort-nested-policies.rst @@ -0,0 +1,154 @@ + +.. role:: cppkokkos(code) + :language: cppkokkos + +Sort for team- and thread-level +=============================== + +Header File: ````. + + +Parallel sort functions to use within ``TeamPolicy`` kernels. +These perform sorting using team-level (``TeamThreadRange``) or thread-level (``ThreadVectorRange``) parallelism. + + +API +--- + +.. warning:: The following functions are currently inside the ``Kokkos::Experimental`` namespace. + + +.. cppkokkos:kokkosinlinefunction:: template void sort_team(const TeamMember& t, const ViewType& view); + +.. cppkokkos:kokkosinlinefunction:: template void sort_team(const TeamMember& t, const ViewType& view, const Comparator& comp); + +.. cppkokkos:kokkosinlinefunction:: template void sort_by_key_team(const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); + +.. cppkokkos:kokkosinlinefunction:: template 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); + +.. cppkokkos:kokkosinlinefunction:: template void sort_thread(const TeamMember& t, const ViewType& view); + +.. cppkokkos:kokkosinlinefunction:: template void sort_thread(const TeamMember& t, const ViewType& view, const Comparator& comp); + +.. cppkokkos:kokkosinlinefunction:: template void sort_by_key_thread(const TeamMember& t, const KeyViewType& keyView, const ValueViewType& valueView); + +.. cppkokkos:kokkosinlinefunction:: template 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. + +The ``sort_by_key`` functions sort ``keyView``, while simultaneously applying the same permutation to the elements of ``valueView``. It is equivalent to sorting ``(key[i], value[i])`` tuples according to key. An example of where this is commonly used is to sort the entries and values in each row of a CRS (compressed row sparse) matrix. These functions require that ``keyView.extent(0) == valueView.extent(0)``. + +Versions taking a ``Comparator`` object will use it to order the keys. ``Comparator::operator()`` should be a const member function that accepts two keys ``a`` and ``b``, and returns a bool that is true if and only if ``a`` goes before ``b`` in the sorted list. For versions not taking a ``Comparator`` object, keys are sorted into ascending order (according to ``operator<``). For example, this comparator will sort a view of ``int`` in *descending* order: + +.. code-block:: cpp + + struct IntComparator { + KOKKOS_FUNCTION constexpr bool operator()(const int& a, const int& b) const { + return a > b; //a precedes b if a is larger + } + }; + +Additional Information +---------------------- + +* All functions include a final barrier at their level of parallelism, so all elements of ``view`` / ``keyView`` / ``valueView`` may be accessed immediately after they return. + +* These functions can operate on views in both global and scratch memory spaces. + +* These functions use the bitonic sorting algorithm, which is not stable. This means if a key is repeated in the input, then the values corresponding to that key might be in any order after doing a sort by key. + +Example +------- + +.. code-block:: cpp + + #include + #include + #include + + int main(int argc, char* argv[]) { + using ExecSpace = Kokkos::DefaultExecutionSpace; + using TeamPol = Kokkos::TeamPolicy; + using TeamMem = typename TeamPol::member_type; + Kokkos::initialize(argc, argv); + { + int n = 10; + Kokkos::Random_XorShift64_Pool rand_pool(13718); + Kokkos::View A("A", n, n); + Kokkos::fill_random(A, rand_pool, 100); + Kokkos::parallel_for( + TeamPol(n, Kokkos::AUTO()), + KOKKOS_LAMBDA(const TeamMem& t) + { + //Sort a row of A using the whole team. + auto A_row_i = Kokkos::subview(A, t.league_rank(), Kokkos::ALL()); + Kokkos::Experimental::sort_team(t, A_row_i); + }); + auto Ahost = Kokkos::create_mirror_view_and_copy(Kokkos::HostSpace(), A); + std::cout << "A, with each row sorted:\n"; + for(int i = 0; i < n; i++) { + for(int j = 0; j < n; j++) { + std::cout << Ahost(i, j) << ' '; + } + std::cout << '\n'; + } + int vectorLen = TeamPol::vector_length_max(); + Kokkos::parallel_for( + TeamPol(1, Kokkos::AUTO(), vectorLen), + KOKKOS_LAMBDA(const TeamMem& t) + { + Kokkos::parallel_for(Kokkos::TeamThreadRange(t, n), + [=](int i) + { + //Now sort a column of A by using just this thread. + auto A_col_i = Kokkos::subview(A, Kokkos::ALL(), i); + Kokkos::Experimental::sort_thread(t, A_col_i); + }); + }); + Kokkos::deep_copy(Ahost, A); + std::cout << "\nA, with each column sorted:\n"; + for(int i = 0; i < n; i++) { + for(int j = 0; j < n; j++) { + std::cout << Ahost(i, j) << ' '; + } + std::cout << '\n'; + } + } + Kokkos::finalize(); + return 0; + } + +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 + + 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 From b96e0be6ac07929c733d989702efe7a996516fc5 Mon Sep 17 00:00:00 2001 From: Francesco Rizzi Date: Wed, 16 Aug 2023 12:30:46 +0200 Subject: [PATCH 2/3] rename --- docs/source/API/algorithms-index.rst | 2 +- .../API/algorithms/{Sort.rst => sort-standard-policies.rst} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/source/API/algorithms/{Sort.rst => sort-standard-policies.rst} (100%) diff --git a/docs/source/API/algorithms-index.rst b/docs/source/API/algorithms-index.rst index e3aa1bd1a..f620191a8 100644 --- a/docs/source/API/algorithms-index.rst +++ b/docs/source/API/algorithms-index.rst @@ -5,6 +5,6 @@ API: Algorithms :maxdepth: 1 ./algorithms/Random-Number - ./algorithms/sort + ./algorithms/sort-standard-policies ./algorithms/sort-nested-policies ./algorithms/std-algorithms-index diff --git a/docs/source/API/algorithms/Sort.rst b/docs/source/API/algorithms/sort-standard-policies.rst similarity index 100% rename from docs/source/API/algorithms/Sort.rst rename to docs/source/API/algorithms/sort-standard-policies.rst From 70d7087272bba1331e2ea00affefeabd79b363c2 Mon Sep 17 00:00:00 2001 From: Francesco Rizzi Date: Wed, 27 Sep 2023 17:43:26 +0200 Subject: [PATCH 3/3] WIP binsort --- docs/source/API/algorithms-index.rst | 3 +- docs/source/API/algorithms/sorting-index.rst | 9 ++ .../source/API/algorithms/sorting/binsort.rst | 122 ++++++++++++++++++ .../sort-freefnc-nested-policies.rst} | 4 +- .../sort-freefnc-standard-policies.rst} | 87 ++++++------- 5 files changed, 175 insertions(+), 50 deletions(-) create mode 100644 docs/source/API/algorithms/sorting-index.rst create mode 100644 docs/source/API/algorithms/sorting/binsort.rst rename docs/source/API/algorithms/{sort-nested-policies.rst => sorting/sort-freefnc-nested-policies.rst} (98%) rename docs/source/API/algorithms/{sort-standard-policies.rst => sorting/sort-freefnc-standard-policies.rst} (58%) diff --git a/docs/source/API/algorithms-index.rst b/docs/source/API/algorithms-index.rst index f620191a8..034949b25 100644 --- a/docs/source/API/algorithms-index.rst +++ b/docs/source/API/algorithms-index.rst @@ -5,6 +5,5 @@ API: Algorithms :maxdepth: 1 ./algorithms/Random-Number - ./algorithms/sort-standard-policies - ./algorithms/sort-nested-policies + ./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-nested-policies.rst b/docs/source/API/algorithms/sorting/sort-freefnc-nested-policies.rst similarity index 98% rename from docs/source/API/algorithms/sort-nested-policies.rst rename to docs/source/API/algorithms/sorting/sort-freefnc-nested-policies.rst index e481a9327..cb0fe4b6b 100644 --- a/docs/source/API/algorithms/sort-nested-policies.rst +++ b/docs/source/API/algorithms/sorting/sort-freefnc-nested-policies.rst @@ -2,8 +2,8 @@ .. role:: cppkokkos(code) :language: cppkokkos -Sort for team- and thread-level -=============================== +Sort with nested policies (team- and thread-level) +================================================== Header File: ````. diff --git a/docs/source/API/algorithms/sort-standard-policies.rst b/docs/source/API/algorithms/sorting/sort-freefnc-standard-policies.rst similarity index 58% rename from docs/source/API/algorithms/sort-standard-policies.rst rename to docs/source/API/algorithms/sorting/sort-freefnc-standard-policies.rst index 0efabdd0c..157b00226 100644 --- a/docs/source/API/algorithms/sort-standard-policies.rst +++ b/docs/source/API/algorithms/sorting/sort-freefnc-standard-policies.rst @@ -12,6 +12,9 @@ This page describes the Kokkos' sorting API to use with standard host-based disp 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``. @@ -22,7 +25,10 @@ API Semantics: - - this function is potentially asynchronous + - 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: @@ -44,7 +50,9 @@ API Semantics: - - Before the actual sorting is executed, the function calls ``Kokkos::fence("Kokkos::sort: before")``; after the sort is completed the execution space is fenced with message ``exec.fence("Kokkos::sort: fence after sorting")``. + - 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: @@ -57,14 +65,16 @@ API 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``. - .. versionadded:: 4.2.0 - :param exec: execution space instance :param view: view to sort :param comparator: comparison functor @@ -75,10 +85,10 @@ API - ``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: + - ``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 @@ -91,7 +101,10 @@ API Semantics: - - this function is potentially asynchronous + - 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) @@ -99,8 +112,6 @@ API Sort the elements in ``view`` in non-discending order using the view's associated execution space. Elements are compared using the comparison functor ``comparator``. - .. versionadded:: 4.2.0 - :param view: view to sort :param comparator: comparison functor @@ -112,7 +123,10 @@ API Semantics: - - 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")``. + - 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: @@ -127,14 +141,16 @@ API 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 begin, size_t const end) +.. 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 begin,end: indices representing the range of elements to sort (end is exclusive) + :param startIndex, endIndex: indices representing the range of elements to sort (``endIndex`` is exclusive) Constraints: @@ -142,57 +158,36 @@ API Preconditions: - - ``begin, end`` must represent a valid range, i.e., ``end >= begin``, and be admissible for the given ``view``, i.e., ``end < view.extent(0)`` + - ``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 + - 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 begin, size_t const end) +.. 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 begin,end: indices representing the range of elements to sort (end is exclusive) + :param startIndex, endIndex: indices representing the range of elements to sort (``endIndex`` is exclusive) Constraints: same as overload above Semantics: - - ``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". + - 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 begin, size_t const end) { + void sort(ViewType view, size_t const startIndex, size_t const endIndex) { typename ViewType::execution_space exec; - sort(exec, view, begin, end); + sort(exec, view, startIndex, endIndex); } - -| -| -| - -BinSort -^^^^^^^ - -.. code-block:: cpp - - template - struct copy_functor { } - - 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 { } - } - - template struct BinOp1D { } - template struct BinOp3D { }