This class represents a graph program to be executed on the IPU. More...

#include <Graph.hpp>

Public Types
using	HostFunctionArgument = std::tuple< Type, std::size_t >
	Add a host function to the graph. More...

Public Member Functions
	Graph (const Target &target, replication_factor r=replication_factor(1))
	Construct a graph object. More...

	Graph (const Device &device, replication_factor r=replication_factor(1))
	Construct a graph object. More...

const Target &	getTarget () const
	Retrieve the target that this graph is targeting.

bool	addCodelets (StringRef src, CodeletFileType type=CodeletFileType::Auto, StringRef compileFlags="", StringRef targetName="")
	Add a codelet to the graph. More...

bool	addCodelets (StringRef src, CodeletFileType type, StringRef compileFlags, std::ostream &compileOutput, StringRef targetName="")
	Add a codelet to the graph and write error messages from the compilation process to the given output stream. More...

bool	addCodelets (ArrayRef< std::string > xs, StringRef compileFlags="", StringRef targetName="")
	Add a set of codelets to the graph. More...

void	addCodelets (std::stringstream &stream, StringRef compileFlags="", CodeletFileType type=CodeletFileType::CppSource, StringRef targetName="")
	Take a codelet contained within the `stream` and store it in a temporary file which we then use to compile the codelet. More...

void	addCodeletPlaceholder (std::istream &stream, StringRef targetName="")
	Add a codelet from the description (JSON) to the graph. More...

VertexRef	addVertex (ComputeSet cs, StringRef vertexType)
	Add a vertex to the graph. More...

VertexRef	addVertex (ComputeSet cs, StringRef vertexType, ArrayRef< ConnectionDesc > connections)
	Add a vertex to the graph and connect graph elements to some of its fields. More...

VertexRef	addExternalExchangeVertex (ComputeSet cs, StringRef vertexType, unsigned incomingDownCount, bool usesEastEdge, bool sendsXReq)
	Add an external exchange vertex to the graph. More...

Tensor	addVariable (const Type &type, ArrayRef< std::size_t > shape, const DebugContext &debugContext={})
	Add a variable to the graph. More...

Tensor	addVariable (const Type &type, const Tensor &metadata, ArrayRef< std::size_t > shape, const DebugContext &debugContext={})
	Add a variable to the graph with a type that may require metadata. More...

Tensor	addVariable (const Type &type, ArrayRef< std::size_t > shape, VariableMappingMethod mappingMethod, const DebugContext &debugContext={})
	Add a variable to the graph. More...

Tensor	addVariable (const Type &type, const Tensor &metadata, ArrayRef< std::size_t > shape, VariableMappingMethod mappingMethod, const DebugContext &debugContext={})
	Add a variable to the graph with a type that may require metadata. More...

Tensor	addExternalVariable (const Type &type, ArrayRef< std::size_t > shape, StringRef symbol, const DebugContext &debugContext={})
	Add an external variable to the graph. More...

template<typename T >
Tensor	addConstant (const Type &type, const Tensor &metadata, ArrayRef< std::size_t > shape, ArrayRef< T > values, const DebugContext &debugContext={"<const>"})
	Add a constant to the graph with a type that may require metadata. More...

template<typename T >
Tensor	addConstant (const Type &type, ArrayRef< std::size_t > shape, ArrayRef< T > values, const DebugContext &debugContext={"<const>"})
	Add a constant to the graph. More...

template<typename T >
Tensor	addConstant (const Type &type, const Tensor &metadata, ArrayRef< std::size_t > shape, T val, const DebugContext &debugContext={"<const>"}, typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *=nullptr)
	Add a constant to the graph with a type that may require metadata. More...

template<typename T >
Tensor	addConstant (const Type &type, ArrayRef< std::size_t > shape, T val, const DebugContext &debugContext={"<const>"}, typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *=nullptr)
	Add a constant to the graph. More...

template<typename T >
Tensor	addConstant (const Type &type, ArrayRef< std::size_t > shape, const T val, const DebugContext &debugContext={"<const>"}, typename std::enable_if< TypeTraits::isSimpleType< T >()>::type =nullptr)
	Add a constant to the graph with multiple cell values. More...

Tensor	addConstantHalf (const Type &type, ArrayRef< std::size_t > shape, uint16_t val, const DebugContext &debugContext={"<const>"})
	Add a constant to the graph, where the host data is type IEEE half. More...

Tensor	addConstantHalf (const Type &type, ArrayRef< std::size_t > shape, const uint16_t *val, const DebugContext &debugContext={"<const>"})
	Add a constant to the graph with multiple cell values, where the host data is type IEEE half. More...

Tensor	clone (const Type &type, const Tensor &t, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES)
	Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t. More...

Tensor	clone (const Type &type, const Tensor &metadata, const Tensor &t, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES)
	Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t and that uses a type that may require metadata. More...

Tensor	cloneN (const Type &type, const Tensor &t, std::size_t N, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES, TensorCloneDuplicationMethod duplicationMethod=TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION)
	Clone a tensor N times. More...

Tensor	cloneN (const Type &type, const Tensor &metadata, const Tensor &t, std::size_t N, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES, TensorCloneDuplicationMethod duplicationMethod=TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION)
	Clone a tensor N times. More...

Tensor	clone (const Tensor &t, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES)
	Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t. More...

Tensor	clone (const Tensor &metadata, const Tensor &t, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES)
	Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t and that uses a type that may require metadata. More...

Tensor	cloneN (const Tensor &t, std::size_t N, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES, TensorCloneDuplicationMethod duplicationMethod=TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION)
	Clone a tensor N times. More...

Tensor	cloneN (const Tensor &metadata, const Tensor &t, std::size_t N, const DebugContext &debugContext={}, TensorCloneMethod method=TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES, TensorCloneDuplicationMethod duplicationMethod=TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION)
	Clone a tensor N times. More...

void	connect (FieldRef field, const Tensor &tensor)
	Connect a tensor to a vertex field. More...

template<typename T >
void	connect (FieldRef field, T v, typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *=nullptr)
	Connect a constant value to an input field. More...

void	connect (FieldRef field, ArrayRef< Tensor > tensors)
	Connect a vector of tensors to a vertex field. More...

void	setPerfEstimate (const VertexRef &v, std::uint64_t cycles, std::uint64_t flops=0)
	Set the performance estimate for a vertex. More...

void	setPerfEstimate (const VertexRef &v, const VertexPerfEstimate &estimate)
	Set the performance estimate for a vertex. More...

VertexPerfEstimate	getPerfEstimate (const VertexRef &v) const
	Get the performance estimate for the specified vertex. More...

void	registerPerfEstimator (StringRef vertexTypeName, PerfEstimateFunc f)

unsigned	getNumVertices (void) const
	Get the number of vertices currently in the graph. More...

ComputeSet	addComputeSet (const DebugContext &debugContext={})
	Create a compute set within the graph. More...

void	setFieldSize (FieldRef field, std::size_t size)
	Set the size of a vector field. More...

std::size_t	getFieldSize (FieldRef field) const
	Get the size of a vector field. More...

std::size_t	getMaxFieldDim (StringRef vertexName, StringRef fieldName, unsigned dimIndex) const
	Find the maximum size for a dimension of a field. More...

double	getMaxVertexFieldValue (StringRef vertexName, StringRef fieldName) const
	Find the maximum value that can be represented by an element of a field. More...

template<typename T >
void	setInitialValue (FieldRef field, T val, typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *=nullptr)
	Set the initial value of a field. More...

template<typename T >
void	setInitCallback (FieldRef field, LateInitCallback< T > callback, typename std::enable_if< std::is_arithmetic< T >::value >::type *=nullptr)
	Set the init callback for a field; the callback function will be called after graph construction and must return the init value of the field. More...

void	setInitialValueHalf (FieldRef field, uint16_t val)
	Set the initial value of a field of type IEEE half. More...

template<typename T >
void	setInitialValue (FieldRef field, ArrayRef< T > val)
	Set initial values of a vector field. More...

void	setInitialValueHalf (FieldRef field, ArrayRef< uint16_t > val)
	Set initial values of a vector field of type IEEE half. More...

