MultiConvolution

#include <poplin/MultiConvolution.hpp>

Support performing convolutions in parallel.

namespace poplin

Linear algebra functions.

namespace multiconv

Functions

poplar::Tensor createWeights(poplar::Graph &graph, const std::vector<CreateTensorArgs> &args, unsigned weightsIndex, const poplar::OptionFlags &options = {}, poplin::PlanningCache *cache = nullptr)

Create a specific weights tensor for the multiconvolution.

Parameters

graph – The graph that the tensors will be added to.
args – The same set of parameters as used by convolution().
weightsIndex – Index into args describing the convolution which to create the weights for.
options – Options controlling the implementation.
cache – Optional pointer to a planning cache to use.

Returns

A weights tensor suitable for use with convolution().

poplar::Tensor createInput(poplar::Graph &graph, const std::vector<CreateTensorArgs> &args, unsigned inputIndex, const poplar::OptionFlags &options = {}, poplin::PlanningCache *cache = nullptr)

Create a specific input tensor for the multiconvolution.

Parameters

graph – The graph that the tensors will be added to.
args – The same set of parameters as used by convolution().
inputIndex – Index into args describing the convolution which to create the input for.
options – Options controlling the implementation.
cache – Optional pointer to a planning cache to use.

Returns

A tensor suitable for use as an input to convolution().

void weightsTransposeChansFlipXY(poplar::Graph &graph, std::vector<ConvolutionArgs> &args, const std::vector<poplar::Tensor> &weightsIn, poplar::program::Sequence &prog, const poplar::OptionFlags &options, const poplar::DebugContext &debugContext, poplin::PlanningCache *cache)

For each element in the multi-convolution set, copy the corresponding weightsIn element into the convolution weight input such that each element of the kernel is transposed with respect to the input and output channels and each spatial dimension of the kernel is flipped.

See Convolution.hpp for more information.

Parameters

graph – The graph that the operations will be added to.
args – Collection of inputs, weights, and convolution parameters specifying each convolution in the multiconvolution.
weightsIn – Collection of weights tensor to copy from, the arrangement of which must correspond with the arrangement of the collection of convolution parameters.
prog – Poplar program sequence to append the operations onto.
options – Options controlling the implementation.
debugContext – Optional debug information.
cache – Optional pointer to a planning cache to use.

std::vector<poplar::Tensor> convolution(poplar::Graph &graph, const std::vector<ConvolutionArgs> &args, bool transposeAndFlipWeights, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {}, poplin::PlanningCache *cache = nullptr)

Convolve a set of inputs with a set of weights.

See Convolution.hpp for more information.

Parameters

graph – The graph that the operations will be added to.
args – Collection of inputs, weights, and convolution parameters specifying each convolution in the multiconvolution.
transposeAndFlipWeights – Prepare the weights for the backwards pass.
prog – Poplar program sequence to append the operations onto.
debugContext – Optional debug information.
options – Options controlling the implementation.
cache – Optional pointer to a planning cache to use.

Returns

Set of convolved output tensors.

std::vector<poplar::Tensor> calculateWeightDeltas(poplar::Graph &graph, const std::vector<CalculateWeightDeltasArgs> &args, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {}, poplin::PlanningCache *cache = nullptr)

Append an operation to generate the set of weight delta tensors.

See Convolution.hpp for more information.

Parameters

graph – The graph that the operations will be added to.
args – Collection of zDeltas, activations, and convolution parameters specifying each convolution in the multiconvolution.
prog – Poplar program sequence to append the operations onto.
debugContext – Optional debug information.
options – Options controlling the implementation.
cache – Optional pointer to a planning cache to use.

Returns

Set of weight deltas.

void convolutionWeightUpdate(poplar::Graph &graph, const std::vector<ConvWeightUpdateArgs> &args, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {}, poplin::PlanningCache *cache = nullptr)

Append operations to prog to generate and apply the weight update.

See Convolution.hpp for more information.

Parameters

