3. PopVision Analysis library Python API

This document describes the libpva Python API. Many classes are wrappers around the equivalent C++ class.

3.1. Compilation reports

pva.openReport(*args, **kwargs)

Overloaded function.

  1. openReport(filename: str) -> pva::Report

  2. openReport(profileFilename: str, debugInfoFilename: str) -> pva::Report

class pva.Report
property compilation

Details from the Poplar compilation.

Type

pva.CompilationReport

property execution

Details from the Poplar execution.

Type

pva.ExecutionReport

property instrumentationSettings

Details of the instrumentation settings used.

Type

pva.InstrumentationSettings

listPrintLength(self: pva.pva_core.Report, newLength: int) None
property poplarVersion

The Poplar version.

Type

pva.PoplarVersion

property version

The report format version.

Type

pva.ProfileReportVersion

class pva.PoplarVersion

The Poplar version that was used when generating the report.

property major

Major version number.

Type

int

property minor

Minor version number.

Type

int

property packageHash

Poplar GIT hash

Type

str

property point

Point version number.

Type

int

property string

Poplar version as a string.

Type

str

class pva.ProfileReportVersion

ProfileReportVersion contains the version of the report format that has been used.

property isUnstableFormat

Indicates this report has development changes.

Type

bool

property major

Major version number.

Type

int

property minor

Minor version number.

Type

int

property point

Point version number.

Type

int

class pva.InstrumentationSettings

Information about the instrumentation settings used when compiling the graph.

class ComputeInstrumentationLevel

Members:

Off

Vertex

Tile

Ipu

Device

Unknown

Device = <ComputeInstrumentationLevel.Device: 4>
Ipu = <ComputeInstrumentationLevel.Ipu: 3>
Off = <ComputeInstrumentationLevel.Off: 0>
Tile = <ComputeInstrumentationLevel.Tile: 2>
Unknown = <ComputeInstrumentationLevel.Unknown: 5>
Vertex = <ComputeInstrumentationLevel.Vertex: 1>
property name
property value
Device = <ComputeInstrumentationLevel.Device: 4>
class ExternalExchangeInstrumentationLevel

Members:

Off

Tile

Unknown

Off = <ExternalExchangeInstrumentationLevel.Off: 0>
Tile = <ExternalExchangeInstrumentationLevel.Tile: 1>
Unknown = <ExternalExchangeInstrumentationLevel.Unknown: 2>
property name
property value
Ipu = <ComputeInstrumentationLevel.Ipu: 3>
Off = <ExternalExchangeInstrumentationLevel.Off: 0>
Tile = <ExternalExchangeInstrumentationLevel.Tile: 1>
Unknown = <ExternalExchangeInstrumentationLevel.Unknown: 2>
Vertex = <ComputeInstrumentationLevel.Vertex: 1>
property compute

Compute instrumentation level.

Type

pva.ComputeInstrumentationLevel

property externalExchange

External exchange instrumentation level.

Type

pva.ExternalExchangeInstrumentationLevel

class pva.Graph

Basic details about the graph.

property numComputeSets

The number of compute sets.

Type

int

property numEdges

The number of edges.

Type

int

property numVars

The number of variables.

Type

int

property numVertices

The number of vertices.

Type

int

class pva.Target

Target contains information about the target hardware.

Cpu = <Type.Cpu: 2>
Ipu = <Type.Ipu: 0>
IpuModel = <Type.IpuModel: 1>
class Type

The type of hardware

Members:

Ipu

IpuModel

Cpu

Unknown

Cpu = <Type.Cpu: 2>
Ipu = <Type.Ipu: 0>
IpuModel = <Type.IpuModel: 1>
Unknown = <Type.Unknown: 3>
property name
property value
Unknown = <Type.Unknown: 3>
property architecture

The IPU architecture.

Type

pva.IPU.Architecture

property atomicStoreGranularity

The atomic store granularity. Will return 0 if this data is not present in the report

Type

int

property bytesPerIPU

The number of bytes of memory on an IPU.

Type

int

property bytesPerTile

The number of bytes of memory on a tile.

Type

int

property clockFrequency

The tile clock frequency in Hz

Type

float

property convUnitCoeffLoadBytesPerCycle

The number of convolutional weights that can be loaded in a cycle. Will return 0 if this data is not present in the report

Type

int

property dataPathWidth

The width of the load/store data path within the tile. Will return 0 if this data is not present in the report

Type

int

property exchangeBytesPerCycle

The bandwidth of internal IPU exchange in bytes per cycle. Will return 0 if this data is not present in the report

Type

int

property fp16ConvUnitInputLoadElemsPerCycle

The input elements loaded per cycle for f16 conv. Will return 0 if this data is not present in the report

Type

int

property fp16ConvUnitMaxPipelineDepth

The maximum pipeline depth of the convolution units within tile for fp16. Will return 0 if this data is not present in the report

Type

int

property fp16InFp16OutConvUnitsPerTile

The number of convolution units in the tile that can be used when partial results are outputs as 16-bits and inputs are 16 bits. Will return 0 if this data is not present in the report

Type

int

property fp16InFp32OutConvUnitsPerTile

