Tensor

#include <poplar/Tensor.hpp>
namespace poplar

Poplar classes and functions.

Enums

enum class UpsampleMethod

Enum passed to Tensor::upsample(unsigned scale, unsigned dimension) specifying the upsampling method.

Values:

enumerator REPEAT

If dimension is of size s, for every i in [0, s), repeats the subtensor at index i scale times.

For example, with scale = 2 and dimension = 1: Shape(2,3) Shape(2x6) [[1, 2, 3], becomes [[1, 1, 2, 2, 3, 3], [4, 5, 6]] [4, 4, 5, 5, 6, 6]]

Note that a scale of 0 means repeat each tensor 0 times. So a (i, j, k, l) tensor upsampled with scale = 0 and dimension = 3 would become an (i, j, k, 0) tensor containing 0 elements.

scale = 1 is the identity operation.

Functions

bool operator==(const Tensor &a, const Tensor &b)
inline bool operator!=(const Tensor &a, const Tensor &b)
Tensor concat(ArrayRef<Tensor> ts, unsigned dimension = 0)

Concatenate several tensors.

The tensors are concatenated along the specified dimension.

Parameters

  • ts – The tensors to concatenate

  • dimension – The number of the dimension to concatenate across

Returns

The result of the concatenation

inline Tensor concat(const Tensor &first, const Tensor &second, unsigned dimension = 0)

Concatenate two tensors.

The tensors are concatenated along the specified dimension.

Parameters

  • first – The first tensor to concatenate

  • second – The second tensor to concatenate

  • dimension – The number of the dimension to concatenate across

Returns

The result of the concatenation

Tensor append(const Tensor &first, const Tensor &second, unsigned dimension)

Append a tensor as an element to another tensor.

Parameters

  • first – The tensor to append to

  • second – The tensor to add as an element in the specified dimension

  • dimension – The number of the dimension to append to

Returns

The extended tensor

inline Tensor append(const Tensor &first, const Tensor &second)

Append a tensor to another in their first dimension.

Parameters

  • first – The tensor to append to

  • second – The tensor to add as an element in the first dimension

Returns

The extended tensor

std::ostream &operator<<(std::ostream &os, const Tensor &tensor)

Display the regions of the tensor on a stream.

Parameters

  • os – The ostream to output to

  • tensor – The tensor to display

Returns

The ostream written to

class Tensor
#include <Tensor.hpp>

A reference to a subset of tensor elements.

Public Functions

Tensor()
Tensor(const Tensor &other)
Tensor(Tensor &&other) noexcept
const Tensor &operator=(const Tensor &other) &
Tensor &operator=(Tensor &&other) & noexcept
~Tensor()
Type elementType() const

Get the element type information for this tensor.

Returns

The element type.

Tensor operator[](std::size_t i) const &

Get the sub-tensor indexed by i in the first dimension of the tensor.

Parameters

i – The index into the first dimension of the tensor.

Tensor &&operator[](std::size_t i) &&
Tensor slice(std::size_t begin, std::size_t end, unsigned dimension) const &

Get the sub-tensor given by a specific range [begin, end) in one dimension of the tensor.

Parameters

  • begin – The first element of the range

  • end – The upper bound to the range (the last element + 1)

  • dimension – The dimension to slice in

Tensor &&slice(std::size_t begin, std::size_t end, unsigned dimension) &&
inline Tensor slice(std::size_t begin, std::size_t end) const

Get the sub-tensor given by a specific range [begin, end) in the first dimension of the tensor.

Parameters

  • begin – The first element of the range

  • end – The upper bound to the range (the last element + 1)

inline Tensor slice(const Interval &region, unsigned dimension = 0) const

Get the sub-tensor given by a specific range [begin, end) in one dimension of the tensor.

Parameters

  • region – The region to slice

  • dimension – The dimension to slice in

Tensor slice(ArrayRef<std::size_t> begin, ArrayRef<std::size_t> end) const

Get the sub-tensor given by slicing the tensor in multiple dimensions, starting at dimension 0.

Each pair begin[i], end[i] specifies that the tensor is sliced in dimension i by the range [begin[i], end[i]). The rank of the returned tensor is the same as the input tensor.

