Poplar classes and functions. More...

Namespaces
namespace	layout
	Namespace for layout classes.

Classes
struct	application_runtime_error
	This exception is thrown when running a program fails due to an error in the program or a misuse of an API. More...

class	ComputeSet
	A reference to a compute set within a graph. More...

struct	control_program_error
	This exception is thrown when the construction of a graph program is invalid. More...

class	DataStream
	An object representing a stream for communicating between the host and the device. More...

class	DebugContext
	DebugContext gathers the common external parameters of the context of an operation. More...

class	DebugInfo
	DebugInfo stores and persists a set of data that describes the context of an operation. More...

class	DebugNameAndId
	DebugNameAndId bundles a name and a DebugId to facilitate their propagation through function calls. More...

class	Device
	A device refers to a physical entity that can execute code. More...

class	DeviceManager
	A DeviceManager is able to enumerate and return groups of physical IPUs connected to an entity/host. More...

class	Engine
	A graph compute engine. More...

class	EngineOptions
	A group of properties for a poplar::Executable object. More...

struct	equivalent_device_type
	Template structure to relate a host type to a device type. More...

struct	ErrorLocation
	Uniquely identify the location of an error within a Poplar Device. More...

struct	ErrorLocationHash
	Hash function for ErrorLocation. More...

class	Executable
	An instance of poplar::Executable contains all of the information needed to run a program on an IPU device. More...

class	ExternalExchangeVertex
	ExternalExchangeVertex base class; Any sub-type of this class needs to define a compute() method returning a bool. More...

class	FieldData
	Information about a vertex field, including its size and its initial value, if set. More...

class	FieldRef
	A reference to a field within a vertex instance. More...

struct	FloatingPointBehaviour
	Structure to specify floating point behaviour. More...

class	Function
	A reference to a function stored within a graph. More...

class	FunctionBuffer
	A reference to a function buffer stored within a graph. More...

struct	GenericInterval
	This class represents an interval that is closed at its lower bound and open at its upper bound. More...

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

struct	graph_connection_error
	This exception is thrown during construction of an Engine object if there is an error in the structure of graph, for example, if there are no edges to a vertex input or if there are multiple edges to a vertex input. More...

struct	graph_cycle_error
	This exception is thrown during the construction of an Engine object if there are any cycles in the graph that are not broken by recurrent edges. More...

struct	graph_memory_allocation_error
	This exception is thrown when an memory allocation fails. More...

struct	graph_object_creation_error
	This exception is thrown in the construction of a GraphProgEnv object if there was an error in the creation of the graph program object file. More...

struct	graph_object_load_error
	This exception is thrown in the construction of a GraphProgEnv object if there was an error in loading the graph program object file. More...

struct	graph_program_compilation_error
	This exception is thrown in the construction of a GraphProgEnv object if there are any compilation errors in the graph program. More...

struct	graph_recursion_error
	This exception is thrown during the construction of an Engine object if there are recursive calls. More...

struct	graph_replication_error
	This exception is thrown when an invalid operation is carried out on a replicated graph. More...

class	HostCallback
	Interface used during host function calls to produce/consume the data being exchanged between the host and the device. More...

class	HostCallbackHandle
	Wrapper for HostCallback instances. More...

class	HostFunction
	A reference to a function in the host. More...

class	IeeeHalf
	A IeeeHalf. More...

struct	index_error
	This exception is thrown if the index of a subscript is out of the bounds of the field it is accessing or if a index of a tensor is invalid. More...

class	InOut
	Input. More...

class	InOut< quarter >
	InOut with metadata. More...

class	InOut< Vector< T, L, MinAlign, Interleaved > >
	InOut<Vector>. More...

class	InOut< VectorList< T, L, MinAlign, Interleaved > >
	InOut<VectorList>. More...

class	Input
	Input. More...

class	Input< quarter >
	Input with metadata. More...

class	Input< Vector< T, L, MinAlign, Interleaved > >
	Input<Vector>. More...

class	Input< VectorList< T, L, MinAlign, Interleaved > >
	Input<VectorList>. More...

struct	invalid_machine_model
	This exception is thrown when an invalid model of the IPU (for performance model profiling) has been specified. More...

struct	invalid_option
	This exception is thrown when an unrecognised or invalid option is passed to a Poplar API. More...

struct	invalid_tile_mapping
	This exception is thrown when the tile mapping passed to the UserTilePartitioner is invalid. More...

struct	IPUModel
	A model of an IPU to create an IPUModel Device The IPU Model will simulate the behaviour of the IPU hardware. More...

class	LegacyStreamCallback
	Convenience StreamCallback specialization for implementations that do not support prefetch/complete operations when the data type used does not require metadata. More...

struct	link_error
	This exception is thrown when the linking stage for codelets fails. More...

struct	memory_elem_constraints_error
	This exception is thrown when an invalid memory element constraint has been provided in a codelet. More...

struct	missing_graph_profile
	This exception is thrown if the graph and/or execution profile is required but the graph profile that should had been generated during compilation is not found. More...

struct	missing_perf_estimate
	This exception is thrown when an Engine is constructed with profiling enabled but a vertex does not have a getPerfEstimate method specified. More...

class	Module
	An instance of poplar::Moudle contains all of the information needed to run a program on an IPU device. More...

class	MultiVertex
	MultiVertex base class; Any sub-type of this class needs to define a compute() method taking a single unsigned value and returning a bool. More...

struct	no_environment
	This exception is thrown, in the construction of a GraphProgEnv object, in mixed-mode compilation, if there is no graph-programming environment available, in particular if the program has not been compiled with the 'popc' command-line tool. More...

struct	no_size_specified
	This exception is thrown if the size of a field is not specified in a Graph object when an EngineBuilder object is constructed. More...

class	OptionFlags
	A set of option/value string flags to be used in various APIs. More...

class	Output
	Output. More...

class	Output< quarter >
	Output with metadata. More...

class	Output< Vector< T, L, MinAlign, Interleaved > >
	Output<Vector>. More...

class	Output< VectorList< T, L, MinAlign, Interleaved > >
	Output<VectorList>. More...

struct	overflow_error
	This exception is thrown when an arithmetic overflow occurs within Poplar. More...

struct	parse_error
	This exception is thrown when an input file or string cannot be parsed. More...

struct	poplar_error
	Base class for Poplar exceptions. More...

class	Preallocations
	This class describes where external variables and other pre-existing allocations are in memory. More...

class	ProfileValue
	ProfileValue represents a read-only JSON-like tree of values that are used to store the output of the profiler. More...

struct	profiling_disabled
	This exception is thrown if profiling information is requested from an Engine but that Engine has not been constructed with profiling enabled. More...

class	QuarterMetadata
	Quarter metadata type. More...

struct	recoverable_runtime_error
	This exception is thrown when when running a program fails due to a system error that is likely to be transient. More...

class	RemoteBuffer
	A remote buffer is a region of remote (meaning not on the IPU) memory that is used as a cache. More...

class	ResumableStreamCallback
	Expands StreamCallback API with functions that prevent further progress. More...

struct	runtime_error
	This exception is thrown when running a program on a system fails. More...

class	RuntimeOptions
	A group of properties that are reconfigurable in each engine execution. More...

class	SourceLocation
	This class mimics `std::source_location` that is unavailable as we don't yet support C++20. More...

struct	stream_connection_error
	This exception is thrown when an invalid attempt is made to connect a data stream. More...

struct	stream_memory_allocation_error
	This exception is thrown when allocation of stream buffers fails. More...

class	StreamCallback
	Interface used during stream copies to produce/consume the data being exchanged between the host and the device. More...

