Template Class Tensor¶

Defined in File Tensor.hpp

Class Documentation¶

template<class T = std::complex<float>> class Jet::Tensor¶

Tensor represents an \(n\)-rank data structure of complex-valued data for tensor operations.

The following conventions are used:

- "Rank" and "order" are used interchangeably and refer to the number of
  tensor indices.
- "Dimension" refers to the number of elements along a tensor index.
- "Shape" refers to the dimensions of a tensor; the number of dimensions
  is the rank of the tensor.

tparam T: Underlying complex tensor data type (complex<float> or complex<double>).

Public Types

using scalar_type_t = T ¶: Type of the real and imaginary components of the tensor data.

Public Functions

inline Tensor()¶

Constructs a default Tensor object.

Default tensor objects have a single zero-initialized data value.

Warning

The shape and indices of a default Tensor object are not set.

inline Tensor(const std::vector<size_t> &shape)¶

Constructs a shaped Tensor object.

Shaped Tensor objects have zero-initialized data values and a size of ( \(\prod_i{\textrm{shape}_i}\)). The indices of a shaped Tensor object default to the values from the set ?[a-zA-Z].

Parameters: shape – Dimension of each Tensor index.

inline Tensor(const std::vector<std::string> &indices, const std::vector<size_t> &shape)¶

Constructs a shaped and labeled Tensor object.

Shaped and labeled Tensor objects have zero-initialized data values and a size of ( \(\prod_i{\textrm{shape}_i}\)).

Parameters

indices – Label of each Tensor index.
shape – Dimension of each Tensor index.

inline Tensor(const std::vector<std::string> &indices, const std::vector<size_t> &shape, const std::vector<T> &data)¶

Constructs a shaped, labeled, and populated Tensor object.

The size of a shaped, indexed, and populated Tensor object is ( \(\prod_i{\textrm{shape}_i}\)).

Parameters

indices – Label of each Tensor index.
shape – Dimension of each Tensor index.
data – Row-major encoded complex data representation of the Tensor object.

inline Tensor(const Tensor &other)¶

Constructs a Tensor object by copying another Tensor object.

Parameters: other – Tensor object to be copied.

inline Tensor(Tensor &&other)¶

Constructs a Tensor object by moving another Tensor object.

Parameters: other – Tensor object to be moved.

inline virtual ~Tensor()¶: Destructs this Tensor object.

inline void InitIndicesAndShape(const std::vector<std::string> &indices, const std::vector<size_t> &shape) noexcept¶

Initializes the indices and shape of a Tensor object.

The indices and shapes must be ordered to map directly such that indices[i] has size shape[i].

Note

This function updates the internal index-to-dimension map.

Parameters

indices – Label of each Tensor index.
shape – Dimension of each Tensor index.

inline void SetShape(const std::vector<size_t> &shape) noexcept¶

Sets the shape of a Tensor object.

The shape of a Tensor defines the number of elements per rank (index).

Parameters: shape – Number of elements in each Tensor index.

inline const std::vector<size_t> &GetShape() const noexcept¶

Returns the shape of a Tensor tensor object.

Returns: Number of elements in each Tensor index.

inline T &operator[](size_t pos)¶

Returns a reference to a Tensor object datum.

Warning

Supplying an index greater than or equal to GetSize() is undefined behaviour.

Parameters: pos – Position of the datum to retrieve, encoded as a 1D row-major index (lexicographic ordering).
Returns: Reference to the complex data value at the specified position.

inline const T &operator[](size_t pos) const¶

See: operator[](size_t pos).

inline void RenameIndex(size_t pos, std::string new_label) noexcept¶

Renames a Tensor index label.

Parameters

pos – Position of the Tensor label.
new_label – New Tensor label.

inline bool operator==(const Tensor<T> &other) const noexcept¶

Equality operator for Tensor objects.

Parameters: other – Tensor object to be compared to this Tensor object.
Returns: True if the two Tensor objects are equivalent.

inline bool operator!=(const Tensor<T> &other) const¶

Inequality operator for Tensor objects.

Parameters: other – Tensor object to be compared to this Tensor object.
Returns: True if the two Tensor objects are not equivalent.

inline const Tensor<T> &operator=(const Tensor<T> &other)¶