template<typename T >
void	setInitialValue (const Tensor &t, T val, typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *=nullptr)
	Set the initial value of a tensor element. More...

void	setInitialValue (const Tensor &t, const std::map< unsigned, unsigned > &vals)
	Set a replica based initial value of a tensor element. More...

void	setInitialValueHalf (const Tensor &t, uint16_t val)
	Set the initial value of a tensor element of type IEEE half. More...

void	createHostWrite (StringRef handle, const Tensor &t, bool rearrangeOnHost=false)
	Mark a Tensor as being available as the destination of host to device copies. More...

void	createHostRead (StringRef handle, const Tensor &t, bool rearrangeOnHost=false)
	Mark a Tensor as being available as the source of device to host copies. More...

DataStream	addHostToDeviceFIFO (StringRef handle, const Type &elementType, std::size_t numElements, ReplicatedStreamMode replicatedMode=ReplicatedStreamMode::REPLICATE, const OptionFlags &options={})
	Add a data stream to the graph for copying data from the host to the device. More...

DataStream	addDeviceToHostFIFO (StringRef handle, const Type &elementType, std::size_t numElements, const OptionFlags &options={})
	Add a data stream to the graph for copying data from the device to the host. More...

RemoteBuffer	addRemoteBuffer (StringRef handle, const Type &elementType, std::size_t numElements, std::size_t repeats=1, bool rearrangeOnHost=false, bool optimiseMemory=false)
	Add a remote buffer to the graph. More...

void	outputVertexGraph (std::ostream &outputStream, ArrayRef< program::Program > progs={}) const
	Output the vertex graph to a stream in dot file format. More...

void	outputComputeGraph (std::ostream &outputStream, ArrayRef< program::Program > progs={}) const
	Output the compute graph to a stream in dot file format. More...

void	setTileMapping (VertexRef v, unsigned tileNum)
	Map a vertex to a specific tile on the device. More...

void	setTileMapping (const Tensor &t, unsigned tileNum)
	Map a tensor slice to a specific tile on the device. More...

TileToTensorMapping	getTileMapping (const Tensor &t, bool requireComplete=true, bool allowExternal=false) const
	Inspect the tile mapping of a tensor. More...

TileToTensorMapping	getTileMapping (const Tensor &t, bool *isComplete, bool allowExternal=false) const
	Inspect the tile mapping of a tensor. More...

TileToTensorMapping	getVariableTileMapping (const Tensor &t) const
	Inspect the tile mapping of a tensor. More...

void	setTileMapping (const Tensor &t, const TileToTensorMapping &mapping)
	Set the tile mapping of a tensor based on an explicit map from tiles to tensor intervals. More...

Tensor	getVariable (VariableRef v) const
	Get a tensor representing an entire variable. More...

bool	isConstant (VariableRef v) const
	Check whether a variable reference refers to a constant. More...

std::vector< std::vector< Interval > >	getSortedContiguousRegions (const Tensor &t, ArrayRef< Interval > regions, bool removeAliasedIntervals=false, std::vector< std::size_t > *aliases=nullptr) const
	Get a list of sequences of intervals over a tensor such that each sequence represents a contiguous region of memory. More...

void	reorderToSimplify (Tensor t, ArrayRef< Tensor > ts, bool requireSimplestOrder=true) const
	Reorder elements of a tensor to simplify the view on the data. More...

TensorRearranger	getSimplifyingRearranger (const Tensor &t) const
	Get a rearranger object for simplifying the underlying representation of a tensor. More...

Tensor	findUnbroadcastTensor (const Tensor &t) const
	Attempt to determine the shape of a Tensor prior to it having been broadcast. More...

void	serializeTensors (std::ostream &out, ArrayRef< Tensor > tensors, SerializationFormat format) const
	Serialize a set of tensors to JSON or CapnProto. More...

std::vector< Tensor >	deserializeTensors (std::istream &in, SerializationFormat format)
	Deserialize a set of tensors from a CapnProto message. More...

Graph	createVirtualGraph (unsigned numTilesPerIPU)
	Create a "virtual" graph using a subset of the target's tile. More...

Graph	createVirtualGraph (unsigned lowerTile, unsigned upperTile)
	Create a "virtual" graph that uses a subset of the target's tiles. More...

Graph	createVirtualGraph (const std::vector< unsigned > &perIpuTiles)
	Create a "virtual" graph that uses a subset of the target's tiles. More...

Graph	getTopLevelGraph ()
	Return the top level graph. More...

unsigned	getReplicationFactor () const
	Return the replication factor of the graph.

Tensor	addReplicationIndexConstant (const DebugContext &debugContext={})
	Add a constant that is initialized with the replication index.

void	serialize (std::ostream &out, SerializationFormat format) const
	Serialize a graph to JSON or binary (CapnProto) format. More...

void	serialize (std::ostream &out, ArrayRef< program::Program > progs, SerializationFormat format) const
	Serialize a graph to JSON or binary (CapnProto) format. More...

Function	addFunction (const program::Program &program)
	Add a function to the graph. More...

FunctionBuffer	addFunctionBuffer (const Function &f, FunctionBufferMappingType mappingType)
	Add a function buffer to the graph. More...

unsigned	convertTileToTopLevelGraphTile (unsigned tileId) const
	Convert a tile ID in this graph to a tile ID in the top level graph. More...

unsigned	convertTopLevelGraphTileToTile (unsigned topLevelGraphTileId) const
	Convert a tile ID in the top level graph to a tile ID in this graph. More...

unsigned	convertVirtualTileToPhysicalTile (unsigned tileId) const
	Convert a tile ID in this graph to a physical tile ID. More...

unsigned	convertPhysicalTileToVirtualTile (unsigned physicalTileId) const
	Convert a physical tile ID to a tile ID in this graph. More...

unsigned	convertPhysicalTileToVirtualTile (unsigned ipuId, unsigned physicalTileId) const
	Convert a physical tile ID to a tile ID in this graph. More...

bool	hasCodelet (StringRef codeletName) const
	Check if a graph contains a codelet with this name. More...

Detailed Description

This class represents a graph program to be executed on the IPU.

Member Typedef Documentation

◆ HostFunctionArgument

using poplar::Graph::HostFunctionArgument = std::tuple<Type, std::size_t>

Add a host function to the graph.

A host function allows running host code as part of an IPU program.

Parameters

handle	A name to be associated with this stream.
elementType	The type of data in the stream.
numElements	The number of elements to be transferred to the stream by a Copy program.

Returns: The HostFunction object that can be used by a Call program.

Constructor & Destructor Documentation

◆ Graph() [1/2]

poplar::Graph::Graph	(	const Target &	target,
		replication_factor	r = `replication_factor(1)`
	)

Construct a graph object.

This constructor creates a Graph object using the given graph programming environment.

Parameters

target	The target the graph is being constructed to work with.
r	Number of times graph is to be replicated (default is no replication)

◆ Graph() [2/2]

poplar::Graph::Graph	(	const Device &	device,
		replication_factor	r = `replication_factor(1)`
	)

Construct a graph object.

This constructor creates a Graph object using the given graph programming environment.

Parameters

device	The device the graph is being constructed to work with.
r	Number of times graph is to be replicated (default is no replication).

Member Function Documentation

◆ addCodeletPlaceholder()

void poplar::Graph::addCodeletPlaceholder	(	std::istream &	stream,
		StringRef	targetName = `""`
	)

Add a codelet from the description (JSON) to the graph.

The codelets added are always external ('static const bool isExternalCodelet = true;'), so the compute function must be specified separately. See the External codelets.

For example, the following is an example of codelet states specified in JSON format:

[{
        "name": "Placeholder",
        "type": "SupervisorVertex",
        "fields": {
                "in": "Input<Vector<half>>",
                "out": "Output<Vector<float>>"
        },
        "constraints": [
                "elem(*in) != elem(*out)"
        ]
}]

JSON fields description:

"name" - user defined vertex name;
"type" - vertex subclass type. See the The Vertex Class;
"fields" - descrides the vertex states in a key-value format (name-type);
- field name - user defined codelet state name;
- field type - vertex state type. See the Vertex state;
"constraints" - is an optional field. See the Memory Constraints;

