File tensor.hpp

Defines the interface of a Tensor object.

namespace nuTens
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.

Protected Attributes

bool _hasBatchDim = false
dtypes::scalarType _dType
dtypes::deviceType _device

Friends

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

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