.. image:: https://badge.fury.io/py/tensorly.svg :target: https://badge.fury.io/py/tensorly

.. image:: https://anaconda.org/tensorly/tensorly/badges/version.svg
:target: https://anaconda.org/tensorly/tensorly

.. image:: https://github.com/tensorly/tensorly/actions/workflows/test.yml/badge.svg?branch=main :target: https://github.com/tensorly/tensorly/actions/workflows/test.yml

.. image:: https://codecov.io/gh/tensorly/tensorly/branch/master/graph/badge.svg?token=mnZ234sGSA :target: https://codecov.io/gh/tensorly/tensorly

.. image:: https://img.shields.io/badge/Slack-join-brightgreen :target: https://join.slack.com/t/tensorly/shared_invite/zt-wqnts2sk-wbiRX6ml~Xt6~GDYWRPFfg

======== TensorLy

TensorLy 是一个 Python 库，旨在使张量学习变得简单易用。它能够轻松地进行张量分解、张量学习和张量代数运算。其后端系统支持无缝地使用 NumPy、PyTorch、JAX、TensorFlow、CuPy 或 Paddle 进行计算，并且可以在 CPU 或 GPU 上大规模运行相关方法。

• 官网: https://tensorly.org
• 源代码: https://github.com/tensorly/tensorly
• Jupyter 笔记本: https://github.com/JeanKossaifi/tensorly-notebooks

---

安装 TensorLy

唯一的先决条件是已安装 Python 3。最简单的方式是通过 Anaconda 发行版 <https://www.anaconda.com/download/>_。

+-------------------------------------------+---------------------------------------------------+ |     使用 pip（推荐） |         使用 conda | +-------------------------------------------+---------------------------------------------------+ | | | | .. code:: | .. code:: | | | | | pip install -U tensorly | conda install -c tensorly tensorly | | | | | | | +-------------------------------------------+---------------------------------------------------+ | 开发版本（从 git 克隆） | +-------------------------------------------+---------------------------------------------------+ | | | .. code:: | | | | # 克隆仓库 | | git clone https://github.com/tensorly/tensorly | | cd tensorly | | # 使用 -e 或等价的 --editable 以可编辑模式安装 | | pip install -e . | | | +-----------------------------------------------------------------------------------------------+

注意: TensorLy 默认依赖 NumPy。如果希望使用其他后端，则需要单独安装相应的库。

有关详细说明，请参阅 文档 <http://tensorly.org/dev/installation.html>_。

---

快速入门

创建张量

从 NumPy 数组创建一个 3×4×2 的小型三阶张量，并对其进行简单操作：

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

你也可以创建随机张量：

.. code:: python

from tensorly import random

随机张量

tensor = random.random_tensor((3, 4, 2))

因子分解形式的随机 CP 张量

cp_tensor = random.random_tensor(shape=(3, 4, 2), rank='same')

此外，还可以创建 TT 格式、Tucker 等格式的张量，详情请参阅 随机张量 <http://tensorly.org/stable/modules/api.html#module-tensorly.random>_。

设置后端

你可以更改后端，以便使用不同的框架进行计算。默认情况下，后端为 NumPy，但你也可以使用 PyTorch、TensorFlow、JAX、CuPy 或 Paddle 进行计算（需提前安装这些库）。例如，将后端设置为 PyTorch 后，所有计算都将由 PyTorch 完成，张量也可以在 GPU 上创建：

.. code:: python

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

张量分解

应用张量分解非常容易：

.. code:: python

from tensorly.decomposition import tucker

应用 Tucker 分解

tucker_tensor = tucker(tensor, rank=[2, 2, 2])

从分解形式重建完整张量

tl.tucker_to_tensor(tucker_tensor)

我们还提供了 更多分解方法 <http://tensorly.org/stable/modules/api.html#module-tensorly.decomposition>_，欢迎查阅！

后续步骤

以上只是对 TensorLy 一些基本功能的简要介绍。 如需了解更多入门信息，请查看 用户指南 <http://tensorly.org/dev/user_guide/index.html>；如需函数及其文档的详细参考，请参阅 API 文档 <http://tensorly.org/dev/modules/api.html>

如果您发现任何错误，请提交 问题 <https://github.com/tensorly/tensorly/issues>，或者更好的是，直接提交 拉取请求 <https://github.com/tensorly/tensorly/pulls>！

---

贡献代码

