6. 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>

6.1. 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<AlwaysLiveVariable> alwaysLiveVariables() const

List of always live variables.

List<LivenessProgramStep> livenessProgramSteps() const

List of program steps with liveness information.

Based on a depth first order.

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.

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

MemoryOverlap(const Bytes nonOverlapped, const Bytes overlapped)

Constructor.

Parameters
  • nonOverlapped: nonOverlapped memory

  • overlapped: overlapped memory

Bytes nonOverlapped() const

The memory not overlapped.

Bytes overlapped() const

The memory overlapped.

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

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

Constructor.

Parameters
  • interleaved: interleaved memory region

  • nonInterleaved: non interleaved memory region

  • overflowed: overflowed memory region

MemoryOverlap interleaved() const

The interleaved memory region.

MemoryOverlap nonInterleaved() const

The non interleaved memory region.

MemoryOverlap overflowed() const

The overflowed memory region.

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

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”.

CategoryMemory controlCode() const

Control code memory category.

Code for Program objects and running compute sets.

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.

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.

CategoryMemory copyDescriptor() const

Copy descriptor memory category.

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

CategoryMemory globalExchangeCode() const

Global exchange code memory category.

Code for performing exchange operations between IPUs.

CategoryMemory globalExchangePacketHeader() const

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

CategoryMemory globalMessage() const

Global message memory category.

Message variables holding data being sent between IPUs.

CategoryMemory hostExchangeCode() const

Host exchange code memory category.

Code for performing exchange operations to and from the host.

CategoryMemory hostExchangePacketHeader() const

Host exchange packet header memory category.

Data used as packet headers for host exchange.

CategoryMemory hostMessage() const

Host message memory category.

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

CategoryMemory instrumentationResults() const

Instrumentation results memory category.

Storage for profiling information.

CategoryMemory internalExchangeCode() const

Internal exchange code memory category.

Code for performing internal exchanges.

CategoryMemory message() const

Message memory category.

Message data for internal exchanges.

CategoryMemory multiple() const

Multiple memory category.

Space shared by variables from multiple different categories.

CategoryMemory outputEdge() const

Output edge memory category.

Storage for output edge data before an exchange takes place.

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.

CategoryMemory sharedCodeStorage() const

Shared code storage memory category.

Code shared by vertices.

CategoryMemory sharedDataStorage() const

Shared data storage memory category.

Data shared by vertices.

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.

CategoryMemory variable() const

Variable memory category.

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

CategoryMemory vectorListDescriptor() const

Vector list descriptor memory category.

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

CategoryMemory vertexCode() const

Vertex code memory category.

Code for vertex functions (codelets).

CategoryMemory vertexFieldData() const

Vertex field data memory category.

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

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

MemoryWithAndWithoutGaps(const Bytes excludingGaps, const Bytes includingGaps)

Constructor.

Parameters
  • excludingGaps: Memory excluding gaps

  • includingGaps: Memory including gaps

Bytes excludingGaps() const

The memory excluding gaps.

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.

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

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”.

CategoryMemory controlCode() const

Control code memory category.

Code for Program objects and running compute sets.

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.

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.

CategoryMemory copyDescriptor() const

Copy descriptor memory category.

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

CategoryMemory globalExchangeCode() const

Global exchange code memory category.

Code for performing exchange operations between IPUs.

CategoryMemory globalExchangePacketHeader() const

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

CategoryMemory globalMessage() const

Global message memory category.

Message variables holding data being sent between IPUs.

CategoryMemory hostExchangeCode() const

Host exchange code memory category.

Code for performing exchange operations to and from the host.

CategoryMemory hostExchangePacketHeader() const

Host exchange packet header memory category.

Data used as packet headers for host exchange.

CategoryMemory hostMessage() const

Host message memory category.

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

CategoryMemory instrumentationResults() const

Instrumentation results memory category.

Storage for profiling information.

CategoryMemory internalExchangeCode() const

Internal exchange code memory category.

Code for performing internal exchanges.

CategoryMemory message() const

Message memory category.

Message data for internal exchanges.

CategoryMemory multiple() const

Multiple memory category.

Space shared by variables from multiple different categories.

CategoryMemory outputEdge() const

Output edge memory category.

Storage for output edge data before an exchange takes place.

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.

CategoryMemory sharedCodeStorage() const

Shared code storage memory category.

Code shared by vertices.

CategoryMemory sharedDataStorage() const

Shared data storage memory category.

Data shared by vertices.

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.

CategoryMemory variable() const

Variable memory category.

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

CategoryMemory vectorListDescriptor() const

Vector list descriptor memory category.

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

CategoryMemory vertexCode() const

Vertex code memory category.

Code for vertex functions (codelets).

CategoryMemory vertexFieldData() const

Vertex field data memory category.

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

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

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

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

Constructor.

