Class nuTens::Tensor

class Tensor

Constructors

Use these methods to construct tensors

inline Tensor()

Default constructor with no initialisation.

Tensor(const std::vector<float> &values, dtypes::scalarType type = dtypes::kFloat, dtypes::deviceType device = dtypes::kCPU, bool requiresGrad = true)

Construct a 1-d array with specified values.

  • values The values to include in the tensor

static Tensor eye(int n, dtypes::scalarType type = dtypes::kFloat, dtypes::deviceType device = dtypes::kCPU, bool requiresGrad = true)

Construct an identity tensor (has to be a 2d square tensor)

  • n The size of one of the sides of the tensor

  • type The data type of the tensor

static Tensor rand(const std::vector<long int> &shape, dtypes::scalarType type = dtypes::kFloat, dtypes::deviceType device = dtypes::kCPU, bool requiresGrad = true)

Construct a tensor with entries randomly initialised in the range [0, 1].

  • shape The desired shape of the intitalised tensor

  • type The data type of the tensor

static Tensor diag(const Tensor &diag)

Construct a tensor diag values along the diagonal, and zero elsewhere.

  • diag A 1-d tensor which represents the desired diagonal values

static Tensor ones(const std::vector<long int> &shape, dtypes::scalarType type = dtypes::kFloat, dtypes::deviceType device = dtypes::kCPU, bool requiresGrad = true)

Construct a tensor with ones.

  • shape The desired shape of the intitalised tensor

  • type The data type of the tensor

static Tensor zeros(const std::vector<long int> &shape, dtypes::scalarType type = dtypes::kFloat, dtypes::deviceType device = dtypes::kCPU, bool requiresGrad = true)

Construct a tensor with zeros.

  • shape The desired shape of the intitalised tensor

  • type The data type of the tensor

Setters

Set the underlying data type of this tensor

Tensor &dType(dtypes::scalarType type)
Tensor &device(dtypes::deviceType device)

Set the device that this tensor lives on.

Tensor &requiresGrad(bool reqGrad)

Set whether the tensor requires a gradient.

inline Tensor &hasBatchDim(bool hasBatchDim)

Set whether or not the first dimension should be interpreted as a batch dimension.

Matrix Arithmetic

Generally there are static functions with the pattern <function>(Mat1, Mat2) which will return a new matrix and inline equivalents with the pattern <function>_(Mat2) which will affect the object they are called by

void matmul_(const Tensor &t2)

Inline matrix multiplication.

  • t2 Right hand matrix to multiply with this one

void mul_(const Tensor &t2)

inline element-wise multiplication

  • t2 Right hand tensor

void div_(const Tensor &t2)

inline element-wise division

  • t2 Denominator

void scale_(float s)

Inline matrix scaling.

  • s The scalar

void scale_(std::complex<float> s)

Inline complex matrix scaling.

  • s The scalar

void pow_(float s)

Inline raise to scalar power.

  • s The scalar

void pow_(std::complex<float> s)

Inline raise to scalar power.

  • s The scalar

void exp_()

Inline element-wise exponential.

void transpose_(int dim1, int dim2)

Inline transpose.

  • dim1 The first dimension to swap

  • dim2 The second dimension to swap

static Tensor matmul(const Tensor &t1, const Tensor &t2)

Multiply two matrices together.

  • t1 Left hand tensor

  • t2 Right hand tensor

static Tensor outer(const Tensor &t1, const Tensor &t2)

Outer product of two 1D tensors.

  • t1 Left hand tensor

  • t2 Right hand tensor

static Tensor mul(const Tensor &t1, const Tensor &t2)

Element-wise multiplication of two tensors.

  • t1 Left hand tensor

  • t2 Right hand tensor

static Tensor div(const Tensor &t1, const Tensor &t2)

Element-wise division of two tensors.

  • t1 Numerator

  • t2 Denominator

static Tensor pow(const Tensor &t, float s)

Raise a matrix to a scalar power.

  • t The tensor

  • s The scalar

static Tensor pow(const Tensor &t, std::complex<float> s)

Raise a matrix to a scalar power.

  • t The tensor

  • s The scalar

static Tensor exp(const Tensor &t)

Element-wise exponential.

  • t The tensor

static Tensor transpose(const Tensor &t, int dim1, int dim2)

Get the transpose of a tensor.

  • t The tensor

  • dim1 The first dimension to swap

  • dim2 The second dimension to swap

static Tensor scale(const Tensor &t, float s)

Scale a matrix by some scalar.

  • s The scalar

  • t The tensor

static Tensor scale(const Tensor &t, double s)

Scale a matrix by some scalar.

  • s The scalar

  • t The tensor

static Tensor scale(const Tensor &t, std::complex<float> s)

Scale a matrix by some complex scalar.

  • s The scalar

  • t The tensor

static Tensor scale(const Tensor &t, std::complex<double> s)

Scale a matrix by some complex scalar.

  • s The scalar

  • t The tensor

Mathematical

mathematical function overrides, generally work as expected, unless otherwise noted

