Matlab API Documentation¶

class Tensorino(varargin)¶

Class for multi-dimensional sparse tensors.

Handles sparse tensors with an unlimited number of elements, with the restriction that each individual index dimension must be smaller than 2^32-1.

Tensorino(varargin)¶

Create a Tensorino.

Usage

t = Tensorino(ind, vals, sz): Uses the rows of ind and vals to generate a Tensorino t of size sz = [m1 m2 ... mn]. ind is a p x n array specifying the subscripts of the nonzero values to be inserted into t. The k-th row of ind specifies the subscripts for the k-th value in vals. The argument vals may be scalar, in which case it is expanded to be the same length as ind, i.e., it is equivalent to vals * (p, 1).
t = Tensorino(ind, vals): Same as the three-argument call, where now the size of the Tensorino is taken to be the column-wise maximum of ind.
t = Tensorino: Empty constructor.
t = Tensorino(a): Copies/converts a if it is a Tensorino, a dense array or a sparse matrix.
t = Tensorino(a, sz): Copies/converts a if it is a Tensorino, a dense array or a sparse matrix, and sets the size of a to sz

Example

>> ind = [1 1 1; 1 1 3; 2 2 2; 4 4 4];
>> vals = [0.5; 1.5; 2.5; 3.5];
>> sz = [4 4 4];
>> t = Tensorino(ind, vals, sz) %<-- 4x4x4 Tensorino

Note

Currently the Tensorino constructor does not allow duplicate subscripts in ind, unlike the builtin Matlab sparse.

abs(t)¶

Absolute value and complex magnitude.

Usage

b = abs(t)

Arguments: t (Tensorino) – Input tensor.
Returns: b (Tensorino) – Absolute value of each element in t. If t is complex, abs(t) returns the complex magnitude.

app(t, mat, ind)¶

Apply rescaling matrices on certain indices.

Usage

t_res = app(t, mat1, ind1, mat, ind2, ...)

Arguments

t (Tensorino) – Input tensor.

Repeating Arguments

mat (Tensorino) – Rescaling matrices to be multiplied with t.
ind (int) – Indices onto which rescaling matrices are applied.

Returns

t_res (Tensorino) – Rescaled tensor.

conj(t)¶

Complex conjugate.

Arguments: a (Tensorino) – input array.
Returns: b (Tensorino) – output array.

ctranspose(a)¶

Complex conjugate transpose.

Only defined for 2D Tensorino s.

Usage

b = ctranspose(a)

b = a'

Arguments: a (Tensorino) – input array.
Returns: b (Tensorino) – output array.

distance(t1, t2)¶

Compute the Euclidean distance between two :class:`Tensorino`s.

Arguments: t1, t2 (Tensorino)
Returns: d (double) – Euclidean distance, defined as the norm of the difference.

dot(t1, t2)¶

Compute the scalar dot product of two :class:`Tensorino`s. This is defined as the overlap of the two tensors, which therefore must have sizes. This function is sesquilinear in its arguments.

Arguments: t1, t2 (Tensorino) – Tensors of equal structure.
Returns: d (double) – Scalar dot product of the two tensors.

eig(t)¶

Find eigenvalues and eigenvectors of a square Tensorino.

Usage

e = eig(t)

[V, D] = eig(t)

Arguments

t (Tensorino) – Input tensor of size [a b ... z a b ... z], interpreted as a (a x a x … x z) x (a x a x … x z) matrix.

Returns

e (double) – Column vector containing the eigenvalues of t.
D ((:, :) Tensorino) – Diagonal Tensorino of eigenvalues.
V ((1, :) Tensorino) – Row vector of right eigenvectors such that A * V = V * D.

Todo

Decide on/document index splitting convention (fixing domain and codomain for matrix decomposition).

See also

Documentation for builtin Matlab eig.

eigs(t, n)¶: Find a few eigenvalues and eigenvectors of a Tensorino.

Todo

Decide on/document index splitting convention (fixing domain and codomain for matrix decomposition).

See also

Documentation for builtin Matlab eigs.

find(t)¶

Find subscripts of nonzero elements in a Tensorino.

Arguments

a (Tensorino) – input array

Returns

ind ((:, :) int) – subscripts of nonzero entries.
var ((:, 1) double) – values of nonzero entries.

full(t)¶

Convert a Tensorino to a dense array.

Arguments: a (Tensorino) – input array.
Returns: d (double) – dense output array.

Warning

Limited in size!

groupind(t, g)¶

Group (block) specified sets of contiguous indices.

Arguments

a (Tensorino) – input array.
g ((1, :) int) – list of number of contiguous indices to be grouped in each index of the output tensor.

Returns

b (Tensorino) – output tensor with grouped indices.

