Convolution.hpp

Go to the documentation of this file.

// Copyright (c) 2016 Graphcore Ltd. All rights reserved.
#ifndef poplin_Convolution_hpp
#define poplin_Convolution_hpp
#include "ConvParams.hpp"
 
#include <poplar/Graph.hpp>
#include <poplar/OptionFlags.hpp>
#include <poplar/Program.hpp>
#include <set>
#include <tuple>
 
namespace poplin {
 
class PlanningCache;
 
uint64_t getFwdFlops(const ConvParams &params);
uint64_t getBwdFlops(const ConvParams &params);
uint64_t getWuFlops(const ConvParams &params);
 
double getFwdPerfectCycleCount(const poplar::Graph &graph,
                               const ConvParams &params);
 
double getBwdPerfectCycleCount(const poplar::Graph &graph,
                               const ConvParams &params);
 
double getWuPerfectCycleCount(const poplar::Graph &graph,
                              const ConvParams &params);
 
/*[INTERNAL]
 *    * `numIPUs` Integer [=target.getNumIPUs()]
 *
 *      Number of IPUs to be used.
 *
 *   * `remapOutputTensor`       (true, false) [=true]
 *
 *      If true, the output of the convolution is remapped if the output
 *      is detected to have a poor layout. The convolutions planner will try
 *      to map the channels in groups of 16, 8 or 4. This typically results
 *      in better performance for the operation(s) consuming the output
 *      of the convolution.
 *
 *
 *    * `planConstraints` JSON string
 *
 *      Constraints on the chosen convolution plan. Example:
 *
 *          {"0": {"transform": {"swapOperands": true},
 *                 "partition": {"fieldSplit":{"1": 4},
 *                               "inChanSplit": 4,
 *                               "outChanSplit": {"parallel": 4}}
 *                }
 *          }
 *
 *      Where the outer-most index in the plan is an index into the plan
 *      hierarchy, and any multi-dimensional fields are sparsely indexed
 *      objects. Therefore, constraining dimension 1 of fieldSplit to be 4 is
 *      specified as:
 *
 *          {"fieldSplit": {"1": 4}}
 *
 *      This is only implemented for `partitioning` and for the `swapOperands`
 *      transform for now.
 *
 *    * `planConstraintsOutputFilename` String
 *
 *      If set, plan constraints for each plan used by a convolution will be
 *      saved to file. The file path will be the value of this option appended
 *      with _FWD, _BWD, or _WU (depending on the pass), with a file extension
 *      of .json. The content of these files may be used as input to the
 *      `planConstraints` option (above). The constraints will be complete,
 *      meaning they can only be satisfied by one specific plan - this allows
 *      reliable reproduction regardless of changes to the planner.
 *
 *    * `partialsType.interIPU` (half, float) [=`partialsType`]
 *
 *      Data type of inter-IPU partials. If the type specified
 *      is smaller than the output type then the option is ignored and the
 *      output type is used instead.
 *
 *    * `partialsType.interTile` (half, float) [=`partialsType`]
 *
 *      Data type of inter-tile partials. If the type specified
 *      is smaller than the output type then the option is ignored and the
 *      output type is used instead.
 *
 *    * `tilesPerIPU` Integer [=target.getTilesPerIPU()]
 *
 *      Number of tiles per IPU to be used.
 *
 *   * `gatherConvOutput` (true, false) [=false]
 *
 *     Gather output of the matrix multiply into a single variable
 *
 *   * 'experimental.slicVmac16' (true, false) [=false]
 *
 *     Restricts convolution planner to use SLIC/VMAC vertices with
 *     grouping of 16
 *
 *   * 'disableSRForAMPVertices' (true, false) [=false]
 *
 *     Disable stochastic rounding for vertices that use AMP
 *
 */
poplar::Tensor createWeights(poplar::Graph &graph, const ConvParams &params,
                             const poplar::DebugContext &debugContext = {},
                             const poplar::OptionFlags &options = {},
                             PlanningCache *cache = nullptr);
 
poplar::Tensor
createBiases(poplar::Graph &graph, const poplar::Tensor &activations,
             const poplar::DebugContext &debugContext = {"biases"});
 
poplar::Tensor
createBiases(poplar::Graph &graph, const poplar::Tensor &activations,
             const ConvParams &params,
             const poplar::DebugContext &debugContext = {"biases"},
             const poplar::OptionFlags &options = {},
             PlanningCache *cache = nullptr);
 
poplar::Tensor createInput(poplar::Graph &graph, const ConvParams &params,
                           const poplar::DebugContext &debugContext = {},
                           const poplar::OptionFlags &options = {},
                           PlanningCache *cache = nullptr);
 
poplar::Tensor createConvOutput(poplar::Graph &graph, const ConvParams &params,
                                const poplar::DebugContext &debugContext = {},
                                const poplar::OptionFlags &options = {},
                                PlanningCache *cache = nullptr);
 
poplar::Tensor convolution(poplar::Graph &graph, const poplar::Tensor &in,
                           const poplar::Tensor &weights,
                           const ConvParams &params,
                           bool transposeAndFlipWeights,
                           poplar::program::Sequence &prog,
                           const poplar::DebugContext &debugContext = {},
                           const poplar::OptionFlags &options = {},
                           PlanningCache *cache = nullptr);
 
void convolutionWithOutput(poplar::Graph &graph, const poplar::Tensor &in,
                           const poplar::Tensor &weights,
                           const poplar::Tensor &out, const ConvParams &params,
                           bool transposeAndFlipWeights,
                           poplar::program::Sequence &prog,
                           const poplar::DebugContext &debugContext = {},
                           const poplar::OptionFlags &options = {},
                           PlanningCache *cache = nullptr);
 
using ConvPlanParams = std::tuple<const poplar::Target *, const ConvParams,
                                  const poplar::OptionFlags *>;
void preplanConvolutions(const std::set<ConvPlanParams> &convs,
                         PlanningCache &cache);
 
void preplanConvolutions(poplar::Graph &graph,
                         const std::set<ConvPlanParams> &convs,
                         PlanningCache &cache);
 
void weightsTransposeChansFlipXY(poplar::Graph &graph,
                                 const poplar::Tensor &weightsIn,
                                 const poplar::Tensor &weightsOut,
                                 poplar::program::Sequence &prog,
                                 const poplar::DebugContext &debugContext = {},
                                 const poplar::OptionFlags &options = {});
 
poplar::Tensor
calculateWeightDeltas(poplar::Graph &graph, const poplar::Tensor &zDeltas,
                      const poplar::Tensor &activations,
                      const ConvParams &params, poplar::program::Sequence &prog,
                      const poplar::DebugContext &debugContext = {},
                      const poplar::OptionFlags &options = {},
                      PlanningCache *cache = nullptr);
 
void convolutionWeightUpdate(poplar::Graph &graph,
                             const poplar::Tensor &zDeltas,
                             const poplar::Tensor &weights,
                             const poplar::Tensor &activations,
                             ConvParams params, const poplar::Tensor &scale,
                             poplar::program::Sequence &prog,
                             const poplar::DebugContext &debugContext = {},
                             const poplar::OptionFlags &options = {},
                             PlanningCache *cache = nullptr);
 
void convolutionWeightUpdate(
    poplar::Graph &graph, const poplar::Tensor &zDeltas,
    const poplar::Tensor &weights, const poplar::Tensor &activations,
    ConvParams params, float scale, poplar::program::Sequence &prog,
    const poplar::DebugContext &debugContext = {},
    const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
 
void convolutionBiasUpdate(poplar::Graph &graph, const poplar::Tensor &zDeltas,
                           const poplar::Tensor &biases,
                           const poplar::Tensor &scale,
                           const poplar::OptionFlags &options,
                           poplar::program::Sequence &prog,
                           const poplar::DebugContext &debugContext = {});
 
void convolutionBiasUpdate(poplar::Graph &graph, const poplar::Tensor &zDeltas,
                           const poplar::Tensor &biases, float scale,
                           const poplar::OptionFlags &options,
                           poplar::program::Sequence &prog,
                           const poplar::DebugContext &debugContext = {});
 
void addBias(poplar::Graph &graph, const poplar::Tensor &in,
             const poplar::Tensor &biases, poplar::program::Sequence &prog,
             const poplar::DebugContext &debugContext = {});
 
void reportPlanInfo(std::ostream &out, const poplar::Graph &graph,
                    const ConvParams &params,
                    const poplar::OptionFlags &options = {},
                    PlanningCache *cache = nullptr);
 
struct PlanCosts {
  std::size_t cycles;
  std::size_t memory;
};
 
PlanCosts reportPlanEstimatedCosts(const poplar::Graph &graph,
                                   const ConvParams &params,
                                   const poplar::OptionFlags &options = {},
                                   PlanningCache *cache = nullptr);
 
void reportWeightUpdatePlanInfo(std::ostream &out, const poplar::Graph &graph,
                                const ConvParams &fwdParams,
                                const poplar::OptionFlags &fwdOptions = {},
                                PlanningCache *cache = nullptr);
 
poplar::Tensor fullyConnectedWeightTranspose(
    poplar::Graph &graph, poplar::Tensor weights, const ConvParams &params,
    poplar::program::Sequence &prog,
    const poplar::DebugContext &debugContext = {},
    const poplar::OptionFlags &options = {}, PlanningCache *cache = nullptr);
 
void convolutionValidateOptions(const poplar::OptionFlags &options);
 
struct Plan;
 
class PlanningCacheImpl;
class PlanningCache {
public:
  PlanningCache();
  ~PlanningCache();
 
  std::size_t size() const;
 
  std::unique_ptr<PlanningCacheImpl> impl;
};
 
} // namespace poplin
 
#endif // poplin_Convolution_hpp