API reference

Unified backend interface (tensorly)

There are several libraries for multi-dimensional array computation, including NumPy, PyTorch, TensorFlow, JAX, CuPy and Paddle. 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

You can simply call set_backend('pytorch') to set the backend to PyTorch, and similarly for NumPy, JAX, etc. You can also use the context manager backend_context if you want to execute a block of code with a different backend.

set_backend(backend[, local_threadsafe])

Changes the backend to the specified one

get_backend()

Returns the name (str) of the currently used backend

backend_context(backend[, local_threadsafe])

Context manager to set the backend for TensorLy.

use_dynamic_dispatch()

Dispatch all backend functions dynamically to enable changing backend during runtime

use_static_dispatch()

Switch to static dispatching: backend functions no longer will be dynamically dispatched.

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)

is_tensor(tensor)

to_numpy(tensor)

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[, dtype])

ones(shape[, dtype, order, device, like])

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

zeros(shape[, dtype, order, like])

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

zeros_like(a[, dtype, order, subok, shape, ...])

Return an array of zeros with the same shape and type as a given array.

eye(N[, M, k, dtype, order, device, like])

Return a 2-D array 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(a)

Return the shape of an array.

ndim(tensor)

copy(a[, order, subok])

Return an array copy of the given object.

concatenate([axis, out, dtype, casting])

Join a sequence of arrays along an existing axis.

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

Return the complex conjugate, element-wise.

reshape(a, /[, shape, order, newshape, copy])

Gives a new shape to an array without changing its data.

transpose(a[, axes])

Returns an array with axes transposed.

moveaxis(a, source, destination)

Move axes of an array to new positions.

arange([start,] stop[, step,][, dtype, ...])

Return evenly spaced values within a given interval.

where(condition, [x, y], /)

Return elements chosen from x or y depending on condition.

clip(tensor[, a_min, a_max])

max(a[, axis, out, keepdims, initial, where])

Return the maximum of an array or maximum along an axis.

min(a[, axis, out, keepdims, initial, where])

Return the minimum of an array or minimum along an axis.

argmax(a[, axis, out, keepdims])

Returns the indices of the maximum values along an axis.

argmin(a[, axis, out, keepdims])

Returns the indices of the minimum values along an axis.

all(a[, axis, out, keepdims, where])

Test whether all array elements along a given axis evaluate to True.

mean(a[, axis, dtype, out, keepdims, where])

Compute the arithmetic mean along the specified axis.

sum(a[, axis, dtype, out, keepdims, ...])

Sum of array elements over a given axis.

prod(a[, axis, dtype, out, keepdims, ...])

Return the product of array elements over a given axis.

sign(x, /[, out, where, casting, order, ...])

Returns an element-wise indication of the sign of a number.

abs(x, /[, out, where, casting, order, ...])

Calculate the absolute value element-wise.

sqrt(x, /[, out, where, casting, order, ...])

Return the non-negative square-root of an array, element-wise.

norm(tensor[, order, axis])

Computes the l-order norm of a tensor.

stack(arrays[, axis, out, dtype, casting])

Join a sequence of arrays along a new axis.

sort(a[, axis, kind, order, stable])

Return a sorted copy of an array.

Algebraic operations

dot(a, b[, out])

Dot product of two arrays.

matmul(x1, x2, /[, out, casting, order, ...])

Matrix product of two arrays.

tensordot(a, b[, axes])

Compute tensor dot product along specified axes.

kron(a, b)

Kronecker product of two arrays.

solve(a, b)

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

qr(a[, mode])

Compute the qr factorization of a matrix.

kr(matrices[, weights, mask])

Core functions (tensorly.base)

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

Tensors in CP form (tensorly.cp_tensor)

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

cp_permute_factors(ref_cp_tensor, ...)

Compares factors of a reference cp tensor with factors of other another tensor (or list of tensor) in order to match component order.

Tensors in Tucker form (tensorly.tucker_tensor)

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. a matrix).

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

Tensors in TT (MPS) form (tensorly.tt_tensor)

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

pad_tt_rank(factor_list[, n_padding, ...])

Pads the factors of a Tensor-Train so as to increase its rank without changing its reconstruction

Matrices in TT form (tensorly.tt_matrix)

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

Tensors in PARAFAC2 form (tensorly.parafac2_tensor)

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.

Tensor Algebra (tensorly.tenalg)

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.

A unified SVD interface:

svd_interface(matrix[, method, n_eigenvecs, ...])

Dispatching function to various SVD algorithms, alongside additional properties such as resolving sign invariance, imputation, and non-negativity.

Other tensor algebraic functionalities:

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

Khatri-Rao product of a list of matrices

unfolding_dot_khatri_rao(tensor, cp_tensor, mode)

mode-n unfolding times khatri-rao product of factors

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

inner(tensor1, tensor2[, n_modes])

Generalised inner products between tensors

outer(tensors)

Returns a generalized outer product of the two tensors

batched_outer(tensors)

Returns a generalized outer product of the two tensors

