latest/doxygen/Collectives_8hpp_source.html

// Copyright (c) 2019 Graphcore Ltd. All rights reserved.

#ifndef INCLUDE_GCL_COLLECTIVES_HPP

#define INCLUDE_GCL_COLLECTIVES_HPP


#include <poplar/DebugContext.hpp>

#include <poplar/Graph.hpp>

#include <poplar/OptionFlags.hpp>

#include <poplar/Program.hpp>

#include <poplar/Tensor.hpp>

#include <iosfwd>

#include <vector>


#if __cplusplus >= 201603L

#define GCL_NO_DISCARD [[nodiscard]]

#else

#define GCL_NO_DISCARD

#endif


namespace gcl {


enum class CommGroupType {

  ALL,

  CONSECUTIVE,

  ORTHOGONAL

};


// clang-format off

// clang-format on

struct CommGroup {

  CommGroup() = default;

  CommGroup(const CommGroupType groupType, unsigned groupSize,

            unsigned replicaStride = 1);


  virtual ~CommGroup() = default;


protected:

  // NOLINTNEXTLINE(cppcoreguidelines-non-private-member-variables-in-classes)

  CommGroupType mReplicaGroupType = CommGroupType::ALL;

  // NOLINTNEXTLINE(cppcoreguidelines-non-private-member-variables-in-classes)

  unsigned mReplicaGroupSize = 0;

  // NOLINTNEXTLINE(cppcoreguidelines-non-private-member-variables-in-classes)

  unsigned mReplicaGroupStride = 1;


  friend std::ostream &operator<<(std::ostream &os, const CommGroup &group);

};


enum class CollectiveOperator {

  ADD,

  MEAN,

  MUL,

  MIN,

  MAX,

  LOGICAL_AND,

  LOGICAL_OR,

  SQUARE_ADD,

  LOCAL,

};


std::istream &operator>>(std::istream &is, CollectiveOperator &op);


std::ostream &operator<<(std::ostream &os, const CollectiveOperator &op);


GCL_NO_DISCARD poplar::Tensor

allReduceCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                      CollectiveOperator op, poplar::program::Sequence &prog,