class	StreamCallbackHandle
	Wrapper for StreamCallback instances. More...

class	StreamCallbackWithMetadata
	Interface used to add support for stream copies to produce/consume data if the data type requires metadata. More...

class	SupervisorVertex
	SupervisorVertex base class; Any sub-type of this class needs to define a compute() method returning a bool. More...

struct	system_runtime_error
	This exception is thrown when running a program fails due to an error in the system it is running on. More...

class	Target
	A target representation. More...

class	Tensor
	A reference to a subset of tensor elements. More...

struct	tensor_creation_error
	This exception is thrown in the construction of a tensor if invalid arguments are provided to the tensor creation function or method. More...

struct	tensor_io_state_error
	This exception is thrown when an attempt is made to mark a tensor as an input or output, but the argument references a view of a tensor, rather than a whole tensor. More...

struct	tensor_metadata_error
	This exception is thrown if a tensor uses a type that requires metadata and the metadata is not accessible. More...

class	TensorRearranger
	TensorRearranger can be used to re-order the view on a tensor and to undo that re-ordering. More...

class	Type
	Class representing device data types. More...

struct	type_error
	This exception is thrown when there is an error related to the field types of vertices, for example, when the source of an edge contains an input, the types of inputs and source field between an edge do not match, or when a field cannot be subscripted. More...

struct	TypeTraits
	A structure to provide information about arithmetic (integer and floating point) types. More...

struct	unknown_field
	This exception is thrown when a field name is specified that does not exist in the graph-programming environment. More...

struct	unknown_runtime_error
	This exception is throw when execution fails due to a system error where the cause cannot be automatically determined, for example a timeout without a specific error being raised. More...

struct	unknown_vertex_type
	This exception is thrown when a vertex type name is specified that does not exist in the graph programming environment. More...

struct	unrecoverable_runtime_error
	This exception is thrown when execution fails due to a system error that is likely to persist. More...

struct	VariableInterval
	Type representing a segment of a particular variable. More...

class	VariableRef
	Type representing a reference to a variable in a graph. More...

class	Vector< InOut< T >, L, MinAlign, Interleaved >
	Vector<InOut>. More...

class	Vector< InOut< Vector< T, L1, MinAlign1, Interleaved > >, L2, MinAlign2, false >
	Vector<InOut<Vector<T>>. More...

class	Vector< Input< T >, L, MinAlign, Interleaved >
	Vector<Input>. More...

struct	Vector< Input< Vector< T, L1, MinAlign1, Interleaved > >, L2, MinAlign2, false >
	Vector<Input<Vector<T>>. More...

class	Vector< Output< T >, L, MinAlign, Interleaved >
	Vector<Output>. More...

class	Vector< Output< Vector< T, L1, MinAlign1, Interleaved > >, L2, MinAlign2, false >
	Vector<Output<Vector<T>>. More...

class	Vertex
	Vertex base class. More...

struct	VertexEdgeInfo
	Data structure that will be passed to the callback used for 'late initialisation' for vertex fields. More...

class	VertexIntrospector
	Available to cycle estimators to inspect the shape and initial values of a vertex's fields. More...

class	VertexRef
	A reference to a vertex within a graph. More...

Typedefs
using	DebugId = std::uint64_t
	A unique identifier for the debug context.

typedef unsigned	vertex_id
	Vertex id. More...

template<typename T >
using	LateInitCallback = std::function< T(const VertexEdgeInfo &)>
	A callback function of this type can be specified for a field of a vertex, instead of specifying an initialisation value with setInitialValue. More...

using	PerfEstimateFunc = std::function< VertexPerfEstimate(const VertexIntrospector &v, const Target &target)>
	Functions of this type can be used as performance estimator callbacks for new vertex types. More...

template<bool pred>
using	SupervisorVertexIf = std::conditional_t< pred, SupervisorVertex, Vertex >
	Metafunction that returns a SupervisorVertex if `pred` is true otherwise a Vertex.

Enumerations
enum class	CodeletFileType { PreprocessedAsmSource , AsmSource , CSource , CppSource , IrSource , Object , Auto }

enum class	DataStreamType { HostToDeviceFIFO , DeviceToHostFIFO , HostToDeviceBuffer , DeviceToHostBuffer }
	An enumeration to represent the different types of DataStream or stream components of a RemoteBuffer. More...

enum class	DebugSerializationFormat { JSON , CBOR }

enum class	ErrorCode : unsigned { NONE = 0 , UNKNOWN , TRAP , FLOATING_POINT_INVALID_OPERATION , FLOATING_POINT_DIVIDE_BY_ZERO , FLOATING_POINT_OVERFLOW , TILE_MEMORY_BANK_CONFLICT , INVALID_EXCHANGE_CONFIGURATION , INVALID_ADDRESS , INVALID_OPERAND , INVALID_PROGRAM_COUNTER , INVALID_INSTRUCTION , EXCHANGE_ERROR , MEMORY_ERROR , IPUSOFTERR , LINK_DOWN , HOST_LINK_DOWN , HOST_SYNC_TIMEOUT , IPU_MEMORY_FAILURE }
	Unique error codes for all the possible errors. More...

enum class	RecoveryAction { IPU_RESET , PARTITION_RESET , FULL_RESET }
	An enumeration that specifies how to recover from a recoverable_runtime_error. More...

enum class	FunctionBufferMappingType { REMOTE }
	Type for mapping of FunctionBuffer objects. More...

enum class	IpuLinkConfiguration
	Enum to represent the IPU interconnect layout.

enum class	IpuLinkTopology
	Enum to represent the IPU interconnect layout.

enum class	ReplicatedStreamMode { REPLICATE , BROADCAST }
	Define how a stream is replicated when added to a replicated graph. More...

enum class	SerializationFormat { Binary , JSON }
	Format for serializing a Tensor or Graph object. More...

enum class	SyncType { INTERNAL , EXTERNAL , GLOBAL }
	An enumeration used to state what type of synchronisation a Sync program represents. More...

enum class	TargetType { IPU , IPU_MODEL , CPU }
	Enum to represent the type of a device capable of running a graph. More...

enum class	UpsampleMethod { REPEAT }
	Enum passed to Tensor::upsample(unsigned scale, unsigned dimension) specifying the upsampling method. More...

enum class	TensorCloneMethod { PRESERVE_ORDER_AND_ALIASES , CREATE_NEW_ORDER , PRESERVE_ORDER_UNLESS_ALIASES , GATHER_AND_PRESERVE_TILE_ORDER_AND_ALIASES }
	Define behaviour when a Tensor is cloned. More...

enum class	TensorCloneDuplicationMethod { }
	Define behaviour when a Tensor is cloned and duplicated using Graph::cloneN. More...

enum class	VariableMappingMethod { NONE , LINEAR }
	When variables are added to the graph, a tile mapping can be created. More...

enum class	VectorLayout : unsigned { }
	The memory layout used for a Vector. More...

enum class	VectorListLayout : unsigned { }
	The memory layout used for a VectorList. More...

Functions
void	setFloatingPointBehaviour (poplar::Graph &graph, poplar::program::Sequence &prog, const FloatingPointBehaviour &behaviour, const DebugContext &debugContext={})
	Set the floating point behaviour of a tile. More...

void	setFloatingPointBehaviour (poplar::Graph &graph, poplar::program::Sequence &prog, const poplar::Tensor &behaviour, const DebugContext &debugContext={})
	Set the floating point behaviour of a tile. More...

