Tensors¶
Functions and classes for manipulating tensors in full, canonical, and Tucker format, and for tensor approximation.
A full tensor is simply represented as a numpy.ndarray
.
Additional tensor formats are implemented in the following classes:
In addition, arbitrary tensors can be composed into sums or tensor products using the following classes:
Below, whenever we refer generically to “a tensor”, we mean either an ndarray or an instance of any of these tensor classes.
All tensor classes have members ndim
, shape
, and ravel
which have the same
meaning as for an ndarray.
Any tensor can be expanded to a full ndarray using asarray()
.
In addition, most tensor classes have overloaded operators for adding and
subtracting tensors in their native format.
All tensors can be sliced using the standard numpy []
indexing syntax. The
result is a tensor in the same format, except for the case where all axes have
a single scalar index, in which case the entry at the corresponding index is
returned as a scalar value.
Linear operators on tensors, themselves represented in suitable lowrank formats, are described by
Module members¶

class
pyiga.tensor.
CanonicalOperator
(terms)¶ Represents a linear operator on tensors which is described as a sum of rank one operators (Kronecker products), i.e.,
\[\mathcal A = \sum_{r=1}^{R} A^1_r \otimes\cdots\otimes A^d_r.\]The argument terms is a list of length R of dtuples containing the matrices \(A^k_r\).

R
¶ Kronecker rank of the operator
Type: int

shape
¶ a pair where shape[1] is the shape of input tensors accepted by this operator and shape[0] is the shape of output tensors produced
Type: tuple

ndim
¶ the number of dimensions, i.e., d in the formula above
Type: int

T
¶ Return the transpose of this operator as a
CanonicalOperator
.

apply
(X)¶ Return the result of applying this operator to a tensor X.

asmatrix
(format='csr')¶ Return the raveled form of this operator as a sparse matrix in the given format.

static
eye
(ns, format='dia')¶ Represent the identity as a tensor product of identity matrices with sizes given by the tuple of integers ns.

kron
(other)¶ Construct a new
CanonicalOperator
as the Kronecker product of this and other.


class
pyiga.tensor.
CanonicalTensor
(Xs)¶ A tensor in CP (canonical/PARAFAC) format, i.e., a sum of rank 1 tensors.
For a tensor of order d, Xs should be a tuple of d matrices. Their number of columns should be identical and determines the rank R of the tensor. The number of rows of the jth matrix determines the size of the tensor along the jth axis.
The tensor is given by the sum, for r up to R, of the outer products of the rth columns of the matrices Xs.

asarray
()¶ Convert canonical tensor to a full ndarray.

copy
()¶ Create a deep copy of this tensor.

static
from_tensor
(A)¶ Convert A from other tensor formats to canonical format.

static
from_terms
(terms)¶ Construct a canonical tensor from a list of rank 1 terms, represented as tuples of vectors.

norm
()¶ Compute the Frobenius norm of the tensor.

nway_prod
(Bs)¶ Implements
apply_tprod()
for canonical tensors.Returns: CanonicalTensor
– the result in canonical format

static
ones
(shape)¶ Construct a constant canonical tensor with all entries one and the given shape.

ravel
()¶ Return the vectorization of this tensor.

squeeze
(axis=None)¶ Eliminate singleton axes. Equivalent to
numpy.squeeze()
.

terms
()¶ Return the rank one components as a list of tuples.

static
zeros
(shape)¶ Construct a zero canonical tensor with the given shape.


class
pyiga.tensor.
TensorProd
(*Xs)¶ Represents the abstract tensor product of an arbitrary number of tensors.

asarray
()¶ Convert sum of tensors to a full ndarray.

nway_prod
(Bs)¶ Implements
apply_tprod()
for tensor products.Returns: TensorProd
– the result as a tensor product

ravel
()¶ Return the vectorization of this tensor.


class
pyiga.tensor.
TensorSum
(*Xs)¶ Represents the abstract sum of an arbitrary number of tensors with identical shapes.

asarray
()¶ Convert sum of tensors to a full ndarray.

nway_prod
(Bs)¶ Implements
apply_tprod()
for sums of tensors.Returns: TensorSum
– the result as a sum of tensors

ravel
()¶ Return the vectorization of this tensor.


