API reference

tensorly: A unified backend interface

There are several libraries for multi-dimensional array computation, including NumPy, PyTorch, MXNet, TensorFlow, JAX and CuPy. They all have strenghs and weaknesses, e.g. some are better on CPU, some better on GPU etc. Therefore, in TensorLy we enable you to use our algorithm (and any code you write using the library), with any of these libraries.

However, while they all loosely follow the API introduced and popularized by NumPy, there are differences. To make switching from one backend to another completely transparent, in TensorLy, we provide a thin wrapper to these libraries. So instead of using PyTorch or NumPy functions (pytorch.tensor or numpy.array for instance), you should only use functions through the backend (tensorly.tensor in this case).

Setting the backend

set_backend(backend[, local_threadsafe])

Changes the backend to the specified one

get_backend()

Returns the name of the current backend

backend_context(backend[, local_threadsafe])

Context manager to set the backend for TensorLy.

Context of a tensor

In TensorLy, we provide some convenient functions to manipulate backend specific information on the tensors (the context of that tensor), including dtype (e.g. float32, float64, etc), its device (e.g. CPU and GPU) where applicable, etc. We also provide functions to check if a tensor is on the current backend, convert to NumPy, etc.

context(tensor)

Returns the context of a tensor

is_tensor(obj)

Returns if obj is a tensor for the current backend

to_numpy(tensor)

Returns a copy of the tensor as a NumPy array.

eps(dtype)

Returns the machine epsilon for a given floating point dtype

finfo(dtype)

Machine limits for floating point types.

Index assignement (“NumPy style”)

While in some backends (e.g. NumPy), you can directly combine indexing and assignement, not all backends support this. Instead of tensor[indices] = values, you should use tensor = tensorly.index_update(tensor, tensorly.index, values).

index_update(tensor, indices, values)

Updates the value of tensors in the specified indices

index

Convenience class used as a an array, to be used with index_update

Available backend functions

For each backend, tensorly provides the following uniform functions:

Array creation

tensor(data, **context)

Tensor class

ones(shape[, dtype])

Return a new tensor of given shape and type, filled with ones.

zeros(shape[, dtype])

Return a new tensor of given shape and type, filled with zeros.

zeros_like(tensor)

Return at tensor of zeros with the same shape and type as a given tensor.

eye(N)

Return a 2-D tensor with ones on the diagonal and zeros elsewhere.

diag(v[, k])

Extract a diagonal or construct a diagonal array.

check_random_state(seed)

Returns a valid RandomState

Array manipulation

shape(tensor)

Return the shape of a tensor

ndim(tensor)

Return the number of dimensions of a tensor

copy(tensor)

Return a copy of the given tensor

concatenate(tensors[, axis])

Concatenate tensors along an axis.

conj(x, /[, out, where, casting, order, …])

Return the complex conjugate, element-wise.

reshape(tensor, newshape)

Gives a new shape to a tensor without changing its data.

transpose(tensor)

Permute the dimensions of a tensor.

moveaxis(tensor, source, destination)

Move axes of a tensor to new positions.

arange([start, stop, step])

Return evenly spaced values within a given interval.

where(condition, x, y)

Return elements, either from x or y, depending on condition.

clip(tensor[, a_min, a_max])

Clip the values of a tensor to within an interval.

max(tensor)

The max value in a tensor.

min(tensor)

The min value in a tensor.

argmax(tensor)

The argument of the max value in a tensor.

argmin(tensor)

The argument of the min value in a tensor.

all(tensor)

Returns if all array elements in a tensor are True.

mean(tensor[, axis])

Compute the mean of a tensor, optionally along an axis.

sum(tensor[, axis])

Compute the sum of a tensor, optionally along an axis.

prod(tensor[, axis])

Compute the product of a tensor, optionally along an axis.

sign(tensor)

Computes the element-wise sign of the given input tensor.

abs(tensor)

Computes the element-wise absolute value of the given input tensor.

sqrt(tensor)

Computes the element-wise sqrt of the given input tensor.

norm(tensor[, order, axis])

Computes the l-order norm of a tensor.

