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.

enumerator REPEAT
Functions

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

class Tensor
 #include <Tensor.hpp>
A reference to a subset of tensor elements.
Public Functions

Tensor()

~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 subtensor indexed by i in the first dimension of the tensor.
 Parameters
i – The index into the first dimension of the tensor.

Tensor slice(std::size_t begin, std::size_t end, unsigned dimension) const &
Get the subtensor 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

inline Tensor slice(std::size_t begin, std::size_t end) const
Get the subtensor 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 ®ion, unsigned dimension = 0) const
Get the subtensor 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 subtensor 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 subtensor 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 subtensor 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:
Adds two singleton dimensions at indicies 0 and 1reshapePartial(0, {1, 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:
Removes singleton dimensions 1 and 2 from the tensorreshapePartial(1, 3, {})
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

Tensor subSample(unsigned stride, unsigned dimension) const
Subsample the tensor.
Subsample this tensor by selecting every strideth element of the tensor in a specified dimension
 Parameters
stride – The size of the stride
dimension – The dimension to subsample in
 Returns
The subsampled 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 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

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

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 readonly 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 nonempty metadata tensor.

bool hasMetadata() const
Check that the tensor has a metadata tensor.
Private Functions

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

Tensor()

namespace core

enum class UpsampleMethod