PopART Python API Reference

Introduction

The Poplar Advanced Run Time (PopART) is part of the Poplar SDK for implementing and running algorithms on networks of Graphcore IPU processors.

This document describes the PopART Python API. Many classes are wrappers around the equivalent C++ class, for example popart.builder.Builder wraps the C++ Builder class (renamed BuilderCore in Python). There are more detailed descriptions of some functions in the PopART C++ API.

For more information about PopART, please refer to the PopART User Guide.

PopART Python API

Sessions

class popart.session.InferenceSession(fnModel: bytes, dataFeed: Dict[int, Dict], deviceInfo: popart_core.DeviceInfo, losses: List[popart_core.Loss] = [], inputShapeInfo: popart_core.InputShapeInfo = <popart_core.InputShapeInfo object>, passes: popart_core.Patterns = None, userOptions: popart_core.SessionOptions = <popart_core.SessionOptions object>)

Bases: popart_core._InferenceSessionCore

Create a runtime class for executing an ONNX graph on a set of IPU hardware for inference.

A wrapper around the Session C++ class, renamed SessionCore in pybind, to enable more Pythonic use. See session.hpp for parameter descriptions.

Parameters
  • fnModel – ONNX model proto. Usually a loaded ONNX model, or from builder.getModelProto().

  • dataFeed – Configuration for the data feeds and fetches.

  • deviceInfoDeviceInfo object specifying device type. (one of IPU, IPUModel or CPU) and count.

  • losses – A list of loss layers to use when training. Default: [].

  • inputShapeInfo – Information about the shapes of input and output tensors. Default: popart.InputShapeInfo().

  • passes – Patterns to be run for optimization etc. Note: default for passes must not be popart.Patterns(). When import popart is run, the default arguments are created. If the user then loads a custom pattern using ctypes.cdll.LoadLibrary(custom_pattern_lib.so) then the already constructed popart.Patterns will not include the custom pattern. Default None.

  • userOptions – Session options to apply. Default: popart.SessionOptions().

Raises

popart.PrepareDeviceException – Thrown if an invalid device is provided.

initAnchorArrays() → Dict[str, numpy.array]

Create the anchor arrays to feed data back into Python with.

Returns

Dict of anchor names and their relevant np arrays.

prepareDevice() → None

Prepare the network for execution.

This will create the poplar::Graph and poplar::Engine, and set up poplar::Streams.

Raises

popart.PrepareDeviceException – Thrown if an invalid device is provided.

exception popart.session.PrepareDeviceException(e: popart_core.popart_exception)

Bases: popart_core.popart_exception

Custom expection thrown by the devicePrepare call.

getGraphReport()str

Get the graph report

Returns

The graph report string.

getSummaryReport()str

Get the summary report

Returns

The summary report string.

class popart.session.TrainingSession(fnModel: bytes, dataFeed: Dict[int, Dict], losses: List[popart_core.Loss], optimizer: popart_core.Optimizer, deviceInfo: popart_core.DeviceInfo, inputShapeInfo: popart_core.InputShapeInfo = <popart_core.InputShapeInfo object>, passes: popart_core.Patterns = None, userOptions: popart_core.SessionOptions = <popart_core.SessionOptions object>)

Bases: popart_core._TrainingSessionCore

Create a runtime class for executing an ONNX graph on a set of IPU hardware for training

A wrapper around the Session C++ class, renamed SessionCore in pybind, to enable more Pythonic use. See session.hpp for parameter descriptions.

Parameters
  • fnModel – ONNX model proto. Usually a loaded ONNX model, or from builder.getModelProto().

  • dataFeed – Configuration for the data feeds and fetches.

  • losses – A list of loss layers to use when training.

  • optimizer – The type of optimizer to use when training and it’s properties.

  • deviceInfo – DeviceInfo object specifying device type (IPU, IPUModel, CPU) and count.

  • inputShapeInfo – Information about the shapes of input and output tensors. Default: popart.InputShapeInfo().

  • passes – Optimization patterns to apply. Default: None.

  • userOptions – Session options to apply. Default: popart.SessionOptions().

Raises

popart.PrepareDeviceException – Thrown if an invalid device is provided.

initAnchorArrays() → Dict[str, numpy.array]

Create the anchor arrays to feed data back into Python with.

Returns

Dict of anchor names and their relevant np arrays.

prepareDevice() → None

Prepare the network for execution.

This will create the poplar::Graph and poplar::Engine, and set up poplar::Streams.

Raises

popart.PrepareDeviceException – Thrown if an invalid device is provided.

Builder

class popart.builder.AiGraphcore(builder: popart.builder.Builder, version: int)

Bases: popart.builder.Opset

Return the builder interface for the given ai.graphcore version.

Raises

ValueError – Thrown if an invalid ai.graphcore opset version provided.

call(args: List[int], num_outputs: int, callee: popart.builder.Builder, debugName: str = '') → List[str]

Add a call operation to the model

This is a poplar extension, to expose manual code re-use to the builder

Parameters
  • args – List of tensor ids to feed as arguments.

  • num_outputs – Number of output tensors from the called graph.

  • calleeSubgraphBuilder for the graph to be called.

Keyword Arguments

debugName – A string to prepend to the name of the tensor. Default: “”.

Returns

Output tensor ids.

class popart.builder.AiGraphcoreOpset1(builder: popart.builder.Builder, version: int)