stack(arrays[, axis])

Join a sequence of arrays along a new axis.

sort(tensor, axis[, descending])

Return a sorted copy of an array

Algebraic operations

dot(a, b)

Dot product of two tensors.

kron(a, b)

Kronecker product of two tensors.

solve(a, b)

Solve a linear matrix equation, or system of linear scalar equations.

qr(a)

Compute the qr factorization of a matrix.

kr(matrices[, weights, mask])

Khatri-Rao product of a list of matrices

partial_svd(matrix[, n_eigenvecs, random_state])

Computes a fast partial SVD on matrix

tensorly.base: Core tensor functions

unfold(tensor, mode)

Returns the mode-mode unfolding of tensor with modes starting at 0.

fold(unfolded_tensor, mode, shape)

Refolds the mode-mode unfolding into a tensor of shape shape

tensor_to_vec(tensor)

Vectorises a tensor

vec_to_tensor(vec, shape)

Folds a vectorised tensor back into a tensor of shape shape

partial_unfold(tensor[, mode, skip_begin, …])

Partially unfolds a tensor while ignoring the specified number of dimensions at the beginning and the end.

partial_fold(unfolded, mode, shape[, …])

Re-folds a partially unfolded tensor

partial_tensor_to_vec(tensor[, skip_begin, …])

Partially vectorises a tensor

partial_vec_to_tensor(matrix, shape[, …])

Refolds a partially vectorised tensor into a full one

tensorly.cp_tensor: Tensors in CP form

Core operations on CP tensors.

cp_to_tensor(cp_tensor[, mask])

Turns the Khatri-product of matrices into a full tensor

cp_to_unfolded(cp_tensor, mode)

Turns the khatri-product of matrices into an unfolded tensor

cp_to_vec(cp_tensor)

Turns the khatri-product of matrices into a vector

cp_normalize(cp_tensor)

Returns cp_tensor with factors normalised to unit length

cp_norm(cp_tensor)

Returns the l2 norm of a CP tensor

cp_mode_dot(cp_tensor, matrix_or_vector, mode)

n-mode product of a CP tensor and a matrix or vector at the specified mode

unfolding_dot_khatri_rao(tensor, cp_tensor, mode)

mode-n unfolding times khatri-rao product of factors

tensorly.tucker_tensor: Tensors in Tucker form

Core operations on Tucker tensors.

tucker_to_tensor(tucker_tensor[, …])

Converts the Tucker tensor into a full tensor

tucker_to_unfolded(tucker_tensor[, mode, …])