Example

>> t = Tensorino.random([2, 3, 4, 5, 6], .1);
>> b = groupind(t, [3, 2]); %<-- 24x30 Tensorino

imag(t)¶

Complex imaginary part of sparse tensor.

Arguments: t (Tensorino) – input array.
Returns: b (Tensorino) – output array with real entries corresponding to the imaginary part of the entries of a.

isequal(t1, t2)¶

Compare equality of two :class:`Tensorino`s.

Arguments: t1, t2 (Tensorino) – input tensors to be compared.
Returns: bool (logical) – comparison result.

isnumeric(~)¶

Determine whether input is numeric.

Arguments: t (Tensorino) – input tensor.
Returns: bool (logical) – defaults to true for Tensorino.

isscalar(~)¶

Determine whether input is scalar.

Arguments: t (Tensorino) – input tensor.
Returns: bool (logical) – defaults to false for Tensorino.

isrow(t)¶

Determine whether input is row vector.

Arguments: t (Tensorino) – input tensor.
Returns: bool (logical)

ldivide(a, b)¶

Elementwise left division for Tensorino.

Usage

ldivide(a, b)

a .\ b

Arguments

a (double) – Scalar to divide by
b (Tensorino) – Input tensor.

Returns

c (Tensorino) – Output tensor.

Note

Currently restricted to the case where a is a scalar.

minus(t1, t2)¶

Elementwise subtraction for :class:`Tensorino`s.

Note

Scalars are only subtracted from nonzero entries of the Tensorino.

Usage

minus(a, b)

a - b

a and b must have the same size, unless one is a scalar. A scalar can be subtracted from a Tensorino of any size.

Arguments: t1, t2 (Tensorino or double) – input tensors.
Returns: t (Tensorino) – output tensor.

mrdivide(a, b)¶

Matrix right division for Tensorino.

Usage

mrdivide(a, b)

a / b

Arguments

a (Tensorino) – Input tensor.
b (double) – Scalar to divide by

Returns

c (Tensorino) – Output tensor.

Note

Currently restricted to the case where b is a scalar.

mtimes(a, b)¶

Matrix multiplication for :class:`Tensorino`s.

Usage

t = mtimes(a, b)

t = a * b

Note

Currently restricted to the case where either a or b is a scalar.

ndims(t)¶

Number of dimensions of a Tensorino.

Note that unlike the builtin Matlab behavior trailing singleton dimensions are not ignored.

Example

>> a = Tensorino.random([4 3 1], .1);
>> ndims(a) %<-- returns 3

nnz(t)¶: Number of nonzero elements in a Tensorino.

norm(t)¶: Frobenius norm of a Tensorino.

normalize(t)¶: Normalize Tensorino.

numel(t)¶: Number of elements in a sparse array.

outer(a, b)¶: Outer product of two :class:`Tensorino`s.

Warning

Not kron.

permute(t, order)¶: Permute Tensorino dimensions.

plus(t1, t2)¶

Elementwise addition for :class:`Tensorino`s.

Note

Scalars are only added to nonzero entries of the Tensorino.

Usage

plus(a, b)

a + b

a and b must have the same size, unless one is a scalar. A scalar can be added to a sparse array of any size.

Arguments: t1, t2 (Tensorino or double) – input tensors.
Returns: t (Tensorino) – output tensor

power(a, b)¶: Elementwise power for Tensorino.

purge(t, tol)¶

Set all nonzero values in Tensorino who’s absolute value is below a given threshold to zero.

Arguments

a (Tensorino) – input array.
tol (float , optional) – threshold tolerance for absolute values of entries, defaults to 1e-15.

Returns

b (Tensorino) – sparse array with entries of absolute value below tol set to zero.

rdivide(a, b)¶

Elementwise right division for Tensorino.

Usage

rdivide(a, b)

a ./ b

Arguments

a (Tensorino) – Input tensor.
b (double) – Scalar to divide by

Returns

c (Tensorino) – Output array.

Note

Currently restricted to the case where b is a scalar.

real(t)¶

Complex real part of a Tensorino.

Arguments: t (Tensorino) – input array.
Returns: b (Tensorino) – output array with real entries corresponding to the real part of the entries of a.

reduce(t, dims)¶

Reduce the size of a Tensorino along given dimensions based on the subscripts of its nonzero elements by dropping all unused index values for each given dimension individually.

Arguments

t (Tensorino) – input array.
dims ((1, :) int, optional) – dimensions to be reduced, defaults to ind = 1:ndims(t).

Returns

b (Tensorino) – output array.

rescale(t, dims, factors)¶

Apply rescaling factors along given Tensorino dimensions.

Arguments

