https://github.com/tensorly/tensorly
api.rst
=============
API reference
=============
Unified backend interface (:mod:`tensorly`)
===========================================
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 (:func:`tensorly.tensor` in this case).
.. automodule:: tensorly
:no-members:
:no-inherited-members:
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.
.. autosummary::
:toctree: generated
:template: function.rst
set_backend
get_backend
backend_context
use_dynamic_dispatch
use_static_dispatch
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.
.. autosummary::
:toctree: generated
:template: function.rst
context
is_tensor
to_numpy
eps
finfo
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)``.
.. autosummary::
:toctree: generated
:template: function.rst
index_update
index
Available backend functions
---------------------------
For each backend, tensorly provides the following uniform functions:
Array creation
++++++++++++++
.. autosummary::
:toctree: generated
:template: function.rst
tensor
ones
zeros
zeros_like
eye
diag
check_random_state
Array manipulation
++++++++++++++++++
.. autosummary::
:toctree: generated
:template: function.rst
shape
ndim
copy
concatenate
conj
reshape
transpose
moveaxis
arange
where
clip
max
min
argmax
argmin
all
mean
sum
prod
sign
abs
sqrt
norm
stack
sort
Algebraic operations
++++++++++++++++++++
.. autosummary::
:toctree: generated
:template: function.rst
dot
matmul
tensordot
kron
solve
qr
kr
Core functions (:mod:`tensorly.base`)
=====================================
.. automodule:: tensorly.base
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.base
.. autosummary::
:toctree: generated/
:template: function.rst
unfold
fold
tensor_to_vec
vec_to_tensor
partial_unfold
partial_fold
partial_tensor_to_vec
partial_vec_to_tensor
Tensors in CP form (:mod:`tensorly.cp_tensor`)
==============================================
.. automodule:: tensorly.cp_tensor
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.cp_tensor
.. autosummary::
:toctree: generated/
:template: function.rst
cp_to_tensor
cp_to_unfolded
cp_to_vec
cp_normalize
cp_norm
cp_mode_dot
cp_permute_factors
Tensors in Tucker form (:mod:`tensorly.tucker_tensor`)
======================================================
.. automodule:: tensorly.tucker_tensor
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.tucker_tensor
.. autosummary::
:toctree: generated/
:template: function.rst
tucker_to_tensor
tucker_to_unfolded
tucker_to_vec
tucker_mode_dot
Tensors in TT (MPS) form (:mod:`tensorly.tt_tensor`)
====================================================
.. automodule:: tensorly.tt_tensor
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.tt_tensor
.. autosummary::
:toctree: generated/
:template: function.rst
tt_to_tensor
tt_to_unfolded
tt_to_vec
pad_tt_rank
Matrices in TT form (:mod:`tensorly.tt_matrix`)
===============================================
.. automodule:: tensorly.tt_matrix
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.tt_matrix
.. autosummary::
:toctree: generated/
:template: function.rst
tt_matrix_to_tensor
tt_matrix_to_unfolded
tt_matrix_to_vec
Tensors in PARAFAC2 form (:mod:`tensorly.parafac2_tensor`)
==========================================================
.. automodule:: tensorly.parafac2_tensor
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.parafac2_tensor
.. autosummary::
:toctree: generated/
:template: function.rst
parafac2_to_tensor
parafac2_to_slice
parafac2_to_slices
parafac2_to_unfolded
parafac2_to_vec
Tensor Algebra (:mod:`tensorly.tenalg`)
=======================================
Available functions
-------------------
TensorLy provides you with all the tensor algebra functions you need:
.. automodule:: tensorly.tenalg
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.tenalg
A unified SVD interface:
.. autosummary::
:toctree: generated/
:template: function.rst
svd_interface
Other tensor algebraic functionalities:
.. autosummary::
:toctree: generated/
:template: function.rst
khatri_rao
unfolding_dot_khatri_rao
kronecker
mode_dot
multi_mode_dot
proximal.soft_thresholding
proximal.svd_thresholding
proximal.procrustes
inner
outer
batched_outer
tensordot
higher_order_moment
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!
.. autosummary::
:toctree: generated/
:template: function.rst
set_backend
get_backend
backend_context
Tensor Decomposition (:mod:`tensorly.decomposition`)
====================================================
.. automodule:: tensorly.decomposition
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.decomposition
Classes
-------
Note that these are currently experimental and may change in the future.
.. autosummary::
:toctree: generated/
:template: class.rst
CP
RandomizedCP
CPPower
CP_NN_HALS
Tucker
TensorTrain
Parafac2
SymmetricCP
ConstrainedCP
TensorTrain
TensorRing
TensorTrainMatrix
Functions
---------
.. autosummary::
:toctree: generated/
:template: function.rst
parafac
power_iteration
parafac_power_iteration
symmetric_power_iteration
symmetric_parafac_power_iteration
non_negative_parafac
non_negative_parafac_hals
sample_khatri_rao
randomised_parafac
tucker
partial_tucker
non_negative_tucker
non_negative_tucker_hals
robust_pca
tensor_train
tensor_train_matrix
tensor_ring
parafac2
constrained_parafac
Tensor Regression (:mod:`tensorly.regression`)
==============================================
.. automodule:: tensorly.regression
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.regression
.. autosummary::
:toctree: generated/
:template: class.rst
tucker_regression.TuckerRegressor
cp_regression.CPRegressor
CP_PLSR
Performance measures (:mod:`tensorly.metrics`)
==============================================
.. automodule:: tensorly.metrics
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.metrics
.. autosummary::
:toctree: generated/
:template: function.rst
regression.MSE
regression.RMSE
factors.congruence_coefficient
correlation_index
Sampling tensors (:mod:`tensorly.random`)
=========================================
.. automodule:: tensorly.random
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.random
.. autosummary::
:toctree: generated/
:template: function.rst
random_cp
random_tucker
random_tt
random_tt_matrix
random_parafac2
Datasets (:mod:`tensorly.datasets`)
===================================
.. automodule:: tensorly.datasets
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.datasets
.. autosummary::
:toctree: generated/
:template: function.rst
synthetic.gen_image
load_IL2data
load_covid19_serology
load_indian_pines
load_kinetic
Plugin functionalities (:mod:`tensorly.plugins`)
================================================
Automatically cache the optimal contraction path when using the `einsum` tensor algebra backend
.. automodule:: tensorly.plugins
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.plugins
.. autosummary::
:toctree: generated/
:template: function.rst
use_opt_einsum
use_default_einsum
use_cuquantum
Experimental features (:mod:`tensorly.contrib`)
===============================================
.. automodule:: tensorly.contrib
:no-members:
:no-inherited-members:
.. currentmodule:: tensorly.contrib
.. autosummary::
:toctree: generated/
:template: function.rst
decomposition.tensor_train_cross
decomposition.tensor_train_OI
Sparse tensors
--------------
The :mod:`tensorly.contrib.sparse` module enables tensor operations on sparse tensors.
Currently, the following decomposition methods are supported (for the NumPy backend, using Sparse):
.. automodule:: tensorly.contrib.sparse
.. currentmodule:: tensorly.contrib
.. autosummary::
:toctree: generated/
sparse.decomposition.tucker
sparse.decomposition.partial_tucker
sparse.decomposition.non_negative_tucker
sparse.decomposition.robust_pca
sparse.decomposition.parafac
sparse.decomposition.non_negative_parafac
sparse.decomposition.symmetric_parafac_power_iteration