void	setStochasticRounding (poplar::Graph &graph, poplar::program::Sequence &prog, bool behaviour, const DebugContext &debugContext={})
	Set stochastic rounding on or off for the selected tile. More...

poplar::Tensor	getAndModifyFloatingPointBehaviour (poplar::Graph &graph, poplar::program::Sequence &prog, const FloatingPointBehaviour &clear, const FloatingPointBehaviour &set, const DebugContext &debugContext={})
	Get the current state and modify the floating-point behaviour on every tile that belongs to the target in the graph. More...

poplar::Tensor	cycleCount (poplar::Graph &graph, poplar::program::Sequence &prog, unsigned tile, SyncType syncType, const DebugContext &debugContext={})
	Time the program for a given a sequence program type. More...

poplar::Tensor	cycleStamp (poplar::Graph &graph, poplar::program::Sequence &prog, unsigned tile, SyncType syncType, const DebugContext &debugContext={})
	Add a sequence program to record an absolute hardware cycle stamp on a given tile. More...

std::vector< poplar::Tensor >	cycleStamp (poplar::Graph &graph, poplar::program::Sequence &prog, const std::vector< unsigned > &tiles, SyncType syncType, const DebugContext &debugContext={})
	Add a compute set to record an absolute hardware cycle stamp on the specified tiles. More...

std::ostream &	operator<< (std::ostream &os, const DebugNameAndId &dnai)
	Display the path name of the DebugNameAndId. More...

std::ostream &	operator<< (std::ostream &os, const DebugContext &dc)
	Display the path name of the DebugContext. More...

Executable	compileGraph (Graph &&graph, ArrayRef< program::Program > progs, const OptionFlags &opt={}, ProgressFunc progressCallBack=ProgressFunc(), const DebugContext &debugContext={})
	Compile the given graph and programs to make an executable that can be executed using a poplar::Engine. More...

Module	compileModule (Graph &&graph, program::Program prog, const OptionFlags &opt={}, ProgressFunc progressCallBack=ProgressFunc(), const DebugContext &debugContext={})
	Compile the given graph and single program to make a module. More...

Module	compileModule (Graph &&graph, program::Program prog, const Preallocations &preallocations, const OptionFlags &opt={}, ProgressFunc progressCallBack=ProgressFunc(), const DebugContext &debugContext={})
	Compile the given graph and single program to make a module. More...

Executable	compileGraph (Graph &&graph, ArrayRef< program::Program > progs, const Preallocations &preallocations, const OptionFlags &opt={}, ProgressFunc progressCallBack=ProgressFunc(), const DebugContext &debugContext={})
	Compile the given graph and programs to make an executable that can be executed using a poplar::Engine. More...

std::size_t	hash_value (const EngineOptions &options)
	Obtain a hash value for an EngineOptions object. More...

StringRef	errorCodeToString (ErrorCode error)
	Convert a poplar::ErrorCode code to a string. More...

ErrorCode	errorCodeFromString (StringRef error)
	Convert a string to a poplar::ErrorCode code. More...

std::string	toString (RecoveryAction recoveryAction)
	Convert the recovery action to a string.

void	readJSON (StringRef string, OptionFlags &flags)
	Read options from a string in JSON format. More...

void	readJSON (std::istream &stream, OptionFlags &flags)
	Read options from a stream in JSON format. More...

void	readJSONFromEnv (StringRef envVarName, OptionFlags &flags)
	Read options from a environment variable in JSON format. More...

std::ostream &	operator<< (std::ostream &ostream, const OptionFlags &flags)
	Write the contents of the given flags to an ostream in JSON format. More...

std::ostream &	operator<< (std::ostream &os, const ProfileValue &v)
	Dumps the JSON representation to an output stream.

void	printGraphSummary (std::ostream &out, const std::string &databasePath, const OptionFlags &opts)
	Print a summary of the static graph profiling information - primarily memory use. More...

void	printExecutionSummary (std::ostream &out, const std::string &databasePath, const OptionFlags &opts)
	Print a summary of the execution profiling information - primarily cycle counts. More...

void	printProfileSummary (std::ostream &out, const std::string &databasePath, const OptionFlags &opts={})
	Equivalent to calling printGraphSummary() followed by printExecutionSummary(). More...

Tensor	getHwSeeds (Graph &graph, program::Sequence &prog, const DebugContext &debugContext={})
	Gets a snapshot of the h/w seeds for each worker in device. More...

void	setHwSeeds (Graph &graph, const Tensor &hwSeeds, program::Sequence &prog, const DebugContext &debugContext={})
	Sets the hw seeds for each worker in a device from a snapshot of the seeds. More...

void	copyDeviceHalfToFloat (const Target &target, const void src, float dst, std::size_t numElements)
	Convert device half-precision values to floats. More...

void	copyFloatToDeviceHalf (const Target &target, const float src, void dst, std::size_t numElements)
	Convert float values to device half-precision values. More...

void	copyDeviceHalfToDouble (const Target &target, const void src, double dst, std::size_t numElements)
	Convert device half-precision values to doubles. More...

void	copyDoubleToDeviceHalf (const Target &target, const double src, void dst, std::size_t numElements)
	Convert double precision values to device half-precision values. More...

std::string	toString (TargetType t)
	Convert the target type to a string. More...

Tensor	concat (ArrayRef< Tensor > ts, unsigned dimension=0)
	Concatenate several tensors. More...

Tensor	concat (const Tensor &first, const Tensor &second, unsigned dimension=0)
	Concatenate two tensors. More...

Tensor	append (const Tensor &first, const Tensor &second, unsigned dimension)
	Append a tensor as an element to another tensor. More...

Tensor	append (const Tensor &first, const Tensor &second)
	Append a tensor to another in their first dimension. More...

std::ostream &	operator<< (std::ostream &os, const Tensor &tensor)
	Display the regions of the tensor on a stream. More...

void	convertFromDeviceType (Type type, const void *src, gccs::ArrayRef< float > dst)
	Convert from device data of type that does not require metadata to host buffer of type float. More...

void	convertFromDeviceType (Type type, const poplar::QuarterMetadata &metadata, const void *src, gccs::ArrayRef< float > dst)
	Convert from device data of type Type::QUARTER to host buffer of type float. More...

void	convertFromDeviceType (Type type, const void *src, gccs::ArrayRef< double > dst)
	Convert from device data of type that does not require metadata to host buffer of type double. More...

void	convertFromDeviceType (Type type, const poplar::QuarterMetadata &metadata, const void *src, gccs::ArrayRef< double > dst)
	Convert from device data of type Type::QUARTER to host buffer of type double. More...

void	convertToDeviceType (Type type, gccs::ArrayRef< const float > src, void *dst)
	Convert from host buffer of type float to device data of type that does not require metadata. More...

void	convertToDeviceType (Type type, const poplar::QuarterMetadata &metadata, gccs::ArrayRef< const float > src, void *dst)
	Convert from host buffer of type float to device data of type Type::QUARTER. More...

void	convertToDeviceType (Type type, gccs::ArrayRef< const double > src, void *dst)
	Convert from host buffer of type double to device data of type that does not require metadata. More...

void	convertToDeviceType (Type type, const poplar::QuarterMetadata &metadata, gccs::ArrayRef< const double > src, void *dst)
	Convert from host buffer of type double to device data of type Type::QUARTER. More...

Variables
Type	BOOL
	Device type: bool

Type	CHAR
	Device type: char

Type	UNSIGNED_CHAR
	Device type: unsigned char

Type	SIGNED_CHAR
	Device type: signed char

Type	UNSIGNED_SHORT
	Device type: unsigned short

Type	SHORT
	Device type: short

