Revision a628f79cfbcb1a6b553cb2657aa44177067ac885 authored by Aaron Meyer on 21 September 2022, 18:21:55 UTC, committed by GitHub on 21 September 2022, 18:21:55 UTC
Adding an implementation of tensor PLS.
2 parent s fd5ef2e + b17f3ba
Raw File
Tip revision: a628f79cfbcb1a6b553cb2657aa44177067ac885 authored by Aaron Meyer on 21 September 2022, 18:21:55 UTC
Merge pull request #435 from meyer-lab/plsr
Tip revision: a628f79
.. image::

.. image::   

.. image::

.. image::

.. image::


TensorLy is a Python library that aims at making tensor learning simple and accessible. It allows to easily perform tensor decomposition, tensor learning and tensor algebra. Its backend system allows to seamlessly perform computation with NumPy, PyTorch, JAX, MXNet, TensorFlow or CuPy, and run methods at scale on CPU or GPU.

- **Website:**
- **Source-code:**
- **Jupyter Notebooks:**


Installing TensorLy

The only pre-requisite is to have **Python 3** installed. The easiest way is via the `Anaconda distribution <>`_.

|      **With pip** (recommended)           |         **With conda**                            |
|                                           |                                                   |
| .. code::                                 | .. code::                                         |
|                                           |                                                   |
|   pip install -U tensorly                 |   conda install -c tensorly tensorly              |
|                                           |                                                   |
|                                           |                                                   |
|                               **Development (from git)**                                      |
|                                                                                               |
|          .. code::                                                                            |
|                                                                                               |
|             # clone the repository                                                            |
|             git clone                                    |
|             cd tensorly                                                                       |
|             # Install in editable mode with `-e` or, equivalently, `--editable`               |
|             pip install -e .                                                                  |
|                                                                                               |
**Note:** TensorLy depends on NumPy by default. If you want to use the MXNet or PyTorch backends, you will need to install these packages separately.

For detailed instruction, please see the `documentation <>`_.



Creating tensors

Create a small third order tensor of size 3 x 4 x 2, from a NumPy array and perform simple operations on it:

.. code:: python

   import tensorly as tl
   import numpy as np

   tensor = tl.tensor(np.arange(24).reshape((3, 4, 2)), dtype=tl.float64)
   unfolded = tl.unfold(tensor, mode=0)
   tl.fold(unfolded, mode=0, shape=tensor.shape)

You can also create random tensors:

.. code:: python

   from tensorly import random
   # A random tensor
   tensor = random.random_tensor((3, 4, 2))
   # A random CP tensor in factorized form
   cp_tensor = random.random_tensor(shape=(3, 4, 2), rank='same')

You can also create tensors in TT-format, Tucker, etc, see `random tensors <>`_.

Setting the backend

You can change the backend to perform computation with a different framework. By default, the backend is NumPy, but you can also perform the computation using  PyTorch, TensorFlow, MXNet, JAX or CuPy (requires to have installed them first). For instance, after setting the backend to PyTorch, all the computation is done by PyTorch, and tensors can be created on GPU:

.. code:: python

   tl.set_backend('pytorch') # Or 'mxnet', 'numpy', 'tensorflow', 'cupy' or 'jax'
   tensor = tl.tensor(np.arange(24).reshape((3, 4, 2)), device='cuda:0')
   type(tensor) # torch.Tensor

Tensor decomposition

Applying tensor decomposition is easy:

.. code:: python

   from tensorly.decomposition import tucker
   # Apply Tucker decomposition 
   tucker_tensor = tucker(tensor, rank=[2, 2, 2])
   # Reconstruct the full tensor from the decomposed form
We have `many more decompositions <>`_ available, be sure to check them out!

Next steps
This is just a very quick introduction to some of the basic features of TensorLy. 
For more information on getting started, checkout the `user-guide <>`_  and for a detailed reference of the functions and their documentation, refer to
the `API <>`_   

If you see a bug, open an `issue <>`_, or better yet, a `pull-request <>`_!

Contributing code

All contributions are welcome! So if you have a cool tensor method you want to add, if you spot a bug or even a typo or mistake in the documentation, please report it, and even better, open a Pull-Request on `GitHub <>`_.

Before you submit your changes, you should make sure your code adheres to our style-guide. The easiest way to do this is with `black`:  

.. code:: bash

   pip install black
   black .

Running the tests

Testing and documentation are an essential part of this package and all functions come with uni-tests and documentation.

The tests are ran using the `pytest` package. 
First install `pytest`::

    pip install pytest
Then to run the test, simply run, in the terminal:

.. code::

   pytest -v tensorly
Alternatively, you can specify for which backend you wish to run the tests:

.. code::
   TENSORLY_BACKEND='numpy' pytest -v tensorly



If you use TensorLy in an academic paper, please cite [1]_::

      author  = {Jean Kossaifi and Yannis Panagakis and Anima Anandkumar and Maja Pantic},
      title   = {TensorLy: Tensor Learning in Python},
      journal = {Journal of Machine Learning Research},
      year    = {2019},
      volume  = {20},
      number  = {26},
      pages   = {1-6},
      url     = {}
.. [1] Jean Kossaifi, Yannis Panagakis, Anima Anandkumar and Maja Pantic, **TensorLy: Tensor Learning in Python**, *Journal of Machine Learning Research (JMLR)*, 2019, volume 20, number 26.
back to top