Using Jet

Development

C++ API

Python API

  1. Docs
  2. Overview
  3. Template Class Tensor
  4. Show on GitHub

Template Class Tensor

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<U> &A, const Tensor<U> &B)

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

Slices current Tensor object index.

See

SliceIndex(const Tensor<U> &, 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<U>&, 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<U>&, 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<U>&, const std::vector<std::string>&)

inline Tensor<T> Conj() const

Returns the conjugate of the current Tensor object.

See

Conj(const Tensor<U> &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<U> &A, const Tensor<U> &B)

Public Static Functions

template<class U = T>
static inline Tensor<U> AddTensors(const Tensor<U> &A, const Tensor<U> &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<U> SliceIndex(const Tensor<U> &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<U> Reshape(const Tensor<U> &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<U> Transpose(const Tensor<U> &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<U> Transpose(const Tensor<U> &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<U> Conj(const Tensor<U> &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<U> ContractTensors(const Tensor<U> &A, const Tensor<U> &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.

Previous
Next

Downloads

api/classJet_1_1Tensor
 
Download Python script
 
Download Notebook
 
View on GitHub