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

  • useFloatArithmetic (true, false) [=false]

    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).

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.

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 = {})

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. The type of the output tensor will determine the type of arithmetic used internally, as described above.

This function allows histogram results to be accumulated over a number of calls using the updateOutput parameter.

Parameters

  • graph – The Poplar graph.

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

  • input – 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.