Type	UNSIGNED_INT
	Device type: unsigned int

Type	INT
	Device type: int

Type	UNSIGNED_LONG
	Device type: unsigned long

Type	LONG
	Device type: long

Type	UNSIGNED_LONGLONG
	Device type: unsigned long long

Type	LONGLONG
	Device type: long long

Type	HALF
	Device type: half

Type	FLOAT
	Device type: float

Detailed Description

Poplar classes and functions.

Typedef Documentation

◆ LateInitCallback

template<typename T >

using poplar::LateInitCallback = typedef std::function<T(const VertexEdgeInfo &)>

A callback function of this type can be specified for a field of a vertex, instead of specifying an initialisation value with setInitialValue.

Will be called after the graph has been built. Will be passed information about the vertex fields. Needs to return the value for the field.

◆ PerfEstimateFunc

using poplar::PerfEstimateFunc = typedef std::function<VertexPerfEstimate( const VertexIntrospector &v, const Target &target)>

Functions of this type can be used as performance estimator callbacks for new vertex types.

See also: Graph::registerPerfEstimator

◆ vertex_id

typedef unsigned poplar::vertex_id

Vertex id.

The integral type of unique identifiers to vertices with a graph.

Enumeration Type Documentation

◆ CodeletFileType

enum class poplar::CodeletFileType

strong

Enumerator
PreprocessedAsmSource	A graph assembly language source file.
AsmSource	A graph assembly language file with preprocessor macros.
CSource	A graph C source file.
CppSource	A graph C++ source file.
IrSource	A graph LLVM IR source file.
Object	A graph program object file.
Auto	Auto detect based on file name.

◆ DataStreamType

enum class poplar::DataStreamType

strong

An enumeration to represent the different types of DataStream or stream components of a RemoteBuffer.

See also: Graph::addHostToDeviceFIFO, Graph::addDeviceToHostFIFO, Graph::addRemoteBuffer

Enumerator
HostToDeviceFIFO	A DataStream from host to device.
DeviceToHostFIFO	A DataStream from device to host.
HostToDeviceBuffer	A stream from host to device in a remote buffer.
DeviceToHostBuffer	A stream from device to host in a remote buffer.

◆ DebugSerializationFormat

enum class poplar::DebugSerializationFormat

strong

Enumerator
JSON	Serialise in JSON format.
CBOR	Serialise in CBOR format.

◆ ErrorCode

enum class poplar::ErrorCode : unsigned

strong

Unique error codes for all the possible errors.

These errors can also be simulated using Engine::simulateError().

Floating point exceptions will always be generated for simulated errors. For real errors, floating point exceptions must be enabled for these exceptions to be generated.

Enumerator
NONE	Not an error.
UNKNOWN	The error does not have an error code yet.
TRAP	The tile raises a debug exception event.
FLOATING_POINT_INVALID_OPERATION	The tile failed to execute a floating point operation because it is invalid, for example multiplying a number by a NaN.
FLOATING_POINT_DIVIDE_BY_ZERO	The tile tried to divide a floating point number by zero.
FLOATING_POINT_OVERFLOW	The tile performed some floating point operation that caused a floating point number to overflow.
TILE_MEMORY_BANK_CONFLICT	Two or more threads on the tile tried to access the same memory bank at the same time.
INVALID_EXCHANGE_CONFIGURATION	The tile tried to configure how it communicates with other tiles incorrectly.
INVALID_ADDRESS	The tile tried to access memory that it does not have access to.
INVALID_OPERAND	The tile tried to execute an instruction with an invalid operand.
INVALID_PROGRAM_COUNTER	The tile's program counter does not point to a valid region of memory.
INVALID_INSTRUCTION	The tile tried to execute an invalid instruction.
EXCHANGE_ERROR	The tile failed to successfully communicate with other tiles.
MEMORY_ERROR	The tile has detected one or more memory parity errors indicating that data may be corrupted.
IPUSOFTERR	Same as memory error but reported via the SOC rather than tile exception.
LINK_DOWN	A connection between IPUs failed.
HOST_LINK_DOWN	The connection between the host and the IPUs failed.
HOST_SYNC_TIMEOUT	The host didn't receive any communication from the IPUs for a timeout period. This error can be caused by a large number of things, such as: IPU deadlock, host miscommunication and some types of hardware error.
IPU_MEMORY_FAILURE	GCDA has determined that an excessive number of parity errors have occurred on a particular tile of an IPU, and marked this device as malfunctioning. When this occurs Poplar will get a MEMORY_ERROR or IPUSOFTERR and the GCDA health check will report a failure.

◆ FunctionBufferMappingType

enum class poplar::FunctionBufferMappingType

strong

Type for mapping of FunctionBuffer objects.

See also: Graph::addFunctionBuffer

Enumerator
REMOTE	FunctionBuffer is stored in remote memory.

◆ RecoveryAction

enum class poplar::RecoveryAction

strong

An enumeration that specifies how to recover from a recoverable_runtime_error.

Enumerator
IPU_RESET	Reset the IPU and reload IPU memory.
PARTITION_RESET	Reset the IPU partition. This retrains the IPU-links between IPUs.
FULL_RESET	Power cycle the system.

◆ ReplicatedStreamMode

enum class poplar::ReplicatedStreamMode

strong

Define how a stream is replicated when added to a replicated graph.

See also: Graph::addHostToDeviceFIFO

Enumerator
REPLICATE	Create a stream per replica.
BROADCAST	Create a single stream whose data is implicitly broadcast to every replica.

◆ SerializationFormat

enum class poplar::SerializationFormat

strong

Format for serializing a Tensor or Graph object.

See also: Graph::serializeTensors Graph::deserializeTensors Graph::serialize

Enumerator
Binary	Serialise in binary (CapnProto) format.
JSON	Serialise in JSON format.

◆ SyncType

enum class poplar::SyncType

strong

An enumeration used to state what type of synchronisation a Sync program represents.

Enumerator
INTERNAL	Each tile waits until all the other tiles in the same IPU reach the Sync program before continuing.
EXTERNAL	Each tile waits until all the other tiles in all IPUs in the device reach the Sync program before continuing.
GLOBAL	Each tile waits until all the other tiles in all IPUs globally reach the Sync program before continuing.

◆ TargetType

enum class poplar::TargetType

strong

Enum to represent the type of a device capable of running a graph.

Enumerator

IPU

Run on real IPU hardware.

IPU_MODEL

Model of the IPU which actually runs on the CPU but behaves like an IPU.

CPU

Run code on the CPU.

This does not accurately replicate all the functionality of an IPU and should only be used for running simple tests.

◆ TensorCloneDuplicationMethod

enum class poplar::TensorCloneDuplicationMethod

strong

Define behaviour when a Tensor is cloned and duplicated using Graph::cloneN.

Throws an error if DUPLICATE_BY_TILE_CONTIGUOUS_REGION and a new order needs to be created (either via TensorCloneMethod::CREATE_NEW_ORDER or TensorCloneMethod::PRESERVE_ORDER_UNLESS_ALIASES)

See also: Graph::cloneN; TensorCloneMethod

Enumerator

DUPLICATE_BY_TILE_CONTIGUOUS_REGION

< The multiple clones are concatenated in their outermost dimension.

This means that the result is the same as concat(clone1, clone2, ..., cloneN). There is no guarantee of any ordering constraints in memory between the clones.

◆ TensorCloneMethod

enum class poplar::TensorCloneMethod

strong

Define behaviour when a Tensor is cloned.

See also: Graph::clone

