Functions for Recurrent Neural Networks (RNN) More...

Classes
struct	RnnParams
	Structure of Recurrent Neural Network (RNN) parameters which allows for any customized implementation of the cellular part of the RNN. More...

struct	RnnSlice
	Tensors required for processing a single time step. More...

struct	StateSequence
	Structure that associates a particular state tensor with a user-defined output tensor. More...

Typedefs
using	LoopBodyType = std::function< poplar::program::Sequence(poplar::Graph &graph, const TimeStepState &time, const RnnBatchwiseFlags &, std::vector< poplar::Tensor > &, const RnnSlice &slice, std::vector< poplar::Tensor > &, poplar::program::Sequence *, const poplar::DebugNameAndId &)>
	Create loop body function for the given shard. More...

using	GatherBodyType = std::function< poplar::program::Sequence(poplar::Graph &graph, const RnnSlice &slice, unsigned stepsPerGather, poplar::program::Sequence *, const poplar::DebugNameAndId &)>
	Create gather body function for the given shard. More...

Functions
std::vector< std::pair< poplin::MatMulParams, poplar::OptionFlags > >	getMatMulPrePlanParameters (std::size_t numSteps, std::size_t batchSize, std::size_t inputSize, std::size_t outputSize, const poplar::Type &dType, const poplar::Type &partialsType=poplar::FLOAT, bool inferenceOnly=false, bool hasFeedforwardWeights=true)
	Predict what matrix multiplications will be needed for the given parameters and return list of corresponding matmul parameters and options.

uint64_t	getFwdFlops (unsigned sequenceSize, unsigned batchSize, unsigned inputSize, unsigned outputSize, bool weightInput=true)
	Compute the total floating point operations for the forward pass of RNN.

uint64_t	getBwdFlops (unsigned sequenceSize, unsigned batchSize, unsigned inputSize, unsigned outputSize, bool calcInputGrad=true)
	Compute the total floating point operations for the backward pass of RNN.

uint64_t	getWuFlops (unsigned sequenceSize, unsigned batchSize, unsigned inputSize, unsigned outputSize)
	Compute the total floating point operations for the weight update pass of RNN.