Parameters

  • begin – The lower bounds of the ranges used to slice the tensor

  • end – The upper bounds of the ranges used to slice the tensor

std::vector<Tensor> slices(ArrayRef<Interval> intervals, unsigned dimension = 0) const

Get a vector of slices.

Parameters

  • intervals – A list of intervals.

  • dimension – The dimension to slice in

Returns

A vector of slices where each slice is obtained by slicing this tensor between the two points in the given interval list.

std::vector<Tensor> slices(const std::vector<std::vector<Interval>> &intervals, unsigned dimension = 0) const

Get a vector of slices.

Parameters

  • intervals – A list of sequences of intervals.

  • dimension – The dimension to slice in

Returns

A vector of tensors where each tensor is the concatenation of the sequence of several slices, each slice being this tensor between the two point in the corresponding interval in the sequences given as input.

std::vector<Tensor> slices(const poplar::ArrayRef<unsigned> &indices, unsigned dimension = 0) const

Get a vector of slices.

This is equivalent to repeatedly slicing with intervals of size one.

Parameters

  • indices – A list of indices.

  • dimension – The dimension to slice in

Returns

A vector of tensors where each tensor the slice on the given dimension at the given index.

Tensor index(ArrayRef<std::size_t> indices) const

Get the sub-tensor indexed by the specified indices.

This is equivalent to repeatedly applying operator[] for each index in the vector of indices.

Parameters

indices – The indices used to index into the tensor.

Returns

The sub-tensor indexed by the indices.

Tensor flatten() const

Flatten the tensor.

Returns

A tensor consisting of all elements of the original tensor but with a single dimension.

Tensor flatten(unsigned dimBegin, unsigned dimEnd) const

Flatten a subset of the dimensions of a tensor.

Parameters

  • dimBegin – The first dimension to flatten

  • dimEnd – One past the last dimension to flatten.

Returns

A tensor consisting of all elements of the original tensor with the specified dimension range flattened into one dimension.

Tensor reshape(ArrayRef<std::size_t> shape) const

Reshape the tensor.

The reshaping operation changes the shape of the tensor but cannot change the total number of elements.

Parameters

shape – The new shape of the tensor.

Returns

A tensor consisting of all elements of the original but with new dimensions.

Tensor dimShuffle(ArrayRef<unsigned> permutation) const

Permute the dimensions of a tensor.

The dimShuffle operation reorders the tensor to a permutation of its dimensions. It can be seen as the generalized form of a matrix transpose.

Note that this operation does not create a copy of the tensor but returns a reordered view on this tensor’s data.

Parameters

permutation – The permutation vector specifies a mapping from the output dimension to the input dimension. For example the permutation of {2, 0, 1} specifies that element element [a][b][c] in the original tensor is remapped to element [c][a][b] in the new tensor.

Returns

The shuffled tensor

Tensor dimShufflePartial(ArrayRef<unsigned> source, ArrayRef<unsigned> destination) const

Permute some of a tensor’s dimensions.

dimShufflePartial reorders the tensors dimensions. The unspecified dimensions stay in the same relative order.

Note that this operation does not create a copy of the tensor but returns a reordered view on this tensor’s data.

Parameters

  • source – The dimensions to move.

  • destination – The index at which to move each source dimension.

Returns

The shuffled tensor.

inline Tensor dimRoll(unsigned dimIdx, unsigned newIdx = 0) const

Roll a specified dimension to the specified dimension.

The other dimensions remain in the same relative order

Note that this operation does not create a copy of the tensor but returns a reordered view on this tensor’s data.

Parameters

  • dimIdx – The dimension to move.

  • newIdx – Its new location, default 0.

Returns

The shuffled .

Tensor reshapePartial(unsigned beginIndex, unsigned endIndex, ArrayRef<std::size_t> newDims) const

Reshape a range of dimensions of a tensor.

reshapePartial reshapes the input tensor such that the total number of elements of the resultant tensor is the same as the input tensor.

Note that this operation does not create a copy of the tensor but returns a reshaped view on the input tensor’s data.

The following conditions define the valid use of this function:

1) beginIndex == endIndex

