Poplar and PopLibs
Gru.hpp
Go to the documentation of this file.
1// Copyright (c) 2019 Graphcore Ltd. All rights reserved.
8#ifndef popnn_Gru_hpp
9#define popnn_Gru_hpp
10
11#include <poplar/Tensor.hpp>
12#include <poplin/MatMul.hpp>
13#include <popnn/GruDef.hpp>
14#include <popnn/NonLinearityDef.hpp>
15#include <popnn/Rnn.hpp>
16
17namespace popnn {
18namespace gru {
19
25const std::vector<BasicGruCellUnit> getDefaultBasicGruCellOrder();
26
29struct GruParams {
30 rnn::RnnParams rnn;
31
32 // The datatype of the GRU.
34 poplar::Type dataType;
37 std::size_t batchSize;
40 std::size_t timeSteps;
43 std::vector<std::size_t> layerSizes;
46 bool outputFullSequence = true;
49 bool calcInputGradients = true;
55 std::vector<BasicGruCellUnit> cellOrder = getDefaultBasicGruCellOrder();
58 bool resetAfter = false;
60 NonLinearityType activation = NonLinearityType::TANH;
62 NonLinearityType recurrentActivation = NonLinearityType::SIGMOID;
63
64 GruParams(poplar::Type dataType, std::size_t batchSize, std::size_t timeSteps,
65 std::vector<std::size_t> layerSizes,
66 NonLinearityType activation = NonLinearityType::TANH,
67 NonLinearityType recurrentActivation = NonLinearityType::SIGMOID);
68
69 GruParams(poplar::Type dataType, std::size_t batchSize,
70 std::size_t maxTimeSteps, const poplar::Tensor &timeSteps,
71 std::vector<std::size_t> layerSizes,
72 NonLinearityType activation = NonLinearityType::TANH,
73 NonLinearityType recurrentActivation = NonLinearityType::SIGMOID);
74
75 GruParams(const GruParams &other);
76};
77
78uint64_t getBasicGruCellFwdFlops(const GruParams &params);
79
80uint64_t getBasicGruCellBwdFlops(const GruParams &params);
81
82uint64_t getBasicGruCellWuFlops(const GruParams &params);
83
112poplar::Tensor createInput(poplar::Graph &graph, const GruParams &params,
113 const poplar::DebugContext &debugContext,
114 const poplar::OptionFlags &options = {},
115 poplin::PlanningCache *planningCache = nullptr);
116
117poplar::Tensor createInitialState(poplar::Graph &graph, const GruParams &params,
118 const poplar::DebugContext &debugContext,
119 const poplar::OptionFlags &options,
120 poplin::PlanningCache *cache);
125struct GruWeights {
126 poplar::Tensor inputWeights;
127 poplar::Tensor outputWeights;
128 poplar::Tensor biases;
129};
130
134std::pair<poplar::Tensor, poplar::Tensor>
135createWeightsKernel(poplar::Graph &graph, const GruParams &params,
136 const poplar::DebugContext &debugContext,
137 const poplar::OptionFlags &options = {},
138 poplin::PlanningCache *planningCache = nullptr);
139
142poplar::Tensor
143createWeightsBiases(poplar::Graph &graph, const GruParams &params,
144 const poplar::DebugContext &debugContext,
145 const poplar::OptionFlags &options = {},
146 poplin::PlanningCache *planningCache = nullptr);
147
151GruWeights createWeights(poplar::Graph &graph, const GruParams &params,
152 const poplar::DebugContext &debugContext,
153 const poplar::OptionFlags &options = {},
154 poplin::PlanningCache *planningCache = nullptr);
155
158poplar::Tensor createAttention(poplar::Graph &graph, const GruParams &params,
159 const poplar::DebugContext &debugContext,
160 const poplar::OptionFlags &options = {});
161
207poplar::Tensor gruFwd(poplar::Graph &graph, const GruParams &params,
208 const poplar::Tensor &stateInit, const poplar::Tensor &in,
209 const GruWeights &weights, poplar::Tensor *intermediates,
210 poplar::program::Sequence &fwdProg,
211 const poplar::DebugContext &debugContext = {},
212 const poplar::OptionFlags &options = {},
213 poplin::PlanningCache *planningCache = nullptr);
214
264poplar::Tensor gruFwd(poplar::Graph &graph, const GruParams &params,
265 const poplar::Tensor &stateInit, const poplar::Tensor &in,
266 const poplar::Tensor &realTimeSteps,
267 const GruWeights &weights, poplar::Tensor *intermediates,
268 poplar::program::Sequence &fwdProg,
269 const poplar::DebugContext &debugContext = {},
270 const poplar::OptionFlags &options = {},
271 poplin::PlanningCache *planningCache = nullptr);
272
319poplar::Tensor auGruFwd(poplar::Graph &graph, const GruParams &params,
320 const poplar::Tensor &stateInit,
321 const poplar::Tensor &in, const GruWeights &weights,
322 poplar::Tensor *intermediates,
323 const poplar::Tensor &attScores,
324 poplar::program::Sequence &fwdProg,
325 const poplar::DebugContext &debugContext = {},
326 const poplar::OptionFlags &options = {},
327 poplin::PlanningCache *planningCache = nullptr);
328
379poplar::Tensor
380auGruFwd(poplar::Graph &graph, const GruParams &params,
381 const poplar::Tensor &stateInit, const poplar::Tensor &in,
382 const poplar::Tensor &realTimeSteps, const GruWeights &weights,
383 poplar::Tensor *intermediates, const poplar::Tensor &attScores,
384 poplar::program::Sequence &fwdProg,
385 const poplar::DebugContext &debugContext = {},
386 const poplar::OptionFlags &options = {},
387 poplin::PlanningCache *planningCache = nullptr);
388
427poplar::Tensor gruBwd(
428 poplar::Graph &graph, const GruParams &params,
429 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
430 const poplar::Tensor &fwdIntermediatesSeq, const GruWeights &weights,
431 const poplar::Tensor &fwdInputSeq, const poplar::Tensor &fwdOutput,
432 const poplar::Tensor &gradLayerNext, poplar::Tensor *inputGrad,
433 poplar::Tensor *bwdIntermediates, const poplar::DebugContext &debugContext,
434 const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache);
435
479poplar::Tensor
480gruBwd(poplar::Graph &graph, const GruParams &params,
481 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
482 const poplar::Tensor &fwdIntermediatesSeq, const GruWeights &weights,
483 const poplar::Tensor &fwdInputSeq, const poplar::Tensor &realTimeSteps,
484 const poplar::Tensor &fwdOutput, const poplar::Tensor &gradLayerNext,
485 poplar::Tensor *inputGrad, poplar::Tensor *bwdIntermediates,
486 const poplar::DebugContext &debugContext,
487 const poplar::OptionFlags &options_,
488 poplin::PlanningCache *planningCache);
489
530poplar::Tensor auGruBwd(
531 poplar::Graph &graph, const GruParams &params,
532 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
533 const poplar::Tensor &fwdIntermediatesSeq, const GruWeights &weights,
534 const poplar::Tensor &fwdInputSeq, const poplar::Tensor &fwdOutput,
535 const poplar::Tensor &gradLayerNext, poplar::Tensor *inputGrad,
536 poplar::Tensor *bwdIntermediates, const poplar::Tensor &attentions,
537 poplar::Tensor *attentionsGrad, const poplar::DebugContext &debugContext,
538 const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache);
539
585poplar::Tensor
586auGruBwd(poplar::Graph &graph, const GruParams &params,
587 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
588 const poplar::Tensor &fwdIntermediatesSeq, const GruWeights &weights,
589 const poplar::Tensor &fwdInputSeq, const poplar::Tensor &realTimeSteps,
590 const poplar::Tensor &fwdOutput, const poplar::Tensor &gradLayerNext,
591 poplar::Tensor *inputGrad, poplar::Tensor *bwdIntermediates,
592 const poplar::Tensor &attentions, poplar::Tensor *attentionsGrad,
593 const poplar::DebugContext &debugContext,
594 const poplar::OptionFlags &options_,
595 poplin::PlanningCache *planningCache);
596
625GruWeights gruWU(poplar::Graph &graph, const GruParams &params,
626 poplar::program::Sequence &prog,
627 const poplar::Tensor &fwdOutputInit,
628 const poplar::Tensor &fwdIntermediates,
629 const poplar::Tensor &bwdIntermediates,
630 const GruWeights &weights, const poplar::Tensor &input,
631 const poplar::Tensor &output,
632 const poplar::DebugContext &debugContext,
633 const poplar::OptionFlags &options_,
634 poplin::PlanningCache *planningCache);
635
664GruWeights auGruWU(poplar::Graph &graph, const GruParams &params,
665 poplar::program::Sequence &prog,
666 const poplar::Tensor &fwdOutputInit,
667 const poplar::Tensor &fwdIntermediates,
668 const poplar::Tensor &bwdIntermediates,
669 const GruWeights &weights, const poplar::Tensor &input,
670 const poplar::Tensor &output,
671 const poplar::DebugContext &debugContext,
672 const poplar::OptionFlags &options_,
673 poplin::PlanningCache *planningCache);
674
711poplar::Tensor gruBwdWithWU(
712 poplar::Graph &graph, const GruParams &params,
713 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
714 const poplar::Tensor &fwdIntermediates, const GruWeights &weights,
715 const poplar::Tensor &input, const poplar::Tensor &output,
716 const poplar::Tensor &outputGrad, poplar::Tensor *inputGrad,
717 GruWeights &weightsGrad, const poplar::DebugContext &debugContext,
718 const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache);
719
760poplar::Tensor gruBwdWithWU(
761 poplar::Graph &graph, const GruParams &params,
762 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
763 const poplar::Tensor &fwdIntermediates, const GruWeights &weights,
764 const poplar::Tensor &input, const poplar::Tensor &realTimeSteps,
765 const poplar::Tensor &output, const poplar::Tensor &outputGrad,
766 poplar::Tensor *inputGrad, GruWeights &weightsGrad,
767 const poplar::DebugContext &debugContext,
768 const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache);
769
808poplar::Tensor auGruBwdWithWU(
809 poplar::Graph &graph, const GruParams &params,
810 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
811 const poplar::Tensor &fwdIntermediates, const GruWeights &weights,
812 const poplar::Tensor &input, const poplar::Tensor &output,
813 const poplar::Tensor &outputGrad, poplar::Tensor *inputGrad,
814 GruWeights &weightsGrad, const poplar::Tensor &attentions,
815 poplar::Tensor *attentionsGrad, const poplar::DebugContext &debugContext,
816 const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache);
817
860poplar::Tensor auGruBwdWithWU(
861 poplar::Graph &graph, const GruParams &params,
862 poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit,
863 const poplar::Tensor &fwdIntermediates, const GruWeights &weights,
864 const poplar::Tensor &input, const poplar::Tensor &realTimeSteps,
865 const poplar::Tensor &output, const poplar::Tensor &outputGrad,
866 poplar::Tensor *inputGrad, GruWeights &weightsGrad,
867 const poplar::Tensor &attentions, poplar::Tensor *attentionsGrad,
868 const poplar::DebugContext &debugContext,
869 const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache);
870
871} // namespace gru
872} // namespace popnn
873
874#endif // popnn_Gru_hpp
GruDef.hpp
Definitions for GRU cell operations.
popnn::gru::auGruBwd
poplar::Tensor auGruBwd(poplar::Graph &graph, const GruParams &params, poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit, const poplar::Tensor &fwdIntermediatesSeq, const GruWeights &weights, const poplar::Tensor &fwdInputSeq, const poplar::Tensor &fwdOutput, const poplar::Tensor &gradLayerNext, poplar::Tensor *inputGrad, poplar::Tensor *bwdIntermediates, const poplar::Tensor &attentions, poplar::Tensor *attentionsGrad, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache)
Run AUGRU backward pass.
popnn::gru::createWeightsKernel
std::pair< poplar::Tensor, poplar::Tensor > createWeightsKernel(poplar::Graph &graph, const GruParams &params, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, poplin::PlanningCache *planningCache=nullptr)
Create the weights kernel used to weight the input and output of a GRU.
popnn::gru::gruBwdWithWU
poplar::Tensor gruBwdWithWU(poplar::Graph &graph, const GruParams &params, poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit, const poplar::Tensor &fwdIntermediates, const GruWeights &weights, const poplar::Tensor &input, const poplar::Tensor &output, const poplar::Tensor &outputGrad, poplar::Tensor *inputGrad, GruWeights &weightsGrad, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache)
Run a combined GRU backward and weight update pass.
popnn::gru::getDefaultBasicGruCellOrder
const std::vector< BasicGruCellUnit > getDefaultBasicGruCellOrder()
Get the default order of the gates in a basic GRU cell.
popnn::gru::gruWU
GruWeights gruWU(poplar::Graph &graph, const GruParams &params, poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit, const poplar::Tensor &fwdIntermediates, const poplar::Tensor &bwdIntermediates, const GruWeights &weights, const poplar::Tensor &input, const poplar::Tensor &output, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache)
Run a standalone weight update pass.
popnn::gru::gruFwd
poplar::Tensor gruFwd(poplar::Graph &graph, const GruParams &params, const poplar::Tensor &stateInit, const poplar::Tensor &in, const GruWeights &weights, poplar::Tensor *intermediates, poplar::program::Sequence &fwdProg, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, poplin::PlanningCache *planningCache=nullptr)
Calculate the result of applying a GRU across a sequence.
popnn::gru::gruBwd
poplar::Tensor gruBwd(poplar::Graph &graph, const GruParams &params, poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit, const poplar::Tensor &fwdIntermediatesSeq, const GruWeights &weights, const poplar::Tensor &fwdInputSeq, const poplar::Tensor &fwdOutput, const poplar::Tensor &gradLayerNext, poplar::Tensor *inputGrad, poplar::Tensor *bwdIntermediates, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache)
Run GRU backward pass.
popnn::gru::auGruWU
GruWeights auGruWU(poplar::Graph &graph, const GruParams &params, poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit, const poplar::Tensor &fwdIntermediates, const poplar::Tensor &bwdIntermediates, const GruWeights &weights, const poplar::Tensor &input, const poplar::Tensor &output, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache)
Run a standalone weight update pass.
popnn::gru::auGruFwd
poplar::Tensor auGruFwd(poplar::Graph &graph, const GruParams &params, const poplar::Tensor &stateInit, const poplar::Tensor &in, const GruWeights &weights, poplar::Tensor *intermediates, const poplar::Tensor &attScores, poplar::program::Sequence &fwdProg, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, poplin::PlanningCache *planningCache=nullptr)
Calculate the result of applying an AUGRU across a sequence.
popnn::gru::createWeightsBiases
poplar::Tensor createWeightsBiases(poplar::Graph &graph, const GruParams &params, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, poplin::PlanningCache *planningCache=nullptr)
Create the weights biases.
popnn::gru::auGruBwdWithWU
poplar::Tensor auGruBwdWithWU(poplar::Graph &graph, const GruParams &params, poplar::program::Sequence &prog, const poplar::Tensor &fwdOutputInit, const poplar::Tensor &fwdIntermediates, const GruWeights &weights, const poplar::Tensor &input, const poplar::Tensor &output, const poplar::Tensor &outputGrad, poplar::Tensor *inputGrad, GruWeights &weightsGrad, const poplar::Tensor &attentions, poplar::Tensor *attentionsGrad, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options_, poplin::PlanningCache *planningCache)
Run a combined AUGRU backward and weight update pass.
popnn::gru::createAttention
poplar::Tensor createAttention(poplar::Graph &graph, const GruParams &params, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={})
Create an attention tensor for AUGRU.
NonLinearityDef.hpp
Definitions for non-linearity operations.
Rnn.hpp
Functions for recurrent neural networks (RNN).
poplar::DebugContext
DebugContext gathers the common external parameters of the context of an operation.
Definition: DebugContext.hpp:221
poplar::Graph
This class represents a graph program to be executed on the IPU.
Definition: Graph.hpp:52
poplar::OptionFlags
A set of option/value string flags to be used in various APIs.
Definition: OptionFlags.hpp:24
poplar::Tensor
A reference to a subset of tensor elements.
Definition: Tensor.hpp:38
poplar::Type
Class representing device data types.
Definition: Type.hpp:42
poplar::program::Sequence
Program that executes a sequence of programs.
Definition: Program.hpp:77
popnn
Functions used in neural networks.
Definition: BatchNorm.hpp:14
popnn::NonLinearityType
NonLinearityType
Definition: NonLinearityDef.hpp:11
popnn::NonLinearityType::TANH
@ TANH
Hyperbolic tangent:
MatMul.hpp
Functions and data types for performing matrix multiplies on the IPU.
popnn::gru::GruParams
Structure representing the parameters of the GRU.
Definition: Gru.hpp:29
popnn::gru::GruParams::layerSizes
std::vector< std::size_t > layerSizes
The number of neurons for the input and output layer.
Definition: Gru.hpp:43
popnn::gru::GruParams::cellOrder
std::vector< BasicGruCellUnit > cellOrder
The weights and biases for all of the layers being processed are concatenated in the outermost dimens...
Definition: Gru.hpp:55
popnn::gru::GruParams::batchSize
std::size_t batchSize
The batch size.
Definition: Gru.hpp:37
popnn::gru::GruParams::outputFullSequence
bool outputFullSequence
If true the GRU function returns the entire sequence of outputs, otherwise it returns just the final ...
Definition: Gru.hpp:46
popnn::gru::GruParams::activation
NonLinearityType activation
Activation function.
Definition: Gru.hpp:60
popnn::gru::GruParams::recurrentActivation
NonLinearityType recurrentActivation
Recurrent activation function.
Definition: Gru.hpp:62
popnn::gru::GruParams::dataType
poplar::Type dataType
Definition: Gru.hpp:34
popnn::gru::GruParams::timeSteps
std::size_t timeSteps
The number of time steps in the sequence of the GRU.
Definition: Gru.hpp:40
popnn::gru::GruParams::resetAfter
bool resetAfter
Controls whether the reset gate is applied before or after the candidate weights and biases.
Definition: Gru.hpp:58
popnn::gru::GruParams::calcInputGradients
bool calcInputGradients
If this parameter is set to false then the GRU will skip the calculation of the gradients of the inpu...
Definition: Gru.hpp:49
popnn::gru::GruWeights
Structure holding all the parameters of a GRU cell, or the deltas for those parameters (depending on ...
Definition: Gru.hpp:125
popnn::rnn::RnnParams
Structure of Recurrent Neural Network (RNN) parameters which allows for any customized implementation...
Definition: Rnn.hpp:22