Metadata-Version: 2.4
Name: tensorrsvd
Version: 0.1.0
Summary: Tensor-free randomized HOSVD (randomized Tucker decomposition)
Keywords: tensor,tucker,randomized svd,hosvd,scientific computing,numpy,jax
Author: Paul Virally
Author-email: Paul Virally <pvirally@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=2.4.2
Requires-Dist: pylops>=2.6.0
Requires-Dist: cupy>=12.0.0 ; extra == 'cupy'
Requires-Dist: jax>=0.9.0.1 ; extra == 'jax'
Requires-Dist: jax[cuda12]>=0.9.0.1 ; extra == 'jaxcuda12'
Requires-Dist: jax[cuda13]>=0.9.0.1 ; extra == 'jaxcuda13'
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/PaulVirally/TensorRSVD
Project-URL: Documentation, https://tensorrsvd.readthedocs.io
Project-URL: Repository, https://github.com/PaulVirally/TensorRSVD
Project-URL: Issues, https://github.com/PaulVirally/TensorRSVD/issues
Provides-Extra: cupy
Provides-Extra: jax
Provides-Extra: jaxcuda12
Provides-Extra: jaxcuda13
Description-Content-Type: text/markdown

# TensorRSVD

[![PyPI version](https://img.shields.io/pypi/v/tensorrsvd.svg)](https://pypi.org/project/tensorrsvd/)
[![CI](https://github.com/PaulVirally/TensorRSVD/actions/workflows/ci.yml/badge.svg)](https://github.com/PaulVirally/TensorRSVD/actions/workflows/ci.yml)
[![Documentation](https://readthedocs.org/projects/tensorrsvd/badge/?version=latest)](https://tensorrsvd.readthedocs.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Tensor-free randomized Higher-Order SVD (Tucker decomposition).**

TensorRSVD computes Tucker decompositions of high-dimensional tensors that are
defined as Python functions without ever forming the dense tensor in memory. It
uses randomized linear algebra (Halko et al. 2011) to approximate the dominant
factor matrices mode-by-mode, scaling to tensors that would be impossible to
store explicitly.

## Installation

```bash
pip install tensorrsvd
```

**Optional backends** for GPU or JIT-compiled acceleration:

```bash
pip install "tensorrsvd[jax]"          # JAX (CPU / GPU / TPU)
pip install "tensorrsvd[jaxcuda12]"    # JAX with CUDA 12
pip install "tensorrsvd[jaxcuda13]"    # JAX with CUDA 13
pip install "tensorrsvd[cupy]"         # CuPy (NVIDIA GPU, CUDA required)
```

> **Note:** CuPy wheels are CUDA-version-specific. If the above does not match your
> CUDA installation, install CuPy manually following the
> [CuPy installation guide](https://docs.cupy.dev/en/stable/install.html).

## Quick start

```python
import numpy as np
from tensorrsvd import ho_rsvd

# Define your tensor as a callable
def my_tensor(x0, x1, x2):
    return x0 - x1 + x2

# Compute the randomized Tucker factors
U_list, S_list = ho_rsvd(
    tensor=my_tensor,
    tensor_shape=(64, 64, 64),
    dtype=np.float64,
    rank=4,
    num_oversamples=10,
    num_idxs=3,
)

# U_list[i] has shape (n_i, rank_i) with orthonormal columns
# S_list[i] has shape (rank_i,) (descending singular values)
print([U.shape for U in U_list])   # [(64, 4), (64, 4), (64, 4)]
```

Switch to a JAX or CuPy backend by passing `backend="jax"` or `backend="cupy"`.

## Documentation

Full documentation (installation, user guide, theory, and API reference, etc.)
is available at
**[tensorrsvd.readthedocs.io](https://tensorrsvd.readthedocs.io)**.

## References

- N. Halko, P. G. Martinsson, and J. A. Tropp,
  *Finding Structure with Randomness: Probabilistic Algorithms for Constructing Approximate Matrix Decompositions*,
  SIAM Review, 53(2):217–288, 2011.
  [doi:10.1137/090771806](https://doi.org/10.1137/090771806)

- L. De Lathauwer, B. De Moor, and J. Vandewalle,
  *A Multilinear Singular Value Decomposition*,
  SIAM Journal on Matrix Analysis and Applications, 21(4):1253–1278, 2000.
  [doi:10.1137/S0895479896305696](https://doi.org/10.1137/S0895479896305696)

## License

MIT (see [LICENSE](LICENSE))
