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
andupdate
are only valid with theADD
,SQUARE_ADD
orLOG_ADD
operations.LOG_ADD
performs all arithmetic consistent with the input and output being log probabilities. In other words, theupdate
is another log add operation and thescale
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>floatLOG_ADD
: float>float, half>half, float>half, half>floatMAX
,MIN
: float>float, half>half, int>intLOGICAL_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
andupdate
are only valid with theADD
,SQUARE_ADD
orLOG_ADD
operations.LOG_ADD
performs all arithmetic consistent with the input and output being log probabilities. In other words, theupdate
is another log add operation and thescale
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>floatLOG_ADD
: float>float, half>half, float>half, half>floatMAX
,MIN
: float>float, half>half, int>intLOGICAL_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
andupdate
are only valid with theADD
,SQUARE_ADD
orLOG_ADD
operations.LOG_ADD
performs all arithmetic consistent with the input and output being log probabilities. In other words, theupdate
is another log add operation and thescale
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>floatLOG_ADD
: float>float, half>half, float>half, half>floatMAX
,MIN
: float>float, half>half, int>intLOGICAL_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
andupdate
are only valid with theADD
,SQUARE_ADD
orLOG_ADD
operations.LOG_ADD
performs all arithmetic consistent with the input and output being log probabilities. In other words, theupdate
is another log add operation and thescale
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>floatLOG_ADD
: float>float, half>half, float>half, half>floatMAX
,MIN
: float>float, half>half, int>intLOGICAL_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 ifoutputs
is empty, otherwise it is ignored. Ifoutputs
is empty anduseOutType
isfalse
then the output element type will be set to the same element type as the correspondingin
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 hasparams.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
ormul
).Public Functions

ReduceParams() = default

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 thanout = reduce(in)
.

ReduceParams() = default

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
Public Members

ReduceParams params

bool useOutType
Note that if
useOutType
isfalse
then the element type ofin
is used.Also note that
OutType
is ignored if theoutputs
vector is not empty when calling reduceMany().

ReduceParams params

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