Reduce

#include <popops/Reduce.hpp>

Define types of operations used in a reduce.

namespace popops

Common functions, such as elementwise and reductions.

Unnamed Group

poplar::Tensor reduce(poplar::Graph &graph, const poplar::Tensor &in, const poplar::Type &outType, const std::vector<std::size_t> &dims, ReduceParams params, std::vector<poplar::ComputeSet> &css, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Apply a reduction operation to a tensor.

Deprecated:

The reduce overloads that expect a vector of compute sets are deprecated. Please use the reduceMany() function instead.

These are alternate forms that add their vertices to a vector of compute sets instead of a poplar::program::Sequence. The caller is expected to add each compute set to a poplar::program::Sequence (in a poplar::program::Execute) themselves, like this: 

Sequence seq;
std::vector<ComputeSet> css;
auto A = reduce(..., css);
auto B = reduce(..., css);
for (const auto &cs : css) {
  seq.add(Execute(cs));

This allows you to do multiple reductions in parallel. Note that the reductions are not aware of each other, so it may be more efficient to concatenate tensors and do a single reduction instead if they have the same shape, operation, and input and output types.

scale and update are only valid with the ADD , SQUARE_ADD or LOG_ADD operations. LOG_ADD performs all arithmetic consistent with the input and output being log probabilities. In other words, the update is another log add operation and the scale is a log multiply operation.

Internally, this creates a new variable for the output then calls reduceWithOutput(). The type of the output will be outType.

The options parameter accepts the following:

  • accumType.interTile (float, half)

    The type to use for intermediate values between tiles. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

  • accumType.inVertex (float, half)

    The type to use for intermediate values within a vertex. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

If either of the above options are not set then the intermediate type will default to either the input tensor element type or float if the input is of type half and the reduction operation benefits from higher precision (for example, add).

The input and output types that are supported depend on the operation:

  • ADD, SQUARE_ADD, MUL: float->float, half->half, int->int, float->half, half->float

  • LOG_ADD : float->float, half->half, float->half, half->float

  • MAX, MIN: float->float, half->half, int->int

  • LOGICAL_AND, LOGICAL_OR: bool->bool

Parameters

  • graph – The graph to add the operation to.

  • in – The tensor to be reduced.

  • outType – The output type of the reduce operation.

  • dims – The dimensions to reduce in.

  • prog – The program sequence to add the operation to.

  • debugContext – Optional debug information.

poplar::Tensor reduce(poplar::Graph &graph, const poplar::Tensor &in, const std::vector<std::size_t> &dims, ReduceParams params, std::vector<poplar::ComputeSet> &css, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})
void reduceWithOutput(poplar::Graph &graph, const poplar::Tensor &in, const poplar::Tensor &out, const std::vector<std::size_t> &dims, ReduceParams params, std::vector<poplar::ComputeSet> &css, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Functions

poplar::Tensor reduce(poplar::Graph &graph, const poplar::Tensor &in, const poplar::Type &outType, const std::vector<std::size_t> &dims, ReduceParams params, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Apply a reduction operation to a tensor.

scale and update are only valid with the ADD , SQUARE_ADD or LOG_ADD operations. LOG_ADD performs all arithmetic consistent with the input and output being log probabilities. In other words, the update is another log add operation and the scale is a log multiply operation.

Internally, this creates a new variable for the output then calls reduceWithOutput(). The type of the output will be outType.

The options parameter accepts the following:

  • accumType.interTile (float, half)

    The type to use for intermediate values between tiles. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

  • accumType.inVertex (float, half)

    The type to use for intermediate values within a vertex. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

If either of the above options are not set then the intermediate type will default to either the input tensor element type or float if the input is of type half and the reduction operation benefits from higher precision (for example, add).

The input and output types that are supported depend on the operation:

  • ADD, SQUARE_ADD, MUL: float->float, half->half, int->int, float->half, half->float

  • LOG_ADD : float->float, half->half, float->half, half->float

  • MAX, MIN: float->float, half->half, int->int

  • LOGICAL_AND, LOGICAL_OR: bool->bool

Parameters

  • graph – The graph to add the operation to.

  • in – The tensor to be reduced.

  • outType – The output type of the reduce operation.

  • dims – The dimensions to reduce in.

  • prog – The program sequence to add the operation to.

  • debugContext – Optional debug information.

poplar::Tensor reduce(poplar::Graph &graph, const poplar::Tensor &in, const std::vector<std::size_t> &dims, ReduceParams params, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Apply a reduction operation to a tensor.

An alias for reduce(graph, in, in.elementType(), …)

scale and update are only valid with the ADD , SQUARE_ADD or LOG_ADD operations. LOG_ADD performs all arithmetic consistent with the input and output being log probabilities. In other words, the update is another log add operation and the scale is a log multiply operation.

Internally, this creates a new variable for the output then calls reduceWithOutput(). The type of the output will be outType.

The options parameter accepts the following:

  • accumType.interTile (float, half)

    The type to use for intermediate values between tiles. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

  • accumType.inVertex (float, half)

    The type to use for intermediate values within a vertex. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

If either of the above options are not set then the intermediate type will default to either the input tensor element type or float if the input is of type half and the reduction operation benefits from higher precision (for example, add).

The input and output types that are supported depend on the operation:

  • ADD, SQUARE_ADD, MUL: float->float, half->half, int->int, float->half, half->float

  • LOG_ADD : float->float, half->half, float->half, half->float

  • MAX, MIN: float->float, half->half, int->int

  • LOGICAL_AND, LOGICAL_OR: bool->bool

Parameters

  • graph – The graph to add the operation to.

  • in – The tensor to be reduced.

  • outType – The output type of the reduce operation.

  • dims – The dimensions to reduce in.

  • prog – The program sequence to add the operation to.

  • debugContext – Optional debug information.

void reduceWithOutput(poplar::Graph &graph, const poplar::Tensor &in, const poplar::Tensor &out, const std::vector<std::size_t> &dims, ReduceParams params, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Apply a reduction operation to a tensor.

This is similar to reduce() but allows you to specify the output. If the tile mapping of out is not complete it will be set. Otherwise it won’t be changed.

scale and update are only valid with the ADD , SQUARE_ADD or LOG_ADD operations. LOG_ADD performs all arithmetic consistent with the input and output being log probabilities. In other words, the update is another log add operation and the scale is a log multiply operation.

Internally, this creates a new variable for the output then calls reduceWithOutput(). The type of the output will be outType.

The options parameter accepts the following:

  • accumType.interTile (float, half)

    The type to use for intermediate values between tiles. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

  • accumType.inVertex (float, half)

    The type to use for intermediate values within a vertex. If the type specified is smaller than the output type then the option is ignored and the output type is used instead.

If either of the above options are not set then the intermediate type will default to either the input tensor element type or float if the input is of type half and the reduction operation benefits from higher precision (for example, add).

The input and output types that are supported depend on the operation:

  • ADD, SQUARE_ADD, MUL: float->float, half->half, int->int, float->half, half->float

  • LOG_ADD : float->float, half->half, float->half, half->float

  • MAX, MIN: float->float, half->half, int->int

  • LOGICAL_AND, LOGICAL_OR: bool->bool

Parameters

  • graph – The graph to add the operation to.

  • in – The tensor to be reduced.

  • outType – The output type of the reduce operation.

  • dims – The dimensions to reduce in.

  • prog – The program sequence to add the operation to.

  • debugContext – Optional debug information.

void reduceMany(poplar::Graph &graph, const std::vector<SingleReduceOp> &reductions, std::vector<poplar::Tensor> &outputs, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {})

Perform many reductions (in parallel if possible).

Please see the documentation for reduce() for details of the common inputs.

Parameters

  • reductions – The inputs to each reduction to perform. The outType attribute controls the element type of the output tensor if outputs is empty, otherwise it is ignored. If outputs is empty and useOutType is false then the output element type will be set to the same element type as the corresponding in tensor.

  • outputs – The tensors to store the output of the reductions. This may be empty in which case reduceMany will create the tensors. If the tile mapping is not set or not complete it will be set completely by this function.

Throws

  • poputils::poplibs_error – If outputs is not empty then its size must exactly match the size of reductions else an exception will be thrown.

  • poputils::poplibs_error – If outputs is empty and any reduction has params.update set to true then an exception will be thrown. outputs is required to perform an update reduction.

struct ReduceParams
#include <Reduce.hpp>

Stores parameters for the reduce operation, as well as the basic operation being performed (for example, add or mul).

Public Functions

ReduceParams() = default
inline ReduceParams(popops::Operation op, bool update = false)
inline ReduceParams(popops::Operation op, bool update, poplar::Tensor scale)

Define the details of the reduce operation that will be performed by the reduce() and reduceWithOutput() functions.

Parameters

  • op – The reduce operation to use.

  • scale – Can (optionally) scale the output.

  • update – Specify that the output should be updated, where out += reduce(in) rather than out = reduce(in).

ReduceParams(popops::Operation op, float constantScale, bool update = false) = delete

Public Members

popops::Operation op
bool update
bool useScale
poplar::Tensor scale
struct SingleReduceOp
#include <Reduce.hpp>

The parameterisation of the inputs to a single reduction for the reduceMany() function.

Please see the documentation for reduce() for a description of the struct members.

Public Functions

inline SingleReduceOp(poplar::Tensor in, std::vector<std::size_t> dims, ReduceParams params, poplar::Type outType, std::string debugName = "")
inline SingleReduceOp(poplar::Tensor in, std::vector<std::size_t> dims, ReduceParams params, std::string debugName = "")

Public Members

poplar::Tensor in
std::vector<std::size_t> dims
ReduceParams params
bool useOutType

Note that if useOutType is false then the element type of in is used.

Also note that OutType is ignored if the outputs vector is not empty when calling reduceMany().

poplar::Type outType
std::string debugName