Bases: popart.builder.AiGraphcore

Sub-class for backwards compatibility. Will forward all calls to AiGraphcore class.

class popart.builder.AiOnnx(builder: popart.builder.Builder, version: int)

Bases: popart.builder.Opset

Return the builder interface for the given ai.onnx version.

Parameters
  • builder – Parent class for access.

  • version – ai.Onnx opset version to use; 6 < version < 11. Default: 10.

Raises

ValueError – Thrown if an invalid ai.Onnx opset version provided.

logical_if(args: List[str], num_outputs: int, else_branch: popart.builder.Builder, then_branch: popart.builder.Builder, name: str = '') → List[str]

If conditional operation.

Parameters
  • args – List of tensor ids to feed as arguments.

  • num_outputs – Number of output tensors from the if operator.

  • else_branchSubgraphBuilder for the graph to run if condition is false. Has num_outputs outputs: values you wish to live-out to the subgraph created by the if operation, other tensors will not be accessible to the wider graph. The number of outputs must match the number of outputs in the then_branch.

  • then_branchSubgraphBuilder for the graph to run if condition is true. Has num_outputs outputs: values you wish to be live-out to the enclosing scope. The number of outputs must match the number of outputs in the else_branch.

Keyword Arguments

name – A string to prepend to the name of the tensor. Default: “”.

Returns

Output tensor ids.

loop(args: List[str], num_outputs: int, body: popart.builder.Builder, debugPrefix: str = '') → List[str]

Generic Looping construct op.

Parameters
  • args – List of tensor ids to feed as arguments.

  • num_outputs – Number of output tensors from the loop operator.

  • body – SubgraphBuilder for the graph to run in the loop.

Keyword Arguments

debugPrefix – A string to prepend to the name of the tensor. Default: “”.

Returns

Output tensor ids.

class popart.builder.AiOnnxMl(builder: popart.builder.Builder, version: int)

Bases: popart.builder.Opset

Return the builder interface for the given ai.onnx.ml version.

Raises

ValueError – Thrown if an invalid ai.onnx.ml opset version provided.

class popart.builder.Builder(modelProtoOrFilename: Union[str, bytes] = None, opsets: Dict[str, int] = None, builderCore: popart_core._BuilderCore = None)

Bases: object

A wrapper around the Builder C++ class, renamed BuilderCore in pybind, to enable more Pythonic use. See builder.hpp for the class definition.

Parameters
  • modelProtoOrFilename – Model protobuf string or file path of saved ONNX model proto. Default: None.

  • opsets – Dict of opset versions. Default: None.

  • builderCore_BuilderCore object if you want to create a subgraph builder using an existing buildercore object. Default: None.

createSubgraphBuilder()popart.builder.Builder

Create a child builder to add ops to a subgraph using a call operation.

Returns

The child builder.

reshape_const(aiOnnx: popart.builder.Opset, args: List[str], shape: Iterable[int], debugPrefix: str = '') → List[int]

Const version of the reshape op.

Parameters
  • aiOnnx – Versioned aiOnnx opset, for example: aiOnnxOpset11.

  • args – List of tensor ids to feed as arguments.

  • shape – Shape to reshape to, for example [3, 2, 4].

Keyword Arguments

debugPrefix – String to use as a debug prefix. Default: “”.

Returns

Output tensor ids.

class popart.builder.Opset(builder: popart.builder.Builder, version: int)

Bases: object

Minimal base class for the opsets

Parameters
  • builder – An interface for a Builder, used for creating ONNX graphs.

  • version – Opset version to use for the given opset sub-class.

Tensor information

class popart.tensorinfo.TensorInfo(*args: Union[Iterable, numpy.array])

Bases: popart_core._TensorInfoCore

Python wrapper to TensorInfo to handle numpy types in constructor.

For example:

TensorInfo(dtype, shape) TensorInfo(numpy.ndarray)

Raises

TypeError – Raised if incorrect type is used to create a tensorinfo.

Writer

Framework independent functionality for driving PopART

class popart.writer.NetWriter(inNames, outNames, losses, optimizer, dataFeed, inputShapeInfo)

Bases: object

Base class, to be inherited once per framework

Parameters
  • inNames – A list (in order) of all the inputs to the ONNX Model.

  • outNames – names of the outputs of the ONNX Model.

  • losses – A list of PopART Loss objects

  • optimizer – An optimizer (ConstSGD, SGD, etc) or None if in evaluation mode.

  • anchors – Only relevant if in training mode: the names of tensors which must be computed and returned. If not in training mode, then outputs of forward are the (only) tensors to return.

  • dataFeed – Configuration for the data feeds and fetches.

  • inputShapeInfo – For every loss stream input and standard input: the shape, ONNX DataType and how to get data.

eval(inputsMap)

Perform batchesPerStep evaluation steps. This function only needs to be implemented by frameworks which will be used to verify PopART. See torchwriter.py for an example implementation.

infer(inputsMap)

Perform batchesPerStep inference steps. This function only needs to be implemented by frameworks which will be used to verify PopART. See torchwriter.py for an example implementation.

saveModel(filename)

To be implemented once per framework: framework specific details of generating the ONNX model and writing it to file

train(inputsMap)

Perform batchesPerStep training steps. This function only needs to be implemented by frameworks which will be used to verify PopART. See torchwriter.py for an example implementation.