Enumerator
PRESERVE_ORDER_AND_ALIASES	Preserve the ordering and aliasing within the original tensor reference.
CREATE_NEW_ORDER	Create a new tensor with natural ordering based on the dimensions of the cloned tensor (in the same way as poplar::Graph::addVariable()).
PRESERVE_ORDER_UNLESS_ALIASES	Preserve the ordering of the original tensor unless it contains aliases. In the case of aliases, create a new tensor ordering and duplicate the aliased elements.
GATHER_AND_PRESERVE_TILE_ORDER_AND_ALIASES	Gather elements of the underlying variables that are mapped to the same tile so they form one contiguous region on the tile in the cloned tensor. Contiguous regions on the tile and the aliasing of elements are preserved.

◆ UpsampleMethod

enum class poplar::UpsampleMethod

strong

Enum passed to Tensor::upsample(unsigned scale, unsigned dimension) specifying the upsampling method.

Enumerator

REPEAT

If dimension is of size s, for every i in [0, s), repeats the subtensor at index i scale times.

For example, with scale = 2 and dimension = 1: Shape(2,3) Shape(2x6) [[1, 2, 3], becomes [[1, 1, 2, 2, 3, 3], [4, 5, 6]] [4, 4, 5, 5, 6, 6]]

Note that a scale of 0 means repeat each tensor 0 times. So a (i, j, k, l) tensor upsampled with scale = 0 and dimension = 3 would become an (i, j, k, 0) tensor containing 0 elements.

scale = 1 is the identity operation.

◆ VariableMappingMethod

enum class poplar::VariableMappingMethod

strong

When variables are added to the graph, a tile mapping can be created.

This class enumerates the method for creating that mapping.

Enumerator

NONE

No mapping is created.

The tile mapping will be set later via Graph::setTileMapping.

LINEAR

The variable will be spread evenly across the tiles with the element ordering matching the tile number ordering.

The tile mapping can also be overridden later via Graph::setTileMapping.

◆ VectorLayout

enum class poplar::VectorLayout : unsigned

strong

The memory layout used for a Vector.

Enumerator
SPAN	A pointer to the start of the vector, and a count of the number of elements (not bytes) the vector contains. This means the `.size()` member and iterators are available.
SHORT_SPAN	A pointer to the start of the vector and a count of the number of elements the vector contains. The count is limited to 11 bits. The `.size()` member and iterators are available. Only addresses up to 1 MB can be represented.
ONE_PTR	Similar to `SPAN` but the count is not stored, so this is a single pointer to the start of the vector. The vector does not know its size which must be learned by some other means. The `.size()` member and iterators are not available.
SCALED_PTR32	Similar to `ONE_PTR`, but this uses a compressed 16-bit pointer containing bits 2-17 of the offset from the pointer to the base of memory. Since the lower 2 bits are not stored it can only point to 32-bit aligned addresses (this is where the 32 in the name comes from).
SCALED_PTR64	Similar to `ONE_PTR`, but this uses a compressed 16-bit pointer containing bits 3-18 of a full pointer. Since the lower 3 bits are not stored it can only point to 64-bit aligned addresses (this is where the 64 in the name comes from). Addresses up to 512 KB can be represented.
SCALED_PTR128	Similar to `ONE_PTR`, but this uses a compressed 16-bit pointer containing bits 4-18 of a full pointer. Since the lower 4 bits are not stored it can only point to 128-bit aligned addresses (this is where the 128 in the name comes from). Addresses up to 1 MB can be represented.
COMPACT_PTR	This pointer type will resolve into the best suited, ideally space optimised, pointer given the size of the address space and the alignment. For example on mk1: if the alignment is in the range [4,8) then this will become a `SCALED_PTR32`; if it is 8 or greater then it becomes a `SCALED_PTR64`. For all other alignments this pointer type is an uncompressed `ONE_PTR`.

◆ VectorListLayout

enum class poplar::VectorListLayout : unsigned

strong

The memory layout used for a VectorList.

The ONE_PTR and SCALED_PTR* types are for Poplar runtime internal use only.

Enumerator
ONE_PTR	Poplar runtime use only.
SCALED_PTR32	Poplar runtime use only.
SCALED_PTR64	Poplar runtime use only.
SCALED_PTR128	Poplar runtime use only.
DELTAN	A top-level structure with a 20-bit pointer to the base of the vector data, a 12 bit count for the number of sub-vectors and a `SCALED_PTR32` pointer to an array of structures for each sub-vector. These each have an 18-bit offset from the base address to the sub-vector data, and a 14-bit count for the size of the sub-vector. The maximum number of sub-vectors is 4,095. The maximum number of elements in a sub-vector is 16,383 elements. The `.size()` method and iterators are available.
DELTANELEMENTS	A top-level structure with a 21-bit pointer to the base of the vector data, a 16 bit count for the number of sub-vectors and a 21-bit pointer to an array of structures for each sub-vector. These each have an offset from the base address to the sub-vector data, and a count for the size of the sub-vector. The offset and count are packed into a 32-bit word. For byte-aligned data, the offset is 21 bits and the count is 11 bits. For larger alignments, fewer bits are required for the offset and more bits are available for the count. The maximum number of sub-vectors is 65,535. The maximum size of the sub-vectors depends on the data type. The `.size()` method and iterators are available.
COMPACT_DELTAN	This type will resolve into the best suited, ideally space optimised, inner pointer type depending on the address space. For example, on Mk1 IPUs it will be a DELTAN type, as that can point to everything in the available memory.

Function Documentation

◆ append() [1/2]

Tensor poplar::append	(	const Tensor &	first,
		const Tensor &	second
	)

inline

Append a tensor to another in their first dimension.

Parameters

first	The tensor to append to
second	The tensor to add as an element in the first dimension

Returns: The extended tensor

◆ append() [2/2]

Tensor poplar::append	(	const Tensor &	first,
		const Tensor &	second,
		unsigned	dimension
	)

Append a tensor as an element to another tensor.

Parameters

first	The tensor to append to
second	The tensor to add as an element in the specified dimension
dimension	The number of the dimension to append to

Returns: The extended tensor

◆ compileGraph() [1/2]

Executable poplar::compileGraph	(	Graph &&	graph,
		ArrayRef< program::Program >	progs,
		const OptionFlags &	opt = `{}`,
		ProgressFunc	progressCallBack = `ProgressFunc()`,
		const DebugContext &	debugContext = `{}`
	)

Compile the given graph and programs to make an executable that can be executed using a poplar::Engine.

Unless graph is an rvalue a copy of some graph state will be made.

Parameters

graph	The graph to compile.
progs	The list of programs to run over the graph. Each program can be run separately by calling Engine::run() and passing the index, in this list, of the program to run.
opt	Options that can be used to control compilation and execution. The available options are listed under Engine.
progressCallBack	A function that will be called to indicate engine compilation progress. See Engine::ProgressFunc for more information.
debugContext	Optional DebugId and debug name.

Exceptions

invalid_option	If any of the options passed in `opt` were not recognised or improperly formatted.
link_error	If program linking fails; for example, due to undefined symbols or lack of memory on a tile.

◆ compileGraph() [2/2]

Executable poplar::compileGraph	(	Graph &&	graph,
		ArrayRef< program::Program >	progs,
		const Preallocations &	preallocations,
		const OptionFlags &	opt = `{}`,
		ProgressFunc	progressCallBack = `ProgressFunc()`,
		const DebugContext &	debugContext = `{}`
	)

Compile the given graph and programs to make an executable that can be executed using a poplar::Engine.

Unless graph is an rvalue a copy of some graph state will be made.

Parameters

