From e453f5fdf2c4a7913630fad982ce1e0b1f932e2e Mon Sep 17 00:00:00 2001 From: Dan Hoeflinger <109972525+danhoeflinger@users.noreply.github.com> Date: Wed, 4 Sep 2024 14:07:24 -0400 Subject: [PATCH] [oneDPL] Add Histogram API (#571) --------- Signed-off-by: Dan Hoeflinger Co-authored-by: Alexey Kukanov --- .../elements/oneDPL/source/parallel_api.rst | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/source/elements/oneDPL/source/parallel_api.rst b/source/elements/oneDPL/source/parallel_api.rst index e211af31f9..6e2559c615 100644 --- a/source/elements/oneDPL/source/parallel_api.rst +++ b/source/elements/oneDPL/source/parallel_api.rst @@ -562,5 +562,40 @@ comparator and their associated values maintain the relative order as in the ori and ``Comparator`` must satisfy the requirements for the ``Compare`` parameter of ``std::sort``, as defined by the `C++ Standard`_. +.. code:: cpp + + template + OutputIt + histogram(Policy&& exec, InputIt start, InputIt end, Size num_intervals, + ValueType first_interval_begin, ValueType last_interval_end, OutputIt histogram_first); // (1) + + template + OutputIt + histogram(Policy&& exec, InputIt1 start, InputIt1 end, InputIt2 boundary_start, + InputIt2 boundary_end, OutputIt histogram_first); // (2) + +``oneapi::dpl::histogram`` computes the histogram over the data in ``[start, end)`` +by counting the number of elements that map to each of a set of bins and storing the counts into +the output sequence starting from ``histogram_first``. Input values that do not map to a defined +bin are skipped silently. The value type of ``OutputIt`` must be an integral type of sufficient +size to store the counts of the histogram without overflow. The return value is an iterator targeting +past the last element of the output sequence starting from ``histogram_first``. + +1. The elements of ``[start, end)`` are mapped into ``num_intervals`` bins that evenly divide the range + ``[first_interval_begin, last_interval_end)``. Each bin is of size + ``bin_size = (last_interval_end - first_interval_begin) / num_intervals`` as represented by a real + number without rounding or truncation. An input element ``start[i]`` maps to a bin + ``histogram_first[j]`` if and only if + ``(first_interval_begin + j * bin_size <= start[i]) && (start[i] < first_interval_begin + (j + 1) * bin_size)``. + Both `ValueType` and the value type of ``InputIt`` must be arithmetic types. + +2. The elements of ``[start, end)`` are mapped into ``std::distance(boundary_start, boundary_end) - 1)`` + bins defined by the values in ``[boundary_start, boundary_end)``. An input + element ``start[i]`` maps to a bin ``histogram_first[j]`` if and only if + ``(boundary_start[j] <= start[i]) && (start[i] < boundary_start[j + 1])``. The value types + of ``InputIt1`` and ``InputIt2`` must be arithmetic types. The values in + ``[boundary_start, boundary_end)`` must be sorted with respect to ``operator<``. + .. _`C++ Standard`: https://isocpp.org/std/the-standard .. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html