t (Tensorino) – input array.
dims ((1, :) int) – dimensions to be rescaled.
factors ((1, :) cell) – cell array of rescaling factors for each dimension, where factors{i} is a vector of size size(t, dims(i)).

Returns

t_res (Tensorino) – rescaled tensor.

reshape(t, newsize)¶: Reshape a Tensorino.

simplify(t)¶

Simplify a symbolic Tensorino.

Arguments: t (Tensorino) – input symbolic tensor.
Returns: t_sim (Tensorino) – simplified symbolic tensor.

size(t, dim)¶

Tensorino dimensions.

Usage

d = size(a): returns the size of the Tensorino.
d = size(a, dim): returns the sizes of the dimensions specified by dim, which is either an integer or a vector of integer dimensions.

sparse(t, g_ind)¶

Convert Tensorino to a sparse matrix.

Arguments

t (Tensorino) – input tensor.
g_ind ((1, 2) int, optional) – list of number of contiguous indices to be grouped in each index of the output sparse matrix. If ndims(t) ~= 2, then g_ind must be provided.

Returns

m (sparse) – output sparse matrix, possibly with grouped indices.
Ur (???)
Uc (???)

Example

>> ???

squeeze(t)¶

Remove singleton dimensions from a Tensorino.

Usage

b = squeeze(a): returns a sparse tensor b with the same elements as a but with all the singleton dimensions removed.

Example

>> squeeze(Tensorino.random([2, 1, 3], 0.5)) %<-- returns a 2 x 3 Tensorino
>> squeeze(Tensorino([1, 1, 1], 1, [1, 1, 1])) %<-- returns a scalar

subs(t, symbols, values)¶: Symbolic substitution for a Tensorino.

See also

Builtin

subsasgn(t, s, b)¶: Subscripted assignment for a Tensorino.

Todo

Write docstring.

subsref(t, s)¶

Subscripted reference for a Tensorino.

Todo

Fix case where all dimensions are indexed, fix indexing with ranges, write docstring.

Usage

a_sub = a(i1, i2, ..., iN): where each in is an integer index, returns a scalar.
a_sub = a(R1, R2, ..., RN): where each Rn is either a colon, an array of integers representing a slice in this dimension or a logical array representing the logical indexing of this dimension. Returns a sparse array.

Example

>> t = Tensorino([4, 4, 4; 2, 2, 1; 2, 3, 2], [3; 5; 1], [4, 4, 4]);
>> t(1, 2, 1) %<-- returns zero
>> t(4, 4, 4) %<-- returns 3
>> t(2, :, :) %<-- returns a 1 x 4 x 4 Tensorino

sum(t)¶: Sum of all elements of a Tensorino.

symp(t)¶: Symbolic something

Todo

Figure out what this does.

tensorprod(A, B, dimA, dimB, options)¶

Tensor products between two :class:`Tensorino`s.

Usage

C = tensorprod(A, B, dimA, dimB): returns the tensor product of tensors A and B. The arguments

dimA and dimB are vectors that specify which dimensions to contract in A and B. The size of the output tensor is the size of the uncontracted dimensions of A followed by the size of the uncontracted dimensions of B.
C = tensorprod(A, B): returns the outer product of tensors A and B. This is

equivalent to the previous syntax with dimA = dimB = [].
C = tensorprod(_, 'NumDimensionsA', ndimsA): optionally specifies the number of dimensions in tensor A in

addition to combat the removal of trailing singleton dimensions.

times(a, b)¶

Product of a Tensorino and a scalar.

Usage

t = times(t, a)

t = a .* t

transpose(t)¶

Transpose.

Only defined for 2D Tensorino.

Usage

a = transpose(t)

a = t.'

Arguments: t (Tensorino) – input tensor.
Returns: a (Tensorino) – output tensor.

uminus(t)¶

Unary minus.

Usage

b = uminus(a)

b = -a

Arguments: a (Tensorino) – input array.
Returns: b (Tensorino) – output array.

uplus(a)¶

Unary plus.

Usage

b = uplus(a)

b = +a

Arguments: a (Tensorino) – input array.
Returns: b (Tensorino) – output array.

static delta(numinds, inddim)¶

Create delta- (ghz-) tensor with given number of indices and index dimension.

Arguments

numinds (int) – Number of indices of delta-array.
inddim (int) – Dimension of each index of delta-array.

Returns

t (Tensorino) – output delta-array.

static new(fun, sz, density)¶

Create a Tensorino with data generated using a function handle.

Arguments

fun (function_handle) – Function of signature fun(dims). If this is left empty, the tensor data will be uninitialized.
sz ((1, :) int) – Size of the sparse tensor.
density (double) – Density of nonzero elements (0 < density < 1).

Returns

t (Tensorino) – Output tensor.