Converts the Tucker decomposition into an unfolded tensor (i.e.

tucker_to_vec(tucker_tensor[, skip_factor, …])

Converts a Tucker decomposition into a vectorised tensor

tucker_mode_dot(tucker_tensor, …[, …])

n-mode product of a Tucker tensor and a matrix or vector at the specified mode

tensorly.tt_tensor: Tensors in Tensor-Train (MPS) form

Core operations on tensors in Tensor-Train (TT) format, also known as Matrix-Product-State (MPS)

tt_to_tensor(factors)

Returns the full tensor whose TT decomposition is given by ‘factors’

tt_to_unfolded(factors, mode)

Returns the unfolding matrix of a tensor given in TT (or Tensor-Train) format

tt_to_vec(factors)

Returns the tensor defined by its TT format (‘factors’) into

tensorly.tt_matrix: Matrices in TT form

Module for matrices in the TT format

tt_matrix_to_tensor(tt_matrix)

Returns the full tensor whose TT-Matrix decomposition is given by ‘factors’

tt_matrix_to_unfolded(tt_matrix, mode)

Returns the unfolding matrix of a tensor given in TT-Matrix format

tt_matrix_to_vec(tt_matrix)

Returns the tensor defined by its TT-Matrix format (‘factors’) into

tensorly.parafac2_tensor: Tensors in PARAFAC2 form

Core operations on PARAFAC2 tensors whose second mode evolve over their first.

parafac2_to_tensor(parafac2_tensor)

Construct a full tensor from a PARAFAC2 decomposition.

parafac2_to_slice(parafac2_tensor, slice_idx)

Generate a single slice along the first mode from the PARAFAC2 tensor.

parafac2_to_slices(parafac2_tensor[, validate])

Generate all slices along the first mode from a PARAFAC2 tensor.

parafac2_to_unfolded(parafac2_tensor, mode)

Construct an unfolded tensor from a PARAFAC2 decomposition.

parafac2_to_vec(parafac2_tensor)

Construct a vectorized tensor from a PARAFAC2 decomposition.

tensorly.tenalg: Tensor Algebra

Available functions

TensorLy provides you with all the tensor algebra functions you need:

The tensorly.tenalg module contains utilities for Tensor Algebra operations such as khatri-rao or kronecker product, n-mode product, etc.

khatri_rao(matrices[, weights, skip_matrix, …])

Khatri-Rao product of a list of matrices

kronecker(matrices[, skip_matrix, reverse])

Kronecker product of a list of matrices

mode_dot(tensor, matrix_or_vector, mode[, …])

n-mode product of a tensor and a matrix or vector at the specified mode

multi_mode_dot(tensor, matrix_or_vec_list[, …])

n-mode product of a tensor and several matrices or vectors over several modes

proximal.soft_thresholding(tensor, threshold)

Soft-thresholding operator

proximal.svd_thresholding(matrix, threshold)

Singular value thresholding operator

proximal.procrustes(matrix)

Procrustes operator

inner(tensor1, tensor2[, n_modes])

Generalised inner products between tensors

contract(tensor1, modes1, tensor2, modes2)

Tensor contraction between two tensors on specified modes

tensor_dot(tensor1, tensor2)

Returns a generalized outer product of the two tensors

batched_tensor_dot(tensor1, tensor2)

Returns a generalized outer product of the two tensors

higher_order_moment(tensor, order)

Computes the Higher-Order Momemt

Tensor Algebra Backend

For advanced users, you may want to dispatch all the computation to einsum (if available) instead of using our manually optimized functions. In TensorLy, we enable this very easily through our tensor algebra backend. If you have your own library implementing tensor algebraic functions, you could even use it that way!

set_tenalg_backend([backend, local_threadsafe])

Set the current tenalg backend

get_tenalg_backend()

Returns the current backend

tenalg_backend_context(backend[, …])

Context manager to set the backend for TensorLy.

tensorly.decomposition: Tensor Decomposition

The tensorly.decomposition module includes utilities for performing tensor decomposition such as CANDECOMP-PARAFAC and Tucker.

Classes

Note that these are currently experimental and may change in the future.

CP(rank[, n_iter_max, tol, init, svd, …])

Candecomp-Parafac decomposition via Alternating-Least Square

RandomizedCP(rank, n_samples[, n_iter_max, …])

Randomised CP decomposition via sampled ALS

CPPower(rank[, n_repeat, n_iteration, verbose])

CP Decomposition via Robust Tensor Power Iteration

CP_NN_HALS(rank[, n_iter_max, tol, init, …])

Non-Negative Candecomp-Parafac decomposition via Alternating-Least Square

Tucker([rank, n_iter_max, init, svd, tol, …])

Tucker decomposition via Higher Order Orthogonal Iteration (HOI).

TensorTrain(rank[, verbose])

TT decomposition via recursive SVD

Parafac2(rank[, n_iter_max, init, svd, …])

PARAFAC2 decomposition [R08ccc3506ae1-1] of a third order tensor via alternating least squares (ALS)

SymmetricCP(rank[, n_repeat, n_iteration, …])

Symmetric CP Decomposition via Robust Symmetric Tensor Power Iteration

Functions

parafac(tensor, rank[, n_iter_max, init, …])

CANDECOMP/PARAFAC decomposition via alternating least squares (ALS) Computes a rank-rank decomposition of tensor [R2df4af999528-1] such that.

power_iteration(tensor[, n_repeat, …])

A single Robust Tensor Power Iteration

parafac_power_iteration(tensor, rank[, …])

CP Decomposition via Robust Tensor Power Iteration

symmetric_power_iteration(tensor[, …])

A single Robust Symmetric Tensor Power Iteration

symmetric_parafac_power_iteration(tensor, rank)

Symmetric CP Decomposition via Robust Symmetric Tensor Power Iteration

non_negative_parafac(tensor, rank[, …])

Non-negative CP decomposition

non_negative_parafac_hals(tensor, rank[, …])

Non-negative CP decomposition via HALS

sample_khatri_rao(matrices, n_samples[, …])

Random subsample of the Khatri-Rao product of the given list of matrices

randomised_parafac(tensor, rank, n_samples)

Randomised CP decomposition via sampled ALS

tucker(tensor, rank[, fixed_factors, …])

Tucker decomposition via Higher Order Orthogonal Iteration (HOI)

partial_tucker(tensor, modes[, rank, …])

Partial tucker decomposition via Higher Order Orthogonal Iteration (HOI)

non_negative_tucker(tensor, rank[, …])

Non-negative Tucker decomposition

robust_pca(X[, mask, tol, reg_E, reg_J, …])

Robust Tensor PCA via ALM with support for missing values

tensor_train(input_tensor, rank[, verbose])

TT decomposition via recursive SVD

tensor_train_matrix(tensor, rank)

Decompose a tensor into a matrix in tt-format

parafac2(tensor_slices, rank[, n_iter_max, …])

PARAFAC2 decomposition [Ra07d22ce3f71-1] of a third order tensor via alternating least squares (ALS)

tensorly.regression: Tensor Regression

The tensorly.regression module includes classes for performing Tensor Regression.

tucker_regression.TuckerRegressor(weight_ranks)

Tucker tensor regression

cp_regression.CPRegressor(weight_rank[, …])

CP tensor regression

tensorly.metrics: Performance measures

The tensorly.metrics module includes utilities to measure performance (e.g. regression error).

regression.MSE(y_true, y_pred[, axis])

Returns the mean squared error between the two predictions

regression.RMSE(y_true, y_pred[, axis])

Returns the regularised mean squared error between the two predictions (the square-root is applied to the mean_squared_error)

tensorly.random: Sampling tensors

random_cp(shape, rank[, full, orthogonal, …])

Generates a random CP tensor

random_tucker(shape, rank[, full, …])

Generates a random Tucker tensor

random_tt(shape, rank[, full, random_state])

Generates a random TT/MPS tensor

random_tt_matrix(shape, rank[, full, …])

Generates a random tensor in TT-Matrix format

random_parafac2(shapes, rank[, full, …])

Generate a random PARAFAC2 tensor

tensorly.datasets: Datasets

The tensorly.datasets module includes utilities to load datasets and create synthetic data, e.g. for testing purposes.

synthetic.gen_image([region, image_height, …])

Generates an image for regression testing

tensorly.contrib: Experimental features

A module for experimental functions

Allows to add quickly and test new functions for which the API is not necessarily fixed

decomposition.tensor_train_cross(…[, tol, …])

TT (tensor-train) decomposition via cross-approximation (TTcross) [1]

Sparse tensors

The tensorly.contrib.sparse module enables tensor operations on sparse tensors. Currently, the following decomposition methods are supported (for the NumPy backend, using Sparse):

sparse.decomposition.tucker(tensor, rank[, …])

Tucker decomposition via Higher Order Orthogonal Iteration (HOI)

sparse.decomposition.partial_tucker(tensor, …)

Partial tucker decomposition via Higher Order Orthogonal Iteration (HOI)

sparse.decomposition.non_negative_tucker(…)

Non-negative Tucker decomposition

sparse.decomposition.robust_pca(X[, mask, …])

Robust Tensor PCA via ALM with support for missing values

sparse.decomposition.parafac(tensor, rank[, …])

CANDECOMP/PARAFAC decomposition via alternating least squares (ALS) Computes a rank-rank decomposition of tensor [R8eaaee98a9c3-1] such that.

sparse.decomposition.non_negative_parafac(…)

Non-negative CP decomposition

sparse.decomposition.symmetric_parafac_power_iteration(…)

Symmetric CP Decomposition via Robust Symmetric Tensor Power Iteration