graph	The graph to compile.
progs	The list of programs to run over the graph. Each program can be run separately by calling Engine::run() and passing the index, in this list, of the program to run.
preallocations	A datastructure describing where variables external to the graph are placed.
opt	Options that can be used to control compilation and execution. The available options are listed under Engine.
progressCallBack	A function that will be called to indicate engine compilation progress. See Engine::ProgressFunc for more information.
debugContext	Optional DebugId and debug name.

Exceptions

invalid_option	If any of the options passed in `opt` were not recognised or improperly formatted.
link_error	If program linking fails; for example, due to undefined symbols or lack of memory on a tile.

◆ compileModule() [1/2]

Module poplar::compileModule	(	Graph &&	graph,
		program::Program	prog,
		const OptionFlags &	opt = `{}`,
		ProgressFunc	progressCallBack = `ProgressFunc()`,
		const DebugContext &	debugContext = `{}`
	)

Compile the given graph and single program to make a module.

The module cannot be executed directly using a poplar::Engine. The runtime that executes a module must be able to branch to the start of the code on each tile. A module cannot contain any data streams, and consists of a single program, so no control streams are created for selecting the program to run.

Parameters

graph	The graph to compile.
progs	The program to run over the graph.
opt	Options that can be used to control compilation and execution. The available options are listed under Engine.
progressCallBack	A function that will be called to indicate engine compilation progress. See Engine::ProgressFunc for more information.
debugContext	Optional DebugId and debug name.

Exceptions

invalid_option	If any of the options passed in `opt` were not recognised or improperly formatted.
link_error	If program linking fails; for example, due to undefined symbols or lack of memory on a tile.

◆ compileModule() [2/2]

Module poplar::compileModule	(	Graph &&	graph,
		program::Program	prog,
		const Preallocations &	preallocations,
		const OptionFlags &	opt = `{}`,
		ProgressFunc	progressCallBack = `ProgressFunc()`,
		const DebugContext &	debugContext = `{}`
	)

Compile the given graph and single program to make a module.

The module cannot be executed directly using a poplar::Engine. The runtime that executes a module must be able to branch to the start of the code on each tile. A module cannot contain any data streams, and consists of a single program, so no control streams are created for selecting the program to run.

Parameters

graph	The graph to compile.
progs	The program to run over the graph.
preallocations	A data structure describing where variables external to the graph are placed.
opt	Options that can be used to control compilation and execution. The available options are listed under Engine.
progressCallBack	A function that will be called to indicate engine compilation progress. See Engine::ProgressFunc for more information.
debugContext	Optional DebugId and debug name.

Exceptions

invalid_option	If any of the options passed in `opt` were not recognised or improperly formatted.
link_error	If program linking fails; for example, due to undefined symbols or lack of memory on a tile.

◆ concat() [1/2]

Tensor poplar::concat	(	ArrayRef< Tensor >	ts,
		unsigned	dimension = `0`
	)

Concatenate several tensors.

The tensors are concatenated along the specified dimension.

Parameters

ts	The tensors to concatenate
dimension	The number of the dimension to concatenate across

Returns: The result of the concatenation

◆ concat() [2/2]

Tensor poplar::concat	(	const Tensor &	first,
		const Tensor &	second,
		unsigned	dimension = `0`
	)

inline

Concatenate two tensors.

The tensors are concatenated along the specified dimension.

Parameters

first	The first tensor to concatenate
second	The second tensor to concatenate
dimension	The number of the dimension to concatenate across

Returns: The result of the concatenation

◆ convertFromDeviceType() [1/4]

void poplar::convertFromDeviceType	(	Type	type,
		const poplar::QuarterMetadata &	metadata,
		const void *	src,
		gccs::ArrayRef< double >	dst
	)

Convert from device data of type Type::QUARTER to host buffer of type double.

Parameters

type	Data type on device which must be Type::QUARTER.
metadata	Metadata value to use for the conversion.
src	Pointer to the start of the device data to read.
dst	Host data buffer to write to.

◆ convertFromDeviceType() [2/4]

void poplar::convertFromDeviceType	(	Type	type,
		const poplar::QuarterMetadata &	metadata,
		const void *	src,
		gccs::ArrayRef< float >	dst
	)

Convert from device data of type Type::QUARTER to host buffer of type float.

Parameters

type	Data type on device which must be Type::QUARTER.
metadata	Metadata value to use for the conversion.
src	Pointer to the start of the device data to read.
dst	Host data buffer to write to.

◆ convertFromDeviceType() [3/4]

void poplar::convertFromDeviceType	(	Type	type,
		const void *	src,
		gccs::ArrayRef< double >	dst
	)

Convert from device data of type that does not require metadata to host buffer of type double.

Parameters

type	Data type on device.
src	Pointer to the start of the device data to read.
dst	Host data buffer to write to.

◆ convertFromDeviceType() [4/4]

void poplar::convertFromDeviceType	(	Type	type,
		const void *	src,
		gccs::ArrayRef< float >	dst
	)

Convert from device data of type that does not require metadata to host buffer of type float.

Parameters

type	Data type on device.
src	Pointer to the start of the device data to read.
dst	Host data buffer to write to.

◆ convertToDeviceType() [1/4]

void poplar::convertToDeviceType	(	Type	type,
		const poplar::QuarterMetadata &	metadata,
		gccs::ArrayRef< const double >	src,
		void *	dst
	)

Convert from host buffer of type double to device data of type Type::QUARTER.

Parameters

type	Data type on device which must be Type::QUARTER.
metadata	Metadata value to use for the conversion.
src	Host data buffer to read.
dst	Pointer to the start of the device data to write.

◆ convertToDeviceType() [2/4]

void poplar::convertToDeviceType	(	Type	type,
		const poplar::QuarterMetadata &	metadata,
		gccs::ArrayRef< const float >	src,
		void *	dst
	)

Convert from host buffer of type float to device data of type Type::QUARTER.

Parameters

type	Data type on device which must be Type::QUARTER.
metadata	Metadata value to use for the conversion.
src	Host data buffer to read.
dst	Pointer to the start of the device data to write.

◆ convertToDeviceType() [3/4]

void poplar::convertToDeviceType	(	Type	type,
		gccs::ArrayRef< const double >	src,
		void *	dst
	)

Convert from host buffer of type double to device data of type that does not require metadata.

Parameters

type	Data type on device.
src	Host data buffer to read.
dst	Pointer to the start of the device data to write.

◆ convertToDeviceType() [4/4]

void poplar::convertToDeviceType	(	Type	type,
		gccs::ArrayRef< const float >	src,
		void *	dst
	)

Convert from host buffer of type float to device data of type that does not require metadata.

Parameters

type	Data type on device.
src	Host data buffer to read.
dst	Pointer to the start of the device data to write.

◆ copyDeviceHalfToDouble()

void poplar::copyDeviceHalfToDouble	(	const Target &	target,
		const void *	src,
		double *	dst,
		std::size_t	numElements
	)

Convert device half-precision values to doubles.

Parameters

target	The target that the half-precision data is to be copied from.
src	The pointer to the start of the half-precision data.
dst	The pointer to the double precision data to write.
numElements	The number of items to convert.

Deprecated:: Use the poplar::convertFromDeviceType method appropriate for the data type.

◆ copyDeviceHalfToFloat()

void poplar::copyDeviceHalfToFloat	(	const Target &	target,
		const void *	src,
		float *	dst,
		std::size_t	numElements
	)

Convert device half-precision values to floats.

Parameters

target	The target that the half-precision data is to be copied from.
src	The pointer to the start of the half-precision data.
dst	The pointer to the float data to write.
numElements	The number of items to convert.