The number of convolution units in the tile that can be used when partial results are outputs as 32-bits and inputs are 16 bits. Will return 0 if this data is not present in the report

Type

int

property fp32ConvUnitInputLoadElemsPerCycle

The input elements loaded per cycle for f32 conv. Will return 0 if this data is not present in the report

Type

int

property fp32ConvUnitMaxPipelineDepth

The maximum pipeline depth of the convolution units within tile for fp32 Will return 0 if this data is not present in the report.

Type

int

property fp32InFp32OutConvUnitsPerTile

The number of convolution units in the tile that can be used when partial results are outputs as 32-bits and inputs are 32 bits. Will return 0 if this data is not present in the report

Type

int

property fp8ConvUnitInputLoadElemsPerCycle

The input elements loaded per cycle for f8 conv. Will return 0 if this data is not present in the report

Type

int

property fp8ConvUnitMaxPipelineDepth

The maximum pipeline depth of the convolution units within tile for fp8. Will return 0 if this data is not present in the report

Type

int

property fp8InFp16OutConvUnitsPerTile

The number of convolution units in the tile that can be used when partial results are outputs as 16-bits and inputs are 8 bits. Will return 0 if this data is not present in the report

Type

int

property globalExchangePacketBytes

Size of the packet used to transfer data between tiles in bytes. Will return 0 if this data is not present in the report

Type

int

property globalSyncCycles

The number of clock cycles required to synchronize all IPUs. Will return 0 if this data is not present in the report

Type

int

property instructionBytes

The size of an instruction in bytes. Will return 0 if this data is not present in the report

Type

int

property interleavedMemoryStart

The start of interleaved memory.

Type

int

property ipusPerReplica

The number of IPUS in a replica.

Type

int

property maxImmediateOffsetInRunInstr

Max range of immediate operand in run instruction zimm16 operand multiplied implicitly by 4 when added to register operand. Will return 0 if this data is not present in the report

Type

int

property memcpyBytesPerCycle

The number of bytes per cycle that can be copied from one location to another using a memcpy. Will return 0 if this data is not present in the report

Type

int

property memoryElementOffsets

std::vector<int> Offsets for each memory element.

property memoryPerReplica

The total memory in a replia.

Type

int

property memoryRegionOffsets

std::vector<int> Offsets for each memory region.

property minSyncDelay

The minimum sync delay for any tile.

Type

int

property numIPUs

The number of IPU chips in the system.

Type

int

property numReplicas

The number of replicas.

Type

int

property numStrideBits

Number of stride bits. Will return 0 if this data is not present in the report

Type

int

property numTiles

The total number of tiles. This is the product of numIPUs and tilesPerIPU. It is stored redundantly for convenience.

Type

int

property numWorkerContexts

The number of worker contexts per tile. Will return 0 if this data is not present in the report

Type

int

property rptCountMax

Max number of repeat counter. Will return 0 if this data is not present in the report

Type

int

property supervisorInstrFetchDelay

The delay of a supervisor instruction fetch.

Type

int

property supportsSuperTileSendReceive

Whether a tile in a super-tile can use all the exchange bandwidth of the super-tile to send or receive, when the other tile is idle or receiving the same data. Will return false if this data is not present in the report

Type

bool

property tileLocalSyncExitDelay

Number of cycles after a worker has issued its exit instruction that the supervisor can resume. Will return 0 if this data is not present in the report

Type

int

property tileLocalSyncSyncDelay

Number of cycles from issuing a sync instruction to the earliest time that instructions can resume. Will return 0 if this data is not present in the report

Type

int

property tileMemoryBaseAddress

The physical address where tile memory starts.

Type

int

property tilesPerIpu

The number of tiles on each IPU chip.

Type

int

property tilesPerReplica

The number of tiles in a replica.

Type

int

property tilesPerSuperTile

The number of tiles per super-tile. Will return 0 if this data is not present in the report

Type

int

property totalMemory

The total memory. This is the product of bytesPerTile and numTiles (or bytesPerIPU and numIPUs).

Type

int

property type

The target typ.

Type

pva.Target.Type

property workerInstrFetchDelay

Number of bytes worker context may be loading instructions from memory ahead of current PC. Will return 0 if this data is not present in the report

Type

int

class pva.VertexType

VertexType represents a vertex type.

Asm = <Source.Asm: 0>
CPlusPlus = <Source.CPlusPlus: 1>
class Source

Indicates how the vertex has been implemented.

Members:

Asm : Implemented in assembler.

CPlusPlus : Implemented in C++.

Unknown : Implementation unknown.

Asm = <Source.Asm: 0>
CPlusPlus = <Source.CPlusPlus: 1>
Unknown = <Source.Unknown: 2>
property name
property value
Unknown = <Source.Unknown: 2>
property name

The name of the vertex type.

Type

str

property size

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.

Type

int

property source

How the vertex type has been implemented.

Type

pva.VertexType.Source

class pva.VertexMemory

VertexMemory represents how much memory a vertex type uses on a tile.

property codeBytes

The amount of code.

Type

int

property copyPtrBytes

The amount of copy pointers.

Type

int

property descriptorBytes

The amount of descriptors.

Type

int