Assignment operator for Tensor objects.

Parameters: other – Tensor object to be assigned from.
Returns: Reference to this Tensor object.

inline const Tensor<T> &operator=(Tensor<T> &&other)¶

Assignment operator for Tensor objects using move semantics.

Parameters: other – Tensor object to take ownership of.
Returns: Reference to this Tensor object.

inline const std::unordered_map<std::string, size_t> &GetIndexToDimension() const¶

Returns the index-to-dimension map.

Returns: Mapping from Tensor index labels to dimension sizes.

inline void SetValue(const std::vector<size_t> &indices, const T &value)¶

Sets the Tensor data value at the given \(n\)-dimensional index.

Parameters

indices – \(n\)-dimensional Tensor data index in row-major order.
value – Data value to set at given index.

inline T GetValue(const std::vector<size_t> &indices) const¶

Returns the Tensor data value at the given \(n\)-dimensional index.

Parameters: indices – \(n\)-dimensional Tensor data index in row-major order.
Returns: Complex data value.

inline void SetData(const std::vector<T> &data)¶

Sets the data of a Tensor.

Parameters: data – Data of the Tensor in row-major order.
Throws: Jet::Exception – Data has the wrong size.

inline const std::vector<T> &GetData() const noexcept¶

Returns the Tensor data in row-major order.

Returns: Vector of complex data values.

inline std::vector<T> &GetData()¶

See: GetData().

inline const std::vector<std::string> &GetIndices() const noexcept¶

Returns the Tensor index labels.

Returns: Vector of index labels.

inline size_t GetSize() const¶

Returns the size of a Tensor object.

Returns: Number of data elements.

inline const T &GetScalar() const¶

Returns a single scalar value from the Tensor object.

Note

This is equivalent to calling GetValue({}).

Returns: Complex data value.

inline bool IsScalar() const noexcept¶

Reports whether a Tensor object is a scalar.

Returns: True if this Tensor object is rank-0 (and false otherwise).

inline void FillRandom(size_t seed)¶

Assigns random values to the Tensor object data.

The real and imaginary components of each datum will be independently sampled from a uniform distribution with support over [-1, 1].

Note

This overload enables reproducible random number generation for a given seed.

Parameters: seed – Seed to supply to the RNG engine.

inline void FillRandom()¶

Assigns random values to the Tensor object data.

The real and imaginary components of each datum will be independently sampled from a uniform distribution with support over [-1, 1].

inline Tensor<T> AddTensor(const Tensor<T> &other) const¶

Adds current and other Tensor object with the same index sets.

See: AddTensors(const Tensor &A, const Tensor &B)

inline Tensor<T> SliceIndex(const std::string &index, size_t value) const¶

Slices current Tensor object index.

See: SliceIndex(const Tensor &, const std::string &, size_t)

inline Tensor<T> Reshape(const std::vector<size_t> &new_shape) const¶

Reshapes Tensor object to the given dimensions.

See: Reshape(const Tensor&, const std::vector<size_t>&)

inline Tensor<T> Transpose(const std::vector<size_t> &new_ordering) const¶

Transposes the indices of the Tensor object to a new ordering.

See: Transpose(const Tensor&, const std::vector<size_t>&)

inline Tensor<T> Transpose(const std::vector<std::string> &new_indices) const¶

Transposes the indices of the Tensor object to a new ordering.

See: Transpose(const Tensor&, const std::vector<std::string>&)

inline Tensor<T> Conj() const¶

Returns the conjugate of the current Tensor object.

See: Conj(const Tensor &A)

inline Tensor<T> ContractWithTensor(const Tensor<T> &other) const¶

Contracts the current Tensor object with other over the intersection of their index sets.

See: ContractTensors(const Tensor &A, const Tensor &B)

Public Static Functions

template<class U = T> static inline Tensor AddTensors(const Tensor &A, const Tensor &B)¶

Adds two Tensor objects with the same index sets.

The resulting tensor will have the same index set as the operand tensors. The order of the indices follows that of the first argument (i.e., A).

Example: Given a 2x3 tensor A(i,j) and a 2x3 tensor B(i,j), the addition of A and B is a 2x3 tensor C(i,j):