Parameters
  • interleaved: interleaved memory region

  • nonInterleaved: non interleaved memory region

  • overflowed: overflowed memory region

MemoryOverlap interleaved() const

The interleaved memory region.

MemoryOverlap nonInterleaved() const

The non interleaved memory region.

MemoryOverlap overflowed() const

The overflowed memory region.

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.

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

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”.

CategoryMemory controlCode() const

Control code memory category.

Code for Program objects and running compute sets.

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.

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.

CategoryMemory copyDescriptor() const

Copy descriptor memory category.

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

CategoryMemory globalExchangeCode() const

Global exchange code memory category.

Code for performing exchange operations between IPUs.

CategoryMemory globalExchangePacketHeader() const

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

CategoryMemory globalMessage() const

Global message memory category.

Message variables holding data being sent between IPUs.

CategoryMemory hostExchangeCode() const

Host exchange code memory category.

Code for performing exchange operations to and from the host.

CategoryMemory hostExchangePacketHeader() const

Host exchange packet header memory category.

Data used as packet headers for host exchange.

CategoryMemory hostMessage() const

Host message memory category.

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

CategoryMemory instrumentationResults() const

Instrumentation results memory category.

Storage for profiling information.

CategoryMemory internalExchangeCode() const

Internal exchange code memory category.

Code for performing internal exchanges.

CategoryMemory message() const

Message memory category.

Message data for internal exchanges.

CategoryMemory multiple() const

Multiple memory category.

Space shared by variables from multiple different categories.

CategoryMemory outputEdge() const

Output edge memory category.

Storage for output edge data before an exchange takes place.

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.

CategoryMemory sharedCodeStorage() const

Shared code storage memory category.

Code shared by vertices.

CategoryMemory sharedDataStorage() const

Shared data storage memory category.

Data shared by vertices.

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.

CategoryMemory variable() const

Variable memory category.

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

CategoryMemory vectorListDescriptor() const

Vector list descriptor memory category.

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

CategoryMemory vertexCode() const

Vertex code memory category.

Code for vertex functions (codelets).

CategoryMemory vertexFieldData() const

Vertex field data memory category.

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

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

MemoryOverlap(const Bytes nonOverlapped, const Bytes overlapped)

Constructor.

Parameters
  • nonOverlapped: nonOverlapped memory

  • overlapped: overlapped memory

Bytes nonOverlapped() const

The memory not overlapped.

Bytes overlapped() const

The memory overlapped.

Bytes total() const

The sum of overlapped and not overlapped memory.

class MemoryWithAndWithoutGaps

Public Functions

MemoryWithAndWithoutGaps(const Bytes excludingGaps, const Bytes includingGaps)

Constructor.

Parameters
  • excludingGaps: Memory excluding gaps

  • includingGaps: Memory including gaps

Bytes excludingGaps() const

The memory excluding gaps.

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

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

~Program() = default

Destructor.

std::string name() const

The name of the program.

May be empty.

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

List of child programs.

The list of children programs may be empty.

Type type() const = 0

The type of the program.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

std::string name() const

The name of the program.

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

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

std::string name() const

The name of the program.

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

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

std::string name() const

The name of this program.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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

void accept(ProgramVisitor &visitor) const

The visitor pattern accept method.

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::AlwaysLiveVariable, pva::NotAlwaysLiveVariable

Public Functions

Variable(const FileReaderPtr filereader, const VariableId varId)

Constructor.

Parameters
  • filereader: Pointer to the file reader

  • varId: The ID of the variable

  • stepId: Program step ID. Must be supplied if and only if this variable is not always live.

std::string name() const = 0

The name of the variable.

Bytes size() const = 0

The size of the variable.

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.

Bytes notAlwaysLiveBytes() const

The total not always live bytes.

List<NotAlwaysLiveVariable> notAlwaysLiveVariables() const

List of not always live variables.

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.

Bytes notAlwaysLiveBytes() const

The total not always live bytes.

List<NotAlwaysLiveVariable> notAlwaysLiveVariables() const

List of not always live variables.

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<AlwaysLiveVariable> alwaysLiveVariables() const

List of always live variables.

List<LivenessProgramStep> livenessProgramSteps() const

List of program steps with liveness information.

Based on a depth first order.

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.

6.2. 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

CycleRange(Cycles min, Cycles max, Cycles average)

Constructor.

Parameters
  • min: Minimum number of cycles

  • max: Maximum number of cycles

  • average: Average number of cycles

Cycles min() const

The minimum number of cycles.

Cycles max() const

The maximum number of cycles.

Cycles average() const

The average number of cycles.

class CyclesInfo

The class contains the start and end cycles.

Public Functions

CyclesInfo(CycleRange from, CycleRange to)

Constructor.

Parameters
  • from: Minimum number of cycles

  • to: Maximum number of cycles

CycleRange from() const

The start of the cycles.

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.