PopVision analysis C++ API

This is the C++ API for the PopVision analysis library (libpva) for reading and analysing Poplar report files.

#include <pva.hpp>

Compilation reports

class pva::PoplarVersion

This class contains the version of poplar that was used when generating report.

Public Functions

PoplarVersion(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

std::string string() const: Poplar version as a string.

std::string packageHash() const: Poplar GIT hash.

uint32_t majorVer() const: major version.

uint32_t minorVer() const: minor version.

uint32_t pointVer() const: point version.

class pva::ProfileReportVersion

This class contains the version of report format that has been used.

Public Functions

ProfileReportVersion(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

uint32_t majorVer() const: major version.

uint32_t minorVer() const: minor version.

uint32_t pointVer() const: point version.

bool isUnstableFormat() const: indicates this report has development changes.

class pva::InstrumentationSettings

This class contains information about the instrumentation settings used when compiling the graph.

Public Types

enum ComputeInstrumentationLevel

The type of compute instrumentation.

Values:

enumerator Off

enumerator Vertex

enumerator Tile

enumerator Ipu

enumerator Device

enumerator Unknown

enum ExternalExchangeInstrumentationLevel

The type of external exchange instrumentation.

Values:

enumerator Off

enumerator Tile

enumerator Unknown

Public Functions

InstrumentationSettings(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

ComputeInstrumentationLevel compute() const: Compute instrumentation level.

ExternalExchangeInstrumentationLevel externalExchange() const: External exchange instrumentation level.

class pva::CompilationReport

This class contain information known at the end of graph complation.

Public Functions

CompilationReport(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

Target target() const: Detail of the target hardware.

Graph graph() const: Details of the graph.

List<VariableSize> alwaysLiveVariables() const: List of always live variables.

List<LivenessProgramStep> livenessProgramSteps() const

List of program steps with liveness information.

Based on a depth first order.

List<Tile> tilesWithLivenessInfo() const: Tiles whose liveness info has been recorded and can be retrieved with LivenessProgramStep::notAlwaysLiveForTile.

List<Variable> variables() const: List of unlowered variables.

const List<Tile> &tiles() const

List of tiles.

Provided as convience rather than iterate IPUs or Replicas.

List<IPU> ipus() const: List of IPUs.

List<Replica> replicas() const: List of replicas.

List<std::shared_ptr<Program>> programs() const: List of all programs.

List<std::shared_ptr<Program>> controlPrograms() const: List of all control programs.

List<std::shared_ptr<Program>> functions() const: List of all functions.

List<ComputeSet> computeSets() const: A list of all compute sets.

std::string timestamp() const: A time stamp of date & time when the application when compiled.

bool isDebugInfoPresent() const: True if debug info is present.

List<DebugContext> debugContexts(const DebugContext::Filter &filter = {}) const

List of debug contexts filtered by Filter.

Throws if isDebugInfoPresent() is false.

class pva::Graph

This class contains basic details about the graph.

Public Functions

Graph(const FileReaderPtr filereader)

Constructor.

Parameters

filereader – Pointer to the file reader
stepId – The ID of the step

uint64_t numComputeSets() const: The number of compute sets.

uint64_t numEdges() const: The number of edges.

uint64_t numVars() const: The number of variables.

uint64_t numVertices() const: The number of vertices.

std::unordered_map<std::string, double> optimisationMetrics() const

Internal metrics of the optimisations performed on the graph.

The keys may change but this will always be a map from strings to doubles

class pva::Target

This class contains information about the target hardware.

Public Types

enum Type

The type of hardware.

Values:

enumerator Ipu

enumerator IpuModel

enumerator Cpu

enumerator Unknown

Public Functions

Target(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

std::uint64_t numIPUs() const: The number of IPU chips in the system.

std::uint64_t tilesPerIpu() const: The number of tiles on each IPU chip.

std::uint64_t numTiles() const

The total number of tiles.

This is the product of numIPUs and tilesPerIPU. It is stored redundantly for convenience.

Bytes bytesPerTile() const: The number of bytes of memory on a tile.

Bytes bytesPerIpu() const: The number of bytes of memory on an IPU.

std::uint64_t totalMemory() const

The total memory.

This is the product of bytesPerTile and numTiles (or bytesPerIPU and numIPUs). It is stored redundantly for convenience.

double clockFrequency() const: The tile clock frequency in Hz.

std::uint64_t numReplicas() const: The number of replica.s.

std::uint64_t ipusPerReplica() const: The number of IPUS in a replica.

std::uint64_t tilesPerReplica() const: The number of tiles in a replica.

Bytes memoryPerReplica() const: The total memory in a replia.

Type type() const: The target type.

IPU::Architecture architecture() const: The IPU architecture.

uint64_t minSyncDelay() const: The minimum sync delay for any tile.

std::uint64_t supervisorInstrFetchDelay() const: The delay of a supervisor instruction fetch.

std::uint64_t interleavedMemoryStart() const: The start of interleaved memory.

std::vector<std::uint64_t> memoryElementOffsets() const: Offsets for each memory element (a memory element is an address range that does not allow simultaneous access).

class pva::VertexType

This class represents a vertex type.

Public Types

enum Source

Enum of how the vertex has been implemented.

Values:

enumerator Asm: Implemented in assembler.

enumerator CPlusPlus: Implemented in C++.

enumerator Unknown: Implementation unknown.

Public Functions

VertexType(const FileReaderPtr filereader, const VertexTypeId vertexId)

Constructor.

Parameters

filereader – Pointer to the file reader
vertexId – The vertex type id

std::string name() const: The name of the vertex type.

Bytes size() const

The size of the vertex type in bytes.

Contains the size of the vertex state (the class members) of each vertex type. For example Doubler might have 4 bytes of state.

Source source() const: How the vertex type has been implemented.

class pva::VertexMemory

Public Functions

VertexMemory(const FileReaderPtr filereader, const VertexTypeId vertexTypeId, const TileId tileId)

Constructor.

Parameters

filereader – Pointer to the
vertexId – The vertex type id
tileId – The tile id

VertexType type() const: The type of vertex.

Bytes codeBytes() const: The amount of code.

Bytes copyPtrBytes() const: The amount of copy pointers.

Bytes descriptorBytes() const: The amount of descriptors.

Bytes edgePtrBytes() const: The amount of edge pointers.

Bytes paddingBytes() const: The amount of padding pointers.

Bytes vertexDataBytes() const: The amount of vertex data.

class pva::Tile::MemoryOverlap

This class represents how much memory with in a category / region is overlapped or not overlapped.

The memory used by some variables can be overlapped with others, because they are not live at the same time. Hence, the usage is split into overlappedand nonOverlapped components.

Public Functions

inline MemoryOverlap(const Bytes nonOverlapped, const Bytes overlapped)

Constructor.

Parameters

nonOverlapped – nonOverlapped memory
overlapped – overlapped memory

inline Bytes nonOverlapped() const: The memory not overlapped.

inline Bytes overlapped() const: The memory overlapped.

inline Bytes total() const: The sum of overlapped and not overlapped memory.

class pva::Tile::CategoryMemory

This class represents the breakdown of memory by region for a category.

Category is a breakdown of memory usage across the whole system by the type of data, and the region it is in.

There are two memory regions on each tile, interleaved and non-interleaved, the use of each of these is reported separately. If the memory requirement is greater than the available memory, then this is reported as overflowed.

Public Functions

inline CategoryMemory(const MemoryOverlap interleaved, const MemoryOverlap nonInterleaved, MemoryOverlap overflowed)

Constructor.

Parameters

interleaved – interleaved memory region
nonInterleaved – non interleaved memory region
overflowed – overflowed memory region

inline MemoryOverlap interleaved() const: The interleaved memory region.

inline MemoryOverlap nonInterleaved() const: The non interleaved memory region.

inline MemoryOverlap overflowed() const: The overflowed memory region.

inline Bytes total() const: The sum of interleaved, non interleaved, and overflowed memory.

class pva::Tile::Memory::Categories

Public Functions

Categories(const FileReaderPtr filereader, const TileId tileid)

Constructor.

Parameters

filereader – Pointer to the file reader
tileId – The ID of the tile

inline CategoryMemory constant() const

Constants memory category.

Constants added by the user. Variables added by the compiler that happen to be constant will be categorised as “variable”.

inline CategoryMemory controlCode() const

Control code memory category.

Code for Program objects and running compute sets.

inline CategoryMemory controlId() const

Control id memory category.

Variables that are used in switch programs or variables that store a sync ID for tracking host/device synchronisation points.

inline CategoryMemory controlTable() const

Control table memory category.

A table that lists the vertices to run in each compute set. Only used if the table scheduler is enabled.

inline CategoryMemory copyDescriptor() const

Copy descriptor memory category.

Copy descriptors are special variable-sized fields used by copy vertices.

inline CategoryMemory globalExchangeCode() const

Global exchange code memory category.

Code for performing exchange operations between IPUs.

inline CategoryMemory globalExchangePacketHeader() const

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

inline CategoryMemory globalMessage() const

Global message memory category.

Message variables holding data being sent between IPUs.

inline CategoryMemory hostExchangeCode() const

Host exchange code memory category.

Code for performing exchange operations to and from the host.

inline CategoryMemory hostExchangePacketHeader() const

Host exchange packet header memory category.

Data used as packet headers for host exchange.

inline CategoryMemory hostMessage() const

Host message memory category.

Message variables holding data being sent or received from the host.

inline CategoryMemory instrumentationResults() const

Instrumentation results memory category.

Storage for profiling information.

inline CategoryMemory internalExchangeCode() const

Internal exchange code memory category.

Code for performing internal exchanges.

inline CategoryMemory message() const

Message memory category.

Message data for internal exchanges.

inline CategoryMemory multiple() const

Multiple memory category.

Space shared by variables from multiple different categories.

inline CategoryMemory outputEdge() const

Output edge memory category.

Storage for output edge data before an exchange takes place.

inline CategoryMemory rearrangement() const

Rearrangement memory category.

Variables holding rearranged versions of tensor data. A rearranged variable will never be always live as it is only required in the context of a specific compute set.

inline CategoryMemory sharedCodeStorage() const

Shared code storage memory category.

Code shared by vertices.

inline CategoryMemory sharedDataStorage() const

Shared data storage memory category.

Data shared by vertices.

inline CategoryMemory stack() const

Stack memory category.

The worker and supervisor stacks allocated on the specified tile. For more information about worker stack allocation see the Vertex Assembly Programming Guide.

inline CategoryMemory variable() const

Variable memory category.

Variables created in the program (for example, created by the Poplar graph.addVariable() function).

inline CategoryMemory vectorListDescriptor() const

Vector list descriptor memory category.

The data for VectorList<Input<…>, DeltaN> fields.

inline CategoryMemory vertexCode() const

Vertex code memory category.

Code for vertex functions (codelets).

inline CategoryMemory vertexFieldData() const

Vertex field data memory category.

Variable-sized fields, e.g. the data for Vector<float>, Vector<Input<…>> and InputSet<…> fields.

inline CategoryMemory vertexInstanceState() const

Vertex instance state memory category.

An instance of a Vertex class object. This will be sizeof(VertexName) for each vertex.

class pva::Tile::MemoryWithAndWithoutGaps

Public Functions

inline MemoryWithAndWithoutGaps(const Bytes excludingGaps, const Bytes includingGaps)

Constructor.

Parameters

excludingGaps – Memory excluding gaps
includingGaps – Memory including gaps

inline Bytes excludingGaps() const: The memory excluding gaps.

inline Bytes includingGaps() const: The memory include gaps.

class pva::Tile::Memory

This class represent the memory layout of a tile in various different ways.

The memory object contains a lot of information about memory use. All memory is statically allocated so you don’t need to run the program to gather this data.

Public Functions

Memory(const FileReaderPtr filereader, const TileId &tileId)

Constructor.

Parameters

filereader – Pointer to the file reader
tileId – The ID of the tile

MemoryWithAndWithoutGaps nonInterleaved() const: Details of memory with the non interleaved region for this tile.

MemoryWithAndWithoutGaps interleaved() const: Details of memory with the interleaved region for this tile.

MemoryWithAndWithoutGaps overflowed() const: Details of memory with the overflowed region for this tile.

MemoryWithAndWithoutGaps total() const: Details of the total memory usage for this tile.

Categories category() const: Details memory by category.

virtual List<VertexMemory> vertices() const: List of vertex memory usage on this tile.

class Categories

Public Functions

Categories(const FileReaderPtr filereader, const TileId tileid)

Constructor.

Parameters

filereader – Pointer to the file reader
tileId – The ID of the tile

inline CategoryMemory constant() const

Constants memory category.

Constants added by the user. Variables added by the compiler that happen to be constant will be categorised as “variable”.

inline CategoryMemory controlCode() const

Control code memory category.

Code for Program objects and running compute sets.

inline CategoryMemory controlId() const

Control id memory category.

Variables that are used in switch programs or variables that store a sync ID for tracking host/device synchronisation points.

inline CategoryMemory controlTable() const

Control table memory category.

A table that lists the vertices to run in each compute set. Only used if the table scheduler is enabled.

inline CategoryMemory copyDescriptor() const

Copy descriptor memory category.

Copy descriptors are special variable-sized fields used by copy vertices.

inline CategoryMemory globalExchangeCode() const

Global exchange code memory category.

Code for performing exchange operations between IPUs.

inline CategoryMemory globalExchangePacketHeader() const

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

inline CategoryMemory globalMessage() const

Global message memory category.

Message variables holding data being sent between IPUs.

inline CategoryMemory hostExchangeCode() const

Host exchange code memory category.

Code for performing exchange operations to and from the host.

inline CategoryMemory hostExchangePacketHeader() const

Host exchange packet header memory category.

Data used as packet headers for host exchange.

inline CategoryMemory hostMessage() const

Host message memory category.

Message variables holding data being sent or received from the host.

inline CategoryMemory instrumentationResults() const

Instrumentation results memory category.

Storage for profiling information.

inline CategoryMemory internalExchangeCode() const

Internal exchange code memory category.

Code for performing internal exchanges.

inline CategoryMemory message() const

Message memory category.

Message data for internal exchanges.

inline CategoryMemory multiple() const

Multiple memory category.

Space shared by variables from multiple different categories.

inline CategoryMemory outputEdge() const

Output edge memory category.

Storage for output edge data before an exchange takes place.

inline CategoryMemory rearrangement() const

Rearrangement memory category.

Variables holding rearranged versions of tensor data. A rearranged variable will never be always live as it is only required in the context of a specific compute set.

inline CategoryMemory sharedCodeStorage() const

Shared code storage memory category.

Code shared by vertices.

inline CategoryMemory sharedDataStorage() const

Shared data storage memory category.

Data shared by vertices.

inline CategoryMemory stack() const

Stack memory category.

The worker and supervisor stacks allocated on the specified tile. For more information about worker stack allocation see the Vertex Assembly Programming Guide.

inline CategoryMemory variable() const

Variable memory category.

Variables created in the program (for example, created by the Poplar graph.addVariable() function).

inline CategoryMemory vectorListDescriptor() const

Vector list descriptor memory category.

The data for VectorList<Input<…>, DeltaN> fields.

inline CategoryMemory vertexCode() const

Vertex code memory category.

Code for vertex functions (codelets).

inline CategoryMemory vertexFieldData() const

Vertex field data memory category.

Variable-sized fields, e.g. the data for Vector<float>, Vector<Input<…>> and InputSet<…> fields.

inline CategoryMemory vertexInstanceState() const

Vertex instance state memory category.

An instance of a Vertex class object. This will be sizeof(VertexName) for each vertex.

class pva::Tile

Public Functions

Tile(const FileReaderPtr filereader, const TileId tileId)

Constructor.

Parameters

filereader – Pointer to the file reader
tileId – The ID of the tile

inline TileId tileId() const: The sofware tile ID.

Memory memory() const: Details of memory usage by this tile.

uint64_t relativeSyncDelay() const: The sync delay for this tile (relative to the minimum value).

double clockFrequency() const: The tile clock frequency in Hz.

class CategoryMemory

This class represents the breakdown of memory by region for a category.

Category is a breakdown of memory usage across the whole system by the type of data, and the region it is in.

There are two memory regions on each tile, interleaved and non-interleaved, the use of each of these is reported separately. If the memory requirement is greater than the available memory, then this is reported as overflowed.

Public Functions

inline CategoryMemory(const MemoryOverlap interleaved, const MemoryOverlap nonInterleaved, MemoryOverlap overflowed)

Constructor.

Parameters

interleaved – interleaved memory region
nonInterleaved – non interleaved memory region
overflowed – overflowed memory region

inline MemoryOverlap interleaved() const: The interleaved memory region.

inline MemoryOverlap nonInterleaved() const: The non interleaved memory region.

inline MemoryOverlap overflowed() const: The overflowed memory region.

inline Bytes total() const: The sum of interleaved, non interleaved, and overflowed memory.

class Memory

This class represent the memory layout of a tile in various different ways.

The memory object contains a lot of information about memory use. All memory is statically allocated so you don’t need to run the program to gather this data.

Public Functions

Memory(const FileReaderPtr filereader, const TileId &tileId)

Constructor.

Parameters

filereader – Pointer to the file reader
tileId – The ID of the tile

MemoryWithAndWithoutGaps nonInterleaved() const: Details of memory with the non interleaved region for this tile.

MemoryWithAndWithoutGaps interleaved() const: Details of memory with the interleaved region for this tile.

MemoryWithAndWithoutGaps overflowed() const: Details of memory with the overflowed region for this tile.

MemoryWithAndWithoutGaps total() const: Details of the total memory usage for this tile.

Categories category() const: Details memory by category.

virtual List<VertexMemory> vertices() const: List of vertex memory usage on this tile.

class Categories

Public Functions

Categories(const FileReaderPtr filereader, const TileId tileid)

Constructor.

Parameters

filereader – Pointer to the file reader
tileId – The ID of the tile

inline CategoryMemory constant() const

Constants memory category.

Constants added by the user. Variables added by the compiler that happen to be constant will be categorised as “variable”.

inline CategoryMemory controlCode() const

Control code memory category.

Code for Program objects and running compute sets.

inline CategoryMemory controlId() const

Control id memory category.

Variables that are used in switch programs or variables that store a sync ID for tracking host/device synchronisation points.

inline CategoryMemory controlTable() const

Control table memory category.

A table that lists the vertices to run in each compute set. Only used if the table scheduler is enabled.

inline CategoryMemory copyDescriptor() const

Copy descriptor memory category.

Copy descriptors are special variable-sized fields used by copy vertices.

inline CategoryMemory globalExchangeCode() const

Global exchange code memory category.

Code for performing exchange operations between IPUs.

inline CategoryMemory globalExchangePacketHeader() const

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

inline CategoryMemory globalMessage() const

Global message memory category.

Message variables holding data being sent between IPUs.

inline CategoryMemory hostExchangeCode() const

Host exchange code memory category.

Code for performing exchange operations to and from the host.

inline CategoryMemory hostExchangePacketHeader() const

Host exchange packet header memory category.

Data used as packet headers for host exchange.

inline CategoryMemory hostMessage() const

Host message memory category.

Message variables holding data being sent or received from the host.

inline CategoryMemory instrumentationResults() const

Instrumentation results memory category.

Storage for profiling information.

inline CategoryMemory internalExchangeCode() const

Internal exchange code memory category.

Code for performing internal exchanges.

inline CategoryMemory message() const

Message memory category.

Message data for internal exchanges.

inline CategoryMemory multiple() const

Multiple memory category.

Space shared by variables from multiple different categories.

inline CategoryMemory outputEdge() const

Output edge memory category.

Storage for output edge data before an exchange takes place.

inline CategoryMemory rearrangement() const

Rearrangement memory category.

Variables holding rearranged versions of tensor data. A rearranged variable will never be always live as it is only required in the context of a specific compute set.

inline CategoryMemory sharedCodeStorage() const

Shared code storage memory category.

Code shared by vertices.

inline CategoryMemory sharedDataStorage() const

Shared data storage memory category.

Data shared by vertices.

inline CategoryMemory stack() const

Stack memory category.

The worker and supervisor stacks allocated on the specified tile. For more information about worker stack allocation see the Vertex Assembly Programming Guide.

inline CategoryMemory variable() const

Variable memory category.

Variables created in the program (for example, created by the Poplar graph.addVariable() function).

inline CategoryMemory vectorListDescriptor() const

Vector list descriptor memory category.

The data for VectorList<Input<…>, DeltaN> fields.

inline CategoryMemory vertexCode() const

Vertex code memory category.

Code for vertex functions (codelets).

inline CategoryMemory vertexFieldData() const

Vertex field data memory category.

Variable-sized fields, e.g. the data for Vector<float>, Vector<Input<…>> and InputSet<…> fields.

inline CategoryMemory vertexInstanceState() const

Vertex instance state memory category.

An instance of a Vertex class object. This will be sizeof(VertexName) for each vertex.

class MemoryOverlap

This class represents how much memory with in a category / region is overlapped or not overlapped.

The memory used by some variables can be overlapped with others, because they are not live at the same time. Hence, the usage is split into overlappedand nonOverlapped components.

Public Functions

inline MemoryOverlap(const Bytes nonOverlapped, const Bytes overlapped)

Constructor.

Parameters

nonOverlapped – nonOverlapped memory
overlapped – overlapped memory

inline Bytes nonOverlapped() const: The memory not overlapped.

inline Bytes overlapped() const: The memory overlapped.

inline Bytes total() const: The sum of overlapped and not overlapped memory.

class MemoryWithAndWithoutGaps

Public Functions

inline MemoryWithAndWithoutGaps(const Bytes excludingGaps, const Bytes includingGaps)

Constructor.

Parameters

excludingGaps – Memory excluding gaps
includingGaps – Memory including gaps

inline Bytes excludingGaps() const: The memory excluding gaps.

inline Bytes includingGaps() const: The memory include gaps.

class pva::IPU

This class represents details of a single IPU.

Public Functions

List<Tile> tiles() const: List of tiles on this IPU.

Architecture architecture() const: The architecture type of this IPU.

class pva::Replica

This class represents details of a single replica.

Public Functions

Replica(const FileReaderPtr filereader, const ReplicaId replicaId)

Constructor.

Parameters

filereader – Pointer to the file reader
replicaId – The ID of the replica

inline ReplicaId replicaId() const: The replica id.

List<IPU> ipus() const: List of tiles on this replica.

class pva::ComputeSet

This class represents details of a single compute set.

Subclassed by pva::execution::ComputeSet

Public Functions

ComputeSet(const FileReaderPtr filereader, const ComputeSetId computeSetId)

Constructor.

Parameters

filereader – Pointer to the file reader
computeSetId – The ID of the compute set

std::string name() const: The name of the compute set.

List<VertexInstances> vertices() const: The vertices used by this compute set.

std::vector<Cycles> estimatedCyclesByTile() const

Estimated cycles by tile for this compute set.

Returns an empty vector if cycle estimates are unavailable.

class pva::Program

This class is a base class that represents program type.

Subclassed by pva::CallProgram, pva::DoExchangeProgram, pva::GetGlobalConsensusProgram, pva::GlobalExchangeProgram, pva::IfElseProgram, pva::OnEveryTileSwitchProgram, pva::OnTileExecuteProgram, pva::OnTileSwitchProgram, pva::RepeatProgram, pva::RepeatWhileProgram, pva::SansProgram, pva::SequenceProgram, pva::SetLocalConsensusFromVarProgram, pva::SetLocalConsensusProgram, pva::StreamCopyBeginProgram, pva::StreamCopyEndProgram, pva::StreamCopyMidProgram, pva::SyncAnsProgram, pva::SyncProgram, pva::UnknownProgram, pva::WriteUndefProgram

Public Types

enum Type

Type of program.

Values:

enumerator Unknown

enumerator Sequence

enumerator OnTileExecute

enumerator Repeat

enumerator RepeatWhile

enumerator OnTileSwitch

enumerator OnEveryTileSwitch

enumerator IfElse

enumerator DoExchange

enumerator GlobalExchange

enumerator StreamCopyBegin

enumerator StreamCopyMid

enumerator StreamCopyEnd

enumerator WriteUndef

enumerator Sync

enumerator SetLocalConsensus

enumerator SetLocalConsensusFromVar

enumerator GetGlobalConsensus

enumerator Sans

enumerator Call

enumerator SyncAns

enum SyncType

Type of synchronisation.

Internal means all tiles on the current IPU. GS1, GS2, GS3 and GS4 are group syncs that can span multiple IPUs. Poplar determines which IPUs are in each group, and this is subject to change. Unknown means the sync type was not recorded.

Values:

enumerator Internal

enumerator GS1

enumerator GS2

enumerator GS3

enumerator GS4

enumerator Unknown

Public Functions

Program(const FileReaderPtr filereader, const ProgramId progamId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual ~Program() = default: Destructor.

virtual std::string name() const

The name of the program.

May be empty.

std::vector<DebugContext> debugContexts() const

List of debug contexts of the program.

May be empty.

virtual List<std::shared_ptr<Program>> children() const

List of child programs.

The list of children programs may be empty.

virtual Type type() const = 0: The type of the program.

virtual void accept(ProgramVisitor &visitor) const = 0

The visitor pattern accept method.

The visitor pattern allows you to visit a program dependent on its type.

class pva::OnTileExecuteProgram : public pva::Program 

OnTileExecuteProgram details.

Public Functions

OnTileExecuteProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual std::string name() const

The name of the program.

The name of this program is based on the name of the compute set.

virtual Type type() const: The type of the program.

ComputeSet computeset() const: The compute set this program uses.

class pva::UnknownProgram : public pva::Program 

UnknownProgram details.

Public Functions

UnknownProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::SequenceProgram : public pva::Program 

SequenceProgram details.

Public Functions

SequenceProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::OnTileExecuteProgram : public pva::Program

OnTileExecuteProgram details.

Public Functions

OnTileExecuteProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual std::string name() const

The name of the program.

The name of this program is based on the name of the compute set.

virtual Type type() const: The type of the program.

ComputeSet computeset() const: The compute set this program uses.

class pva::RepeatProgram : public pva::Program 

RepeatProgram details.

Public Functions

RepeatProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::RepeatWhileProgram : public pva::Program 

RepeatWhileProgram details.

Public Functions

RepeatWhileProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::OnTileSwitchProgram : public pva::Program 

OnTileSwitchProgram details.

Public Functions

OnTileSwitchProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::OnEveryTileSwitchProgram : public pva::Program 

OnEveryTileSwitchProgram details.

Public Functions

OnEveryTileSwitchProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::IfElseProgram : public pva::Program 

IfElseProgram details.

Public Functions

IfElseProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::DoExchangeProgram : public pva::Program 

DoExchangeProgram details.

Public Functions

DoExchangeProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

std::vector<Bytes> bytesReceivedByTile() const: The number of bytes received on each tile.

std::vector<Bytes> bytesSentByTile() const: The number of bytes received on each tile.

std::vector<uint64_t> estimatedCyclesByTile() const: \ The estimated number of cycles used to execute this program.

std::vector<Bytes> codeBytesByTile() const: The size of the code required for this program on each tile.

class pva::GlobalExchangeProgram : public pva::Program 

GlobalExchangeProgram details.

Public Functions

GlobalExchangeProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

std::vector<uint64_t> bytesReceivedByTile() const: The number of bytes received on each tile.

std::vector<uint64_t> bytesSentByTile() const: The number of bytes sent on each tile.

std::vector<uint64_t> estimatedCyclesByTile() const: The estimated number of cycles used to execute this program.

std::vector<uint64_t> exchangeCyclesByTile() const: The number of exchange cycles for this program.

std::vector<uint64_t> syncCyclesByTile() const: The number of sync cycles for this program.

SyncType syncType() const: The type of synchronisation used by this program.

class pva::StreamCopyBeginProgram : public pva::Program 

StreamCopyBeginProgram details.

Public Functions

StreamCopyBeginProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::StreamCopyMidProgram : public pva::Program 

StreamCopyMidProgram details.

Public Functions

StreamCopyMidProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

std::vector<uint64_t> bytesReceivedByTile() const: The number of bytes received on each tile.

std::vector<uint64_t> bytesSentByTile() const: The number of bytes sent on each tile.

std::vector<uint64_t> estimatedCyclesByTile() const: The estimated number of cycles used to execute this program.

class pva::StreamCopyEndProgram : public pva::Program 

StreamCopyEndProgram details.

Public Functions

StreamCopyEndProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::WriteUndefProgram : public pva::Program 

WriteUndefProgram details.

Public Functions

WriteUndefProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::SyncProgram : public pva::Program 

SyncProgram details.

Subclassed by pva::ImplicitSyncProgram

Public Functions

SyncProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual std::string name() const: The name of this program.

virtual Type type() const: The type of the program.

SyncType syncType() const: The type of synchronisation for this program.

class pva::SetLocalConsensusProgram : public pva::Program 

SetLocalConsensusProgram details.

Public Functions

SetLocalConsensusProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::SetLocalConsensusFromVarProgram : public pva::Program 

SetLocalConsensusFromVarProgram details.

Public Functions

SetLocalConsensusFromVarProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::GetGlobalConsensusProgram : public pva::Program 

GetGlobalConsensusProgram details.

Public Functions

GetGlobalConsensusProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

class pva::SansProgram : public pva::Program 

SansProgram details.

Public Functions

SansProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

uint64_t numTiles() const: Number of tiles involved in this Sans program.

class pva::CallProgram : public pva::Program 

CallProgram details.

Public Functions

CallProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

std::shared_ptr<Program> target() const: The program that this call program invokes.

class pva::SyncAnsProgram : public pva::Program 

SyncAnsProgram details.

The non particaptory sync.

Public Functions

SyncAnsProgram(const FileReaderPtr filereader, const ProgramId programId)

Constructor.

Parameters

filereader – Pointer to the file reader
programId – The ID of the program

virtual void accept(ProgramVisitor &visitor) const: The visitor pattern accept method.

virtual Type type() const: The type of the program.

uint64_t numTiles() const: Number of tiles involved in this SanAns program.

class ProgramVisitor

ProgramVisitor interface.

It is expected that users would create a subclass of this class and then visit the programs.

class pva::Variable

This class represents details of a variable.

Subclassed by pva::VariableSize

Public Functions

inline std::string name() const: The name of the variable.

std::vector<DebugContext> debugContexts() const

List of debug contexts of the program.

May be empty.

class pva::LivenessProgramStep

This class represents details liveness for step in the program.

Public Functions

LivenessProgramStep(const FileReaderPtr filereader, const StepId stepId)

Constructor.

Parameters

filereader – Pointer to the file reader
stepId – The ID of the step

std::shared_ptr<Program> program() const: The program this step is for.

class pva::LivenessProgramStep

This class represents details liveness for step in the program.

Public Functions

LivenessProgramStep(const FileReaderPtr filereader, const StepId stepId)

Constructor.

Parameters

filereader – Pointer to the file reader
stepId – The ID of the step

std::shared_ptr<Program> program() const: The program this step is for.

class pva::CompilationReport

This class contain information known at the end of graph complation.

Public Functions

CompilationReport(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

Target target() const: Detail of the target hardware.

Graph graph() const: Details of the graph.

List<VariableSize> alwaysLiveVariables() const: List of always live variables.

List<LivenessProgramStep> livenessProgramSteps() const

List of program steps with liveness information.

Based on a depth first order.

List<Tile> tilesWithLivenessInfo() const: Tiles whose liveness info has been recorded and can be retrieved with LivenessProgramStep::notAlwaysLiveForTile.

List<Variable> variables() const: List of unlowered variables.

const List<Tile> &tiles() const

List of tiles.

Provided as convience rather than iterate IPUs or Replicas.

List<IPU> ipus() const: List of IPUs.

List<Replica> replicas() const: List of replicas.

List<std::shared_ptr<Program>> programs() const: List of all programs.

List<std::shared_ptr<Program>> controlPrograms() const: List of all control programs.

List<std::shared_ptr<Program>> functions() const: List of all functions.

List<ComputeSet> computeSets() const: A list of all compute sets.

std::string timestamp() const: A time stamp of date & time when the application when compiled.

bool isDebugInfoPresent() const: True if debug info is present.

List<DebugContext> debugContexts(const DebugContext::Filter &filter = {}) const

List of debug contexts filtered by Filter.

Throws if isDebugInfoPresent() is false.

Execution reports

class pva::Run

This class contains information about each Poplar Engine::run.

Public Functions

Run(const FileReaderPtr filereader, const RunId runId)

Constructor.

Parameters

filereader – Pointer to the file reader
runId – The id of a run

std::string name() const: Name given to this run.

List<ExecutionStep> steps() const: A list of program steps in this run.

Period<Microseconds> microseconds() const: The start and end of this run.

std::vector<Period<Cycles>> cyclesByIpu() const

The cycles by Ipu at the start and end of this run.

Note: vector may be empty if the run was too short to record cycles

class pva::ExecutionStep::Ipu

The class contains the measured information for an IPU.

Public Functions

Ipu(const FileReaderPtr filereader, const IpuId ipuId, const StepId stepid)

Constructor.

Parameters

filereader – Pointer to the file reader
ipuId – The id of an IPU
stepId – The id of a step in the execution

CyclesInfo allCycles() const

The range of cycles for all tiles on this IPU.

Note : Will return 0’s if this ipu has not be profiled.

CyclesInfo activeCycles() const

The range of cycles for all tiles involved on this IPU.

Note : Will return 0’s if this ipu has not be profiled.

uint64_t cycles() const

Total cycles executed on this IPU.

This is the sum of cycles on all tiles.

Note : Will return 0 if this ipu has not be profiled.

uint64_t activeTiles() const

The number of tiles involved.

The number of tiles that are computing (or exchanging for exchanges).

Note : Will return 0 if this ipu has not be profiled.

float threadBalance() const

Indication of hardware thread utilisation.

Measures how well-utilised the hardware threads are. If you always run 6 threads or 0 threads this will be 1.0 even if the total computation on each tile takes a different amount of time.

Note : Will return 0 if this ipu has not be profiled.

float tileBalance() const

Indication of hardware tile utilisation.

Measures how well-utilised the hardware tiles are. Larger values (up to a maximum of 1.0) indicate that work has been shared amongst tiles on this IPU more evenly.

Note : Only valid for OnTileExecute, GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

float activeTileBalance() const

Indication of active hardware tile utilisation.

Measures how well-utilised the active hardware tiles are. Larger values (up to a maximum of 1.0) indicate that work has been shared amongst the active tiles on this IPU more evenly.

Note : Only valid for OnTileExecute, GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

Bytes dataIn() const

Total data received by this IPU.

Note : Only valid for GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

Bytes dataOut() const

Total data sent by this IPU.

Note : Only valid for GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

float dataBalance() const

Indication of how well-balanced the data transfer was.

Note : Only valid for GlobalExchange, StreamCopy, DoExchange Note : Will return 0 if this ipu has not be profiled.

bool profiled() const

Indication if this IPU was profiled.

With the poplar engine option ‘replicaToProfile’, only a subset of the ipu’s may have execution profile information.

IpuId id() const: The ID of this IPU.

class pva::ExecutionStep

The class contains information about a step of execution.

Each step will represent the execution of poplar program

Public Functions

ExecutionStep(const FileReaderPtr filereader, const StepId stepId)

Constructor.

Parameters

filereader – Pointer to the file reader
stepId – The id of a step in the execution

std::shared_ptr<Program> program() const: The program being executed.

std::vector<Cycles> cyclesByTile() const

The measured cycles by tile for this execution step *.

When using the ‘replicaToProfile’ option tiles, on the replica profiled will have measured values, the other tiles will return 0

List<execution::ComputeSet> computeSets() const: A list of all compute sets in this step.

List<Ipu> ipus() const: Details of a program step execution per IPU.

class CycleRange

The class contains the range of cycles executed for this step.

Each tile executes a step with different number of cycles

Public Functions

inline CycleRange(Cycles min, Cycles max, Cycles average)

Constructor.

Parameters

min – Minimum number of cycles
max – Maximum number of cycles
average – Average number of cycles

inline Cycles min() const: The minimum number of cycles.

inline Cycles max() const: The maximum number of cycles.

inline Cycles average() const: The average number of cycles.

class CyclesInfo

The class contains the start and end cycles.

Public Functions

inline CyclesInfo(CycleRange from, CycleRange to)

Constructor.

Parameters

from – Minimum number of cycles
to – Maximum number of cycles

inline CycleRange from() const: The start of the cycles.

inline CycleRange to() const: The end of the cycles.

class Ipu

The class contains the measured information for an IPU.

Public Functions

Ipu(const FileReaderPtr filereader, const IpuId ipuId, const StepId stepid)

Constructor.

Parameters

filereader – Pointer to the file reader
ipuId – The id of an IPU
stepId – The id of a step in the execution

CyclesInfo allCycles() const

The range of cycles for all tiles on this IPU.

Note : Will return 0’s if this ipu has not be profiled.

CyclesInfo activeCycles() const

The range of cycles for all tiles involved on this IPU.

Note : Will return 0’s if this ipu has not be profiled.

uint64_t cycles() const

Total cycles executed on this IPU.

This is the sum of cycles on all tiles.

Note : Will return 0 if this ipu has not be profiled.

uint64_t activeTiles() const

The number of tiles involved.

The number of tiles that are computing (or exchanging for exchanges).

Note : Will return 0 if this ipu has not be profiled.

float threadBalance() const

Indication of hardware thread utilisation.

Measures how well-utilised the hardware threads are. If you always run 6 threads or 0 threads this will be 1.0 even if the total computation on each tile takes a different amount of time.

Note : Will return 0 if this ipu has not be profiled.

float tileBalance() const

Indication of hardware tile utilisation.

Measures how well-utilised the hardware tiles are. Larger values (up to a maximum of 1.0) indicate that work has been shared amongst tiles on this IPU more evenly.

Note : Only valid for OnTileExecute, GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

float activeTileBalance() const

Indication of active hardware tile utilisation.

Measures how well-utilised the active hardware tiles are. Larger values (up to a maximum of 1.0) indicate that work has been shared amongst the active tiles on this IPU more evenly.

Note : Only valid for OnTileExecute, GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

Bytes dataIn() const

Total data received by this IPU.

Note : Only valid for GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

Bytes dataOut() const

Total data sent by this IPU.

Note : Only valid for GlobalExchange, StreamCopy, DoExchange. Note : Will return 0 if this ipu has not be profiled.

float dataBalance() const

Indication of how well-balanced the data transfer was.

Note : Only valid for GlobalExchange, StreamCopy, DoExchange Note : Will return 0 if this ipu has not be profiled.

bool profiled() const

Indication if this IPU was profiled.

With the poplar engine option ‘replicaToProfile’, only a subset of the ipu’s may have execution profile information.

IpuId id() const: The ID of this IPU.

class pva::ExecutionReport

This class contains information collected from the execution of a model.

Public Functions

ExecutionReport(const FileReaderPtr filereader)

Constructor.

Parameters: filereader – Pointer to the file reader

List<Run> runs() const: A list of poplar engine runs.

List<ExecutionStep> steps() const: A list of all program steps for the entire execution.

TileCycleTotals totalCycles() const

Total cycles executed on all IPUs.

For all IPUs and replicas.