Deprecated:: Use the poplar::convertFromDeviceType method appropriate for the data type.

◆ copyDoubleToDeviceHalf()

void poplar::copyDoubleToDeviceHalf	(	const Target &	target,
		const double *	src,
		void *	dst,
		std::size_t	numElements
	)

Convert double precision values to device half-precision values.

Parameters

target	The target that the half-precision data is to be copied to.
src	The pointer to the double precision data to read.
dst	The pointer to the half-precision data to write.
numElements	The number of items to convert.

Deprecated:: Use the poplar::convertToDeviceType method appropriate for the data type.

◆ copyFloatToDeviceHalf()

void poplar::copyFloatToDeviceHalf	(	const Target &	target,
		const float *	src,
		void *	dst,
		std::size_t	numElements
	)

Convert float values to device half-precision values.

Parameters

target	The target that the half-precision data is to be copied to.
src	The pointer to the float data to read.
dst	The pointer to the half-precision data to write.
numElements	The number of items to convert.

Deprecated:: Use the poplar::convertToDeviceType method appropriate for the data type.

◆ cycleCount()

poplar::Tensor poplar::cycleCount	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		unsigned	tile,
		SyncType	syncType,
		const DebugContext &	debugContext = `{}`
	)

Time the program for a given a sequence program type.

The result is returned as a 64-bit value in a tensor of two unsigned integers. The first element of the tensor is the lower 32 bits and the second element is the upper 32 bits. The sequence is timed by adding sync and timing programs around the original sequence. You must also specify the tile on which the program is to be timed.

Parameters

graph	The Poplar graph.
prog	The program sequence to time.
tile	The tile on which the program is timed.
syncType	The type of synchronisation to wrap the original sequence in.
debugContext	Optional debug context.

Returns: An unsigned integer tensor of length 2.

◆ cycleStamp() [1/2]

std::vector< poplar::Tensor > poplar::cycleStamp	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		const std::vector< unsigned > &	tiles,
		SyncType	syncType,
		const DebugContext &	debugContext = `{}`
	)

Add a compute set to record an absolute hardware cycle stamp on the specified tiles.

Parameters

graph	The Poplar graph.
prog	The program sequence to which the time stamp is added.
tiles	The tiles on which the time stamp is added.
syncType	The type of synchronisation to perform before stamping.
debugContext	Optional debug context.

Returns: A vector of tensors of 2 integers.

◆ cycleStamp() [2/2]

poplar::Tensor poplar::cycleStamp	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		unsigned	tile,
		SyncType	syncType,
		const DebugContext &	debugContext = `{}`
	)

Add a sequence program to record an absolute hardware cycle stamp on a given tile.

The stamp is a snapshot of a continuously running hardware counter on a tile. For consistent results, measurements must be done on the same tile.

The result is a tensor containing two 32-bit elements of a 64-bit snapshot of the hardware counter. The first element of the tensor is the lower 32 bits and the second the upper 32 bits.

The timestamp is added after a sync is executed.

Parameters

graph	The Poplar graph.
prog	The program sequence to which the time stamp is added.
tile	The tile on which the time stamp is added.
syncType	The type of synchronisation to perform before stamping.
debugContext	Optional debug context.

Returns: An unsigned integer tensor of length 2.

◆ errorCodeFromString()

ErrorCode poplar::errorCodeFromString ( StringRef error )

Convert a string to a poplar::ErrorCode code.

Exceptions

poplar::poplar_error If error cannot be converted to a poplar::ErrorCode.

◆ errorCodeToString()

StringRef poplar::errorCodeToString ( ErrorCode error )

Convert a poplar::ErrorCode code to a string.

Exceptions

poplar::poplar_error If error cannot be converted to a string.

◆ getAndModifyFloatingPointBehaviour()

poplar::Tensor poplar::getAndModifyFloatingPointBehaviour	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		const FloatingPointBehaviour &	clear,
		const FloatingPointBehaviour &	set,
		const DebugContext &	debugContext = `{}`
	)

Get the current state and modify the floating-point behaviour on every tile that belongs to the target in the graph.

Returns the previous state and modifies the behaviour. Behaviour modification first clears the behaviours set in clear followed by setting the behaviours set in set.

This can be used to set the behaviour for a section of code, and then restore the original behaviour afterwards. The recommended usage of this function should be as follows to avoid unexpected numerical behaviour:

 ...
 auto state = getAndModifyFloatingPointBehaviour(...)
 // operations that require the modified FP behaviour
 ...
 setFloatingPointBehaviour(state)

Parameters

graph	The Poplar graph.
prog	The program to be extended.
clear	Select the behaviours to clear. If a field in `clear` is set to true, then that behaviour will be cleared. If a field is false then the behaviour is unchanged.
set	Select behaviours to set. If a field in `set` is set to true, then that behaviour will be set. The values in `set` are applied after the values in `clear`. So if a field is set to true in both `clear` and `set`, then the behaviour will be set.
debugPrefix	The prefix prepended to debugging info.

Returns: The state before the floating-point behaviour is modified.

◆ getHwSeeds()

Tensor poplar::getHwSeeds	(	Graph &	graph,
		program::Sequence &	prog,
		const DebugContext &	debugContext = `{}`
	)

Gets a snapshot of the h/w seeds for each worker in device.

Parameters

graph	The Poplar graph.
prog	The program sequence to be extended.
debugPrefix	The prefix prepended to debugging info.

Returns: A tensor of shape {number of tiles, number of worker contexts, 4}, containing seed values for each of the 4 PRNG_x_y registers for each worker context on each tile.

◆ hash_value()

std::size_t poplar::hash_value ( const EngineOptions & options )

Obtain a hash value for an EngineOptions object.

The hash is performed on all the options that affect a poplar::Executable, including the target. The hash is not performed on run time engine options.

Parameters

options The engine options object to use.

◆ operator<<() [1/4]

std::ostream & poplar::operator<<	(	std::ostream &	os,
		const DebugContext &	dc
	)

Display the path name of the DebugContext.

Parameters

os	The ostream to output to.
dc	The DebugContext to display.

Returns: The ostream written to.

◆ operator<<() [2/4]

std::ostream & poplar::operator<<	(	std::ostream &	os,
		const DebugNameAndId &	dnai
	)

Display the path name of the DebugNameAndId.

Parameters

os	The ostream to output to.
dnai	The DebugNameAndId to display.

Returns: The ostream written to.

◆ operator<<() [3/4]

std::ostream & poplar::operator<<	(	std::ostream &	os,
		const Tensor &	tensor
	)

Display the regions of the tensor on a stream.

Parameters

os	The ostream to output to
tensor	The tensor to display

Returns: The ostream written to

◆ operator<<() [4/4]

std::ostream & poplar::operator<<	(	std::ostream &	ostream,
		const OptionFlags &	flags
	)

Write the contents of the given flags to an ostream in JSON format.

Parameters

ostream	The stream to write to.
flags	The OptionFlags to write.

◆ printExecutionSummary()

void poplar::printExecutionSummary	(	std::ostream &	out,
		const std::string &	databasePath,
		const OptionFlags &	opts
	)

Print a summary of the execution profiling information - primarily cycle counts.

The information printed depends on the target and the execution profiling mode. IPUModel always prints a simulation of execution.

Parameters

out	The output stream to which the summary will be written.
databasePath	The full pathname of the `profile.pop` file for which the summary will be printed.
opts	The set of option flags configuring the contents of the summary. The available options are:

showExecutionSteps (true, false) [=false]

