A reference to a subset of tensor elements. More...

#include <Tensor.hpp>

Public Member Functions
Type	elementType () const
	Get the element type information for this tensor. More...

Tensor	operator[] (std::size_t i) const &
	Get the sub-tensor indexed by i in the first dimension of the tensor. More...

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. More...

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. More...

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. More...

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. More...

std::vector< Tensor >	slices (ArrayRef< Interval > intervals, unsigned dimension=0) const
	Get a vector of slices. More...

std::vector< Tensor >	slices (const std::vector< std::vector< Interval > > &intervals, unsigned dimension=0) const
	Get a vector of slices. More...

std::vector< Tensor >	slices (const poplar::ArrayRef< unsigned > &indices, unsigned dimension=0) const
	Get a vector of slices. More...

Tensor	index (ArrayRef< std::size_t > indices) const
	Get the sub-tensor indexed by the specified indices. More...

Tensor	flatten () const
	Flatten the tensor. More...

Tensor	flatten (unsigned dimBegin, unsigned dimEnd) const
	Flatten a subset of the dimensions of a tensor. More...

Tensor	reshape (ArrayRef< std::size_t > shape) const
	Reshape the tensor. More...

Tensor	dimShuffle (ArrayRef< unsigned > permutation) const
	Permute the dimensions of a tensor. More...

Tensor	dimShufflePartial (ArrayRef< unsigned > source, ArrayRef< unsigned > destination) const
	Permute some of a tensor's dimensions. More...

Tensor	dimRoll (unsigned dimIdx, unsigned newIdx=0) const
	Roll a specified dimension to the specified dimension. More...

Tensor	reshapePartial (unsigned beginIndex, unsigned endIndex, ArrayRef< std::size_t > newDims) const
	Reshape a range of dimensions of a tensor. More...

Tensor	expand (ArrayRef< std::size_t > indices) const
	Expand tensor by adding singleton dimensions at specified indices of tensor. More...

Tensor	squeeze (ArrayRef< std::size_t > indices) const
	Reduce dimension of tensor by removing singleton dimensions at specified indices of tensor. More...

Tensor	transpose () const
	Transpose a 2-dimensional tensor. More...

Tensor	subSample (unsigned stride, unsigned dimension) const
	Sub-sample the tensor. More...

Tensor	upsample (unsigned scale, unsigned dimension, UpsampleMethod method) const
	Upsample the tensor. More...

Tensor	broadcast (unsigned N, unsigned dimension) const
	Broadcast/repeat the tensor along a specified dimension. More...

Tensor	reinterpret (const Type &type) const
	Reinterpret the tensor as a new type. More...

Tensor	reverse (unsigned dimension) const
	reverse this tensor along a specified dimension. More...

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. More...

std::vector< std::size_t >	shape () const
	Get the shape of the tensor. More...

unsigned	rank () const
	Get the rank of the tensor. More...

bool	isContiguous () const
	Get whether the tensor is contiguous.

bool	containsAliases () const
	Get whether the tensor contains an alias to the same storage location. More...

bool	containsConstant () const
	Get whether the tensor contains any constant tensors. More...

bool	isParallelWriteable () const
	Get whether the elements of this tensor can be written in parallel. More...

const std::vector< Interval >	getContiguousRegions () const
	Get the contiguous regions of a tensor. More...

const std::vector< VariableInterval >	getVarRegions () const
	Get the contiguous regions of a tensor with reference to the variables allocated in the graph. More...

template<typename T >
bool	getConstantValue (T *val) const
	Read a single element of data from a tensor if it is a constant. More...

bool	intersectsWith (const Tensor &other) const
	Return whether this tensor intersects with another tensor. More...

std::ostream &	output (std::ostream &os) const
	Display the expression representing the tensor on a stream. More...

std::ostream &	outputRegions (std::ostream &os) const
	Display the regions of the tensor on a stream. More...

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. More...

std::string	getDebugStr () const
	Get the debug name associated with the tensor.

Tensor	getMetadata () const
	getMetadata() retrieves the metadata tensor associated with the data tensor. More...

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

Detailed Description

A reference to a subset of tensor elements.

Member Function Documentation

◆ broadcast()

Tensor poplar::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.

◆ containsAliases()

bool poplar::Tensor::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.

◆ containsConstant()

bool poplar::Tensor::containsConstant ( ) const

Get whether the tensor contains any constant tensors.

