GatherStatistics

#include <popops/GatherStatistics.hpp>

Functions to generate histograms of data.

namespace popops

Common functions, such as elementwise and reductions.

Functions

poplar::Tensor histogram(poplar::Graph &graph, const poplar::Tensor &input, const poplar::Tensor &levels, bool absoluteOfInput, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Gather a histogram representing the statistics of the input tensor.

Compare each element of input to each value in the levels tensor. Where input >= levels[N-1] and input < levels[N], the histogram entry for that range will be incremented by 1. The lowest and highest histogram entries are bounded only by levels[0] and levels[N-1], respectively. The function returns a histogram tensor with a size one greater than the size of the levels tensor.

Histogram options

  • useFloatArithmeticWithUnsignedIntOutput (true, false) [=false]

    If true, use float arithmetic internally and reduce the result to unsigned int. This has the benefit of simplicity and speed, but integer accuracy limited by the 32-bit float data format (integers > 16,777,216 are not all exactly represented).

  • useFloatArithmetic (true, false) [=false]

    Deprecated:

    use useFloatArithmeticWithUnsignedIntOutput instead.

    If true, use float arithmetic internally and return a float result rather than an unsigned int result. This has the benefit of simplicity and speed, but integer accuracy limited by the 32-bit float data format (integers > 16,777,216 are not all exactly represented).

    The options useFloatArithmeticWithUnsignedIntOutput and useFloatArithmetic must not both be true.

Parameters

  • graph – The Poplar graph.

  • input – The input tensor on which to gather histogram statistics.

  • levels – The levels defining the comparisons to carry out in generating the histogram output.

  • absoluteOfInput – If true, the absolute value of each input is calculated before comparison to the levels data.

  • prog – A sequence program to which the code performing the histogram will be appended.

  • debugContext – Optional debug information.

  • options – A list of options to control the operation of the histogram function.

Throws

poplar::invalid_option – If options useFloatArithmetic and useFloatArithmeticWithUnsignedIntOutput are both true.

Returns

A tensor of type unsigned int that contains the levels + 1 histogram results. If the option useFloatArithmetic is “true” the returned tensor will have type float.

void histogram(poplar::Graph &graph, const poplar::Tensor &input, poplar::Tensor &output, bool updateOutput, const poplar::Tensor &levels, bool absoluteOfInput, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Fill a tensor with a histogram representing the statistics of the input tensor.

Performs the same function as histogram() but writes the output to output. This must be one element larger than the levels tensor and have elements of type float or unsigned integer. This function allows histogram results to be accumulated over a number of calls using the updateOutput parameter.

Deprecated Behaviour The determination of the internally used arithmetic based on the type of the output tensor is deprecated.

The usage of output tensor argument of type FLOAT is deprecated.

Histogram options

  • useFloatArithmeticWithUnsignedIntOutput (true, false) [=false]

    If true, use float arithmetic internally and reduce the result to unsigned int. This has the benefit of simplicity and speed, but integer accuracy limited by the 32-bit float data format (integers > 16,777,216 are not all exactly represented).

The useFloatArithmetic option must be false.

Parameters

  • graph – The Poplar graph.

  • input – The input tensor on which to gather histogram statistics.

  • output – The output tensor which will store the histogram results.

  • updateOutput – If true, the histogram counts will be added to the values already in output.

  • levels – The levels defining the comparisons to carry out in generating the histogram output.

  • absoluteOfInput – If true, the absolute value of each input is calculated before comparison to the levels data.

  • prog – A sequence program to which the code performing the histogram will be appended.

  • debugContext – Optional debug information.

  • options – A list of options to control the operation of the histogram function.

Throws

  • poputil::poplibs_error – If option useFloatArithmeticWithUnsignedIntOutput is true and output does not have UNSIGNED_INT type.

  • poplar::invalid_option – If option useFloatArithmetic is true.