property edgePtrBytes

The amount of edge pointers.

Type

int

property paddingBytes

The amount of padding pointers.

Type

int

property type

The type of vertex.

Type

pva.VertexType

property vertexDataBytes

The amount of vertex data.

Type

int

class pva.VertexInstances

VertexInstances represents a number of instances of a vertex type in a compute set.

property count

The number of vertex instances.

Type

int

property countByTile

The number of vertex instances by tile.

Type

List[int]

property estimatedCycles

The estimated cycles for this vertex type.

Type

int

property type

The type of the vertex instances.

Type

pva.VertexType

class pva.MemoryOverlap

MemoryOverlap represents how much memory within 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 overlapped and non-overlapped components.

property nonOverlapped

The memory not overlapped.

Type

int

property overlapped

The memory overlapped.

Type

int

property total

The sum of overlapped and not overlapped memory.

Type

int

class pva.CategoryMemory

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

property interleaved

The interleaved memory region.

Type

pva.MemoryOverlap

property nonInterleaved

The non interleaved memory region

Type

pva.MemoryOverlap

property overflowed

The overflowed memory region.

Type

pva.MemoryOverlap

property total

The sum of interleaved, non interleaved, and overflowed memory.

Type

pva.MemoryOverlap

class pva.TileMemoryCategories

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

property constant

Constants memory category.

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

Type

pva.CategoryMemory

property controlCode

Control code memory category.

Code for Program objects and running compute sets.

Type

pva.CategoryMemory

property controlId

Control id memory category.

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

Type

pva.CategoryMemory

property controlTable

Control table memory category.

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

Type

pva.CategoryMemory

property copyDescriptor

Copy descriptor memory category.

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

Type

pva.CategoryMemory

property dwarf

DWARF memory category.

DWARF debug information.

Type

pva.CategoryMemory

property globalExchangeCode

Global exchange code memory category.

Code for performing exchange operations between IPUs.

Type

pva.CategoryMemory

property globalExchangePacketHeader

Global exchange packet header category.

Packet headers for exchange operations between IPUs.

Type

pva.CategoryMemory

property globalMessage

Global message memory category.

Message variables holding data being sent between IPUs.

Type

pva.CategoryMemory

property hostExchangeCode

Host exchange code memory category.

Code for performing exchange operations to and from the host

Type

pva.CategoryMemory

property hostExchangePacketHeader

Host exchange packet header memory category.

Data used as packet headers for host exchange.

Type

pva.CategoryMemory

property hostMessage

Host message memory category.

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

Type

pva.CategoryMemory

property instrumentationResults

Instrumentation results memory category.

Storage for profiling information.

Type

pva.CategoryMemory

property internalExchangeCode

Internal exchange code memory category.

Code for performing internal exchanges.

Type

pva.CategoryMemory

property message

Message memory category.

Message data for internal exchanges.

Type

pva.CategoryMemory

property multiple

Multiple memory category.

Space shared by variables from multiple different categories.

Type

pva.CategoryMemory

property outputEdge

Output edge memory category.

Storage for output edge data before an exchange takes place.

Type

pva.CategoryMemory

property rearrangement

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.

Type

pva.CategoryMemory

property sharedCodeStorage

Shared code storage memory category.

Code shared by vertices.

Type

pva.CategoryMemory

property sharedDataStorage

Shared data storage memory category.

Data shared by vertices.

Type

pva.CategoryMemory

property stack

Stack memory category.

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

Type

pva.CategoryMemory

property variable

Variable memory category.

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

Type

pva.CategoryMemory

property vectorListDescriptor

Vector list descriptor memory category.

The data for VectorList[Input[…] DeltaN] fields.

Type

pva.CategoryMemory

property vertexCode

Vertex code memory category.

Code for vertex functions (codelets).

Type

pva.CategoryMemory

property vertexFieldData

Vertex field data memory category.

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

Type

pva.CategoryMemory

property vertexInstanceState

Vertex instance state memory category.

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

Type

pva.CategoryMemory

class pva.MemoryWithAndWithoutGaps

MemoryWithAndWithoutGaps represents the amount of memory with and without gaps between allocations.

The memory usage in each region is provided, both with and without gaps. Gaps arise because of memory allocation constraints, such as alignment requirements. For more information on the tile memory architecture, refer to the IPU Programmer’s Guide. Memory with and without gaps between allocations.

property excludingGaps

Memory excluding gaps between allocations.

Type

int

property includingGaps

Memory including gaps between allocations.

Type

int

class pva.NotAlwaysLiveMemory
property bytes
property variables

List of not always live variables for this step.

Type

List[pva.Variable]

class pva.Memory

Memory represents the memory layout of a tile in various 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.

property alwaysLiveBytes

The total always live memory for this tile.

Variables that exist for the entire execution are always live.

Type

int

property category

Details memory by category.

Type

pva.CategoryMemory

property interleaved

Details of memory with the interleaved region for this tile.

Type

pva.MemoryWithAndWithoutGaps

property nonInterleaved

Details of memory with the non interleaved region for this tile.

Type

pva.MemoryWithAndWithoutGaps

property notAlwaysLiveBytes

The total not always live memory for this tile.