class
pyiga.tensor.
TuckerTensor
(Us, X)¶ A ddimensional tensor in Tucker format is given as a list of d basis matrices
\[U_k \in \mathbb R^{n_k \times m_k}, \qquad k=1,\ldots,d\]and a (typically small) core coefficient tensor
\[X \in \mathbb R^{m_1 \times \ldots \times m_d}.\]When expanded (using
TuckerTensor.asarray()
), a Tucker tensor turns into a full tensor\[A \in \mathbb R^{n_1 \times \ldots \times n_d}.\]One way to compute a Tucker tensor approximation from a full tensor is to first compute the HOSVD using
hosvd()
and then truncate it usingTuckerTensor.truncate()
to the rank estimated byfind_truncation_rank()
. Such a rank compression is implemented inTuckerTensor.compress()
.
asarray
()¶ Convert Tucker tensor to a full ndarray.

compress
(tol=1e15, rtol=1e15)¶ Approximate this Tucker tensor by another one of smaller rank, up to an absolute error tolerance tol or a relative error tolerance rtol.
Returns: the approximation as a TuckerTensor

copy
()¶ Create a deep copy of this tensor.

static
from_tensor
(A)¶ Convert A from other tensor formats to Tucker format.

norm
()¶ Compute the Frobenius norm of the tensor.

nway_prod
(Bs)¶ Implements
apply_tprod()
for Tucker tensors.Returns: TuckerTensor
– the result in Tucker format

static
ones
(shape)¶ Construct a constant Tucker tensor with all entries one and the given shape.

orthogonalize
()¶ Compute an equivalent Tucker representation of the current tensor where the matrices U have orthonormal columns.
Returns: TuckerTensor
– the orthonormalized Tucker tensor

ravel
()¶ Return the vectorization of this tensor.

squeeze
(axis=None)¶ Eliminate singleton axes. Equivalent to
numpy.squeeze()
.

truncate
(k)¶ Truncate a Tucker tensor T to the given rank k.

static
zeros
(shape)¶ Construct a zero Tucker tensor with the given shape.


pyiga.tensor.
als
(A, R, tol=1e10, maxiter=10000, startval=None)¶ Compute best rank R approximation to tensor A using Alternating Least Squares.
Parameters:  A (tensor) – the tensor to be approximated
 R (int) – the desired rank
 tol (float) – tolerance for the stopping criterion
 maxiter (int) – maximum number of iterations
 startval – starting tensor for iteration. By default, a random rank R
tensor is used. A
CanonicalTensor
with rank R may be supplied for startval instead.
Returns: CanonicalTensor
– a rank R approximation to A; generally close to the best rank R approximation if the algorithm converged to a small enough tolerance.

pyiga.tensor.
als1
(A, tol=1e15)¶ Compute best rank 1 approximation to tensor A using Alternating Least Squares.
Parameters:  A (tensor) – the tensor to be approximated
 tol (float) – tolerance for the stopping criterion
Returns: A tuple of vectors (x1, …, xd) such that
outer(x1, ..., xd)
is the approximate best rank 1 approximation to A.

pyiga.tensor.
als1_ls
(A, B, tol=1e15, maxiter=10000, spd=False)¶ Compute rank 1 approximation to the solution of a linear system by Alternating Least Squares.

pyiga.tensor.
als1_ls_structured
(A, B, tol=1e15, maxiter=10000)¶ Compute rank 1 approximation to the solution of a linear system by Alternating Least Squares.
Faster version of
als1_ls()
, but works only if all the matrices in the operator A have identical sparsity structure.

pyiga.tensor.
apply_tprod
(ops, A)¶ Apply multiway tensor product of operators to tensor A.
Parameters:  ops (seq) – a list of matrices, sparse matrices, or LinearOperators
 A (tensor) – the tensor to apply the multiway tensor product to
Returns: a new tensor with the same number of axes as A that is the result of applying the tensor product operator
ops[0] x ... x ops[1]
to A. The return type is typically the same type as A.The initial dimensions of A must match the sizes of the operators, but A is allowed to have an arbitrary number of trailing dimensions.
None
is a valid operator and is treated like the identity.An interpretation of this operation is that the Kronecker product of the matrices ops is applied to the vectorization of the tensor A.

pyiga.tensor.
array_outer
(*xs)¶ Outer product of an arbitrary number of ndarrays.
Parameters: xs – an arbitrary number of input ndarrays Returns: ndarray – the outer product of the inputs. Its shape is the concatenation of the shapes of the inputs.