◆ addCodelets() [1/4]

bool poplar::Graph::addCodelets	(	ArrayRef< std::string >	xs,
		StringRef	compileFlags = `""`,
		StringRef	targetName = `""`
	)

inline

Add a set of codelets to the graph.

These codelets can depend on each other. For example, symbols defined in one can be used by any other. The order is not important.

Returns: True if all the codelets are added successfully, or false if any of the codelets are not added because they already exist in the graph.

◆ addCodelets() [2/4]

void poplar::Graph::addCodelets	(	std::stringstream &	stream,
		StringRef	compileFlags = `""`,
		CodeletFileType	type = `CodeletFileType::CppSource`,
		StringRef	targetName = `""`
	)

Take a codelet contained within the stream and store it in a temporary file which we then use to compile the codelet.

The language type of the codelet in the stream can be specified, defaulting to C++.

Note that this is not idempotent, in other words, this function will throw an exception if called twice with the same stream, unlike the overload that takes a file path instead.

◆ addCodelets() [3/4]

bool poplar::Graph::addCodelets	(	StringRef	src,
		CodeletFileType	type,
		StringRef	compileFlags,
		std::ostream &	compileOutput,
		StringRef	targetName = `""`
	)

Add a codelet to the graph and write error messages from the compilation process to the given output stream.

By default they are printed to cerr.

◆ addCodelets() [4/4]

bool poplar::Graph::addCodelets	(	StringRef	src,
		CodeletFileType	type = `CodeletFileType::Auto`,
		StringRef	compileFlags = `""`,
		StringRef	targetName = `""`
	)

Add a codelet to the graph.

A codelet is either a C, C++, or assembly source file, or a .gp object file. If a source file is given it is compiled for the graph's target and then loaded into the graph. If it is an object file then it is loaded into the graph.

Symbols that codelets use are not resolved until the engine is built, so codelets can use symbols from each other by calling addCodelets() for each source or object file (or passing a list of files as a vector).

Parameters

src	The path to a source or object file containing codelets.
type	Specify the type of the codelet (source or precompiled). If the value is CodeletFileType::Auto is used, the type is determined from the filename extension.
compileFlags	Additional flags to pass to the compiler if using source code. For example, `-g` to generate debug info.
targetName	Allows you to load a specific target from a precompiled '.gp' object file. An object file can have multiple targets built-in, for example, built with different sets of compilation flags or/and architectures. If not provided, graph's target will be used to look for a target to load. This option doesn't have any effect when adding codelets from a source file.

Returns: True if the codelet is added to the graph successfully, or false if the codelet already existed in the graph.

◆ addComputeSet()

ComputeSet poplar::Graph::addComputeSet ( const DebugContext & debugContext = {} )

Create a compute set within the graph.

Parameters

debugContext An optional debug context to identify the compute set for debugging/profiling purposes.

Returns: The reference to the compute set.

◆ addConstant() [1/5]

template<typename T >

Tensor poplar::Graph::addConstant	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		ArrayRef< T >	values,
		const DebugContext &	debugContext = `{"<const>"}`
	)

inline

Add a constant to the graph.

An associated metadata tensor is created if the type requires metadata.

A constant tensor is a tensor with every element initialized.

Parameters

type	The type of the elements of the constant.
shape	The shape of the constant.
values	Vector of values to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

◆ addConstant() [2/5]

template<typename T >

Tensor poplar::Graph::addConstant	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		const T *	val,
		const DebugContext &	debugContext = `{"<const>"}`,
		typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *	= `nullptr`
	)

inline

Add a constant to the graph with multiple cell values.

A constant tensor is a tensor with every element initialized to the same value. It cannot be connected to a vertex output.

Parameters

type	The type of the elements of the constant.
shape	The shape of the constant.
val	The value to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

◆ addConstant() [3/5]

template<typename T >

Tensor poplar::Graph::addConstant	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		T	val,
		const DebugContext &	debugContext = `{"<const>"}`,
		typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *	= `nullptr`
	)

inline

Add a constant to the graph.

An associated metadata tensor is created if the type requires metadata.

A constant tensor is a tensor with every element initialized to the same value. It cannot be connected to a vertex output.

Parameters

type	The type of the elements of the constant.
shape	The shape of the constant.
val	The value to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

◆ addConstant() [4/5]

template<typename T >

Tensor poplar::Graph::addConstant	(	const Type &	type,
		const Tensor &	metadata,
		ArrayRef< std::size_t >	shape,
		ArrayRef< T >	values,
		const DebugContext &	debugContext = `{"<const>"}`
	)

inline

Add a constant to the graph with a type that may require metadata.

A constant tensor is a tensor with every element initialized.

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Parameters

type	The type of the elements of the constant.
metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
shape	The shape of the constant.
values	Vector of values to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

◆ addConstant() [5/5]

template<typename T >

Tensor poplar::Graph::addConstant	(	const Type &	type,
		const Tensor &	metadata,
		ArrayRef< std::size_t >	shape,
		T	val,
		const DebugContext &	debugContext = `{"<const>"}`,
		typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *	= `nullptr`
	)

inline

Add a constant to the graph with a type that may require metadata.

A constant tensor is a tensor with every element initialized to the same value. It cannot be connected to a vertex output.

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Parameters

type	The type of the elements of the constant.
metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
shape	The shape of the constant.
val	The value to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

◆ addConstantHalf() [1/2]

Tensor poplar::Graph::addConstantHalf	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		const uint16_t *	val,
		const DebugContext &	debugContext = `{"<const>"}`
	)

inline

Add a constant to the graph with multiple cell values, where the host data is type IEEE half.

A constant tensor is a tensor with every element initialized to the same value. It cannot be connected to a vertex output.

Parameters

type	The type of the elements of the constant.
shape	The shape of the constant.
val	The value to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

◆ addConstantHalf() [2/2]

Tensor poplar::Graph::addConstantHalf	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		uint16_t	val,
		const DebugContext &	debugContext = `{"<const>"}`
	)

inline

Add a constant to the graph, where the host data is type IEEE half.

A constant tensor is a tensor with every element initialized to the same value. It cannot be connected to a vertex output.

Parameters

type	The type of the elements of the constant.
shape	The shape of the constant.
val	The value to initialize tensor elements to.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the constant in the graph.

◆ addDeviceToHostFIFO()

DataStream poplar::Graph::addDeviceToHostFIFO	(	StringRef	handle,
		const Type &	elementType,
		std::size_t	numElements,
		const OptionFlags &	options = `{}`
	)

Add a data stream to the graph for copying data from the device to the host.

Supported options:

splitLimit Integer [=50 * 1024 * 1024]

The maximum size of the FIFO before it is split into multiple FIFOs. This is a useful option to avoid exceeding the stream buffer size limit. If the original FIFO is larger than the specified split limit, then it is replaced by a number of FIFOs which represent chunks of the original FIFO, and are read from sequentially. Setting splitLimit to 0 or UINT_MAX disables this option.

Parameters

handle	A name to be associated with this stream.
elementType	The type of data in the stream.
numElements	The number of elements to be transferred to the stream by a Copy program.
options	List of options.

◆ addExternalExchangeVertex()

VertexRef poplar::Graph::addExternalExchangeVertex	(	ComputeSet	cs,
		StringRef	vertexType,
		unsigned	incomingDownCount,
		bool	usesEastEdge,
		bool	sendsXReq
	)

Add an external exchange vertex to the graph.

A compute set can contain at most one external exchange vertex per tile. External exchange vertices cannot be mixed with non external exchange vertices in the same compute set. Before an external vertex is called we set the INCOMING_DCOUNT and INCOMING_MUX mux registers and synchronize all tiles containing external exchange vertices.

Parameters

cs	The compute set to add the vertex to.
vertexType	The name of the type of the vertex. This must be a declared vertex type in the graph programming environment used to create the graph builder.
incomingDownCount	The value to set the `INCOMING_DCOUNT` register to.
usesEastEdge	Whether the vertex uses an east edge exchange block. The `INCOMING_MUX` register is set to point to either the east edge or west edge depending on this argument.
sendsXReq	Whether this vertex is responsible for sending the XREQ packet. There must be at most one tile per exchange block context that sends the XREQ and the tile must be the same in every compute set containing external exchange vertices.