Variables that are created and/or deleted during execution are not. always live.

Type

int

property overflowed

Details of memory with the overflowed region for this tile.

Type

pva.MemoryWithAndWithoutGaps

property total

Details of the total memory usage for this tile.

Type

pva.MemoryWithAndWithoutGaps

property vertices

List of vertex memory usage on this tile.

Type

List[VertexMemory]

class pva.Tile

Tile represents details of a single tile on an IPU.

property clockFrequency

The tile clock frequency in Hertz.

Type

float

property memory

Details of memory usage by this tile.

Type

pva.Memory

property relativeSyncDelay

The sync delay for each tile (relative to the minimum value).

Type

int

property tileId

The id of this tile.

Type

int

class pva.IPU

IPU represents details of a single IPU.

class Architecture

Enum of the different IPU architectures

Members:

Ipu1 : IPU Mk1

Ipu2 : IPU Mk2

Unknown : Unknown

property name
property architecture

The architecture type of this IPU.

Type

pva.IPU.Architecture

property tiles

List of tiles on this IPU.

Type

List[Tile]

class pva.IPU.Architecture

Enum of the different IPU architectures

Members:

Ipu1 : IPU Mk1

Ipu2 : IPU Mk2

Unknown : Unknown

Ipu1 = <Architecture.Ipu1: 0>
Ipu2 = <Architecture.Ipu2: 1>
Unknown = <Architecture.Unknown: 4>
property name
property value
class pva.Replica

Replica represents details of a single replica.

property ipus

List of tiles on this replica.

Type

List[pva.IPU]

class pva.ComputeSet

ComputeSet represents details of a single compute set.

property debugContexts

List of Debug Contexts. May be empty.

Type

List[pva.DebugContext]

property estimatedCyclesByTile

Estimated cycles by tile for this compute set.

Type

List[int]

property name

The name of the compute set.

Type

str

property varIds

The lowered variable ids used by the vertices of this compute set.

Type

List[int]

property vars

The lowered variables used by the vertices of this compute set.

Type

List[pva.LoweredVariable]

property vertices

The vertices used by this compute set.

Type

List[pva.VertexInstances]

class pva.Program

Program is a base class that represents a program type.

Block = <Type.Block: 22>
Call = <Type.Call: 19>
CodeCopy = <Type.CodeCopy: 21>
DoExchange = <Type.DoExchange: 8>
GS1 = <SyncType.GS1: 1>
GS2 = <SyncType.GS2: 2>
GS3 = <SyncType.GS3: 3>
GS4 = <SyncType.GS4: 4>
GetGlobalConsensus = <Type.GetGlobalConsensus: 17>
GlobalExchange = <Type.GlobalExchange: 9>
IfElse = <Type.IfElse: 7>
Internal = <SyncType.Internal: 0>
OnEveryTileSwitch = <Type.OnEveryTileSwitch: 6>
OnTileExecute = <Type.OnTileExecute: 2>
OnTileSwitch = <Type.OnTileSwitch: 5>
Repeat = <Type.Repeat: 3>
RepeatWhile = <Type.RepeatWhile: 4>
Sans = <Type.Sans: 18>
Sequence = <Type.Sequence: 1>
SetLocalConsensus = <Type.SetLocalConsensus: 15>
SetLocalConsensusFromVar = <Type.SetLocalConsensusFromVar: 16>
StreamCopyBegin = <Type.StreamCopyBegin: 10>
StreamCopyEnd = <Type.StreamCopyEnd: 12>
StreamCopyMid = <Type.StreamCopyMid: 11>
Sync = <Type.Sync: 14>
SyncAns = <Type.SyncAns: 20>
class SyncType

Members:

Internal

GS1

GS2

GS3

GS4

Unknown

GS1 = <SyncType.GS1: 1>
GS2 = <SyncType.GS2: 2>
GS3 = <SyncType.GS3: 3>
GS4 = <SyncType.GS4: 4>
Internal = <SyncType.Internal: 0>
Unknown = <SyncType.Unknown: 5>
property name
property value
class Type

Members:

Unknown

Sequence

OnTileExecute

Repeat

RepeatWhile

OnTileSwitch

OnEveryTileSwitch

IfElse

DoExchange

GlobalExchange

StreamCopyBegin

StreamCopyMid

StreamCopyEnd

WriteUndef

Sync

SetLocalConsensus

SetLocalConsensusFromVar

GetGlobalConsensus

Sans

Call

SyncAns

CodeCopy

Block