Tensor A({"i", "j"}, {2, 3}, {0, 1, 2, 3, 4, 5});
Tensor B({"i", "j}, {2, 3}, {5, 5, 5, 6, 6, 6});
Tensor C = AddTensors(A, B);  // {5, 6, 7, 9, 10, 11}

Warning

The program is aborted if the index sets of the given Tensor objects to not match.

Template Parameters

U – Tensor data type.

Parameters

A – tensor on the LHS of the addition.
B – tensor on the RHS of the addition.

Returns

Tensor object representing the element-wise sum of the given tensors.

template<class U = T> static inline Tensor SliceIndex(const Tensor &tensor, const std::string &index, size_t value)¶

Slices a Tensor object index.

The result is a Tensor object whose given indices and data are a subset of the provided tensor object, sliced along the given index argument.

Example: Consider a 2x3 tensor A(i,j). The following example slices along each index with the resulting slices selected as required:

Tensor A({"i", "j"}, {2, 3});
A.FillRandom();

SliceIndex(A, "i", 0);  // [1x3] tensor, slice 0
SliceIndex(A, "i", 1);  // [1x3] tensor, slice 1

SliceIndex(A, "j", 0);  // [2x1] tensor, slice 0
SliceIndex(A, "j", 1);  // [2x1] tensor, slice 1
SliceIndex(A, "j", 2);  // [2x1] tensor, slice 2

Template Parameters

U – Tensor data type.

Parameters

tensor – Tensor object to slice.
index – Tensor index label on which to slice.
value – Value to slice the Tensor index on.

Returns

Slice of the Tensor object.

template<class U = T> static inline Tensor Reshape(const Tensor &old_tensor, const std::vector<size_t> &new_shape)¶

Reshapes a Tensor object to the given dimensions.

Template Parameters

U – Tensor data type.

Parameters

old_tensor – Original tensor object to reshape.
new_shape – Index dimensionality for new tensor object.

Returns

Reshaped copy of the Tensor object.

template<class U = T, size_t BLOCKSIZE = 1024, size_t MINSIZE = 32> static inline Tensor Transpose(const Tensor &A, const std::vector<std::string> &new_indices)¶

Transposes the indices of a Tensor object to a new ordering.

Template Parameters

U – Tensor data type.

Parameters

A – Reference Tensor object.
new_indices – New Tensor index label ordering.

Returns

Transposed Tensor object.

template<class U = T, size_t BLOCKSIZE = 1024, size_t MINSIZE = 32> static inline Tensor Transpose(const Tensor &A, const std::vector<size_t> &new_ordering)¶

Transposes the indices of a Tensor to a new ordering.

Warning

The program is aborted if the number of elements in the new ordering does match the number of indices in the tensor.

Template Parameters

U – Tensor data type.

Parameters

A – Reference Tensor object.
new_ordering – New Tensor index permutation.

Returns

Transposed Tensor object.

template<class U = T> static inline Tensor Conj(const Tensor &A)¶

Returns the conjugate of a Tensor object.

Template Parameters: U – Tensor data type.
Parameters: A – Reference Tensor object.
Returns: Tensor object representing the conjugate of A.

template<class U = T> static inline Tensor ContractTensors(const Tensor &A, const Tensor &B)¶

Contracts two Tensor objects over the intersection of their index sets.

The resulting tensor will be formed with indices given by the symmetric difference of the index sets.

Example: Given a 3x2x4 tensor A(i,j,k) and a 2x4x2 tensor B(j,k,l), the common indices are (j,k) and the symmetric difference of the sets is (i,l). The result of the contraction is a 3x2 tensor C(i,l).

Tensor A({"i", "j", "k"}, {3, 2, 4});
Tensor B({"j", "k", "l"}, {2, 4, 2});
A.FillRandom();
B.FillRandom();
Tensor C = ContractTensors(A, B);

See: TODO: Link to documentation

Template Parameters

U – Tensor data type.

Parameters

A – tensor on the LHS of the contraction.
B – tensor on the RHS of the contraction.

Returns

Tensor object representing the contraction of the tensors.

api/classJet_1_1Tensor

Download Python script

Download Notebook

View on GitHub

Template Class Tensor¶

Class Documentation¶

Contents