◆ addExternalVariable()

Tensor poplar::Graph::addExternalVariable	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		StringRef	symbol,
		const DebugContext &	debugContext = `{}`
	)

Add an external variable to the graph.

Parameters

type	The type of the elements of the variable.
shape	The shape of the variable.
symbol	The symbol the external variable is associated with.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the external variable in the graph.

◆ addFunction()

Function poplar::Graph::addFunction ( const program::Program & program )

Add a function to the graph.

A function is a partial control program that can be reused. By registering a repeated program as a function and calling it, less control code is generated than repeating the sequence.

Parameters

program The control program to register as a callable function.

Returns: The Function object that can be used by a Call program.

◆ addFunctionBuffer()

FunctionBuffer poplar::Graph::addFunctionBuffer	(	const Function &	f,
		FunctionBufferMappingType	mappingType
	)

Add a function buffer to the graph.

A function buffer is an object that stores code and constant graph state associated with a particular Function. The FunctionBuffer has an initial value the same as the code/graph state it contains, and may be copied to/from another FunctionBuffer or to a Function via a Poplar Copy program.

This can be used to manage the lifetime and storage of code and constant graph state associated with a particular Function. The following example places state associated with a Function 'f' in remote memory and copies it to executable memory just before calling it:

Sequence someProgram;
auto f = graph.addFunction(someProgram);
auto fBuffer =
  graph.addFunctionBuffer(f, FunctionBufferMappingType::REMOTE);
 
Sequence prog;
// code/graph state associated with f becomes live during the
// following Copy program which moves the code/graph state into tile
// memory ready for execution.
prog.add(Copy(fBuffer, f));
// code/graph state is read during execution of the function.
prog.add(Call(f));
// Now code/graph state associated with f no longer need be live, unless
// it is called elsewhere in Poplar programs.

Parameters

f	The function whose code/graph state will be stored in the buffer.
mappingType	The mapping of storage for the buffer.

Returns: A FunctionBuffer object that may be used with Poplar Copy programs between other FunctionBuffer and Function objects.

◆ addHostToDeviceFIFO()

DataStream poplar::Graph::addHostToDeviceFIFO	(	StringRef	handle,
		const Type &	elementType,
		std::size_t	numElements,
		ReplicatedStreamMode	replicatedMode = `ReplicatedStreamMode::REPLICATE`,
		const OptionFlags &	options = `{}`
	)

Add a data stream to the graph for copying data from the host to the device.

Supported options:

splitLimit Integer [=50 * 1024 * 1024]

The maximum size of the FIFO before it is split into multiple FIFOs. This is a useful option to avoid exceeding the stream buffer size limit. If the original FIFO is larger than the specified split limit, then it is replaced by a number of FIFOs which represent chunks of the original FIFO, and are read from sequentially. Setting splitLimit to 0 or UINT_MAX disables this option.
bufferingDepth Integer [=1]

The depth of the FIFO which can be prefetched before being read by the device. By default the FIFO size is 1, so it prefetches a single entry, after it has been read, to refill the FIFO. Increasing the size of the FIFO allows for prefetching of multiple entries, increasing the probability there will be a valid entry in the FIFO for the device to read before falling back to synchronously fetching the next entry.

Parameters

handle	A name to be associated with this stream.
elementType	The type of data in the stream.
numElements	The number of elements to be transferred from the stream by a Copy program.
replicatedMode	How the stream is replicated if this is a replicated graph.
options	List of options.

◆ addRemoteBuffer()

RemoteBuffer poplar::Graph::addRemoteBuffer	(	StringRef	handle,
		const Type &	elementType,
		std::size_t	numElements,
		std::size_t	repeats = `1`,
		bool	rearrangeOnHost = `false`,
		bool	optimiseMemory = `false`
	)

Add a remote buffer to the graph.

A remote buffer is memory outside the IPU which can be read and written by the IPU. A read returns the last written value. The remote buffer is (repeats * numElements * sizeof(elementType) + padding) bytes in size. Padding is added to meet any alignment constraints of the hardware.

Parameters

handle	A name to be associated with this remote buffer.
elementType	The type of data in the remote buffer.
numElements	The number of elements to be transferred to the remote buffer by a Copy program.
repeats	The buffer can store multiple blocks of data to be transferred. The total number of data elements in the buffer is `numElements` * `repeats`.
rearrangeOnHost	Perform any necessary data rearrangement on the on the host instead of on the IPU.
optimiseMemory	Optimise for memory use rather than speed.

◆ addVariable() [1/4]

Tensor poplar::Graph::addVariable	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		const DebugContext &	debugContext = `{}`
	)

Add a variable to the graph.

An associated metadata tensor is created if the type requires metadata.

If using this function with a target with multiple tiles then the variable will initially have no tile mapping. It is expected that the tile mapping will be set later with Graph::setTileMapping(). If the target of the graph has only one tile then the tensor will be automatically mapped to that tile.

Parameters

type	The type of the elements of the variable.
shape	The shape of the variable.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the variable in the graph.

◆ addVariable() [2/4]

Tensor poplar::Graph::addVariable	(	const Type &	type,
		ArrayRef< std::size_t >	shape,
		VariableMappingMethod	mappingMethod,
		const DebugContext &	debugContext = `{}`
	)

Add a variable to the graph.

An associated metadata tensor is created if the type requires metadata.

Parameters

type	The type of the elements of the variable.
shape	The shape of the variable.
mappingMethod	The method to use to initially map the variable to tiles.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the variable in the graph.

◆ addVariable() [3/4]

Tensor poplar::Graph::addVariable	(	const Type &	type,
		const Tensor &	metadata,
		ArrayRef< std::size_t >	shape,
		const DebugContext &	debugContext = `{}`
	)

Add a variable to the graph with a type that may require metadata.

If using this function with a target with multiple tiles then the variable will initially have no tile mapping. It is expected that the tile mapping will be set later with Graph::setTileMapping(). If the target of the graph has only one tile then the tensor will be automatically mapped to that tile.

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Parameters

type	The type of the elements of the variable.
metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
shape	The shape of the variable.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the variable in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

◆ addVariable() [4/4]

Tensor poplar::Graph::addVariable	(	const Type &	type,
		const Tensor &	metadata,
		ArrayRef< std::size_t >	shape,
		VariableMappingMethod	mappingMethod,
		const DebugContext &	debugContext = `{}`
	)

Add a variable to the graph with a type that may require metadata.

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Parameters

type	The type of the elements of the variable.
metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
shape	The shape of the variable.
mappingMethod	The method to use to initially map the variable to tiles.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.

Returns: A tensor referring to the variable in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

◆ addVertex() [1/2]

VertexRef poplar::Graph::addVertex	(	ComputeSet	cs,
		StringRef	vertexType
	)

Add a vertex to the graph.

Parameters

cs	The compute set to add the vertex to.
vertexType	The name of the type of the vertex. This must be a declared vertex type in the graph programming environment used to create the graph builder.

◆ addVertex() [2/2]

VertexRef poplar::Graph::addVertex	(	ComputeSet	cs,
		StringRef	vertexType,
		ArrayRef< ConnectionDesc >	connections
	)

inline

Add a vertex to the graph and connect graph elements to some of its fields.

This variant of add vertex allows you to pass in a list of connection descriptions to connect graph elements to fields of the newly created vertex. The connection descriptions can be initialized with:

{ string, Tensor } - connect a tensor to a field.
{ string, FieldRef, bool } - connect a vertex field to a field.
{ string, T v } - connect a constant value to an input field.

For example, the following:

addVertex(cs, "MyVertex", {{"x", tensor[4]}, {"y", v["z"], false}});

poplar::Graph::addVertex

VertexRef addVertex(ComputeSet cs, StringRef vertexType)

Add a vertex to the graph.

Will create a vertex and connect a tensor to its x field and the vertex field v["z"] to its y field.

Parameters