Block = <Type.Block: 22>
Call = <Type.Call: 19>
CodeCopy = <Type.CodeCopy: 21>
DoExchange = <Type.DoExchange: 8>
GetGlobalConsensus = <Type.GetGlobalConsensus: 17>
GlobalExchange = <Type.GlobalExchange: 9>
IfElse = <Type.IfElse: 7>
OnEveryTileSwitch = <Type.OnEveryTileSwitch: 6>
OnTileExecute = <Type.OnTileExecute: 2>
OnTileSwitch = <Type.OnTileSwitch: 5>
Repeat = <Type.Repeat: 3>
RepeatWhile = <Type.RepeatWhile: 4>
Sans = <Type.Sans: 18>
Sequence = <Type.Sequence: 1>
SetLocalConsensus = <Type.SetLocalConsensus: 15>
SetLocalConsensusFromVar = <Type.SetLocalConsensusFromVar: 16>
StreamCopyBegin = <Type.StreamCopyBegin: 10>
StreamCopyEnd = <Type.StreamCopyEnd: 12>
StreamCopyMid = <Type.StreamCopyMid: 11>
Sync = <Type.Sync: 14>
SyncAns = <Type.SyncAns: 20>
Unknown = <Type.Unknown: 0>
WriteUndef = <Type.WriteUndef: 13>
property name
property value
Unknown = <SyncType.Unknown: 5>
WriteUndef = <Type.WriteUndef: 13>
accept(self: pva.pva_core.Program, arg0: pva::ProgramVisitor) None

The visitor pattern accept method.

property children

List of child programs. May be empty.

Type

List[pva.Program]

property controlCodeByTile

The size in bytes of the control code of this program and its children (if any) for each tile.

Type

List[int]

property debugContexts

List of Debug Contexts. May be empty.

Type

List[pva.DebugContext]

property name

The name of the program. May be empty.

Type

str

property type

The type of the program.

Type

pva.Program.Type

property vars

The lowered variables used by this program.

Type

List[pva.LoweredVariable]

class pva.OnTileExecuteProgram
property computeset

The compute set used by this on-tile execute program.

Type

pva.Computeset

class pva.UnknownProgram
class pva.SequenceProgram
class pva.RepeatProgram
property repeatCount

How many times this Repeat program repeats. May be None if this program repeats indefinitely or the report does not contain repeat counts.

Type

int

class pva.RepeatWhileProgram
class pva.OnTileSwitchProgram
class pva.OnEveryTileSwitchProgram
class pva.IfElseProgram
class pva.DoExchangeProgram
property bytesReceivedByTile

The number of bytes received on each tile.

Type

List[int]

property bytesSentByTile

The number of bytes sent on each tile.

Type

List[int]

property codeBytesByTile

The size of the code required for this program on each tile.

Type

List[int]

property estimatedCyclesByTile

The estimated number of cycles used to execute this program.

Type

List[int]

property vars

The lowered variables used by this exchange.

Type

List[pva.LoweredVariable]

class pva.GlobalExchangeProgram
property bytesReceivedByTile

The number of bytes received on each tile.

Type

List[int]

property bytesSentByTile

The number of bytes sent on each tile.

Type

List[int]

property estimatedCyclesByTile

The estimated number of cycles used to execute this program.

Type

List[int]

property exchangeCyclesByTile

The number of exchange cycles for this program.

Type

List[int]

property syncCyclesByTile

The number of sync cycles for this program.

Type

List[int]

property syncType

The type of synchronisation used by this program.

Type

pva.Program.SyncType

property vars

The lowered variables used by this exchange.

Type

List[pva.LoweredVariable]

class pva.StreamCopyBeginProgram
class pva.StreamCopyMidProgram
Host = <StreamCopyType.Host: 0>
Mixed = <StreamCopyType.Mixed: 2>
RemoteBuffer = <StreamCopyType.RemoteBuffer: 1>
class StreamCopyType

Indicates whether the stream copy is to/from the host or a remote buffer.

Members:

Host

RemoteBuffer

Mixed

Unknown

Host = <StreamCopyType.Host: 0>
Mixed = <StreamCopyType.Mixed: 2>
RemoteBuffer = <StreamCopyType.RemoteBuffer: 1>
Unknown = <StreamCopyType.Unknown: 3>
property name
property value
Unknown = <StreamCopyType.Unknown: 3>
property bytesReceivedByTile

The number of bytes received on each tile.

Type

List[int]

property bytesSentByTile

The number of bytes sent on each tile.

Type

List[int]

property estimatedCyclesByTile

The estimated number of cycles used to execute this program.

Type

List[int]

property streamCopyType

Indicates whether this stream copy is to/from the host or a remote buffer.

Type

pva.StreamCopyMidProgram.StreamCopyType

property vars

The lowered variables used by this exchange.

Type

List[pva.LoweredVariable]

class pva.StreamCopyEndProgram
class pva.WriteUndefProgram
class pva.SyncProgram
property syncType

The type of synchronisation used by this program.

Type

pva.Program.SyncType

class pva.SetLocalConsensusProgram
class pva.SetLocalConsensusFromVarProgram
property children

List of child programs.

Type

List[pva.Program]

class pva.GetGlobalConsensusProgram
class pva.SansProgram
class pva.CallProgram
property target

The program that this call program invokes.

Type

pva.Program