我们欢迎所有贡献！如果您有一个很棒的张量方法想要添加，或者发现了 bug，甚至是文档中的错别字或错误，请及时报告，更理想的做法是在 GitHub <https://github.com/tensorly/tensorly/> 上提交拉取请求。

在提交更改之前，您应该确保代码符合我们的编码规范。最简单的方法是使用 black 工具：

.. code:: bash

pip install black black .

运行测试

测试和文档是本项目的重要组成部分，所有函数都附带单元测试和文档。

测试使用 pytest 包运行。
首先安装 pytest::

pip install pytest

然后，在终端中运行以下命令即可执行测试：

.. code::

pytest -v tensorly

或者，你也可以指定要针对哪个后端运行测试：

.. code::

TENSORLY_BACKEND='numpy' pytest -v tensorly

---

引用

如果你在学术论文中使用了 TensorLy，请引用 [1]_::

@article{tensorly,
  author  = {Jean Kossaifi 和 Yannis Panagakis 和 Anima Anandkumar 和 Maja Pantic},
  title   = {TensorLy：Python 中的张量学习},
  journal = {机器学习研究期刊},
  year    = {2019},
  volume  = {20},
  number  = {26},
  pages   = {1-6},
  url     = {http://jmlr.org/papers/v20/18-277.html}
}

.. [1] Jean Kossaifi、Yannis Panagakis、Anima Anandkumar 和 Maja Pantic，《TensorLy：Python 中的张量学习》，《机器学习研究期刊（JMLR）》，2019 年，第 20 卷，第 26 号。

TensorLy 快速上手指南

TensorLy 是一个旨在让张量学习变得简单易懂的 Python 库。它支持轻松的张量分解、张量学习和张量代数运算。其独特的后端系统允许你无缝切换使用 NumPy、PyTorch、JAX、TensorFlow、CuPy 或 Paddle 进行计算，并支持在 CPU 或 GPU 上大规模运行。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：Python 3.x
• 前置依赖：
  • 默认依赖：NumPy（安装 TensorLy 时会自动安装）。
  • 可选后端：若需使用 PyTorch、TensorFlow、JAX、CuPy 或 Paddle 作为计算后端，请预先单独安装对应的框架包。

提示：国内用户建议使用 Anaconda 发行版管理环境，或使用 pip 配合国内镜像源（如清华源、阿里源）以加速安装。

安装步骤

你可以选择以下任意一种方式进行安装：

方式一：使用 pip 安装（推荐）

pip install -U tensorly

国内加速示例（使用清华源）：

pip install -U tensorly -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 conda 安装

conda install -c tensorly tensorly

方式三：开发模式安装（从源码）

如果你需要修改源码或贡献代码：

# 克隆仓库
git clone https://github.com/tensorly/tensorly
cd tensorly

# 以可编辑模式安装
pip install -e .

基本使用

1. 创建张量与基础运算

默认情况下，TensorLy 使用 NumPy 作为后端。以下示例展示如何创建张量并进行展开（unfold）和折叠（fold）操作：

import tensorly as tl
import numpy as np

# 创建一个 3x4x2 的三阶张量
tensor = tl.tensor(np.arange(24).reshape((3, 4, 2)), dtype=tl.float64)

# 沿模式 0 展开张量
unfolded = tl.unfold(tensor, mode=0)

# 将展开后的张量折叠回原始形状
reconstructed = tl.fold(unfolded, mode=0, shape=tensor.shape)

2. 切换计算后端

TensorLy 的核心优势在于可以灵活切换后端。例如，切换到 PyTorch 并在 GPU 上进行计算：

import tensorly as tl
import numpy as np

# 设置后端为 pytorch (也可设为 'tensorflow', 'jax', 'cupy' 等)
tl.set_backend('pytorch')

# 创建张量并指定设备为 CUDA
tensor = tl.tensor(np.arange(24).reshape((3, 4, 2)), device='cuda:0')

# 验证类型，此时应为 torch.Tensor
print(type(tensor)) 

3. 张量分解

执行张量分解非常简单。以下示例演示了 Tucker 分解：

from tensorly.decomposition import tucker
import tensorly as tl

# 假设 tensor 已经定义
# 应用 Tucker 分解，设定秩为 [2, 2, 2]
tucker_tensor = tucker(tensor, rank=[2, 2, 2])

# 从分解形式重构完整张量
full_tensor = tl.tucker_to_tensor(tucker_tensor)

更多分解方法（如 CP 分解、TT 格式等）及详细 API 文档，请访问 TensorLy 官方文档。