cs	The compute set to add the vertex to.
vertexType	The name of the type of the vertex. This must be a declared vertex type in the graph programming environment used to create the graph builder.
connections	A list of connection descriptions.

◆ clone() [1/4]

Tensor poplar::Graph::clone	(	const Tensor &	metadata,
		const Tensor &	t,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`
	)

inline

Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t and that uses a type that may require metadata.

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Note: If tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
t	The tensor to be cloned.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The method to use for the cloning (decides whether to preserve ordering/aliasing in the new tensor).

Returns: A tensor referring to the cloned variable in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

◆ clone() [2/4]

Tensor poplar::Graph::clone	(	const Tensor &	t,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`
	)

inline

Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t.

An associated metadata tensor is created if the type requires metadata.

Note: If tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

t	The tensor to be cloned.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The method to use for the cloning (decides whether to preserve ordering/aliasing in the new tensor).

Returns: A tensor referring to the cloned variable in the graph.

◆ clone() [3/4]

Tensor poplar::Graph::clone	(	const Type &	type,
		const Tensor &	metadata,
		const Tensor &	t,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`
	)

Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t and that uses a type that may require metadata.

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Note: If type requires metadata and tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

type	The element type of the new tensor.
metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
t	The tensor to be cloned.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The method to use for the cloning (decides whether to preserve ordering/aliasing in the new tensor).

Returns: A tensor referring to the cloned variable in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

◆ clone() [4/4]

Tensor poplar::Graph::clone	(	const Type &	type,
		const Tensor &	t,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`
	)

Add a non-constant tensor to the graph that has the same size and tile mapping as Tensor t.

An associated metadata tensor is created if the type requires metadata.

Note: If type requires metadata and tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

type	The element type of the new tensor.
t	The tensor to be cloned.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The method to use for the cloning (decides whether to preserve ordering/aliasing in the new tensor).

Returns: A tensor referring to the cloned variable in the graph.

◆ cloneN() [1/4]

Tensor poplar::Graph::cloneN	(	const Tensor &	metadata,
		const Tensor &	t,
		std::size_t	N,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`,
		TensorCloneDuplicationMethod	duplicationMethod = `TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION`
	)

inline

Clone a tensor N times.

The tensor uses a type that may require metadata.

Given a tensor of shape [D1, D2, ... Dn], this function will create a new tensor of shape [N, D1, D2, ..., Dn] where each of the N sub-tensors is a clone of the original tensor (meaning it has the same layout and tile mapping).

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Note: If tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
t	The tensor to clone.
N	The replication factor to clone with.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The tensor cloning method (see Graph::clone()).
duplicationMethod	The behaviour used when a tensor is cloned.

Returns: A tensor referring to the cloned variable in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

See also: TensorCloneDuplicationMethod

◆ cloneN() [2/4]

Tensor poplar::Graph::cloneN	(	const Tensor &	t,
		std::size_t	N,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`,
		TensorCloneDuplicationMethod	duplicationMethod = `TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION`
	)

inline

Clone a tensor N times.

The tensor uses a type that does not require metadata.

Given a tensor of shape [D1, D2, ... Dn], this function will create a new tensor of shape [N, D1, D2, ..., Dn] where each of the N sub-tensors is a clone of the original tensor (meaning it has the same layout and tile mapping).

Note: If tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

t	The tensor to clone.
N	The replication factor to clone with.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The tensor cloning method (see Graph::clone()).
duplicationMethod	The behaviour used when a tensor is cloned.

Returns: A tensor referring to the cloned variable in the graph.

See also: TensorCloneDuplicationMethod

◆ cloneN() [3/4]