class pva.SyncAnsProgram
class pva.ProgramVisitor
visitCall(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.CallProgram) None
visitCodeCopy(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.CodeCopyProgram) None
visitDoExchange(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.DoExchangeProgram) None
visitGetGlobalConsensus(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.GetGlobalConsensusProgram) None
visitGlobalExchange(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.GlobalExchangeProgram) None
visitIfElse(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.IfElseProgram) None
visitOnEveryTileSwitch(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.OnEveryTileSwitchProgram) None
visitOnTileExecute(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.OnTileExecuteProgram) None
visitOnTileSwitch(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.OnTileSwitchProgram) None
visitProgram(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.Program) None
visitRepeat(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.RepeatProgram) None
visitRepeatWhile(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.RepeatWhileProgram) None
visitSans(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.SansProgram) None
visitSequence(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.SequenceProgram) None
visitSetLocalConsensus(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.SetLocalConsensusProgram) None
visitSetLocalConsensusFromVar(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.SetLocalConsensusFromVarProgram) None
visitStreamCopyBegin(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.StreamCopyBeginProgram) None
visitStreamCopyEnd(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.StreamCopyEndProgram) None
visitStreamCopyMid(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.StreamCopyMidProgram) None
visitSync(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.SyncProgram) None
visitSyncAns(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.SyncAnsProgram) None
visitUnknown(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.UnknownProgram) None
visitWriteUndef(self: pva.pva_core.ProgramVisitor, arg0: pva.pva_core.WriteUndefProgram) None
class pva.VariableSize

VariableSize represents details of a variable with size information.

property size

The size of the variable in bytes.

Type

int

class pva.VariableCategory

This class describes the category of the data stored in a variable (for example Message, Constant, Stack).

property description

The description of this category.

Type

string

property id

The id of this category.

Type

int

property name

The name of this category.

Type

string

class pva.Variable

Variable represents details of a variable.

property debugContexts

List of debug contexts of the variable. May be empty.

Type

List[pva.DebugContext]

property name

The name of the variable.

Type

str

class pva.LivenessProgramStep

LivenessProgramStep represents details liveness for step in the program.

notAlwaysLiveBytesForVariable(self: pva.pva_core.LivenessProgramStep, arg0: pva.pva_core.Variable) int
property notAlwaysLiveMemory
notAlwaysLiveMemoryForIpu(self: pva.pva_core.LivenessProgramStep, arg0: int) pva.pva_core.NotAlwaysLiveMemory
notAlwaysLiveMemoryForTile(self: pva.pva_core.LivenessProgramStep, arg0: int) pva.pva_core.NotAlwaysLiveMemory
property program
class pva.LoweredVariable

Contains information about a lowered variable.

property accessedInVertex

If true, this variable is accessed in a vertex.

Type

bool

property alignment

The alignment in bytes. Normally at least 4 bytes.

Type

int

property allocated

True if this variable has been allocated to a tile. If not, the rest of the struct should be ignored..

Type

bool

property alwaysLive

If true, this variable can never overlap with others. Other variables may end up always live as a result of their usage, but those flagged as such we know should be always live and will be discounted for liveness analysis and reporting.

Type

bool

property bytes

The size in bytes of the variable.

Type

int

property category

Category for the data stored in the variable.

Type

VariableCategory

property constant

True if this variable stores constant data that is never written to.

Type

bool

property elementConstraints

The variables that cannot be stored in the same memory element as this variable.

Type

List[pva.LoweredVariable]

property equivalenceClass

The equivalence class of this variable. Variables with the same equivalence class have the same liveness profile.

Type

pva.EquivalenceClass

property executable

If true, this variable needs to be allocated in an executable region of memory.

Type

bool

property hasUnloweredVar

True if this variable comes from an unlowered variable.

Type

bool

property inInterleavedMem

If true, this variable must be stored in interleaved memory.

Type

bool

property lowest256KBytes

If true, this variable contains vertex state that should be in the first 256KB of memory so that it can be addressed via the run instruction.

Type

bool

property name

The name of this lowered variable.

Type

string

property offset

The offset of the variable within the .graph section.

Type

int

property regionConstraints

The variables that cannot be stored in the same memory region as this variable.

Type

List[pva.LoweredVariable]

property startSection

If true, this variable contains an entrypoint that may need special allocation.

Type

bool

property tileId

The tile this variables is on.

Type

int

property unloweredVar

The unlowered variable that originated this variable. Note an exception is thrown if hasUnloweredVar is false.

Type

Variable

property vertexCode

If true, this variable is allocated up-front and excludes other variables from the elements this variable is allocated in.

Type

bool

class pva.LoweredVariableBrief

Contains brief information about a lowered variable.

property bytes

The size in bytes of the variable.

Type

int

property equivalenceClass

The liveness equivalence class of the variable.

Type

pva.EquivalenceClass

property id

The id of this variable.

Type

int

property tileId

The tile this variables is on.

Type

int

class pva.LoweredVariables

This class allows access to lowered variables by tile and by unlowered variable.

property allBriefVars

Brief information for each lowered variable.

Type

List[pva.LoweredVariableBrief]

forTile(self: pva.pva_core.LoweredVariables, arg0: int) pva::List<pva::LoweredVariable>

List[pva.LoweredVariable]: A list of lowered variables for a given tile.

forVar(self: pva.pva_core.LoweredVariables, arg0: pva.pva_core.Variable) pva::List<pva::LoweredVariable>
List[pva.LoweredVariable]: A list of lowered variables for a given

unlowered variable.

class pva.EquivalenceClass

This class describes the liveness profile of a group of lowered variables.

property id

The id of this equivalence class.

Type