beginIndex and endIndex must each lie in the closed interval [0, rank()]. Singleton dimensions are added before beginIndex. The number of dimensions added is equal to the length of the newDims vector. For example: 

reshapePartial(0, {1, 1})
Adds two singleton dimensions at indicies 0 and 1

2) size(newDims) == 0 and beginIndex != endIndex

beginIndex must lie in the half closed interval [0, rank()) endIndex must lie in the half closed interval (0, rank()] The product of vector newDims must be 1. For example: 

reshapePartial(1, 3, {})
Removes singleton dimensions 1 and 2 from the tensor

3) size(newDims) != 0 and beginIndex != endIndex

beginIndex must lie in the half closed interval [0, rank()) endIndex must lie in the half close interval (0, rank()] The product of vector newDims must be equal to the product of the number of elements in the interval [beginIndex, endIndex)

The input dimensions [0, beginIndex) and [endIndex, rank()) are prepended and appended at the end of the tensor respectively. For example: 

reshapePartial(1, 3, {10, 20, 30})
reshapePartial(1, 3, {10})

Parameters

  • beginIndex – Index of the dimension from which reshape starts

  • endIndex – Index of the first dimension after reshape ends

  • newDims – The new dimensions of the partial tensor

Returns

Reshaped view of tensor

Tensor expand(ArrayRef<std::size_t> indices) const

Expand tensor by adding singleton dimensions at specified indices of tensor.

The rank is expanded by the size of dimensions to be added. To add more than one dimension at a given position, the same index shall be repeated.

Parameters

indices – Dimension indices before which the singleton dimensions are added

Returns

A view of expanded tensor

Tensor squeeze(ArrayRef<std::size_t> indices) const

Reduce dimension of tensor by removing singleton dimensions at specified indices of tensor.

Parameters

indices – Indices of singleton dimensions which are removed

Returns

A view of squeezed tensor

inline Tensor transpose() const

Transpose a 2-dimensional tensor.

Returns

The transposed tensor.

Tensor subSample(unsigned stride, unsigned dimension) const

Sub-sample the tensor.

Sub-sample this tensor by selecting every stride-th element of the tensor in a specified dimension

Parameters

  • stride – The size of the stride

  • dimension – The dimension to sub-sample in

Returns

The sub-sampled tensor

Tensor upsample(unsigned scale, unsigned dimension, UpsampleMethod method) const

Upsample the tensor.

Note that this operation does not create a copy of the tensor but creates a view of the tensor’s data. The repeated data is represented by repeated views into the tensor.

See also

UpsampleMethod for descriptions of how the tensor can be upsampled.

Parameters

  • scale – The scaling factor, >= 0.

  • dimension – The dimension to upsample in.

  • method – The method by which to upsample the tensor.

Returns

The upsampled tensor.

Tensor broadcast(unsigned N, unsigned dimension) const

Broadcast/repeat the tensor along a specified dimension.

Create a view with this tensor repeated N times along a specified dimension.

Parameters

  • N – The number of times to repeat.

  • dimension – The dimension to broadcast in.

Returns

The broadcast tensor.

Tensor reinterpret(const Type &type) const

Reinterpret the tensor as a new type.

The new type must be the same size as the old type. See elementType() for a list of valid types and their sizes.

The new type must not require metadata. If the old type requires metadata the reinterpretted tensor will only contain the data part of the original tensor but not the metadata part.

Parameters

type – The type to reinterpret to

Throws
Returns

A tensor with the same shape and referencing the same data but of the new type.

Tensor reverse(unsigned dimension) const

reverse this tensor along a specified dimension.

Parameters

dimension – The dimension to reverse.

Returns

The reversed tensor.

std::size_t numElements() const

Get the total number of elements in the tensor.

std::size_t dim(unsigned i) const

Get a dimension of the tensor.

Parameters

i – The index of the dimension to get.

std::vector<std::size_t> shape() const

Get the shape of the tensor.

Returns

A vector of all the dimensions of the tensor.

unsigned rank() const

Get the rank of the tensor.

Returns

The number of dimensions a tensor has.

bool isContiguous() const

Get whether the tensor is contiguous.

bool containsAliases() const

Get whether the tensor contains an alias to the same storage location.

