=============
API reference
=============

:mod:`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 (:func:`tensorly.tensor` in this case).

.. automodule:: tensorly
    :no-members:
    :no-inherited-members:

Setting the backend
-------------------

.. autosummary::
    :toctree: generated
    :template: function.rst

    set_backend
    get_backend
    backend_context

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
    kron
    solve
    qr
    kr
    partial_svd


:mod:`tensorly.base`: Core tensor functions
============================================

.. 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


:mod:`tensorly.cp_tensor`: Tensors in CP form
=============================================

.. 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
    unfolding_dot_khatri_rao


:mod:`tensorly.tucker_tensor`: Tensors in Tucker form
=====================================================

.. 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


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

.. 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


:mod:`tensorly.tt_matrix`: Matrices in TT form
==============================================

.. 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


:mod:`tensorly.parafac2_tensor`: Tensors in PARAFAC2 form
=========================================================

.. 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


:mod:`tensorly.tenalg`: Tensor Algebra
======================================

Available functions
-------------------

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

.. automodule:: tensorly.tenalg
    :no-members:
    :no-inherited-members:

.. currentmodule:: tensorly.tenalg

.. autosummary::
    :toctree: generated/
    :template: function.rst

    khatri_rao
    kronecker
    mode_dot
    multi_mode_dot
    proximal.soft_thresholding
    proximal.svd_thresholding
    proximal.procrustes
    inner
    contract
    tensor_dot
    batched_tensor_dot
    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_tenalg_backend
    get_tenalg_backend
    tenalg_backend_context


:mod:`tensorly.decomposition`: Tensor 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

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
    robust_pca
    tensor_train
    tensor_train_matrix
    parafac2


:mod:`tensorly.regression`: Tensor Regression
==============================================

.. automodule:: tensorly.regression
    :no-members:
    :no-inherited-members:

.. currentmodule:: tensorly.regression

.. autosummary::
    :toctree: generated/
    :template: class.rst

    tucker_regression.TuckerRegressor
    cp_regression.CPRegressor


:mod:`tensorly.metrics`: Performance measures
==============================================

.. automodule:: tensorly.metrics
    :no-members:
    :no-inherited-members:

.. currentmodule:: tensorly.metrics

.. autosummary::
    :toctree: generated/
    :template: function.rst

    regression.MSE
    regression.RMSE
    factors.congruence_coefficient


:mod:`tensorly.random`: Sampling tensors
========================================

.. 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



:mod:`tensorly.datasets`: Datasets
==================================

.. automodule:: tensorly.datasets
    :no-members:
    :no-inherited-members:

.. currentmodule:: tensorly.datasets

.. autosummary::
    :toctree: generated/
    :template: function.rst

    synthetic.gen_image


:mod:`tensorly.contrib`: Experimental features
==============================================

.. automodule:: tensorly.contrib
    :no-members:
    :no-inherited-members:

.. currentmodule:: tensorly.contrib

.. autosummary::
    :toctree: generated/
    :template: function.rst

    decomposition.tensor_train_cross

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