bool operator==(const Tensor &rhs) const
bool operator!=(const Tensor &rhs) const
Tensor operator+(const Tensor &rhs) const
Tensor operator-(const Tensor &rhs) const
Tensor operator+(double rhs) const
Tensor operator-(double rhs) const
Tensor operator*(const Tensor &rhs) const
Tensor operator*(double rhs) const
Tensor operator/(const Tensor &rhs) const
Tensor operator/(double rhs) const
Tensor operator-() const

Gradients

void backward() const

Compute gradients of this tensor with respect to leaves Those can then be accessed using gradient()

Tensor grad() const

Return a tensor containing the accumulated gradients calculated for this tensor after calling backward()

Linear Algebra

static void eig(const Tensor &t, Tensor &eVals, Tensor &eVecs)

Get eigenvalues and vectors of a tensor.

  • t The tensor

Parameters:

  • eVals – [out] The eigenvalues

  • eVecs – [out] The eigenvectors

static void eigh(const Tensor &t, Tensor &eVals, Tensor &eVecs)

Get eigenvalues and vectors of a hermitian matrix.

  • t The tensor

Parameters:

  • eVals – [out] The eigenvalues

  • eVecs – [out] The eigenvectors This is in general faster and more stable than Tensor::eig and should be preferred in basically all cases where it can be used

static void eigvals(const Tensor &t, Tensor &eVals)

Get eigenvalues of a tensor.

  • t The tensor

Parameters:

eVals – [out] The eigenvalues

static void eigvalsh(const Tensor &t, Tensor &eVals)

Get eigenvalues of a hermitian matrix.

  • t The tensor

Parameters:

eVals – [out] The eigenvalues This is in general faster and more stable than Tensor::eigvals and should be preferred in basically all cases where it can be used

static void qr(const Tensor &t, Tensor &Q, Tensor &R)

Perform QR decomposition on a hermitian matrix.

  • t The tensor

Parameters:

  • Q – [out]

  • R – [out]

Trigonometric

static Tensor sin(const Tensor &t)

Get element-wise sin of a tensor.

Parameters:

t – The tensor

static Tensor cos(const Tensor &t)

Get element-wise cosine of a tensor.

Parameters:

t – The tensor

Public Types

using indexType = std::variant<int, std::string>

Holds the possible β€œindex” types, this allows us to pass integers OR strings as index values which allows us to do some basic slicing of tensors similar to python

using variantType = std::variant<int, float, double, std::complex<float>, std::complex<double>>

Container that holds all allowed types that can be returned by a tensor.

Public Functions

Tensor &addBatchDim()

If the tensor does not already have a batch dimension (as set by hasBatchDim()) this will add one.

Tensor &unsqueeze(int index)

add new dimension to the tensor at a particular index

Tensor real() const

Get the real part of a complex tensor.

Tensor imag() const

Get the imaginary part of a complex tensor.

Tensor conj() const

Get the complex conjugate of this tensor. If the underlying tensor is not complex, this will just return the tensor.

Tensor abs() const

Get elementwise absolute magnitude of a complex tensor.

Tensor angle() const

Get elementwise phases of a complex tensor.

Tensor cumsum(int dim) const

Get the cumulative sum over some dimension.

Parameters:

dim – The dimension to sum over

Tensor sum() const

Get the result of summing this tensor over all dimensions.

Tensor sum(const std::vector<long int> &dims) const

Get the result of summing this tensor over all dimensions.

Parameters:

dims – The dimensions to sum over

std::string toString() const

Print this object to a summary string.

void setValue(const Tensor &indices, const Tensor &value)

Set the value at a particular index of the tensor.

  • indices The indices of the value to set

  • value The value to set it to

void setValue(const std::vector<indexType> &indices, const Tensor &value)
void setValue(const std::vector<int> &indices, float value)
void setValue(const std::vector<int> &indices, double value)
void setValue(const std::vector<int> &indices, std::complex<float> value)
void setValue(const std::vector<int> &indices, std::complex<double> value)
Tensor getValues(const std::vector<indexType> &indices) const

Get the value at a certain entry in the tensor.

Parameters:

indices – The index of the entry to get

variantType getVariantValue(const std::vector<int> &indices) const

Get the value at a certain entry in the tensor as an std::variant.

This mainly exists so we can get the values of a tensor in python as pybind11 DOES NOT like templated functions If using the c++ interface it is probably easier, faster and safer to use the templated getValue() function.

size_t getNdim() const

Get the number of dimensions in the tensor.

int getBatchDim() const

Get the size of the batch dimension of the tensor.

bool getHasBatchDim() const

Check if tensor has batch dimension prepended.

std::vector<int> getShape() const

Get the shape of the tensor.

Public Static Functions

static inline Tensor cumsum(const Tensor &t, int dim)

Get the cumulative sum over some dimension.

Parameters:

dim – The dimension to sum over

static inline Tensor sum(const Tensor &t)

Get the result of summing this tensor over all dimensions.

static inline Tensor sum(const Tensor &t, const std::vector<long int> &dims)

Get the result of summing this tensor over all dimensions.

Parameters:

dims – The dimensions to sum over

static std::string getTensorLibrary()

Get the name of the backend library used to deal with tensors.

Friends

inline friend std::ostream &operator<<(std::ostream &stream, const Tensor &tensor)

Overwrite the << operator to print this tensor out to the command line.