Tensor poplar::Graph::cloneN	(	const Type &	type,
		const Tensor &	metadata,
		const Tensor &	t,
		std::size_t	N,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`,
		TensorCloneDuplicationMethod	duplicationMethod = `TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION`
	)

Clone a tensor N times.

The tensor uses a type that may require metadata.

Given a tensor of shape [D1, D2, ... Dn], this function will create a new tensor of shape [N, D1, D2, ..., Dn] where each of the N sub-tensors is a clone of the original tensor (meaning it has the same layout and tile mapping).

If the type requires metadata and an empty tensor is passed to the metadata argument poplar internally creates a metadata tensor. A tensor is considered to be "empty" if the Tensor::valid() method returns false.

Note: If type requires metadata and tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

type	The element type of the new tensor.
metadata	Metadata tensor if the type requires metadata. If the type does not require metadata an empty tensor should be passed.
t	The tensor to clone.
N	The replication factor to clone with.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The tensor cloning method (see Graph::clone()).
duplicationMethod	The behaviour used when a tensor is cloned.

Returns: A tensor referring to the cloned variable in the graph.

Exceptions

tensor_creation_error If type is not QUARTER and a non-empty metadata argument is used.

See also: TensorCloneDuplicationMethod

◆ cloneN() [4/4]

Tensor poplar::Graph::cloneN	(	const Type &	type,
		const Tensor &	t,
		std::size_t	N,
		const DebugContext &	debugContext = `{}`,
		TensorCloneMethod	method = `TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES`,
		TensorCloneDuplicationMethod	duplicationMethod = `TensorCloneDuplicationMethod::DUPLICATE_BY_OUTER_DIMENSION`
	)

Clone a tensor N times.

An associated metadata tensor is created if the type requires metadata.

Given a tensor of shape [D1, D2, ... Dn], this function will create a new tensor of shape [N, D1, D2, ..., Dn] where each of the N sub-tensors is a clone of the original tensor (meaning it has the same layout and tile mapping).

Note: If type requires metadata and tensor t has metadata the tensor returned by this function will not use the same metadata as t. The caller is responsible for initialising the newly created metadata tensor.

Parameters

type	The element type of the new tensor.
t	The tensor to clone.
N	The replication factor to clone with.
debugContext	An optional debug context to identify the variable for debugging/profiling purposes.
method	The tensor cloning method (see Graph::clone()).
duplicationMethod	The behaviour used when a tensor is cloned.

Returns: A tensor referring to the cloned variable in the graph.

See also: TensorCloneDuplicationMethod

◆ connect() [1/3]

void poplar::Graph::connect	(	FieldRef	field,
		ArrayRef< Tensor >	tensors
	)

inline

Connect a vector of tensors to a vertex field.

This function connects an vector a tensors with a vertex field. The field must be a vector of inputs or outputs. The field will be sized to the provided vector and each element will be connect to the corresponding element of the field.

Parameters

tensors	The vector of tensors.
field	Reference to the vertex field to connect.

◆ connect() [2/3]

void poplar::Graph::connect	(	FieldRef	field,
		const Tensor &	tensor
	)

Connect a tensor to a vertex field.

This function connects an a tensor with a vertex field. If the vertex field is an scalar input/output then a simple edge is added (and the tensor must be of zero dimension; in other words, a scalar).

If the vertex field is an input/output of a vector then a vector edge is added (and the tensor must be of dimension 1).

If the vertex field is a vector of inputs or outputs then the size of the field is set to the correct size and edges are added for every element of the tensor tensor (and the tensor must be of dimension 1).

If the vertex field is a vector of input or output vectors then the tensor must be 2-dimensional. In this case, the size of the vector field is set to the size of the first dimension and vector edges are added for every sub-vector of the two dimensional tensor.

Parameters

tensor	The tensor.
field	Reference to the vertex field to connect.

◆ connect() [3/3]

template<typename T >

void poplar::Graph::connect	(	FieldRef	field,
		T	v,
		typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *	= `nullptr`
	)

inline

Connect a constant value to an input field.

This method creates a single-element tensor containing a specified value and connects that tensor element to an input field.

Parameters

v	The value to connect.
field	The field to connect to.

◆ convertPhysicalTileToVirtualTile() [1/2]

unsigned poplar::Graph::convertPhysicalTileToVirtualTile	(	unsigned	ipuId,
		unsigned	physicalTileId
	)		const

Convert a physical tile ID to a tile ID in this graph.

This returns the tile ID in this graph of the respective IPU and and physical tile ID.

Parameters

ipuId	The IPU ID.
physicalTileId	The physical tile ID.

Returns: The corresponding tile ID in this graph.

◆ convertPhysicalTileToVirtualTile() [2/2]

unsigned poplar::Graph::convertPhysicalTileToVirtualTile ( unsigned physicalTileId ) const

Convert a physical tile ID to a tile ID in this graph.

This returns the tile ID in this graph of respective physical tile ID, implicitly on IPU 0.

Parameters

physicalTileId A physical tile ID.

Returns: The corresponding virtual tile ID.

◆ convertTileToTopLevelGraphTile()

unsigned poplar::Graph::convertTileToTopLevelGraphTile ( unsigned tileId ) const

Convert a tile ID in this graph to a tile ID in the top level graph.

Parameters

tileId A tile ID in this graph.

Returns: The corresponding tile ID in the top level graph.

◆ convertTopLevelGraphTileToTile()

unsigned poplar::Graph::convertTopLevelGraphTileToTile ( unsigned topLevelGraphTileId ) const

Convert a tile ID in the top level graph to a tile ID in this graph.

Parameters

topLevelGraphTileId A poplar tile ID in the top level graph.

Returns: The corresponding tile ID in this graph.

◆ convertVirtualTileToPhysicalTile()

unsigned poplar::Graph::convertVirtualTileToPhysicalTile ( unsigned tileId ) const

Convert a tile ID in this graph to a physical tile ID.

Parameters

tileId A virtual tile ID.

Returns: The corresponding physical tile ID.

◆ createHostRead()

void poplar::Graph::createHostRead	(	StringRef	handle,
		const Tensor &	t,
		bool	rearrangeOnHost = `false`
	)

Mark a Tensor as being available as the source of device to host copies.

This is a convenience function that creates a device-to-host FIFO, and a Copy program that copies data to the FIFO from the tensor. When you call Engine::writeTensor() it executes the Copy program on the device and then outputs the data from the FIFO.

See also: Engine::readTensor()

Parameters

handle	A name to be associated with this host copy.
t	The tensor to be marked as an output.
rearrangeOnHost	Save IPU memory at the cost of exchange speed by sending data in any order and rearranging it on the host, rather than doing an internal exchange before sending it.

◆ createHostWrite()

void poplar::Graph::createHostWrite	(	StringRef	handle,
		const Tensor &	t,
		bool	rearrangeOnHost = `false`
	)

Mark a Tensor as being available as the destination of host to device copies.

This is a convenience function that creates a host-to-device FIFO, and a Copy program that copies data from the FIFO to the tensor. When you call Engine::writeTensor() it copies the input data to the FIFO and then executes the Copy program on the device.

See also: Engine::writeTensor()

Parameters

handle	A name to be associated with this host copy.
t	The tensor to be marked as an input.
rearrangeOnHost	Save IPU memory at the cost of exchange speed by rearranging the data on the host before sending it to the IPU, rather than doing an internal exchange. Note that due to alignment and size requirements of host exchange packets this may still require part of the transfer to be received to a temporary variable and copied to its destination.

◆ createVirtualGraph() [1/3]

Graph poplar::Graph::createVirtualGraph ( const std::vector< unsigned > & perIpuTiles )

Create a "virtual" graph that uses a subset of the target's tiles.

This method returns a graph object that references the same state as this graph but has a virtual target than only uses a subset of the target's tiles.

This variant of the method takes the set of tiles in each IPU that should be included in the new graph.

If the getTarget() method is called on the new graph it will return a target with the new number of tiles.

Parameters

perIpuTiles The tiles to include in the graph. Tiles are specified by their index in the IPU. Each tile index must be unique and less than the number of tiles per IPU.

Returns: The virtual graph object.

◆ createVirtualGraph() [2/3]

Graph poplar::Graph::createVirtualGraph	(	unsigned	lowerTile,
		unsigned	upperTile
	)

Create a "virtual" graph that uses a subset of the target's tiles.

This method returns a graph object that references the same state as this graph but has a virtual target than only uses a subset of the target's tiles.

This variant of the method takes a tile range for the new virtual graph to use. The range is [lowerTile, upperTile). This tile range must be contained within a single IPU.

If the getTarget() method is called on the new graph it will return a target with the new number of tiles.

Parameters

lowerTile	The starting tile of the tile range for the virtual graph to use.
upperTile	The upper bound of the tile range for the virtual graph to use. This is a non-inclusive upper bound.

Returns: The virtual graph object.

◆ createVirtualGraph() [3/3]

Graph poplar::Graph::createVirtualGraph ( unsigned numTilesPerIPU )

Create a "virtual" graph using a subset of the target's tile.

This method returns a graph object that references the same state as this graph but has a virtual target than only uses a subset of the target's tiles.

If the getTarget() method is called on the new graph it will return a target with the new number of tiles.

Parameters

numTilesPerIPU The number of tiles per IPU for the new graph to use.

Returns: The virtual graph object.

◆ deserializeTensors()

std::vector< Tensor > poplar::Graph::deserializeTensors	(	std::istream &	in,
		SerializationFormat	format
	)

Deserialize a set of tensors from a CapnProto message.

JSON deserialization is not currently supported and an exception will be thrown if format is SerializationFormat::JSON.

This will recreate the tensors in this graph. It throws an exception on failure (for example, if the tensor type does not match the variable types). Whenever a variable is used by a tensor a new variable is added to the graph.

The layout of the tensors and variables should be the same as when they were serialized.

This function is primarily intended for testing and benchmarks. You should not use it as a general method of creating tensors.

Parameters

in	A stream from which serialised tensor data can be read.
format	Must be SerializationFormat::Binary.

Returns: The deserialized set of tensors.

◆ findUnbroadcastTensor()

Tensor poplar::Graph::findUnbroadcastTensor ( const Tensor & t ) const

Attempt to determine the shape of a Tensor prior to it having been broadcast.

Under some circumstances this may not be possible, failure is indicated by the returned tensor having the same shape as the input tensor

Parameters

t	The input tensor

Returns: A tensor which will be set to the unbroadcast (sliced from t) tensor if it is possible to do so. Each dimension of the returned tensor will be a factor of the same dimension of the input tensor. The returned tensor will have the same rank as the input tensor. If it is not possible to determine the shape of the unbroadcast tensor the input tensor will be returned.

◆ getFieldSize()

std::size_t poplar::Graph::getFieldSize ( FieldRef field ) const

Get the size of a vector field.

Parameters

field The reference to the field.

Returns: The size of the field.

◆ getMaxFieldDim()

std::size_t poplar::Graph::getMaxFieldDim	(	StringRef	vertexName,
		StringRef	fieldName,
		unsigned	dimIndex
	)		const

Find the maximum size for a dimension of a field.

Parameters

vertexType	The type of vertex
field	The field
dimIndex	The index of the dimension

Exceptions

index_error	If there is no such dimension
poplar_error	If the field is not indexable

◆ getMaxVertexFieldValue()

double poplar::Graph::getMaxVertexFieldValue	(	StringRef	vertexName,
		StringRef	fieldName
	)		const

Find the maximum value that can be represented by an element of a field.

Parameters

vertexType	The type of vertex
field	The field

◆ getNumVertices()

unsigned poplar::Graph::getNumVertices ( void ) const

Get the number of vertices currently in the graph.

Returns: The numbers of vertices currently in the graph.

◆ getPerfEstimate()

VertexPerfEstimate poplar::Graph::getPerfEstimate ( const VertexRef & v ) const

Get the performance estimate for the specified vertex.

Parameters

v	The vertex to get the estimate for.

Returns: The performance estimates used when this vertex is run.

Exceptions

missing_perf_estimate if the performance estimate is not available (for example, because the graph hasn't been executed yet).

◆ getSimplifyingRearranger()

TensorRearranger poplar::Graph::getSimplifyingRearranger ( const Tensor & t ) const

Get a rearranger object for simplifying the underlying representation of a tensor.

This rearranger will rearrange the tensor to simplify the underlying representation to reduce the processing time for functions such as getContiguousRegions(), getTileMapping().

The actual reordering is unspecified and depends on the underlying representation with the Poplar library (however it can always be undone using the TensorRearranger object).

Parameters

t	The tensor to simplify.

Returns: A TensorRearranger object that can perform the rearrangement.

◆ getSortedContiguousRegions()

std::vector< std::vector< Interval > > poplar::Graph::getSortedContiguousRegions	(	const Tensor &	t,
		ArrayRef< Interval >	regions,
		bool	removeAliasedIntervals = `false`,
		std::vector< std::size_t > *	aliases = `nullptr`
	)		const

Get a list of sequences of intervals over a tensor such that each sequence represents a contiguous region of memory.

Parameters

t	The tensor to get intervals over.
regions	A list of intervals representing the elements to sort in to contiguous sequences in memory.
removeAliasedIntervals	If true, remove intervals which alias others in the given regions from the result.
aliases	Optional list of indices for each region in the returned intervals where an index is always the same for a region representing the same underlying elements in memory. If this is nullptr, then no aliases will be returned.

Returns: A list of sequences of intervals. The intervals will cover the same elements as the intput tensor.

◆ getTileMapping() [1/2]

TileToTensorMapping poplar::Graph::getTileMapping	(	const Tensor &	t,
		bool *	isComplete,
		bool	allowExternal = `false`
	)		const

Inspect the tile mapping of a tensor.

Parameters

t	The tensor to inspect
isComplete	If non-null, updated to indicate whether the mapping is complete.
allowExternal	Allow some of the tensor to be mapped to tiles not belonging to this Graph. These elements will not be included in the result.

Returns: The mapping from tiles to a vector of intervals mapped to the tile (implemented as vector indexed by the tile number). The lower and upper bound of each interval are elements number in the flattened tensor.

◆ getTileMapping() [2/2]

TileToTensorMapping poplar::Graph::getTileMapping	(	const Tensor &	t,
		bool	requireComplete = `true`,
		bool	allowExternal = `false`
	)		const

Inspect the tile mapping of a tensor.

Parameters

t	The tensor to inspect.
requireComplete	If `t` is not fully mapped and `requireComplete` is true then an invalid_tile_mapping exception will be thrown.
allowExternal	Allow some of the tensor to be mapped to tiles not belonging to this Graph. These elements will not be included in the result.

Returns: The mapping from tiles to a vector of intervals mapped to the tile (implemented as vector indexed by the tile number). The lower and upper bound of each interval are elements number in the flattened tensor.

◆ getTopLevelGraph()

Graph poplar::Graph::getTopLevelGraph ( )

Return the top level graph.

The createVirtualGraph() method can be used to create graph objects that are views on an underlying graph. If this is a virtual graph then this function returns the top level underlying graph, otherwise it returns the current graph.

◆ getVariable()

Tensor poplar::Graph::getVariable ( VariableRef v ) const

Get a tensor representing an entire variable.

Parameters

v	The variable to retrieve.

Returns: A Tensor object representing that variable.

◆ getVariableTileMapping()

TileToTensorMapping poplar::Graph::getVariableTileMapping ( const Tensor & t ) const

Inspect the tile mapping of a tensor.

This excludes any constant regions.

Parameters

t	The tensor to inspect

Returns: The mapping from tiles to a vector of intervals mapped to the tile (implemented as vector indexed by the tile number). The lower and upper bound of each interval are elements number in the flattened tensor.

◆ hasCodelet()

bool poplar::Graph::hasCodelet ( StringRef codeletName ) const

Check if a graph contains a codelet with this name.

Parameters

codeletName The name of the codelet to check for.

Returns: True if the codelet is in the graph.

◆ isConstant()

bool poplar::Graph::isConstant ( VariableRef v ) const

Check whether a variable reference refers to a constant.

When Graph::addConstant() is called, a variable is created to represent that constant. This call checks whether a variable was created by that method or by Graph::addVariable().

Parameters

v	The variable to examine.

Returns: True if and only if the variable refers to a constant.

◆ outputComputeGraph()

void poplar::Graph::outputComputeGraph	(	std::ostream &	outputStream,
		ArrayRef< program::Program >	progs = `{}`
	)		const

Output the compute graph to a stream in dot file format.

The graph will contain the following:

Green boxes represent variables (tensors), with the number of elements in square brackets.
Blue boxes represent compute sets.
Orange boxes within the blue boxes represent the number of vertices in the compute set.
Yellow boxes that are not linked to anything else in the graph, represent individual variables. The code attempts to simplify the layout by merging them when they have the same name, size and connectivity.
Black edges are the inputs and outputs of a compute set.
Red edges represent data copies.

Parameters

outputStream	The C++ stream to output the dot file onto.
progs	The list of programs to generate a graph of.

◆ outputVertexGraph()

void poplar::Graph::outputVertexGraph	(	std::ostream &	outputStream,
		ArrayRef< program::Program >	progs = `{}`
	)		const

Output the vertex graph to a stream in dot file format.

Parameters

outputStream The C++ stream to output the dot file onto.

◆ registerPerfEstimator()

void poplar::Graph::registerPerfEstimator	(	StringRef	vertexTypeName,
		PerfEstimateFunc	f
	)

Parameters

vertexTypeName	The type of vertex to register the estimator for.
f	Callback function that will compute a performance estimate for all vertices of this type.

◆ reorderToSimplify()

void poplar::Graph::reorderToSimplify	(	Tensor *	t,
		ArrayRef< Tensor * >	ts,
		bool	requireSimplestOrder = `true`
	)		const

Reorder elements of a tensor to simplify the view on the data.

All the tensors provided to this function must be of rank 1 (flattened tensors) and have the same number of elements.

The elements of \t are reordered and \t is updated to be the reordered view of the data. The same reordering is also applied to all tensors in ts.

The reordering is the same for all tensors, so order-invariant or elementwise operations on t and ts can still be performed. The main purpose of this method is to provide a way to implement more efficient graph construction of elementwise or order-invariant operations.

If requireSimplestOrder is set to true the reordering is chosen to minimise the number of contiguous regions in t. Note the reordering may increase the number of contiguous regions of tensors in ts.

If requireSimplestOrder is set to false the reordering is chosen to simplify the internal representation Poplar uses for t. Often this minimizes the number of contiguous regions in t but that is not guaranteed in all cases. This balances reducing the number of contiguous regions against not increasing graph construction time due to a more complex internal representation.

Parameters

t	The tensor to base the reordering on.
ts	A list of other tensors to apply the same reordering to.
requireSimplestOrder	Whether to reorder into the guaranteed minimum of contiguous regions.

Exceptions

index_error If the tensors do not have rank 1 or do not have the same number of elements.

◆ serialize() [1/2]

void poplar::Graph::serialize	(	std::ostream &	out,
		ArrayRef< program::Program >	progs,
		SerializationFormat	format
	)		const

Serialize a graph to JSON or binary (CapnProto) format.

Programs can be passed so that information about Copy programs can be serialized (the Graph class itself does not know about them).

Note that this does not currently serialize every bit of graph data, so it cannot be used to save and reload a graph.

Parameters

out	Stream to write to.
progs	A set of programs that are searched for Copy programs. Information about the variables copied is serialised.
format	Serialize in JSON or CapnProto format. JSON is pretty printed.

◆ serialize() [2/2]

void poplar::Graph::serialize	(	std::ostream &	out,
		SerializationFormat	format
	)		const

Serialize a graph to JSON or binary (CapnProto) format.

This is equivalent to serialize(out, {}, format).

Note that this does not currently serialize every bit of graph data, so it cannot be used to save and reload a graph.

Parameters

out	Stream to write to.
format	Serialize in JSON or CapnProto format. JSON is pretty printed.

◆ serializeTensors()

void poplar::Graph::serializeTensors	(	std::ostream &	out,
		ArrayRef< Tensor >	tensors,
		SerializationFormat	format
	)		const

Serialize a set of tensors to JSON or CapnProto.

The tensors must all be from this graph or an exception is thrown. The information saved is:

The type, shape and expression of the tensors.
The type and number of elements of any variables used.

This is intended to be used for debugging, testing and visualisation.

Parameters

out	Stream to write to.
tensors	A set of tensors to serialize.
format	Serialize in JSON or CapnProto format. JSON is pretty printed.

Exceptions

poplar_error if any tensor is not from this graph. CapnProto may also throw an exception if serialization fails.

◆ setFieldSize()

void poplar::Graph::setFieldSize	(	FieldRef	field,
		std::size_t	size
	)

Set the size of a vector field.

Parameters

field	The reference to the field.
size	The size of the field.

◆ setInitCallback()

template<typename T >

void poplar::Graph::setInitCallback	(	FieldRef	field,
		LateInitCallback< T >	callback,
		typename std::enable_if< std::is_arithmetic< T >::value >::type *	= `nullptr`
	)

inline

Set the init callback for a field; the callback function will be called after graph construction and must return the init value of the field.

This can be called instead of calling setInitialValue(), or both can be called for the field, to ensure that the field has a (at least partially) valid starting value, for instance it if needs to be retrieved in an early stage of graph compilation, before storage allocation (for instance during cycle estimation)

Note that you must explicitly provide the template parameter T in the specialisation when using this function. For example:

 setInitCallback<uint16_t>(vertex["size"], sizeCallback)

This is because the compiler will not be able to detect the correct type from the callback parameter.

Parameters

field	The reference to the field.
callback	The callback that will return the value for the field.
<unnamed>	This exists only to allow the insertion of the `is_arithmetic<T>` check for the type `T`.

◆ setInitialValue() [1/4]

void poplar::Graph::setInitialValue	(	const Tensor &	t,
		const std::map< unsigned, unsigned > &	vals
	)

Set a replica based initial value of a tensor element.

Parameters

t	The tensor representing the value to set. Must be an UNSIGNED_INT scalar.
vals	A map of values to set the field to when the graph engine is created. The map contains the value to use for each replica.

◆ setInitialValue() [2/4]

template<typename T >

void poplar::Graph::setInitialValue	(	const Tensor &	t,
		T	val,
		typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *	= `nullptr`
	)

inline

Set the initial value of a tensor element.

Parameters

t	The tensor representing the value to set.
val	The value to set the field to when the graph engine is created. A buffer of values can be provided to set the elements of a non-scalar tensor.

◆ setInitialValue() [3/4]

template<typename T >

void poplar::Graph::setInitialValue	(	FieldRef	field,
		ArrayRef< T >	val
	)

inline

Set initial values of a vector field.

Parameters

field	The reference to the vector field.
val	A vector value to set the field to when the graph engine is created.

◆ setInitialValue() [4/4]

template<typename T >

void poplar::Graph::setInitialValue	(	FieldRef	field,
		T	val,
		typename std::enable_if< TypeTraits::isSimpleType< T >()>::type *	= `nullptr`
	)

inline

Set the initial value of a field.

Parameters

field	The reference to the field.
val	The value to set the field to when the graph engine is created.

◆ setInitialValueHalf() [1/3]

void poplar::Graph::setInitialValueHalf	(	const Tensor &	t,
		uint16_t	val
	)

inline

Set the initial value of a tensor element of type IEEE half.

Parameters

t	The tensor representing the value to set.
val	The value to set the field to when the graph engine is created. A buffer of values can be provided to set the elements of a non-scalar tensor.

◆ setInitialValueHalf() [2/3]

void poplar::Graph::setInitialValueHalf	(	FieldRef	field,
		ArrayRef< uint16_t >	val
	)

inline

Set initial values of a vector field of type IEEE half.

Parameters

field	The reference to the vector field.
val	A vector value to set the field to when the graph engine is created.

◆ setInitialValueHalf() [3/3]

void poplar::Graph::setInitialValueHalf	(	FieldRef	field,
		uint16_t	val
	)

inline

Set the initial value of a field of type IEEE half.

Parameters

field	The reference to the field.
val	The value to set the field to when the graph engine is created.

◆ setPerfEstimate() [1/2]

void poplar::Graph::setPerfEstimate	(	const VertexRef &	v,
		const VertexPerfEstimate &	estimate
	)

Set the performance estimate for a vertex.

Parameters

v	The vertex to set the estimate for.
estimate	The performance estimates for this vertex when run.

◆ setPerfEstimate() [2/2]

void poplar::Graph::setPerfEstimate	(	const VertexRef &	v,
		std::uint64_t	cycles,
		std::uint64_t	flops = `0`
	)

Set the performance estimate for a vertex.

Parameters

v	The vertex to set the estimate for.
cycles	The number of cycles that this vertex will use when run.
flops	The number of flops that this vertex will use when run.

◆ setTileMapping() [1/3]

void poplar::Graph::setTileMapping	(	const Tensor &	t,
		const TileToTensorMapping &	mapping
	)

Set the tile mapping of a tensor based on an explicit map from tiles to tensor intervals.

Parameters

t	The tensor to map
mapping	The mapping from tiles to a vector of intervals to be placed on that tile (implemented as vector indexed by the tile number). The lower and upper bound of each interval are elements number in the flattened tensor.

◆ setTileMapping() [2/3]

void poplar::Graph::setTileMapping	(	const Tensor &	t,
		unsigned	tileNum
	)

Map a tensor slice to a specific tile on the device.

Parameters

t	The tensor or tensor slice to map.
tileNum	The tile number to map to.

◆ setTileMapping() [3/3]

void poplar::Graph::setTileMapping	(	VertexRef	v,
		unsigned	tileNum
	)

Map a vertex to a specific tile on the device.

Parameters

v	Reference to the vertex to map.
tileNum	The tile number to map the vertex to.

The documentation for this class was generated from the following file:

include/poplar/Graph.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ HostFunctionArgument

Constructor & Destructor Documentation

◆ Graph() [1/2]

◆ Graph() [2/2]

Member Function Documentation

◆ addCodeletPlaceholder()

◆ addCodelets() [1/4]

◆ addCodelets() [2/4]

◆ addCodelets() [3/4]

◆ addCodelets() [4/4]

◆ addComputeSet()

◆ addConstant() [1/5]

◆ addConstant() [2/5]

◆ addConstant() [3/5]

◆ addConstant() [4/5]

◆ addConstant() [5/5]

◆ addConstantHalf() [1/2]

◆ addConstantHalf() [2/2]

◆ addDeviceToHostFIFO()

◆ addExternalExchangeVertex()

◆ addExternalVariable()

◆ addFunction()

◆ addFunctionBuffer()

◆ addHostToDeviceFIFO()

◆ addRemoteBuffer()

◆ addVariable() [1/4]

◆ addVariable() [2/4]

◆ addVariable() [3/4]

◆ addVariable() [4/4]

◆ addVertex() [1/2]

◆ addVertex() [2/2]

◆ clone() [1/4]

◆ clone() [2/4]

◆ clone() [3/4]

◆ clone() [4/4]

◆ cloneN() [1/4]

◆ cloneN() [2/4]

◆ cloneN() [3/4]

◆ cloneN() [4/4]

◆ connect() [1/3]

◆ connect() [2/3]

◆ connect() [3/3]

◆ convertPhysicalTileToVirtualTile() [1/2]

◆ convertPhysicalTileToVirtualTile() [2/2]

◆ convertTileToTopLevelGraphTile()

◆ convertTopLevelGraphTileToTile()

◆ convertVirtualTileToPhysicalTile()

◆ createHostRead()

◆ createHostWrite()

◆ createVirtualGraph() [1/3]

◆ createVirtualGraph() [2/3]

◆ createVirtualGraph() [3/3]

◆ deserializeTensors()

◆ findUnbroadcastTensor()

◆ getFieldSize()

◆ getMaxFieldDim()

◆ getMaxVertexFieldValue()

◆ getNumVertices()

◆ getPerfEstimate()

◆ getSimplifyingRearranger()

◆ getSortedContiguousRegions()

◆ getTileMapping() [1/2]

◆ getTileMapping() [2/2]

◆ getTopLevelGraph()

◆ getVariable()

◆ getVariableTileMapping()

◆ hasCodelet()

◆ isConstant()

◆ outputComputeGraph()

◆ outputVertexGraph()

◆ registerPerfEstimator()

◆ reorderToSimplify()

◆ serialize() [1/2]

◆ serialize() [2/2]

◆ serializeTensors()

◆ setFieldSize()