Skip to content

Commit

Permalink
[oneDPL] Add Histogram API (#571)
Browse files Browse the repository at this point in the history
---------

Signed-off-by: Dan Hoeflinger <dan.hoeflinger@intel.com>
Co-authored-by: Alexey Kukanov <alexey.kukanov@intel.com>
  • Loading branch information
danhoeflinger and akukanov authored Sep 4, 2024
1 parent 13362b4 commit e453f5f
Showing 1 changed file with 35 additions and 0 deletions.
35 changes: 35 additions & 0 deletions source/elements/oneDPL/source/parallel_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <typename Policy, typename InputIt, typename Size, typename ValueType,
typename OutputIt>
OutputIt
histogram(Policy&& exec, InputIt start, InputIt end, Size num_intervals,
ValueType first_interval_begin, ValueType last_interval_end, OutputIt histogram_first); // (1)
template <typename Policy, typename InputIt1, typename InputIt2, typename OutputIt>
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

0 comments on commit e453f5f

Please sign in to comment.