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

type_error – If the new and the old type do not have the same size.
tensor_metadata_error – If the new type requires metadata.

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