int

property interferenceClasses

The equivalence classes that interfere with this equivalence class.

Type

List[pva.EquivalenceClass]

property steps

The list of step intervals where this class is live.

Type

List[pva.Interval]

class pva.CompilationReport

Information from the compilation of your model.

property allocationOrderByTile

For each tile, a list of variable ids in the same order they were allocated in memory.

Type

List[List[int]]

property alwaysLiveVariables

List of always live variables.

Type

List[pva.Variable]

alwaysLiveVariablesForTile(self: pva.pva_core.CompilationReport, arg0: int) pva.pva_core.VariableSizes

List[pva.Variable]: List of always live variables for a given tile.

property compilationParameters

A list of all compilation parameters used in poplar

Type

List[pva.EngineOption]

property computeSets

A list of all compute sets for all steps.

Type

List[pva.ComputeSet]

property controlPrograms

List of all control programs.

Type

List[pva.Program]

debugContext(self: pva.pva_core.CompilationReport, arg0: int) pva.pva_core.DebugContext

pva.DebugContext: Get DebugContext by ID.

debugContexts(self: pva.pva_core.CompilationReport, arg0: pva.pva_core.DebugContextFilter) pva.pva_core.DebugContexts
List[pva.DebugContext]: List of debug contexts

filtered by pva.DebugContextFilter.

property functions

List of all functions.

Type

List[pva.Program]

property graph

Basic information about the graph.

Type

pva.Graph

property ipus

List of IPUs.

Type

List[pva.IPU]

property livenessProgramSteps

List of program steps with liveness information.

Type

List[pva.LivenessProgramStep]

property loweredVariables

An accessor object that contains the lowered variables.

Type

pva.LoweredVariables

property programs

List of all programs.

Type

List[pva.Program]

property replicas

List of Replicas.

Type

List[pva.Replica]

property target

Information about the target hardware.

Type

pva.Target

property targetParameters

A list of all target parameters used in poplar

Type

List[pva.EngineOption]

property tiles

List of tiles.

Type

List[pva.Tile]

property tilesWithLivenessInfo

List of tiles with liveness info.

Type

List[Tile]

property timestamp

A date and time timestamp when the application was compiled

Type

str

property variables

List of unlowered variables.

Type

List[Variable]

class pva.EngineOption

A Poplar option which controls the behaviour of a graph at compile-time.

property isDefault

True if this option is a default, False if it is overridden

Type

bool

property name

The name of this option

Type

str

property value

The value of this option in string form

Type

str

class pva.Variable

Variable represents details of a variable.

property debugContexts

List of debug contexts of the variable. May be empty.

Type

List[pva.DebugContext]

property name

The name of the variable.

Type

str

class pva.DebugContext

DebugContext describes the context of an operation (e.g. variable and program creation)

property children

List of child debug contexts.

Type

List[pva.DebugContext]

property id

Unique identifier for DebugContext.

Type

int

property json

Other context data in JSON format.

Type

str

property layer

The layer of this context (e.g. poplibs).

Type

str

property location

The location in code where the debug context was created.

Type

DebugContextLocation

property name

The name of a DebugContext.

Type

str

property parents

The immediate parent debug contexts.

Type

List[pva.DebugContext]

programs(self: pva.pva_core.DebugContext, inlineCalls: bool = True) pva::List<std::shared_ptr<pva::Program> >

List[pva.Programs]: List of programs that correspond to this debug context or any of its descendants.

property variables

The variables that correspond to this debug context or any of its descendants.

Type

List[pva.Variable]

class pva.DebugContextFilter

This class describes a filter to be used when fetching debug contexts.

property layer

Filter DebugContext of this layer.

Type

str

property withoutParent

If True, filter DebugContext without a parent.

Type

bool

class pva.TileCycleTotals

This class contains the total cycles for various activities, such as exchange and compute.

property activeCompute

Active compute cycles.

Type

int

property compute

Cycles when at least one thread is still executing.

Type

int

property interIpuExchange

Cycles during inter-IPU exchange.

Type

int

property internalExchange

Cycles during internal exchange.

Type

int

property streamCopy

Cycles during the main part of stream copy.

Type

int

property streamCopyBegin

Cycles during the beginning part of stream copy.

Type

int

property streamCopyEnd

Cycles during the end part of stream copy.

Type

int

property sync

Cycles during sync.

Type

int

property total

Total cycles.

Type

int

class pva.Interval
property end

The end of the interval.

Type

int

property start

The start of the interval.

Type

int

3.2. Execution reports

class pva.Run

Run contains information about each Poplar engine run.

property cyclesByIpu

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

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

Type

VectorList[pva.Period[int]]

property executionParameters

The execution parameters used for this run.

Type

List[pva.EngineOption]

property microseconds

The start and end of this run in microseconds.

Type

pva.Period[int]

property name

Name given to this run.

Type

str

property steps

A list of program steps in this run.

Type

List[ExecutionStep]

class pva.ExecutionStepIpu
property activeCycles

Statistics for the cycles on active tiles.

Note : Will return zeros if this IPU has not been profiled.

Type

pva.CyclesInfo

property activeTileBalance

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.