poplar::Tensor	createInput (poplar::Graph &graph, unsigned numSteps, unsigned batchSize, unsigned inputSize, unsigned outputSize, const poplar::Type &dType, const poplar::Type &partialsType=poplar::FLOAT, bool inferenceOnly=false, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Create a tensor which is input to a vanilla RNN. More...

poplar::Tensor	createFwdState (poplar::Graph &graph, const poplar::Type &dType, unsigned batchSize, unsigned outputSize, poplar::program::Sequence &prog, bool initState, bool inferenceOnly, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Create initial state for a vanilla RNN. More...

poplar::Tensor	getOutputFromFwdState (const poplar::Tensor &fwdState)
	Extract previous output tensor from the hidden state. More...

poplar::Tensor	createWeightsInput (poplar::Graph &graph, unsigned sequenceSize, unsigned batchSize, unsigned inputSize, unsigned outputSize, const poplar::Type &dType, const poplar::Type &partialsType=poplar::FLOAT, bool inferenceOnly=false, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Create the weights used to weight the input of a vanilla RNN layer. More...

poplar::Tensor	createWeightsFeedback (poplar::Graph &graph, unsigned batchSize, unsigned outputSize, const poplar::Type &dType, const poplar::Type &partialsType=poplar::FLOAT, bool inferenceOnly=false, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Create the weights used in the recurrent part of a vanilla RNN layer. More...

poplar::Tensor	forwardWeightInput (poplar::Graph &graph, const poplar::Tensor &actIn, const poplar::Tensor &weights, poplar::program::Sequence &prog, const poplar::Type &partialsType=poplar::FLOAT, bool inferenceOnly=false, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Perform the feedforward part of a RNN layer. More...

poplar::Tensor	forwardIterate (poplar::Graph &graph, const poplar::Tensor &feedFwdIn, const poplar::Tensor &initState, const poplar::Tensor &feedbackWeights, const poplar::Tensor &biases, poplar::program::Sequence &prog, popnn::NonLinearityType nonLinearityType, const poplar::Type &partialsType=poplar::FLOAT, bool inferenceOnly=false, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Perform the feedback part of the RNN layer. More...

poplar::Tensor	createBwdState (poplar::Graph &graph, const poplar::Type &dType, unsigned batchSize, unsigned outputSize, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Create initial state for backward pass of a vanilla RNN. More...

std::pair< poplar::Tensor, poplar::Tensor >	backwardGradientStep (poplar::Graph &graph, const poplar::Tensor &nextLayerGrad, const poplar::Tensor &bwdState, const poplar::Tensor &actOut, const poplar::Tensor &weightsInput, const poplar::Tensor &weightsFeedback, poplar::program::Sequence &prog, popnn::NonLinearityType nonLinearityType, const poplar::Type &partialsType=poplar::FLOAT, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Compute a single step of the backward pass of a vanilla RNN layer. More...

poplar::Tensor	backwardGradientStep (poplar::Graph &graph, const poplar::Tensor &nextLayerGrad, const poplar::Tensor &bwdState, const poplar::Tensor &actOut, const poplar::Tensor &weightsFeedback, poplar::program::Sequence &prog, popnn::NonLinearityType nonLinearityType, const poplar::Type &partialsType=poplar::FLOAT, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Same as backwardGradientStep(poplar::Graph&, const poplar::Tensor&, const poplar::Tensor&, const poplar::Tensor&, const poplar::Tensor&, const poplar::Tensor &, poplar::program::Sequence&, popnn::NonLinearityType, const poplar::Type&, const poplar::DebugContext&, poplin::PlanningCache*) with the difference that the input gradients are not computed.

void	paramDeltaUpdate (poplar::Graph &graph, const poplar::Tensor &bwdState, const poplar::Tensor &actIn, const poplar::Tensor &prevOut, poplar::Tensor &weightsInputDeltasAcc, poplar::Tensor &weightsFeedbackDeltasAcc, poplar::Tensor &biasDeltasAcc, poplar::program::Sequence &prog, const poplar::Type &partialsType=poplar::FLOAT, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Update parameter deltas for a vanilla RNN step. More...

poplar::Tensor	rnnFwdSequence (poplar::Graph &graph, poplar::program::Sequence &prog, const poplar::Tensor &fwdStateInit, const poplar::Tensor weightedIn, const poplar::Tensor &biases, const poplar::Tensor &feedFwdWeights, const poplar::Tensor &feedbackWeights, const poplar::Tensor &prevLayerActs, const popnn::NonLinearityType &nonLinearityType, const poplar::Type &partialsType, bool inferenceOnly, const poplar::DebugContext &debugContext={}, poplin::PlanningCache planningCache=nullptr)
	Perform the forward part of the RNN layer. More...

std::tuple< poplar::Tensor, poplar::Tensor, poplar::Tensor, poplar::Tensor >	rnnBwdSequence (poplar::Graph &graph, bool doWU, bool ignoreInputGradientCalc, poplar::program::Sequence &prog, const poplar::Tensor &fwdStateInit, const poplar::Tensor &fwdState, const poplar::Tensor &biases, const poplar::Tensor &feedFwdWeights, const poplar::Tensor &feedbackWeights, const poplar::Tensor &outGradient, const poplar::Tensor &actIn, const popnn::NonLinearityType &nonLinearityType, const poplar::Type &partialsType, const poplar::DebugContext &debugContext={}, poplin::PlanningCache *planningCache=nullptr)
	Perform the feedback part of the RNN layer. More...

poplar::Tensor	createInitialState (poplar::Graph &graph, const RnnParams &params, bool isOutput, unsigned multiple, unsigned numShards, const poplar::DebugContext &debugContext={})
	Create state tensor to be used in all recurrences of the RNN. More...

poplar::Tensor	createRecurrentTensor (poplar::Graph &graph, const RnnParams &params, unsigned size, unsigned numShards, const poplar::DebugContext &debugContext={})
	Create recurrent tensor of shape [`timeSteps`, `batchSize`, `size`] suitable for slicing and/or sharding of the outermost dimension. More...

poplar::Tensor	createInputTensor (poplar::Graph &graph, const RnnParams &params, unsigned numShards, const poplar::DebugContext &debugContext={})
	Create input tensor of shape [`timeSteps`, `batchSize`, `inputSize`] suitable for slicing and/or sharding of the outermost dimension. More...

poplar::Tensor	createOutputTensor (poplar::Graph &graph, const RnnParams &params, unsigned numShards, const poplar::DebugContext &debugContext={})
	Create a standard output tensor of shape [`timeSteps`, `batchSize`, `outputSize`] suitable for slicing and/or sharding of the outermost dimension. More...

poplar::Tensor	createOutputTensor (poplar::Graph &graph, const RnnParams &params, unsigned multiple, unsigned numShards, const poplar::DebugContext &debugContext={})
	Create a single output tensor with `multiple` (standard) output tensors concatenated along the outermost (`timeSteps`) dimension. More...

poplar::Tensor	shiftRnnTensor (poplar::Graph &graph, const RnnParams &params, const poplar::Tensor &tBase, const poplar::Tensor &tSingle, poplar::program::Sequence &prog, unsigned numShards, const poplar::DebugContext &debugContext={})
	Create a single-step shifted RNN tensor from an input tensor. More...

std::vector< poplar::Tensor >	Rnn (poplar::Graph &graph, const RnnParams &params, bool reverse, const std::vector< poplar::Tensor > &initState, const StateSequence &stateSequence, const std::vector< poplar::Tensor > &inputs, const poplar::Tensor interimIn, poplar::Tensor interimOut, const std::vector< poplar::Tensor > &outputs, const std::vector< poplar::Tensor > &created, poplar::program::Sequence &prog, const LoopBodyType &loopFn, unsigned numShards, poplar::OptionFlags &options, const poplar::DebugContext &debugContext={})
	Run custom Recurrent Neural Net cell implementation recurrently. More...

std::vector< poplar::Tensor >	Rnn (poplar::Graph &graph, const RnnParams &params, const std::vector< poplar::Tensor > &initState, const StateSequence &stateSequence, const std::vector< poplar::Tensor > &inputs, const poplar::Tensor &interimIn, const unsigned numTemps, poplar::program::Sequence &prog, const LoopBodyType &loopFn, const std::vector< poplar::Tensor > &gatherInputs, const GatherBodyType &gatherFn, unsigned numShards, unsigned stepsPerGather, poplar::OptionFlags &options, const poplar::DebugContext &debugContext={})
	Run custom Recurrent Neural Net cell callback at every time step in decrementing order. More...

Detailed Description

Functions for Recurrent Neural Networks (RNN)

Typedef Documentation

◆ GatherBodyType

using popnn::rnn::GatherBodyType = typedef std::function<poplar::program::Sequence( poplar::Graph &graph, const RnnSlice &slice, unsigned stepsPerGather, poplar::program::Sequence *, const poplar::DebugNameAndId &)>

Create gather body function for the given shard.

Parameters

graph	The graph object
slice	The input/output tensors for a specific shard
stepsPerGather	The time step interval between calls to this function.
prog	The program initialization sequence
dnai	Debug name and Id

Returns: Gather body function for the given shard.

◆ LoopBodyType

using popnn::rnn::LoopBodyType = typedef std::function<poplar::program::Sequence( poplar::Graph &graph, const TimeStepState &time, const RnnBatchwiseFlags &, std::vector<poplar::Tensor> &, const RnnSlice &slice, std::vector<poplar::Tensor> &, poplar::program::Sequence *, const poplar::DebugNameAndId &)>

Create loop body function for the given shard.

Parameters

graph	The graph object.
shardIdx	The tensor that specifies the starting sequence index for the current shard.
seqIdx	The tensor that iterates over the range of input sequences that are mapped on the current shard, beginning from 0.
batchwiseFlags	Flags that indicate batches for which the current step is within the batchwise step limit.
state	State tensors.
slice	The input/output tensors for a specific shard.
created	The output tensors which are created by this function.
prog	The program initialization sequence.
dnai	Debug name and Id.

Returns: Loop body function for the given shard.

Function Documentation

◆ backwardGradientStep()

std::pair< poplar::Tensor, poplar::Tensor > popnn::rnn::backwardGradientStep	(	poplar::Graph &	graph,
		const poplar::Tensor &	nextLayerGrad,
		const poplar::Tensor &	bwdState,
		const poplar::Tensor &	actOut,
		const poplar::Tensor &	weightsInput,
		const poplar::Tensor &	weightsFeedback,
		poplar::program::Sequence &	prog,
		popnn::NonLinearityType	nonLinearityType,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Compute a single step of the backward pass of a vanilla RNN layer.

Two gradient outputs are produced. The first gradient is at the input of the RNN layer for the step. The second gradient is at the adder and can be used to backward propagate through the earlier steps.

Parameters

graph	The graph object.
nextLayerGrad	The loss gradient fed as input to this step.
bwdState	The gradient state for the previous step.
actOut	The output activation.
weightsInput	The input weights.
weightsFeedback	The feedback weights.
prog	The control program to which programs are added.
nonLinearityType	The type of non-linearity.
partialsType	The data type used in intermediate calculations.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: A pair of tensors. The first tensor is the loss gradient at the input layer. The second tensor is the backward state needed to run the next backward step.

◆ createBwdState()

poplar::Tensor popnn::rnn::createBwdState	(	poplar::Graph &	graph,
		const poplar::Type &	dType,
		unsigned	batchSize,
		unsigned	outputSize,
		poplar::program::Sequence &	prog,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Create initial state for backward pass of a vanilla RNN.

Parameters

graph	The graph object.
dType	The data type of the created tensor.
batchSize	The number of batch elements processed.
outputSize	The number of output activations.
prog	The control program.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: Tile mapped initial state tensor.

◆ createFwdState()

poplar::Tensor popnn::rnn::createFwdState	(	poplar::Graph &	graph,
		const poplar::Type &	dType,
		unsigned	batchSize,
		unsigned	outputSize,
		poplar::program::Sequence &	prog,
		bool	initState,
		bool	inferenceOnly,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Create initial state for a vanilla RNN.

The state, apart from the activations, is initialised by the control program.

The number of hidden states may depend on whether the RNN is used for inference or training.

Parameters

graph	The graph object.
dType	The data type of the created tensor.
batchSize	The number of batch elements.
outputSize	The output (hidden) of each sequence element.
prog	The control program.
initState	If true, indicates that the state should be initialised.
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore backwards and weight update passes.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: A 2D tensor of shape [batchSize, outputSize]

◆ createInitialState()

poplar::Tensor popnn::rnn::createInitialState	(	poplar::Graph &	graph,
		const RnnParams &	params,
		bool	isOutput,
		unsigned	multiple,
		unsigned	numShards,
		const poplar::DebugContext &	debugContext = `{}`
	)

Create state tensor to be used in all recurrences of the RNN.

The tensor shape is [multiple, batchSize, size] where size is determined by whether the state tensor is an input or output tensor, depending on isOutput. If the RNN is sharded, a tensor of this shape is created for each shard.

Parameters

graph	The graph object.
params	The RNN parameters.
isOutput	Flag that indicates that the state tensor will be an output tensor. If false, indicates that this is an input tensor.
multiple	The number of state variables that are concatenated into a single state tensor.
numShards	The number of shards to be used.
debugContext	Debug information.

Returns: State tensor of shape [multiple, batchSize, size].

◆ createInput()

poplar::Tensor popnn::rnn::createInput	(	poplar::Graph &	graph,
		unsigned	numSteps,
		unsigned	batchSize,
		unsigned	inputSize,
		unsigned	outputSize,
		const poplar::Type &	dType,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		bool	inferenceOnly = `false`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Create a tensor which is input to a vanilla RNN.

The layout of the tensor is best for a multiplication of the input weight matrix with the given number of steps.

Parameters

graph	The graph object.
numSteps	The number of steps used in the forward weighting of the input.
batchSize	The number of batch elements.
inputSize	The size of the input for each sequence step.
outputSize	The output (hidden) size of each sequence element.
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore the backwards and weight update passes.
dType	The data type of the created tensor.
partialsType	The data type of intermediate calculations.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: Tensor of shape [numSteps, batchSize, inputSize]

◆ createInputTensor()

poplar::Tensor popnn::rnn::createInputTensor	(	poplar::Graph &	graph,
		const RnnParams &	params,
		unsigned	numShards,
		const poplar::DebugContext &	debugContext = `{}`
	)

Create input tensor of shape [timeSteps, batchSize, inputSize] suitable for slicing and/or sharding of the outermost dimension.

Parameters

graph	The graph object.
params	The RNN parameters.
numShards	The number of shards to be used.
debugContext	Debug information.

Returns: Input tensor of shape [timeSteps, batchSize, inputSize].

◆ createOutputTensor() [1/2]

poplar::Tensor popnn::rnn::createOutputTensor	(	poplar::Graph &	graph,
		const RnnParams &	params,
		unsigned	multiple,
		unsigned	numShards,
		const poplar::DebugContext &	debugContext = `{}`
	)

Create a single output tensor with multiple (standard) output tensors concatenated along the outermost (timeSteps) dimension.

The concatenated tensor is of shape [multiple * timeSteps, batchSize, outputSize] which is suitable for slicing and/or sharding along the outermost dimension.

Parameters

graph	The graph object.
params	The RNN parameters.
multiple	The number of standard output tensors to be concatenated.
numShards	The number of shards to be used.
debugContext	Debug information.

Returns: Output tensor of shape [multiple * timeSteps, batchSize, outputSize].

◆ createOutputTensor() [2/2]

poplar::Tensor popnn::rnn::createOutputTensor	(	poplar::Graph &	graph,
		const RnnParams &	params,
		unsigned	numShards,
		const poplar::DebugContext &	debugContext = `{}`
	)

Create a standard output tensor of shape [timeSteps, batchSize, outputSize] suitable for slicing and/or sharding of the outermost dimension.

Parameters

graph	The graph object.
params	The RNN parameters.
numShards	The number of shards to be used.
debugContext	Debug information.

Returns: Output tensor of shape [timeSteps, batchSize, outputSize].

◆ createRecurrentTensor()

poplar::Tensor popnn::rnn::createRecurrentTensor	(	poplar::Graph &	graph,
		const RnnParams &	params,
		unsigned	size,
		unsigned	numShards,
		const poplar::DebugContext &	debugContext = `{}`
	)

Create recurrent tensor of shape [timeSteps, batchSize, size] suitable for slicing and/or sharding of the outermost dimension.

Parameters

graph	The graph object.
params	The RNN parameters.
size	The innermost dimension of the tensor.
numShards	The number of shards to be used.
debugContext	Debug information.

Returns: Recurrent tensor of shape [timeSteps, batchSize, size].

◆ createWeightsFeedback()

poplar::Tensor popnn::rnn::createWeightsFeedback	(	poplar::Graph &	graph,
		unsigned	batchSize,
		unsigned	outputSize,
		const poplar::Type &	dType,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		bool	inferenceOnly = `false`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Create the weights used in the recurrent part of a vanilla RNN layer.

Parameters

graph	The graph object.
batchSize	The number of batch elements.
outputSize	The output (hidden) size of each sequence.
dType	The data type of the created tensor.
partialsType	The data type of partial results in the computation
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore backwards and weight update passes.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

◆ createWeightsInput()

poplar::Tensor popnn::rnn::createWeightsInput	(	poplar::Graph &	graph,
		unsigned	sequenceSize,
		unsigned	batchSize,
		unsigned	inputSize,
		unsigned	outputSize,
		const poplar::Type &	dType,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		bool	inferenceOnly = `false`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Create the weights used to weight the input of a vanilla RNN layer.

The best tile mapping of the weight tensor is when it matches the sequence size in the input activation tensor used to multiply the input weights.

Parameters

graph	The graph object.
sequenceSize	The number of sequence steps used in the forward weighting of the input. The best tile mapping is when this matches the sequence size of the input activation tensor.
batchSize	The number of batch elements.
inputSize	The input size of each sequence.
outputSize	The output (hidden) size of each sequence.
dType	The data type of the created tensor.
partialsType	The data type of partial results in the computation.
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore backwards and weight update passes.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

◆ forwardIterate()

poplar::Tensor popnn::rnn::forwardIterate	(	poplar::Graph &	graph,
		const poplar::Tensor &	feedFwdIn,
		const poplar::Tensor &	initState,
		const poplar::Tensor &	feedbackWeights,
		const poplar::Tensor &	biases,
		poplar::program::Sequence &	prog,
		popnn::NonLinearityType	nonLinearityType,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		bool	inferenceOnly = `false`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Perform the feedback part of the RNN layer.

The feedback part of the RNN layer must be preceded by the feedforward part of the RNN layer to complete the layer.

See also: forwardWeightInput

The following definitions apply:

numSteps is the number of steps.
batchSize is the number of batch elements.
inputSize is the size of the input for each step.
outputSize is the size of the output for each step.

Parameters

graph	The graph object.
feedFwdIn	The input to this function (output from the feedforward part of the RNN layer.
initState	The initial state of the RNN layer, which means the the previous output.
feedbackWeights	The feedback weights.
biases	The biases.
prog	The program sequence. Programs added by this function are appended to this program sequence.
nonLinearityType	The non linearity used for the output activations
partialsType	The data type for intermediates.
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore backwards and weight update passes.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: The output activations of the RNN layer.

◆ forwardWeightInput()

poplar::Tensor popnn::rnn::forwardWeightInput	(	poplar::Graph &	graph,
		const poplar::Tensor &	actIn,
		const poplar::Tensor &	weights,
		poplar::program::Sequence &	prog,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		bool	inferenceOnly = `false`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Perform the feedforward part of a RNN layer.

The feedforward part of the RNN layer must be followed by the feedback part to complete the RNN layer. In other words, the output must be fed as the feedforward input to the feedback part.

See also: forwardIterate

The following definitions apply:

numSteps is the number of sequence steps.
batchSize is the number of batch elements.
inputSize is the size of the input for each step.
outputSize is the size of the output for each step.

Parameters

graph	The graph object.
actIn	The input activation tensor with shape [`numSteps`, `batchSize`, `inputSize`].
weights	Feedforward weights with shape [`outputSize`, `inputSize`].
prog	The program sequence. Programs added by this function are appended to this program sequence.
partialsType	The data type for intermediates.
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore backwards and weight update passes.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: The output tensor with shape [numSteps, batchSize, outputSize].

◆ getOutputFromFwdState()

poplar::Tensor popnn::rnn::getOutputFromFwdState ( const poplar::Tensor & fwdState )

Extract previous output tensor from the hidden state.

The returned tensor is a view of the tensor and can be used to initialise the tensor, if required.

◆ paramDeltaUpdate()

void popnn::rnn::paramDeltaUpdate	(	poplar::Graph &	graph,
		const poplar::Tensor &	bwdState,
		const poplar::Tensor &	actIn,
		const poplar::Tensor &	prevOut,
		poplar::Tensor &	weightsInputDeltasAcc,
		poplar::Tensor &	weightsFeedbackDeltasAcc,
		poplar::Tensor &	biasDeltasAcc,
		poplar::program::Sequence &	prog,
		const poplar::Type &	partialsType = `poplar::FLOAT`,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Update parameter deltas for a vanilla RNN step.

The parameter deltas updated are:

Feedback Weights
Input Weights
Bias The new deltas computed for this step are added to the accumulated deltas from previous steps. The caller must zero the accumulated tensors at the first call if the tensors to maintain the result are in-place.

Parameters

graph	The graph object.
bwdState	The gradient state for this step.
actIn	The input activations for this step.
prevOut	The previous RNN output activations for this step.
weightsInputDeltasAcc	The previous weights input deltas tensor. This tensor must be tile-mapped. The deltas from this step are added to this tensor.
weightsFeedbackDeltasAcc	The previous feedback weights deltas tensor. This tensor must be tile-mapped. The deltas from this step are added to this tensor.
biasDeltasAcc	The previous bias deltas tensor. This tensor must be tile-mapped. The deltas from this step are added to this tensor.
prog	The control program to which programs are added.
partialsType	The data type used in intermediate calculations.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

◆ Rnn() [1/2]

std::vector< poplar::Tensor > popnn::rnn::Rnn	(	poplar::Graph &	graph,
		const RnnParams &	params,
		bool	reverse,
		const std::vector< poplar::Tensor > &	initState,
		const StateSequence &	stateSequence,
		const std::vector< poplar::Tensor > &	inputs,
		const poplar::Tensor *	interimIn,
		poplar::Tensor *	interimOut,
		const std::vector< poplar::Tensor > &	outputs,
		const std::vector< poplar::Tensor > &	created,
		poplar::program::Sequence &	prog,
		const LoopBodyType &	loopFn,
		unsigned	numShards,
		poplar::OptionFlags &	options,
		const poplar::DebugContext &	debugContext = `{}`
	)

Run custom Recurrent Neural Net cell implementation recurrently.

RNN options

codeReuse (true, false) [=false]

If true, the custom RNN implementation defined by the loopFn parameter will be reused by every shard. If false, the RNN code is duplicated for every shard.

Parameters

graph	The graph to which the RNN cell belongs.
params	The RNN parameters.
reverse	Process tensors in reverse order, so beginning with the last element.
initState	The state tensors that specify the initial states.
stateSequence	Optionally, specify that the recurrent updates of a state tensor need to be stored in a user-defined output tensor.
inputs	The input tensors for each recurrence.
*interimIn	Pointer to the intermediate inputs to cell computation.
*interimOut	Pointer to the intermediate outputs from cell computation.
output	The output tensor for each recurrence. Each tensor must be defined prior to calling Rnn().
created	The output tensor that is allocated by the custom implementation defined in `loopFn`.
prog	Program sequence.
loopFn	The loop body function for RNN cell computation which is invoked for every shard.
numShards	The number of shards to be used.
options	The RNN implementation options. See createInput().
debugContext	Optional debug information.

◆ Rnn() [2/2]

std::vector< poplar::Tensor > popnn::rnn::Rnn	(	poplar::Graph &	graph,
		const RnnParams &	params,
		const std::vector< poplar::Tensor > &	initState,
		const StateSequence &	stateSequence,
		const std::vector< poplar::Tensor > &	inputs,
		const poplar::Tensor &	interimIn,
		const unsigned	numTemps,
		poplar::program::Sequence &	prog,
		const LoopBodyType &	loopFn,
		const std::vector< poplar::Tensor > &	gatherInputs,
		const GatherBodyType &	gatherFn,
		unsigned	numShards,
		unsigned	stepsPerGather,
		poplar::OptionFlags &	options,
		const poplar::DebugContext &	debugContext = `{}`
	)

Run custom Recurrent Neural Net cell callback at every time step in decrementing order.

At each time step, create a temporary variable and pass it to the gatherFn callback function which gets called at a time step interval determined by the stepsPerGather parameter.

RNN options

codeReuse (true, false) [=false]

If true, the custom RNN implementation defined by the loopFn parameter will be reused by every shard. If false, the RNN code is duplicated for every shard.

Parameters

graph	The graph to which the RNN cell belongs.
params	The RNN parameters.
initState	The state tensors that specify the initial states.
stateSequence	Optionally, specify that the recurrent updates of a state tensor need to be stored in a user-defined output tensor.
inputs	The input tensors to the loop body function `loopFn`
interimIn	The intermediate inputs to cell computation.
numTemps	The number of temporary variables of shape [`batchSize`, size] per time step which are to be passed to the `gatherFn` callback function.
prog	Program sequence.
loopFn	Function for RNN cell computation which is invoked for every time step.
gatherInputs	The input tensors to the gather body function `gatherFn`.
gatherFn	The gather body function which processes the temporary buffer generated by the loop body function `loopFn` with the time step interval between calls determined by the `stepsPerGather` parameter.
numShards	The number of shards to be used.
stepsPerGather	The time step interval used by the `gatherFn` callback.
options	The RNN implementation options. See createInput().
debugContext	Optional debug information.

◆ rnnBwdSequence()

std::tuple< poplar::Tensor, poplar::Tensor, poplar::Tensor, poplar::Tensor > popnn::rnn::rnnBwdSequence	(	poplar::Graph &	graph,
		bool	doWU,
		bool	ignoreInputGradientCalc,
		poplar::program::Sequence &	prog,
		const poplar::Tensor &	fwdStateInit,
		const poplar::Tensor &	fwdState,
		const poplar::Tensor &	biases,
		const poplar::Tensor &	feedFwdWeights,
		const poplar::Tensor &	feedbackWeights,
		const poplar::Tensor &	outGradient,
		const poplar::Tensor &	actIn,
		const popnn::NonLinearityType &	nonLinearityType,
		const poplar::Type &	partialsType,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Perform the feedback part of the RNN layer.

The feedback part of the RNN layer must be preceded by the feedforward part of the RNN layer to complete the layer.

See also: forwardWeightInput

The following definitions apply:

numSteps is the number of steps.
batchSize is the number of batch elements.
inputSize is the size of the input for each step.
outputSize is the size of the output for each step.

Parameters

graph	The graph object.
doWU	Calculate weight updates.
ignoreInputGradientCalc	Do not calculate the gradients over the input weights.
prog	The control program.
fwdStateInit	The forward state tensor for initial step.
fwdState	The forward state tensor for all steps [0:seqSize).
biases	The biases.
feedFwdWeights	The input weights.
feedbackWeights	The feedback weights.
outGradient	The gradient from next layer.
actIn	The activations from the previous layer, so the output from the feedforward part of the RNN layer.
nonLinearityType	The type of non-linearity used for the output activations.
partialsType	The data type for intermediates.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns

Returns four tensors:

gradients for the previous layer
input weight deltas
output weight deltas
bias deltas When doWU is false, the weight and bias deltas are not calculated.

◆ rnnFwdSequence()

poplar::Tensor popnn::rnn::rnnFwdSequence	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		const poplar::Tensor &	fwdStateInit,
		const poplar::Tensor *	weightedIn,
		const poplar::Tensor &	biases,
		const poplar::Tensor &	feedFwdWeights,
		const poplar::Tensor &	feedbackWeights,
		const poplar::Tensor &	prevLayerActs,
		const popnn::NonLinearityType &	nonLinearityType,
		const poplar::Type &	partialsType,
		bool	inferenceOnly,
		const poplar::DebugContext &	debugContext = `{}`,
		poplin::PlanningCache *	planningCache = `nullptr`
	)

Perform the forward part of the RNN layer.

The feedback part of the RNN layer must be preceded by the feedforward part of the RNN layer to complete the layer.

See also: forwardWeightInput

The following definitions apply:

numSteps is the number of steps
batchSize is the number of batch elements.
inputSize is the size of the input for each step.
outputSize is the size of the output for each step.

Parameters

graph	The graph object.
prog	The control program.
fwdStateInit	The forward state tensor for initial step.
weightedIn	The preweighted input, or `nullptr` if `feedFwdWeights` is to be applied.
biases	The biases.
feedFwdWeights	The input weights.
feedbackWeights	The feedback weights.
prevLayerActs	The activations from previous layer (output from feedforward part of the RNN layer.
nonLinearityType	The type of non-linearity used for the output activations.
partialsType	The data type for intermediates.
inferenceOnly	Indicates whether the RNN layer is for inference only. If true, we can ignore backwards and weight update passes.
debugContext	Optional debug information.
planningCache	The matmul planning cache.

Returns: Forward state tensor for all steps [0:seqSize).

◆ shiftRnnTensor()

poplar::Tensor popnn::rnn::shiftRnnTensor	(	poplar::Graph &	graph,
		const RnnParams &	params,
		const poplar::Tensor &	tBase,
		const poplar::Tensor &	tSingle,
		poplar::program::Sequence &	prog,
		unsigned	numShards,
		const poplar::DebugContext &	debugContext = `{}`
	)

Create a single-step shifted RNN tensor from an input tensor.

For an input tensor tBase, n-th iteration of the RNN tensor points to the n-1-th iteration of tBase. For the 0-th iteration of the RNN tensor, a copy is made from the provided tensor tSingle tensor.

Parameters

graph	The graph object.
params	The RNN parameters.
tBase	The tensor to shift.
tSingle	The tensor to be copied in the 0-th iteration.
prog	The program to add a tensor copy.
numShards	The number of shards to be used.
debugContext	Debug information.

Returns: RNN tensor which is a single-step shifted version of tBase.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ GatherBodyType

◆ LoopBodyType

Function Documentation

◆ backwardGradientStep()

◆ createBwdState()

◆ createFwdState()

◆ createInitialState()

◆ createInput()

◆ createInputTensor()

◆ createOutputTensor() [1/2]

◆ createOutputTensor() [2/2]

◆ createRecurrentTensor()

◆ createWeightsFeedback()

◆ createWeightsInput()

◆ forwardIterate()

◆ forwardWeightInput()

◆ getOutputFromFwdState()

◆ paramDeltaUpdate()

◆ Rnn() [1/2]

◆ Rnn() [2/2]

◆ rnnBwdSequence()

◆ rnnFwdSequence()

◆ shiftRnnTensor()