If true, the program execution sequence with cycle estimates is included in the summary output.
colours (true, false)

See printGraphSummary().

◆ printGraphSummary()

void poplar::printGraphSummary	(	std::ostream &	out,
		const std::string &	databasePath,
		const OptionFlags &	opts
	)

Print a summary of the static graph profiling information - primarily memory use.

Parameters

out	The output stream to which the summary will be written.
databasePath	The full pathname of the `profile.pop` file for which the summary will be printed.
opts	The set of option flags configuring the contents of the summary. The available options are:

showOptimizations (true, false) [=false]

If true, information about the optimisations performed are included in the summary output.
showPerIpuMemoryUsage (true, false) [=false]

If true, total memory usage per-IPU is included in the summary output in addition to memory usage for the whole device.
showVarStorage (true, false) [=false]

If true, information about variable storage liveness is included in the summary output. This is provided for some tiles with the highest maximum live bytes as well as a total for all tiles. The maximum live bytes is output along with information about always-live variables.
colours (true, false)

Specify whether colours should be displayed in the profile report. If not set, colours will be displayed only if outputting to a supported terminal. If not set, using environment variable CLICOLOR_FORCE=1 forces colours to be displayed, while CLICOLOR=0 disables colours.

◆ printProfileSummary()

void poplar::printProfileSummary	(	std::ostream &	out,
		const std::string &	databasePath,
		const OptionFlags &	opts = `{}`
	)

Equivalent to calling printGraphSummary() followed by printExecutionSummary().

Parameters

out	The output stream to which the summary will be written.
databasePath	The full pathname of the `profile.pop` file for which the summary will be printed.
opts	The set of option flags configuring the contents of the summary. See printGraphSummary() and printExecutionSummary().

◆ readJSON() [1/2]

void poplar::readJSON	(	std::istream &	stream,
		OptionFlags &	flags
	)

Read options from a stream in JSON format.

Parameters

stream	The input stream to read from.
flags	The OptionFlags to update.

Exceptions

parse_error if the input cannot be parsed.

◆ readJSON() [2/2]

void poplar::readJSON	(	StringRef	string,
		OptionFlags &	flags
	)

Read options from a string in JSON format.

Parameters

string	The string to parse.
flags	The OptionFlags to update.

Exceptions

parse_error if the input cannot be parsed.

◆ readJSONFromEnv()

void poplar::readJSONFromEnv	(	StringRef	envVarName,
		OptionFlags &	flags
	)

Read options from a environment variable in JSON format.

Parameters

envVarName	The environment variable to retrieve and parse.
flags	The OptionFlags to update.

Exceptions

parse_error if the input cannot be parsed.

◆ setFloatingPointBehaviour() [1/2]

void poplar::setFloatingPointBehaviour	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		const FloatingPointBehaviour &	behaviour,
		const DebugContext &	debugContext = `{}`
	)

Set the floating point behaviour of a tile.

Configures the floating point behaviour of a tile, affecting the treatment of exceptions and selecting stochastic rounding according to the passed behaviour structure.

Note that, in Poplar, stochastic rounding is disabled by default until either this function, setStochasticRounding() or the Engine options are used to enable it.

Parameters

graph	The Poplar graph.
prog	The program to be extended.
behaviour	A structure of type floatingPointBehaviour.
debugPrefix	The prefix prepended to debugging info.

◆ setFloatingPointBehaviour() [2/2]

void poplar::setFloatingPointBehaviour	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		const poplar::Tensor &	behaviour,
		const DebugContext &	debugContext = `{}`
	)

Set the floating point behaviour of a tile.

Configures the floating point behaviour of a tile, affecting the treatment of exceptions and selecting stochastic rounding according to the passed behaviour tensor.

The behaviour tensor must be one returned by getAndModifyFloatingPointBehaviour().

Parameters

graph	The Poplar graph.
prog	The program to be extended.
behaviour	A tensor containing representation of floatingPointBehaviour.
debugPrefix	The prefix prepended to debugging info.

◆ setHwSeeds()

void poplar::setHwSeeds	(	Graph &	graph,
		const Tensor &	hwSeeds,
		program::Sequence &	prog,
		const DebugContext &	debugContext = `{}`
	)

Sets the hw seeds for each worker in a device from a snapshot of the seeds.

Parameters

graph	The Poplar graph.
hwSeeds	A tensor of shape {number of tiles, number of worker contexts, 4} containing seed values for each of the 4 `PRNG_x_y` registers for each worker context on each tile.
prog	The program sequence to be extended.
debugPrefix	The prefix prepended to debugging info.

◆ setStochasticRounding()

void poplar::setStochasticRounding	(	poplar::Graph &	graph,
		poplar::program::Sequence &	prog,
		bool	behaviour,
		const DebugContext &	debugContext = `{}`
	)

Set stochastic rounding on or off for the selected tile.

Configures the stochastic rounding operation of a tile according to the passed behaviour parameter.

Note that, in Poplar, stochastic rounding is disabled by default until either this function, setFloatingPointBehaviour() or the Engine options are used to enable it.

Parameters

graph	The Poplar graph.
prog	The program to be extended.
behaviour	Select stochastic rounding: true or false.
debugPrefix	The prefix prepended to debugging info.

◆ toString()

std::string poplar::toString ( TargetType t )

Convert the target type to a string.

Throws an exception if an undefined type is passed, for example static_cast<TargetType>(100).

Namespaces

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ LateInitCallback

◆ PerfEstimateFunc

◆ vertex_id

Enumeration Type Documentation

◆ CodeletFileType

◆ DataStreamType

◆ DebugSerializationFormat

◆ ErrorCode

◆ FunctionBufferMappingType

◆ RecoveryAction

◆ ReplicatedStreamMode

◆ SerializationFormat

◆ SyncType

◆ TargetType

◆ TensorCloneDuplicationMethod

◆ TensorCloneMethod

◆ UpsampleMethod

◆ VariableMappingMethod

◆ VectorLayout

◆ VectorListLayout

Function Documentation

◆ append() [1/2]

◆ append() [2/2]

◆ compileGraph() [1/2]

◆ compileGraph() [2/2]

◆ compileModule() [1/2]

◆ compileModule() [2/2]

◆ concat() [1/2]

◆ concat() [2/2]

◆ convertFromDeviceType() [1/4]

◆ convertFromDeviceType() [2/4]

◆ convertFromDeviceType() [3/4]

◆ convertFromDeviceType() [4/4]

◆ convertToDeviceType() [1/4]

◆ convertToDeviceType() [2/4]

◆ convertToDeviceType() [3/4]

◆ convertToDeviceType() [4/4]

◆ copyDeviceHalfToDouble()

◆ copyDeviceHalfToFloat()

◆ copyDoubleToDeviceHalf()

◆ copyFloatToDeviceHalf()

◆ cycleCount()

◆ cycleStamp() [1/2]

◆ cycleStamp() [2/2]

◆ errorCodeFromString()

◆ errorCodeToString()

◆ getAndModifyFloatingPointBehaviour()

◆ getHwSeeds()

◆ hash_value()

◆ operator<<() [1/4]

◆ operator<<() [2/4]

◆ operator<<() [3/4]

◆ operator<<() [4/4]

◆ printExecutionSummary()

◆ printGraphSummary()

◆ printProfileSummary()

◆ readJSON() [1/2]

◆ readJSON() [2/2]

◆ readJSONFromEnv()

◆ setFloatingPointBehaviour() [1/2]

◆ setFloatingPointBehaviour() [2/2]

◆ setHwSeeds()

◆ setStochasticRounding()

◆ toString()