Poplar and PopLibs
MatMul.hpp
Go to the documentation of this file.
1// Copyright (c) 2017 Graphcore Ltd. All rights reserved.
8#ifndef poplin_MatMul_hpp
9#define poplin_MatMul_hpp
10#include "poplin/Convolution.hpp"
11#include <iosfwd>
12#include <map>
13#include <poplar/Graph.hpp>
14#include <poplar/OptionFlags.hpp>
15#include <poplar/Program.hpp>
16#include <set>
17#include <tuple>
18#include <unordered_map>
19#include <vector>
20
21namespace poplin {
22namespace matmul {
23
24class PlanningCache;
25
26} // namespace matmul
27
28class PlanningCache;
29
97/*[INTERNAL OPTIONS]
98 * * `planConstraints` JSON string
99 *
100 * See createWeights().
101 *
102 * * `gatherOutput` (true, false) [=false]
103 * Gather output of the matrix multiply into a single variable
104 *
105 * * 'disableSRForAMPVertices' (true, false) [=false]
106 *
107 * Disable stochastic rounding for vertices that use AMP
108 */
110poplar::Tensor matMul(poplar::Graph &graph, const poplar::Tensor &A,
111 const poplar::Tensor &B, poplar::program::Sequence &prog,
112 const poplar::Type &outputType,
113 const poplar::DebugContext &debugContext = {},
114 const poplar::OptionFlags &options = {},
115 PlanningCache *cache = nullptr);
116
118poplar::Tensor matMul(poplar::Graph &graph, const poplar::Tensor &A,
119 const poplar::Tensor &B, poplar::program::Sequence &prog,
120 const poplar::DebugContext &debugContext = {},
121 const poplar::OptionFlags &options = {},
122 PlanningCache *cache = nullptr);
123
125void matMulWithOutput(poplar::Graph &graph, const poplar::Tensor &A_,
126 const poplar::Tensor &B_, poplar::Tensor &out,
127 poplar::program::Sequence &prog,
128 const poplar::DebugContext &debugContext = {},
129 const poplar::OptionFlags &options_ = {},
130 PlanningCache *cache = nullptr);
131
145void matMulReportPlan(std::ostream &out, const poplar::Graph &graph,
146 const poplar::Type &inputType,
147 const poplar::Type &outputType,
148 const std::vector<std::size_t> &aShape,
149 const std::vector<std::size_t> &bShape,
150 const poplar::OptionFlags &options = {},
151 PlanningCache *cache = nullptr);
152
181poplar::Tensor matMulGrouped(poplar::Graph &graph, const poplar::Tensor &A,
182 const poplar::Tensor &B,
183 poplar::program::Sequence &prog,
184 const poplar::Type &outputType,
185 const poplar::DebugContext &debugContext = {},
186 const poplar::OptionFlags &options = {},
187 PlanningCache *cache = nullptr);
188
190void matMulGroupedWithOutput(poplar::Graph &graph, const poplar::Tensor &A,
191 const poplar::Tensor &B, poplar::Tensor &out,
192 poplar::program::Sequence &prog,
193 const poplar::DebugContext &debugContext = {},
194 const poplar::OptionFlags &options_ = {},
195 PlanningCache *cache = nullptr);
196
210void matMulGroupedReportPlan(std::ostream &out, const poplar::Graph &graph,
211 const poplar::Type &inputType,
212 const poplar::Type &outputType,
213 const std::vector<std::size_t> &aShape,
214 const std::vector<std::size_t> &bShape,
215 const poplar::OptionFlags &options = {},
216 PlanningCache *cache = nullptr);
217
242void matMulAcc(poplar::Graph &graph, const poplar::Tensor &C, float k,
243 const poplar::Tensor &A, const poplar::Tensor &B,
244 poplar::program::Sequence &prog,
245 const poplar::DebugContext &debugContext = {},
246 const poplar::OptionFlags &options = {},
247 PlanningCache *cache = nullptr);
248
250void matMulAcc(poplar::Graph &graph, const poplar::Tensor &C,
251 const poplar::Tensor &k, const poplar::Tensor &A,
252 const poplar::Tensor &B, poplar::program::Sequence &prog,
253 const poplar::DebugContext &debugContext = {},
254 const poplar::OptionFlags &options = {},
255 PlanningCache *cache = nullptr);
256
287void matMulGroupedAcc(poplar::Graph &graph, const poplar::Tensor &C, float k,
288 const poplar::Tensor &A, const poplar::Tensor &B,
289 poplar::program::Sequence &prog,
290 const poplar::DebugContext &debugContext = {},
291 const poplar::OptionFlags &options = {},
292 PlanningCache *cache = nullptr);
293
296void matMulGroupedAcc(poplar::Graph &graph, const poplar::Tensor &C,
297 const poplar::Tensor &k, const poplar::Tensor &A,
298 const poplar::Tensor &B, poplar::program::Sequence &prog,
299 const poplar::DebugContext &debugContext = {},
300 const poplar::OptionFlags &options = {},
301 PlanningCache *cache = nullptr);
302
324poplar::Tensor createMatMulInputLHS(poplar::Graph &graph,
325 const poplar::Type &inputType,
326 const poplar::Type &outputType,
327 const std::vector<std::size_t> &aShape,
328 const std::vector<std::size_t> &bShape,
329 const poplar::DebugContext &debugContext,
330 const poplar::OptionFlags &options = {},
331 PlanningCache *cache = nullptr);
332
353poplar::Tensor createMatMulInputLHS(poplar::Graph &graph,
354 const poplar::Type &dataType,
355 const std::vector<std::size_t> &aShape,
356 const std::vector<std::size_t> &bShape,
357 const poplar::DebugContext &debugContext,
358 const poplar::OptionFlags &options = {},
359 PlanningCache *cache = nullptr);
360
385poplar::Tensor createMatMulGroupedInputLHS(
386 poplar::Graph &graph, const poplar::Type &inputType,
387 const poplar::Type &outputType, const std::vector<std::size_t> &aShape,
388 const std::vector<std::size_t> &bShape,
389 const poplar::DebugContext &debugContext,
390 const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
391
413poplar::Tensor createMatMulInputRHS(poplar::Graph &graph,
414 const poplar::Type &inputType,
415 const poplar::Type &outputType,
416 const std::vector<std::size_t> &aShape,
417 const std::vector<std::size_t> &bShape,
418 const poplar::DebugContext &debugContext,
419 const poplar::OptionFlags &options = {},
420 PlanningCache *cache = nullptr);
421
426poplar::Tensor createMatMulInputRHS(poplar::Graph &graph,
427 const poplar::Type &dataType,
428 const std::vector<std::size_t> &aShape,
429 const std::vector<std::size_t> &bShape,
430 const poplar::DebugContext &debugContext,
431 const poplar::OptionFlags &options = {},
432 PlanningCache *cache = nullptr);
433
456poplar::Tensor createMatMulOutput(poplar::Graph &graph,
457 const poplar::Type &inputType,
458 const poplar::Type &outputType,
459 const std::vector<std::size_t> &aShape,
460 const std::vector<std::size_t> &bShape,
461 const poplar::DebugContext &debugContext,
462 const poplar::OptionFlags &options = {},
463 PlanningCache *cache = nullptr);
464
469poplar::Tensor createMatMulOutput(poplar::Graph &graph,
470 const poplar::Type &dataType,
471 const std::vector<std::size_t> &aShape,
472 const std::vector<std::size_t> &bShape,
473 const poplar::DebugContext &debugContext,
474 const poplar::OptionFlags &options = {},
475 PlanningCache *cache = nullptr);
476
501poplar::Tensor createMatMulGroupedInputRHS(
502 poplar::Graph &graph, const poplar::Type &inputType,
503 const poplar::Type &outputType, const std::vector<std::size_t> &aShape,
504 const std::vector<std::size_t> &bShape,
505 const poplar::DebugContext &debugContext,
506 const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
507
533poplar::Tensor createMatMulGroupedOutput(
534 poplar::Graph &graph, const poplar::Type &inputType,
535 const poplar::Type &outputType, const std::vector<std::size_t> &aShape,
536 const std::vector<std::size_t> &bShape,
537 const poplar::DebugContext &debugContext,
538 const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
570poplar::Tensor preArrangeMatMulInputRHS(
571 poplar::Graph &graph, const std::vector<std::size_t> &aShape,
572 const poplar::Tensor &B, poplar::program::Sequence &prog,
573 const poplar::Type &outputType,
574 const poplar::DebugContext &debugContext = {},
575 const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
576
578poplar::Tensor preArrangeMatMulInputRHS(
579 poplar::Graph &graph, const std::vector<std::size_t> &aShape,
580 const poplar::Tensor &B, poplar::program::Sequence &prog,
581 const poplar::DebugContext &debugContext = {},
582 const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
583
585poplar::Tensor preArrangeMatMulGroupedInputRHS(
586 poplar::Graph &graph, const std::vector<std::size_t> &aShape,
587 const poplar::Tensor &B, poplar::program::Sequence &prog,
588 const poplar::Type &outputType,
589 const poplar::DebugContext &debugContext = {},
590 const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
591
599poplar::Tensor transposeGroupedMatrix(const poplar::Tensor &A);
600
606struct MatMulParams {
608 poplar::Type inputType;
610 poplar::Type outputType;
611
613 std::vector<std::size_t> aShape;
615 std::vector<std::size_t> bShape;
616
617 friend bool operator<(const MatMulParams &a, const MatMulParams &b);
618};
619
628using MatMulPlanParams = std::tuple<const poplar::Target *, const MatMulParams,
629 const poplar::OptionFlags *>;
630
635using MatMulToConvOptions =
636 std::unordered_map<const poplar::OptionFlags *, poplar::OptionFlags>;
637
648std::set<ConvPlanParams>
649matMulGetConvPlanParams(const std::set<MatMulPlanParams> &matmuls,
650 MatMulToConvOptions &matmulToConvOpts);
651
658void preplanMatMuls(const std::set<MatMulPlanParams> &matmuls,
659 matmul::PlanningCache &cache);
660
667void matmulValidateOptions(const poplar::OptionFlags &options);
668
669namespace matmul {
670
672class PlanningCache : public poplin::PlanningCache {
673public:
674 poplin::PlanningCache &getImpl();
675};
676
677} // namespace matmul
678
679} // namespace poplin
680
681#endif // poplin_MatMul_hpp
Convolution.hpp
Functions and data types to support performing convolutions.
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::Target
A target representation.
Definition: Target.hpp:69
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
poplin::matmul::PlanningCache
Definition: MatMul.hpp:672
poplin
Linear algebra functions.
Definition: Cholesky.hpp:14
poplin::MatMulToConvOptions
std::unordered_map< const poplar::OptionFlags *, poplar::OptionFlags > MatMulToConvOptions
Mapping of pointers to matrix multiplication option flags to the corresponding convolution option fla...
Definition: MatMul.hpp:636
poplin::matMulGetConvPlanParams
std::set< ConvPlanParams > matMulGetConvPlanParams(const std::set< MatMulPlanParams > &matmuls, MatMulToConvOptions &matmulToConvOpts)
Obtain the set of convolution parameters corresponding to the user supplied set of parameters for mat...
poplin::matMulReportPlan
void matMulReportPlan(std::ostream &out, const poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Report the convolution plan corresponding to the parameters and options provided.
poplin::matMulGroupedReportPlan
void matMulGroupedReportPlan(std::ostream &out, const poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Report the convolution plan corresponding to the params and options provided.
poplin::transposeGroupedMatrix
poplar::Tensor transposeGroupedMatrix(const poplar::Tensor &A)
Transposes a grouped matrix tensor.
poplin::matMulWithOutput
void matMulWithOutput(poplar::Graph &graph, const poplar::Tensor &A_, const poplar::Tensor &B_, poplar::Tensor &out, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options_={}, PlanningCache *cache=nullptr)
Matrix multiply with explicitly defined output.
poplin::preArrangeMatMulInputRHS
poplar::Tensor preArrangeMatMulInputRHS(poplar::Graph &graph, const std::vector< std::size_t > &aShape, const poplar::Tensor &B, poplar::program::Sequence &prog, const poplar::Type &outputType, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Pre-arrange right-hand side input.
poplin::createMatMulOutput
poplar::Tensor createMatMulOutput(poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Create a tensor that is used as the output operand of matrix multiplication.
poplin::createMatMulGroupedInputLHS
poplar::Tensor createMatMulGroupedInputLHS(poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Create a tensor that is used as the left operand of a grouped matrix multiplication.
poplin::matMulGroupedAcc
void matMulGroupedAcc(poplar::Graph &graph, const poplar::Tensor &C, float k, const poplar::Tensor &A, const poplar::Tensor &B, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Grouped matrix multiply and accumulate.
poplin::matMul
poplar::Tensor matMul(poplar::Graph &graph, const poplar::Tensor &A, const poplar::Tensor &B, poplar::program::Sequence &prog, const poplar::Type &outputType, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Multiply two matrices.
poplin::preArrangeMatMulGroupedInputRHS
poplar::Tensor preArrangeMatMulGroupedInputRHS(poplar::Graph &graph, const std::vector< std::size_t > &aShape, const poplar::Tensor &B, poplar::program::Sequence &prog, const poplar::Type &outputType, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Pre-arrange grouped input with explicitly defined output type.
poplin::matMulGrouped
poplar::Tensor matMulGrouped(poplar::Graph &graph, const poplar::Tensor &A, const poplar::Tensor &B, poplar::program::Sequence &prog, const poplar::Type &outputType, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Multiply two grouped matrices.
poplin::preplanMatMuls
void preplanMatMuls(const std::set< MatMulPlanParams > &matmuls, matmul::PlanningCache &cache)
poplin::createMatMulGroupedOutput
poplar::Tensor createMatMulGroupedOutput(poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Create a tensor that is used as the output operand of grouped matrix multiplication (with output).
poplin::MatMulPlanParams
std::tuple< const poplar::Target *, const MatMulParams, const poplar::OptionFlags * > MatMulPlanParams
A tuple containing the required parameters to preplan a matmul:
Definition: MatMul.hpp:629
poplin::createMatMulInputLHS
poplar::Tensor createMatMulInputLHS(poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Create a tensor that is used as the left operand of matrix multiplication.
poplin::matMulGroupedWithOutput
void matMulGroupedWithOutput(poplar::Graph &graph, const poplar::Tensor &A, const poplar::Tensor &B, poplar::Tensor &out, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options_={}, PlanningCache *cache=nullptr)
Grouped matmul with explicit output argument.
poplin::createMatMulInputRHS
poplar::Tensor createMatMulInputRHS(poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Create a tensor that is used as the right operand of matrix multiplication.
poplin::matmulValidateOptions
void matmulValidateOptions(const poplar::OptionFlags &options)
Provides an interface to validate the matmul options.
poplin::matMulAcc
void matMulAcc(poplar::Graph &graph, const poplar::Tensor &C, float k, const poplar::Tensor &A, const poplar::Tensor &B, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Multiply two matrices and add to a third (with a scaling factor).
poplin::createMatMulGroupedInputRHS
poplar::Tensor createMatMulGroupedInputRHS(poplar::Graph &graph, const poplar::Type &inputType, const poplar::Type &outputType, const std::vector< std::size_t > &aShape, const std::vector< std::size_t > &bShape, const poplar::DebugContext &debugContext, const poplar::OptionFlags &options={}, PlanningCache *cache=nullptr)
Create a tensor that is used as the right operand of grouped matrix multiplication.
poplin::MatMulParams
Parameters to define a Matrix multiplication.
Definition: MatMul.hpp:606
poplin::MatMulParams::bShape
std::vector< std::size_t > bShape
Shape of the rhs input matrix (B)
Definition: MatMul.hpp:615
poplin::MatMulParams::outputType
poplar::Type outputType
Output type (of C)
Definition: MatMul.hpp:610
poplin::MatMulParams::inputType
poplar::Type inputType
Input type (of A & B)
Definition: MatMul.hpp:608
poplin::MatMulParams::aShape
std::vector< std::size_t > aShape
Shape of the lhs input matrix (A)
Definition: MatMul.hpp:613