graph – The graph that the operations will be added to.
args – Collection of zDeltas, activations, scale, and convolution parameters for the weight updates in the multiconvolution.
prog – Poplar program sequence to append the operations onto.
debugContext – Optional debug information.
options – Options controlling the implementation.
cache – Optional pointer to a planning cache to use.

void convolutionWeightUpdate(poplar::Graph &graph, const std::vector<ConvWeightUpdateArgsScalar> &args, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext = {}, const poplar::OptionFlags &options = {}, poplin::PlanningCache *cache = nullptr)

Append operations to prog to generate and apply the weight update.

See Convolution.hpp for more information.

Parameters

graph – The graph that the operations will be added to.
args – Collection of zDeltas, activations, scale, and convolution parameters for the weight updates in the multiconvolution.
prog – Poplar program sequence to append the operations onto.
debugContext – Optional debug information.
options – Options controlling the implementation.
cache – Optional pointer to a planning cache to use.

struct CalculateWeightDeltasArgs

#include <MultiConvolution.hpp>

Param zDeltas: Tensor containing gradients with respect to the output of the convolution.
Param activations: Tensor containing the inputs of the convolution in the forward pass.
Param params: Parameters specifying the convolution.
Param options: Options controlling the implementation.

Public Members

poplar::Tensor zDeltas

poplar::Tensor activations

ConvParams params

poplar::OptionFlags options

struct ConvolutionArgs

#include <MultiConvolution.hpp>

Param in: Input tensor.
Param weights: Weights tensor.
Param params: Parameters specifying the convolution.
Param options: Options controlling the implementation.

Public Members

poplar::Tensor inputs

poplar::Tensor weights

ConvParams params

poplar::OptionFlags options

struct ConvWeightUpdateArgs

#include <MultiConvolution.hpp>

Param zDeltas: Tensor containing gradients with respect to the output of the convolution.
Param weights: Weights tensor.
Param activations: Tensor containing the inputs of the convolution in the forward pass.
Param scale: Scale to apply to the zDeltas.
Param params: Parameters specifying the convolution.
Param options: Options controlling the implementation.

Public Members

poplar::Tensor zDeltas

poplar::Tensor weights

poplar::Tensor activations

poplar::Tensor scale

ConvParams params

poplar::OptionFlags options

struct ConvWeightUpdateArgsScalar

#include <MultiConvolution.hpp>

Param zDeltas: Tensor containing gradients with respect to the output of the convolution.
Param weights: Weights tensor.
Param activations: Tensor containing the inputs of the convolution in the forward pass.
Param scale: Scale to apply to the zDeltas.
Param params: Parameters specifying the convolution.
Param options: Options controlling the implementation.

Public Members

poplar::Tensor zDeltas

poplar::Tensor weights

poplar::Tensor activations

float scale

ConvParams params

poplar::OptionFlags options

struct CreateTensorArgs

#include <MultiConvolution.hpp>

Multi-convolutions allow for a set of convolutions to be executed in parallel.

The benefit of executing convolutions in parallel is an increase in data throughput. Specifically, executing N independent convolutions in parallel will be faster than sequentially executing them because less time is spent on the ~constant vertex overhead per tile.

Note that the allocation of associated tensors for convolutions should be done through the same api such that they are mapped across tiles appropriately for the operation.

See Convolution.hpp for information about convolutions and each individual operation.

Multi-Convolution options

planType (serial, parallel) [=parallel]

Which multi-conv implementation to use. Serial is the same as using the normal API for each convolution.
perConvReservedTiles Integer [=50]

The amount of tiles to reserve for each convolution when planning.
cycleBackOff Double [=0.1]

A percentage, represented as a proportion between 0 and 1 of how much off the fastest plan when attempting to plan the largest convolution using the least amount of tiles.

This number is scaled up according to how many convolutions are being run in parallel.

Param params: Parameters specifying the convolution.
Param options: Options controlling the implementation.
Param name: Debugging name for the tensor.

Public Members

ConvParams params

poplar::OptionFlags options

std::string name