Returns: True if the tensor contains any constant tensors.

◆ dim()

std::size_t poplar::Tensor::dim ( unsigned i ) const

Get a dimension of the tensor.

Parameters

i	The index of the dimension to get.

◆ dimRoll()

Tensor poplar::Tensor::dimRoll	(	unsigned	dimIdx,
		unsigned	newIdx = `0`
	)		const

inline

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 .

◆ dimShuffle()

Tensor poplar::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

◆ dimShufflePartial()

Tensor poplar::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.

◆ elementType()

Type poplar::Tensor::elementType ( ) const

Get the element type information for this tensor.

Returns: The element type.

◆ expand()

Tensor poplar::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

◆ flatten() [1/2]

Tensor poplar::Tensor::flatten ( ) const

Flatten the tensor.

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

◆ flatten() [2/2]

Tensor poplar::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.

◆ getConstantValue()

template<typename T >

bool poplar::Tensor::getConstantValue ( T * val ) const

inline

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

◆ getContiguousRegions()

const std::vector< Interval > poplar::Tensor::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.

◆ getMetadata()

Tensor poplar::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.

Exceptions

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

◆ getVarRegions()

const std::vector< VariableInterval > poplar::Tensor::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.

◆ getVarStr()

std::string poplar::Tensor::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

◆ index()

Tensor poplar::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.

◆ intersectsWith()

bool poplar::Tensor::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.

◆ isParallelWriteable()

bool poplar::Tensor::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.

◆ operator[]()

Tensor poplar::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.

◆ output()

std::ostream & poplar::Tensor::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

◆ outputRegions()

std::ostream & poplar::Tensor::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

◆ rank()

unsigned poplar::Tensor::rank ( ) const

Get the rank of the tensor.

Returns: The number of dimensions a tensor has.

◆ reinterpret()

Tensor poplar::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.

Parameters

type	The type to reinterpret to

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

◆ reshape()

Tensor poplar::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.

◆ reshapePartial()

Tensor poplar::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

◆ reverse()

Tensor poplar::Tensor::reverse ( unsigned dimension ) const

reverse this tensor along a specified dimension.

Parameters

dimension The dimension to reverse.

Returns: The reversed tensor.

◆ shape()

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

Get the shape of the tensor.

Returns: A vector of all the dimensions of the tensor.

◆ slice() [1/4]

Tensor poplar::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

◆ slice() [2/4]

Tensor poplar::Tensor::slice	(	const Interval &	region,
		unsigned	dimension = `0`
	)		const

inline

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

◆ slice() [3/4]

Tensor poplar::Tensor::slice	(	std::size_t	begin,
		std::size_t	end
	)		const

inline

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)

◆ slice() [4/4]

Tensor poplar::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

◆ slices() [1/3]

std::vector< Tensor > poplar::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.

◆ slices() [2/3]

std::vector< Tensor > poplar::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.

◆ slices() [3/3]

std::vector< Tensor > poplar::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.

◆ squeeze()

Tensor poplar::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

◆ subSample()

Tensor poplar::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

◆ transpose()

Tensor poplar::Tensor::transpose ( ) const

inline

Transpose a 2-dimensional tensor.

Returns: The transposed tensor.

◆ upsample()

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

Upsample the tensor.

See also: UpsampleMethod for descriptions of how the tensor can be upsampled.

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.

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.

The documentation for this class was generated from the following file:

include/poplar/Tensor.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ broadcast()

◆ containsAliases()

◆ containsConstant()

◆ dim()

◆ dimRoll()

◆ dimShuffle()

◆ dimShufflePartial()

◆ elementType()

◆ expand()

◆ flatten() [1/2]

◆ flatten() [2/2]

◆ getConstantValue()

◆ getContiguousRegions()

◆ getMetadata()

◆ getVarRegions()

◆ getVarStr()

◆ index()

◆ intersectsWith()

◆ isParallelWriteable()

◆ operator[]()

◆ output()

◆ outputRegions()

◆ rank()

◆ reinterpret()

◆ reshape()

◆ reshapePartial()

◆ reverse()

◆ shape()

◆ slice() [1/4]

◆ slice() [2/4]

◆ slice() [3/4]

◆ slice() [4/4]

◆ slices() [1/3]

◆ slices() [2/3]

◆ slices() [3/3]

◆ squeeze()

◆ subSample()

◆ transpose()

◆ upsample()