pyiga.tensor.
asarray
(X)¶ Return the tensor X as a full ndarray.

pyiga.tensor.
find_truncation_rank
(X, tol=1e12)¶ A greedy algorithm for finding a good truncation rank for a HOSVD core tensor.

pyiga.tensor.
fro_norm
(X)¶ Compute the Frobenius norm of the tensor X.

pyiga.tensor.
grou
(B, R, tol=1e12, return_errors=False)¶ Canonical tensor approximation by Greedy Rank One Updates.
References
https://doi.org/10.1016/j.cam.2019.03.002
Parameters:  B (tensor) – the tensor to be approximated
 R (int) – the desired canonical rank for the approximation
 tol (double) – the desired absolute error tolerance
 return_errors (bool) – whether to return the error history as a second return value
Returns: The computed approximation as a
CanonicalTensor
. If return_errors is true, instead returns a tuple containing the tensor and a list of the error history over the iterations.

pyiga.tensor.
gta
(A, R, tol=1e12, rtol=1e12, return_errors=False)¶ Greedy Tucker approximation of the tensor A.
References
https://doi.org/10.1016/j.cam.2019.03.002
Parameters:  A (tensor) – the tensor to be approximated
 R (int) – the desired multilinear rank of the approximation
 tol (double) – target absolute error tolerance
 rtol (double) – target relative error tolerance
 return_errors (bool) – whether to return the error history as a second return value
Returns: The computed approximation as a
TuckerTensor
. If return_errors is true, instead returns a tuple containing the tensor and a list of the error history over the iterations.

pyiga.tensor.
gta_ls
(A, F, R, tol=1e12, verbose=0, gs=None, spd=False)¶ Greedy Tucker approximation of the solution of a linear system A U = F.
References
https://doi.org/10.1016/j.cam.2019.03.002
Parameters:  A (list) – the linear operator in low Kronecker rank format given as a list of tuples. Each tuple represents a Kronecker product operator and contains d matrices or linear operators; the operator is considered as the Kronecker product of these operators
 F (tensor) – the righthand side of the linear system as a (possibly lowrank) tensor
 R (int) – the desired multilinear rank of the approximation (number of iterations)
 tol (double) – desired reduction of the initial residual
 verbose (int) – 0 = no printed output, 1 = moderate detail, 2 = full detail
 gs (int) – if this is not None, then this many GaussSeidel iterations are used on the core linear system instead of direct solution; see the paper for details
 spd (bool) – pass True if A is a symmetric positive definite operator; uses a
more efficient and accurate rank 1 approximation algorithm (see the corresponding
parameter of
als1_ls()
)
Returns: the computed approximation as a
TuckerTensor

pyiga.tensor.
hosvd
(X)¶ Compute higherorder SVD (Tucker decomposition).
Parameters: X (ndarray) – a full tensor of arbitrary size Returns: TuckerTensor
– a Tucker tensor which represents X with the core tensor having the same shape as X and the factor matrices Uk being square and orthogonal.

pyiga.tensor.
join_tucker_bases
(T1, T2)¶ Represent the two Tucker tensors T1 and T2 in a joint basis.
Returns: tuple – (U,X1,X2) such that T1 == TuckerTensor(U,X1)
andT2 == TuckerTensor(U,X2)
. The basis U is the concatenation of the bases of T1 and T2.

pyiga.tensor.
matricize
(X, k)¶ Return the modek matricization of the ndarray X.

pyiga.tensor.
modek_tprod
(B, k, X)¶ Compute the modek tensor product of the ndarray X with the matrix or operator B.
Parameters:  B – an ndarray, sparse matrix, or LinearOperator of size m x nk
 k (int) – the mode along which to multiply X
 X (ndarray) – tensor with
X.shape[k] == nk
Returns: ndarray – the modek tensor product of size (n1, … nk1, m, nk+1, …, nN)

pyiga.tensor.
outer
(*xs)¶ Outer product of an arbitrary number of vectors.
Parameters: xs – d input vectors (x1, …, xd) with lengths n1, …, nd Returns: ndarray – the outer product as an ndarray with d dimensions

pyiga.tensor.
pad
(X, pad_width)¶ Pad a tensor with zero rows in each direction.
Parameters: pad_width (list) – a list of (before,after) tuples, the same length as dimensions of X, which specifices how many zeros to prepend/append in each direction. None is admissible and is equivalent to (0,0). Returns: the padded tensor