NoteOnly valid for OnTileExecute, GlobalExchange, StreamCopy,

DoExchange.

Note : Will return 0 if this IPU has not been profiled.

Type

float

property activeTiles

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

Note : Will return 0 if this IPU has not been profiled.

Type

int

property allCycles

Statistics for the cycles on all tiles.

Note : Will return zeros if this IPU has not been profiled.

Type

pva.CyclesInfo

property cycles

Total cycles executed on this IPU. Note : will return 0 if this IPU has not been profiled.

Type

int

property dataBalance

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 been profiled.

Type

float

property dataIn

Total data received by this IPU.

With the Poplar Engine option ‘replicaToProfile’, only a subset of the IPU may have execution profile information.

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

Type

int

property dataOut

Total data sent by this IPU.

With the Poplar Engine option ‘replicaToProfile’, only a subset of the IPU may have execution profile information.

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

Type

int

property id

ID of this IPU.

Type

int

property profiled

Indication if this IPU was profiled.

With the Poplar Engine option ‘replicaToProfile’, only a subset of the IPUs may have execution profile information.

Type

bool

property threadBalance

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 been profiled.

Type

float

property tileBalance

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.

NoteOnly valid for OnTileExecute, GlobalExchange, StreamCopy,

DoExchange.

Note : Will return 0 if this IPU has not been profiled.

Type

float

class pva.ExecutionStep

ExecutionStep contains information about a step of execution. Each step will represent the execution of Poplar program.

property computeSets

A list of all compute sets for this step.

Type

List[pva.execution.ComputeSet]

property cyclesByTile

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

Type

List[int]

property ipus

Details of a program step execution per IPU.

Type

List[pva.ExecutionStepIpu]

property program

The program being executed.

Type

pva.Program

class pva.ExecutionStepCycleRange

Details of the min and max cycles.

property average

mean cycles.

Type

int

property max

maximum cycles.

Type

int

property min

minimum cycles.

Type

int

class pva.ExecutionReport

ExecutionReport contains information collected from the execution of a model.

blocks(self: pva.pva_core.ExecutionReport, arg0: int) pva.pva_core.Blocks

List[pva.Block]: A list of all block measurements. May be empty.

property runs

A list of Poplar engine runs.

Type

List[pva.Run]

property steps

A list of all program steps for the entire execution.

Type

List[pva.ExecutionStep]

property totalCycles

Total cycles executed on all IPUs. For IPUs and replicas.

Type

pva.TileCycleTotals

class pva.Period

A period of time measured in microseconds, cycles, or other units.

property end

The end of this period.

Type

int

property start

The start of this period.

Type

int

class pva.Block

This class represents the cycle measurements around a given program subtree performed by lightweight profiling.

property cyclesFrom

Absolute cycles at the beginning of this block’s execution.

Type

int

property cyclesTo

Absolute cycles at the end of this block’s execution.

Type

int

property debugContext

DebugContext for this block. An exception is thrown if CompilationReport::isDebugInfoPresent is false or if isOverflow() or isAnonymous() or isUnknown() is true.

Type

pva.DebugContext

property isAnonymous

True if this block has no DebugContext because it began while the buffer was full.

Type

bool

property isBlockFlush

True if this block is a StreamCopy introduced to flush the buffer

Type

bool

property isCommon

True if this block is a common block

Type

bool

property isOverflow

True if this block represents a period of time when the instrumentation buffer was full.

Type

bool

property isStreamCopy

True if this block is a StreamCopy and isBlockFlush is false

Type

bool

property isUnknown

True if this block has an unknown meaning.

Type

bool

property program

The program of this block. An exception is thrown if isOverflow() or isAnonymous() or isUnknown() is true.

Type

pva.Program

property tile

The tile that performed these measurements.

Type

int

3.3. Trace reports

class pva.TraceReport

TraceReport contains information collected from the execution of a model on the CPU.

process(self: pva.pva_core.TraceReport, arg0: int) pva.pva_core.Process

pva.Process: Retrieve a process based on its process ID.

property processes

A list of all processes traced on the CPU.

Type

List[pva.Process]

class pva.Process

Information about a process, such as its threads.

property pid

The process ID.

Type

int

thread(self: pva.pva_core.Process, arg0: int) pva.pva_core.Thread

pva.Thread: Retrieve a thread based on its thread ID.

property threads

A list of all threads belonging to a process.

Type

List[pva.Thread]

class pva.Thread

Information about a thread, such as its events.

property events

A list of the root-level events on this thread.

Type

List[pva.Event]

property pid

The ID of the thread owner process.

Type

int

property tid

The thread ID.

Type

int

class pva.Event

Information about an event, such as its channel, label, and children.

property channel

The event’s channel.

Type

str

children(self: pva.pva_core.Event) List[pva.pva_core.Event]

List[pva.Event]: A list of all events that occurred within this one.

property duration

The duration of the event in microseconds.

Type

int

property label

The event’s label.

Type

str

property pid

The ID of the process the event occurred within.

Type

int

property tid

The ID of the thread the event occurred on.

Type

int

property timestamp

The time at which the event occurred in microseconds. Timestamps are not always relative to the same epoch between different trace files.

Type

int