tensordot(tensor1, tensor2, modes[, ...])

Batched tensor contraction between two tensors on specified modes

higher_order_moment(tensor, order)

Computes the Higher-Order Momemt

proximal.soft_thresholding(tensor, threshold)

Soft-thresholding operator

proximal.svd_thresholding(matrix, threshold)

Singular value thresholding operator

proximal.procrustes(matrix)

Procrustes operator

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_backend(backend[, local_threadsafe])

Changes the backend to the specified one

get_backend()

Returns the name (str) of the currently used backend

backend_context(backend[, local_threadsafe])

Context manager to set the backend for TensorLy.

Tensor Decomposition (tensorly.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, 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, init, svd, ...])

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

Tucker([rank, n_iter_max, init, ...])

Tucker decomposition via Higher Order Orthogonal Iteration (HOI).

TensorTrain(rank[, svd, verbose])

Decompose a tensor into a matrix in tt-format

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

ConstrainedCP(rank[, n_iter_max, ...])

CANDECOMP/PARAFAC decomposition via alternating optimization of alternating direction method of multipliers (AO-ADMM):

TensorTrain(rank[, svd, verbose])

Decompose a tensor into a matrix in tt-format

TensorRing(rank[, mode, svd, verbose])

Tensor Ring decomposition via recursive SVD

TensorTrainMatrix(rank[, svd, verbose])

TT decomposition via recursive SVD

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 [Rfe3f26443c3b-3]

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

Tucker decomposition via Higher Order Orthogonal Iteration (HOI)

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

Partial tucker decomposition via Higher Order Orthogonal Iteration (HOI)

non_negative_tucker(tensor, rank[, ...])

Non-negative Tucker decomposition

non_negative_tucker_hals(tensor, rank[, ...])

Non-negative Tucker decomposition with HALS

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

Robust Tensor PCA via ALM with support for missing values

tensor_train(input_tensor, rank[, svd, verbose])

TT decomposition via recursive SVD

tensor_train_matrix(tensor, rank[, svd, verbose])

Decompose a tensor into a matrix in tt-format

tensor_ring(input_tensor, rank[, mode, svd, ...])

Tensor Ring decomposition via recursive SVD

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

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

constrained_parafac(tensor, rank[, ...])

CANDECOMP/PARAFAC decomposition via alternating optimization of alternating direction method of multipliers (AO-ADMM):

Preprocessing (tensorly.preprocessing)

svd_compress_tensor_slices(tensor_slices[, ...])

Compress data with the SVD for running PARAFAC2.

svd_decompress_parafac2_tensor(...)

Decompress the factors obtained by fitting PARAFAC2 on SVD-compressed data

Tensor Regression (tensorly.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

CP_PLSR(n_components[, tol, n_iter_max, ...])

CP tensor regression

Solvers (tensorly.solvers)

Tensorly provides with efficient solvers for nonnegative least squares problems which are crucial to nonnegative tensor decomposition, as well as a generic admm solver useful for constrained decompositions. Several proximal (projection) operators are located in tenalg.

nnls.hals_nnls(UtM, UtU[, V, n_iter_max, ...])

Non Negative Least Squares (NNLS)

nnls.fista(UtM, UtU[, x, n_iter_max, ...])

Fast Iterative Shrinkage Thresholding Algorithm (FISTA), see [R60421ea27cb4-1]

nnls.active_set_nnls(Utm, UtU[, x, ...])

Active set algorithm for non-negative least square solution, see [R2a23de012289-1]

admm.admm(UtM, UtU, x, dual_var[, ...])

Alternating direction method of multipliers (ADMM) algorithm to minimize a quadratic function under convex constraints.

Performance measures (tensorly.metrics)

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)

factors.congruence_coefficient(matrix1, matrix2)

Compute the optimal mean (Tucker) congruence coefficient between the columns of two matrices.

correlation_index(factors_1, factors_2[, ...])

CorrIndex implementation to assess tensor decomposition outputs.

Sampling tensors (tensorly.random)

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

Datasets (tensorly.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

load_IL2data()

Loads tensor of IL-2 mutein treatment responses.

load_covid19_serology()

Load an example dataset of COVID-19 systems serology.

load_indian_pines()

Loads Indian pines hyperspectral data from tensorly datasets and returns it as a bunch.

load_kinetic()

Loads the kinetic fluorescence dataset (X60t) as a tensorly tensor.

Plugin functionalities (tensorly.plugins)

Automatically cache the optimal contraction path when using the einsum tensor algebra backend

use_opt_einsum([optimize])

Plugin to use opt-einsum [R7bf64e8a9b16-1] to precompute (and cache) a better contraction path

use_default_einsum()

Revert to the original einsum for the current backend

use_cuquantum([optimize])

Plugin to use cuQuantum to precompute (and cache) a better contraction path

Experimental features (tensorly.contrib)

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]

decomposition.tensor_train_OI(data_tensor, rank)

Perform tensor-train orthogonal iteration (TTOI) [R2611546cc1a1-1] for tensor train decomposition

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, rank)

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