Returns

True if the tensor contains an alias to the same storage location.

bool containsConstant() const

Get whether the tensor contains any constant tensors.

Returns

True if the tensor contains any constant tensors.

bool isParallelWriteable() const

Get whether the elements of this tensor can be written in parallel.

This is equivalent to !(containsAliases() || containsConstant()).

Returns

True if the tensor can be written in parallel.

const std::vector<Interval> getContiguousRegions() const

Get the contiguous regions of a tensor.

Returns

A vector of intervals in order representing regions of the tensor that are contiguous in the tensors storage ordering.

const std::vector<VariableInterval> getVarRegions() const

Get the contiguous regions of a tensor with reference to the variables allocated in the graph.

Returns

A vector of variable intervals (variable id, interval pairs) representing the regions of the tensor.

template<typename T>
inline bool getConstantValue(T *val) const

Read a single element of data from a tensor if it is a constant.

Parameters

val – Buffer to which tensor data is copied to

Returns

True if tensor is constant and data is read

bool intersectsWith(const Tensor &other) const

Return whether this tensor intersects with another tensor.

Parameters

other – The tensor to compare with.

Returns

True if this tensor intersects with the other tensor.

std::ostream &output(std::ostream &os) const

Display the expression representing the tensor on a stream.

Parameters

os – The ostream to output to

Returns

The ostream written to

std::ostream &outputRegions(std::ostream &os) const

Display the regions of the tensor on a stream.

Parameters

os – The ostream to output to

Returns

The ostream written to

std::string shapeToString() const

Report the shape of a Tensor as a string.

void dump() const

Display the expression representing the tensor.

void dumpRegions() const

Display the regions of the tensor.

std::string getVarStr() const

getVarStr() and getDebugStr() retrieve a summary (limited to the first underlying variable) of information about a Tensor.

In the simplest form a Tensor can be identified by a single variable id and will have a simple debug string provided when it was created. However the tensor can be created from other tensors, broadcast and manipulated with dim shuffling etc. Therefore a full description can be very long. The summary provided includes: VAR:<ID> - getVarStr(): The variableID of the 1st (or only) underlying variable VAR:<ID> - getDebugStr(): The debug string of the 1st (or only) underlying variable Both functions: BROADCAST[<FACTOR>] - The Tensor was formed by broadcasting with a given <FACTOR> DIMSHUFFLE(<DIMS>) - The Tensor was formed by dimshuffling dimensions in the order given by <DIMS> INTERLEAVE[<N>] - The Tensor is formed from <N> other Tensors Get a string with a summary of underlying tensor variables

std::string getDebugStr() const

Get the debug name associated with the tensor.

Tensor(std::unique_ptr<core::Tensor>)
inline core::Tensor &getImpl() const
inline std::unique_ptr<core::Tensor> *getPImpl()
inline bool valid() const
Tensor getMetadata() const

getMetadata() retrieves the metadata tensor associated with the data tensor.

This function will be successful only if the data tensor has an element type format that is modifiable at runtime e.g. Quarter type. This function will return an empty tensor if the element type is not modifiable at runtime. A tensor is considered to be “empty” if the Tensor::valid() method returns false.

Any tensor whose element type is modifiable at runtime must be associated with a metadata tenor. This must be done at the time of creation of the tensor. If the metadata is not a constant its contents can be updated at runtime. Functionally there is strictly one metadata per tensor regardless of the shape, size or mapping of the tensor. Any view transformation of the data tensor is associated with exactly the same metadata.

The metadata has the same liveness as the data tensor, but is not necessarily allocated adjacent to the data tensor allocation.

On connecting the data tensor to a vertex, poplar creates an additional edge to also connect the metadata to that same vertex. The metadata is read-only regardless of the kind of field that it connects to. The user may choose to update the contents of metadata by connecting it explicitly to a vertex field.

Throws

tensor_metadata_error – If type is not QUARTER and the tensor is associated with a non-empty metadata tensor.

bool hasMetadata() const

Check that the tensor has a metadata tensor.

Private Functions

bool getConstantData(void *dst, const TypeTraits &traits) const

Private Members

std::unique_ptr<core::Tensor> impl
namespace core