<p align="center">
  <img src="assets/ttglow_logo.png" alt="TTGlow Logo" width="400"/>
</p>

# TTGlow

Tensor Train linear algebra built on PyTorch for efficient high-dimensional tensor operations.

## Overview

TTGlow provides an efficient implementation of the Tensor Train (TT) decomposition, a powerful technique for representing and manipulating high-dimensional tensors with reduced memory footprint and computational cost. This package is particularly useful for:

- High-dimensional data analysis
- Quantum many-body physics simulations
- Machine learning with tensor methods
- Efficient storage and computation of large-scale tensors

## Installation

### Using pip (Recommended)

```bash
pip install ttglow
```

### From source (for development)

```bash
# Clone the repository
git clone https://github.com/romanellerbrock/ttglow.git
cd ttglow

# Install with pixi
pixi install
pixi shell

# Or install with pip
pip install -e .
```

## Quick Start

```python
import torch
from ttglow import TensorTrain

# Convert a dense tensor to TT format
dense = torch.randn(8, 8, 8, 8, dtype=torch.float64)
tt = TensorTrain.from_dense(dense, max_rank=4)  # Compress with rank truncation

print(f"Original: {dense.numel():,} elements")
print(f"Compressed: {tt.ttnumel:,} elements ({tt.ttnumel/dense.numel():.1%})")

# Arithmetic with operator overloading
tt2 = TensorTrain.random([8, 8, 8, 8], ranks=[4, 4, 4])
result = tt + tt2       # Addition
result = tt * tt2       # Hadamard (elementwise) product
result = 2.5 * tt       # Scalar multiplication
inner = tt @ tt2        # Inner product

# Shape operations (PyTorch-like API)
tt_reshaped = tt.reshape([64, 64])
tt_transposed = tt.transpose(0, 2)
tt_flat = tt.flatten(1, 3)

# Convert back to dense
reconstructed = tt.to_tensor()
```

## Features

- **Efficient TT representation**: Store high-dimensional tensors with minimal memory
- **Core operations**: `dot`, `hadamard`, `add`, `scale`
- **Shape operations**: `reshape`, `transpose`, `permute`, `squeeze`, `unsqueeze`, `flatten`, `cat`, `stack`
- **Decomposition**: `from_dense` (TT-SVD with optional rank truncation), `svd`, `qr`
- **TT-Matrix support**: Matrix-vector products, operator composition, `kron`, `kronadd`
- **PyTorch-like API**: `.to()`, `.clone()`, `.detach()`, familiar tensor interface
- **PyTorch backend**: Full GPU support and automatic differentiation

## Development

### Running Tests

```bash
pixi run test
```

### Code Formatting

```bash
pixi run format
```

### Linting

```bash
pixi run lint
```

### Test Coverage

```bash
pixi run test-cov
```

## Project Structure

```
ttglow/
├── src/ttglow/           # Main package code
│   ├── __init__.py
│   ├── tensortrain.py    # TensorTrain class and operations
│   ├── ttmatrix.py       # TT-Matrix (MPO) support
│   └── linalg.py         # Linear algebra (SVD, QR, norms)
├── tests/                # Test suite
├── examples/             # Usage examples
├── docs/                 # Documentation website
└── pyproject.toml        # Package configuration
```

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## References

- Oseledets, I. V. (2011). "Tensor-train decomposition". SIAM J. Sci. Comput., 33(5), 2295-2317.