                      const CommGroup &group,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


GCL_NO_DISCARD std::vector<poplar::Tensor> allReduceCrossReplica(

    poplar::Graph &graph, const std::vector<poplar::Tensor> &datas,

    CollectiveOperator op, poplar::program::Sequence &prog,

    const CommGroup &group, const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allReduceCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                      CollectiveOperator op, poplar::program::Sequence &prog,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


GCL_NO_DISCARD std::vector<poplar::Tensor>

allReduceCrossReplica(poplar::Graph &graph,

                      const std::vector<poplar::Tensor> &datas,

                      CollectiveOperator op, poplar::program::Sequence &prog,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


void allReduceToDestinationCrossReplica(

    poplar::Graph &graph, const poplar::Tensor &data,

    poplar::Tensor &destination, CollectiveOperator op,

    poplar::program::Sequence &prog, const CommGroup &group,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


void allReduceToDestinationCrossReplica(

    poplar::Graph &graph, const std::vector<poplar::Tensor> &datas,

    const std::vector<poplar::Tensor> &destinations, CollectiveOperator op,

    poplar::program::Sequence &prog, const CommGroup &group,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


void allReduceToDestinationCrossReplica(

    poplar::Graph &graph, const poplar::Tensor &data,

    poplar::Tensor &destination, CollectiveOperator op,

    poplar::program::Sequence &prog,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


void allReduceInPlaceCrossReplica(poplar::Graph &graph, poplar::Tensor &data,

                                  CollectiveOperator op,

                                  poplar::program::Sequence &prog,

                                  const CommGroup &group,

                                  const poplar::DebugContext &debugContext = {},

                                  const poplar::OptionFlags &options = {});


void allReduceInPlaceCrossReplica(poplar::Graph &graph,

                                  std::vector<poplar::Tensor> &datas,

                                  CollectiveOperator op,

                                  poplar::program::Sequence &prog,

                                  const CommGroup &group,

                                  const poplar::DebugContext &debugContext = {},

                                  const poplar::OptionFlags &options = {});


void allReduceInPlaceCrossReplica(poplar::Graph &graph, poplar::Tensor &data,

                                  CollectiveOperator op,

                                  poplar::program::Sequence &prog,

                                  const poplar::DebugContext &debugContext = {},

                                  const poplar::OptionFlags &options = {});


void allReduceInPlaceCrossReplica(poplar::Graph &graph,

                                  std::vector<poplar::Tensor> &datas,

                                  CollectiveOperator op,

                                  poplar::program::Sequence &prog,

                                  const poplar::DebugContext &debugContext = {},

                                  const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor reduceScatterCrossReplica(

    poplar::Graph &graph, const poplar::Tensor &data, CollectiveOperator op,

    poplar::program::Sequence &prog, const CommGroup &group,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


GCL_NO_DISCARD std::vector<poplar::Tensor> reduceScatterCrossReplica(

    poplar::Graph &graph, const std::vector<poplar::Tensor> &datas,

    CollectiveOperator op, poplar::program::Sequence &prog,

    const CommGroup &group, const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


void reduceScatterToDestinationCrossReplica(

    poplar::Graph &graph, const std::vector<poplar::Tensor> &datas,

    const std::vector<poplar::Tensor> &destinations, CollectiveOperator op,

    poplar::program::Sequence &prog, const CommGroup &group,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

reduceScatterCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                          CollectiveOperator op,

                          poplar::program::Sequence &prog,

                          const poplar::DebugContext &debugContext = {},

                          const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allGatherCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                      poplar::program::Sequence &prog, const CommGroup &group,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


GCL_NO_DISCARD std::vector<poplar::Tensor>

allGatherCrossReplica(poplar::Graph &graph,

                      const std::vector<poplar::Tensor> &datas,

                      poplar::program::Sequence &prog, const CommGroup &group,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


void allGatherToDestinationCrossReplica(

    poplar::Graph &graph, const std::vector<poplar::Tensor> &datas,

    const std::vector<poplar::Tensor> &destinations,

    poplar::program::Sequence &prog, const CommGroup &group,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allGatherCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                      poplar::program::Sequence &prog,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allToAllCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                     poplar::program::Sequence &prog, const CommGroup &group,

                     const poplar::DebugContext &debugContext = {},

                     const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allToAllCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                     poplar::program::Sequence &prog,

                     const poplar::DebugContext &debugContext = {},

                     const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

broadcastCrossReplica(poplar::Graph &graph, const poplar::Tensor &data,

                      poplar::program::Sequence &prog,

                      const CommGroup &group = {}, unsigned rootReplica = 0,

                      const poplar::DebugContext &debugContext = {},

                      const poplar::OptionFlags &options = {});


struct Chunk {

  GC_DEPRECATED_MSG("Use get/setTensor() instead")

  // NOLINTNEXTLINE(readability-identifier-naming)

  poplar::Tensor tensor;

  GC_DEPRECATED_MSG("Use get/setIndex() instead")

  // NOLINTNEXTLINE(readability-identifier-naming)

  unsigned index = 0;

  GC_DEPRECATED_MSG("Use get/setOffset() instead")

  // NOLINTNEXTLINE(readability-identifier-naming)

  unsigned offset = 0;


#pragma GCC diagnostic push

#pragma GCC diagnostic ignored "-Wdeprecated-declarations"

#pragma GCC diagnostic ignored "-Wshadow"

  // In the deprecation period we need to ensure none of the

  // default implementations warn about using the deprecated vars.

  Chunk() = default;

  ~Chunk() = default;

  Chunk(const Chunk &) = default;

  Chunk(Chunk &&) noexcept = default;

  Chunk &operator=(const Chunk &) = default;

  Chunk &operator=(Chunk &&) noexcept = default;


  Chunk(poplar::Tensor tensor, unsigned index, unsigned offset);

#pragma GCC diagnostic pop


  GCL_NO_DISCARD poplar::Tensor getTensor() const;


  GCL_NO_DISCARD unsigned getIndex() const;


  GCL_NO_DISCARD unsigned getOffset() const;


  void setTensor(poplar::Tensor tensor);


  void setIndex(unsigned index);


  void setOffset(unsigned offset);

};


struct Chunks {

  GC_DEPRECATED_MSG("Use get/setOriginalInput() instead")

  // NOLINTNEXTLINE(readability-identifier-naming)

  poplar::Tensor originalInput;

  GC_DEPRECATED_MSG("Use get/setChunks() instead")

  // NOLINTNEXTLINE(readability-identifier-naming)

  std::vector<Chunk> chunks;


#pragma GCC diagnostic push

#pragma GCC diagnostic ignored "-Wdeprecated-declarations"

#pragma GCC diagnostic ignored "-Wshadow"

  // In the deprecation period we need to ensure none of the

  // default implementations warn about using the deprecated vars.

  Chunks() = default;

  ~Chunks() = default;

  Chunks(const Chunks &) = default;

  Chunks(Chunks &&) noexcept = default;

  Chunks &operator=(const Chunks &) = default;

  Chunks &operator=(Chunks &&) noexcept = default;


  explicit Chunks(unsigned size) : chunks(std::vector<Chunk>(size)) {}

#pragma GCC diagnostic pop


  GCL_NO_DISCARD poplar::Tensor getOriginalInput() const;


  GCL_NO_DISCARD const std::vector<Chunk> &getChunks() const;


  void setOriginalInput(poplar::Tensor input);


  void setChunk(std::vector<Chunk>::size_type i, Chunk chunk);


  void setChunks(std::vector<Chunk> chunks);


  GCL_NO_DISCARD poplar::Tensor concat() const;

};


GC_DEPRECATED_MSG("Use Chunks::concat() instead")

poplar::Tensor concatChunks(const Chunks &chunks);


GCL_NO_DISCARD Chunks reduceScatterWithinReplica(

    poplar::Graph &graph, const poplar::Tensor &toReduce, CollectiveOperator op,

    poplar::program::Sequence &prog,

    const poplar::DebugContext &debugContext = {},

    const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allGatherWithinReplica(poplar::Graph &graph, const Chunks &toGather,

                       poplar::program::Sequence &prog,

                       const poplar::DebugContext &debugContext = {},

                       const poplar::OptionFlags &options = {});


GCL_NO_DISCARD poplar::Tensor

allReduceWithinReplica(poplar::Graph &graph, const poplar::Tensor &toReduce,

                       CollectiveOperator op, poplar::program::Sequence &prog,

                       const poplar::DebugContext &debugContext = {},

                       const poplar::OptionFlags &options = {});


} // namespace gcl

#endif // INCLUDE_GCL_COLLECTIVES_HPP

GCL_NO_DISCARD
#define GCL_NO_DISCARD
Produce compile time warning for unused return values.
Definition: Collectives.hpp:22

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::program::Sequence
Program that executes a sequence of programs.
Definition: Program.hpp:77

gcl
Graphcore Communications Library.

gcl::CommGroupType
CommGroupType
Enum to define communication group specification type.
Definition: Collectives.hpp:34

gcl::CommGroupType::ALL
@ ALL
All replicas viewed as one group.

gcl::CommGroupType::CONSECUTIVE
@ CONSECUTIVE
Groups are consecutive in replica.

gcl::CommGroupType::ORTHOGONAL
@ ORTHOGONAL
Groups are sliced orthogonal to the replica ordering.

gcl::operator>>
std::istream & operator>>(std::istream &is, CollectiveOperator &op)
Parse token from input stream is to op.

gcl::CollectiveOperator
CollectiveOperator
Supported collective operators.
Definition: Collectives.hpp:106

gcl::CollectiveOperator::LOGICAL_OR
@ LOGICAL_OR
Only supports boolean operands.

gcl::CollectiveOperator::LOCAL
@ LOCAL
Do nothing and keep the local value.

gcl::CollectiveOperator::SQUARE_ADD
@ SQUARE_ADD
Squares each element before applying ADD reduction.

gcl::CollectiveOperator::LOGICAL_AND
@ LOGICAL_AND
Only supports boolean operands.

gcl::allToAllCrossReplica
poplar::Tensor allToAllCrossReplica(poplar::Graph &graph, const poplar::Tensor &data, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Perform an all-to-all exchange of the elements of the input tensor based on replica ID.

gcl::allReduceInPlaceCrossReplica
void allReduceInPlaceCrossReplica(poplar::Graph &graph, poplar::Tensor &data, CollectiveOperator op, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
As allReduceCrossReplica() but writes result back to the input data tensor.

gcl::allGatherWithinReplica
poplar::Tensor allGatherWithinReplica(poplar::Graph &graph, const Chunks &toGather, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Broadcast data distributed over all IPUs.

gcl::allGatherToDestinationCrossReplica
void allGatherToDestinationCrossReplica(poplar::Graph &graph, const std::vector< poplar::Tensor > &datas, const std::vector< poplar::Tensor > &destinations, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
As allGatherCrossReplica() but with vector input/output arguments.

gcl::allReduceCrossReplica
poplar::Tensor allReduceCrossReplica(poplar::Graph &graph, const poplar::Tensor &data, CollectiveOperator op, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Perform an all-reduce operation.

gcl::broadcastCrossReplica
poplar::Tensor broadcastCrossReplica(poplar::Graph &graph, const poplar::Tensor &data, poplar::program::Sequence &prog, const CommGroup &group={}, unsigned rootReplica=0, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Perform a broadcast from one replica to all other replicas.

gcl::reduceScatterWithinReplica
Chunks reduceScatterWithinReplica(poplar::Graph &graph, const poplar::Tensor &toReduce, CollectiveOperator op, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Reduce a rank 2 tensor.

gcl::operator<<
std::ostream & operator<<(std::ostream &os, const CollectiveOperator &op)
Write op to output stream os.

gcl::allReduceWithinReplica
poplar::Tensor allReduceWithinReplica(poplar::Graph &graph, const poplar::Tensor &toReduce, CollectiveOperator op, poplar::program::Sequence &prog, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Perform an all-reduce operation on the specified tensor.

gcl::reduceScatterToDestinationCrossReplica
void reduceScatterToDestinationCrossReplica(poplar::Graph &graph, const std::vector< poplar::Tensor > &datas, const std::vector< poplar::Tensor > &destinations, CollectiveOperator op, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
As reduceScatterCrossReplica() but with vector input/output arguments.

gcl::allReduceToDestinationCrossReplica
void allReduceToDestinationCrossReplica(poplar::Graph &graph, const poplar::Tensor &data, poplar::Tensor &destination, CollectiveOperator op, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
As allReduceCrossReplica() but writes the result to the destination tensor.

gcl::concatChunks
poplar::Tensor concatChunks(const Chunks &chunks)
Concatenates chunks.

gcl::reduceScatterCrossReplica
poplar::Tensor reduceScatterCrossReplica(poplar::Graph &graph, const poplar::Tensor &data, CollectiveOperator op, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Reduce the replicated rank-1 tensor data with the result scattered across the replicas.

gcl::allGatherCrossReplica
poplar::Tensor allGatherCrossReplica(poplar::Graph &graph, const poplar::Tensor &data, poplar::program::Sequence &prog, const CommGroup &group, const poplar::DebugContext &debugContext={}, const poplar::OptionFlags &options={})
Gather the replicated tensor data.

poplar
Poplar classes and functions.
Definition: ArrayRef.hpp:14

gcl::Chunk
Represents a section of a tensor mapped to an IPU.
Definition: Collectives.hpp:802

gcl::Chunk::getOffset
unsigned getOffset() const
Offset within rank (model parallel index.

gcl::Chunk::offset
unsigned offset
Offset within rank (model parallel index.
Definition: Collectives.hpp:814

gcl::Chunk::setOffset
void setOffset(unsigned offset)
Set offset.

gcl::Chunk::Chunk
Chunk(const Chunk &)=default
Defaulted to avoid warnings in deprecation period.

gcl::Chunk::tensor
poplar::Tensor tensor
Mapped tensor.
Definition: Collectives.hpp:806

gcl::Chunk::getIndex
unsigned getIndex() const
Ring index (data parallel index)

gcl::Chunk::setTensor
void setTensor(poplar::Tensor tensor)
Set mapped tensor.

gcl::Chunk::getTensor
poplar::Tensor getTensor() const
Mapped tensor.

gcl::Chunk::setIndex
void setIndex(unsigned index)
Set ring index.

gcl::Chunk::index
unsigned index
Ring index (data parallel index)
Definition: Collectives.hpp:810

gcl::Chunk::Chunk
Chunk(Chunk &&) noexcept=default
Defaulted to avoid warnings in deprecation period.

gcl::Chunks
A vector of Chunk data.
Definition: Collectives.hpp:878

gcl::Chunks::concat
poplar::Tensor concat() const
Concatenates chunks.

gcl::Chunks::getOriginalInput
poplar::Tensor getOriginalInput() const
Used to undo shuffles introduced by scatter.

gcl::Chunks::originalInput
poplar::Tensor originalInput
Used to undo shuffles introduced by scatter.
Definition: Collectives.hpp:882

gcl::Chunks::setOriginalInput
void setOriginalInput(poplar::Tensor input)
Set original input.

gcl::Chunks::Chunks
Chunks(const Chunks &)=default
Defaulted to avoid warnings in deprecation period.

gcl::Chunks::setChunks
void setChunks(std::vector< Chunk > chunks)
Set chunks produced by scatter step.

gcl::Chunks::getChunks
const std::vector< Chunk > & getChunks() const
Chunks produced by the scatter step.

gcl::Chunks::Chunks
Chunks(Chunks &&) noexcept=default
Defaulted to avoid warnings in deprecation period.

gcl::Chunks::chunks
std::vector< Chunk > chunks
Chunks produced by the scatter step.
Definition: Collectives.hpp:886

gcl::Chunks::setChunk
void setChunk(std::vector< Chunk >::size_type i, Chunk chunk)
Set chunk.

gcl::CommGroup
Struct to specify sub-groups of replicas.
Definition: Collectives.hpp:70

gcl::CommGroup::operator<<
friend std::ostream & operator<<(std::ostream &os, const CommGroup &group)
String representation of the CommGroup.

gcl::CommGroup::mReplicaGroupSize
unsigned mReplicaGroupSize
Replica group size.
Definition: Collectives.hpp:90

gcl::CommGroup::CommGroup
CommGroup(const CommGroupType groupType, unsigned groupSize, unsigned replicaStride=1)
Construct CommGroup.

gcl::CommGroup::mReplicaGroupStride
unsigned mReplicaGroupStride
Replica group stride.
Definition: Collectives.hpp:94

gcl::CommGroup::mReplicaGroupType
CommGroupType mReplicaGroupType
Replica group type.
Definition: Collectives.hpp:87