PopLibs API reference

The PopLibs libraries provide application-level functions that can be used in Poplar programs for the IPU.

Library	Depends on	Description
poplin	popops, poputil	Linear algebra functions (matrix multiplications, convolutions)
popnn	poplin, poputil	Functions used in neural networks (for example, non-linearities, pooling and loss functions)
popops	poputil	Operations on tensors in control programs (elementwise functions and reductions)
poprand	poputil	Functions for populating tensors with random numbers
popsparse		Functions for operating on sparse tensors
poputil		General utility functions for building graphs

Utility functions (poputil)

General utility functions for building graphs.

poputil/Broadcast.hpp

Functions to provide numpy-like tensor matching and broadcasting.

namespace poputil

General utility functions for building graphs.

Functions

void expandToMatchRanks(poplar::Tensor &a, poplar::Tensor &b)

Match dimensions of two tensors using numpy-style expansion rules.

Insert singleton dimensions into either of the two tensors so that their ranks match, following numpy-style expansion rules. The tensor with the lower rank has singleton dimensions inserted as the outermost dimensions.

Parameters

• a: First tensor to match.

• b: Second tensor to match.

void broadcastToMatch(poplar::Tensor &a, const std::vector<std::size_t> &shape)

Match dimensions of a tensor to a shape using numpy-style broadcast rules:

1) If the rank of the tensor is less than the required shape then expand to the left by adding dimensions of size 1 to match the rank required.

2) For each dimension, the size of the dimension in the tensor must be the same as the required shape or must be 1. In the case where it is of size 1, the tensor is broadcast in that dimension to match the shape. If neither of these conditions hold then an exception is thrown.

Parameters

• a: The tensor to broadcast to match the shape. This will be updated in place with broadcast dimensions.

• shape: The shape to match.

Exceptions

• poputil::poplibs_error: If a cannot be broadcast to match shape.

void broadcastToMatch(poplar::Tensor &a, poplar::Tensor &b)

Match dimensions of two tensors using numpy-style broadcast rules:

1) If the rank of one tensor is less than the other then extend the dimensions to the left with dimensions of size 1 to match the rank required.

2) For each dimension, the size of each dimension in both tensors must be the same or one of them must have size 1. In the case where one is of size 1, the tensor is broadcast in that dimension to match the other. If neither of these conditions hold then an exception is thrown.

Parameters

• a: First tensor to match. This will be updated in place with broadcast dimensions.

• b: Second tensor to match. This will be updated in place with broadcast dimensions.

Exceptions

• poputil::poplibs_error: If a cannot be broadcast to match a dimension.

void broadcastToMatch(poplar::Tensor &a, poplar::Tensor &b, poplar::Tensor &c)

Match dimensions of three tensors using numpy-style broadcast rules:

1) If the rank of one tensor is less than the other then extend the dimensions to the left with dimensions of size 1 to match the rank required.

2) For each dimension, the size of each dimension in both tensors must be the same or one of them must have size 1. In the case where one is of size 1, the tensor is broadcast in that dimension to match the other. If neither of these conditions hold then an exception is thrown.

Parameters

• a: First tensor to match. This will be updated in place with broadcast dimensions.

• b: Second tensor to match. This will be updated in place with broadcast dimensions.

• c: Third tensor to match. This will be updated in place with broadcast dimensions.

Exceptions

• poputil::poplibs_error: If a cannot be broadcast to match a dimension.

bool canBroadcastToMatch(const poplar::Tensor &a, const poplar::Tensor &b)

Test if the given tensors can be broadcast to match one another using the rules for broadcastToMatch().

Return

True if the two tensors may be broadcast to match one another and false if they cannot be matched with the broadcastToMatch() rules.

Parameters

• a: First tensor to match.

• b: Second tensor to match.