This repository contains python implementations for computing an approximation of multidimensional arrays in hierarchical Tucker format (Grasedyck 2010, Oseledets 2009, Kressner 2014). In addition to that, this repository contains python implementations of 2 new algorithms, BHT-l2r (Batch Hierarchical Tucker - leaves to root) and HT-RISE (Hierarchical Tucker - Rapid Incremental Subspace Expansion).
BHT-l2r computes an approximation of a batch of tensors in batch hierarchical Tucker format, a batch-modified version of the hierarchical Tucker format, which provides a tensor network structure more suitable for incremental updates. HT-RISE incrementally updates an existing approximation in batch hierarchical Tucker format and (to the best of our knowledge) is the first algorithm that updates an existing approximation in hierarchical Tucker format. Both algorithms provide mathematically proven approximation error upper bounds. Please see the corresponding preprint for further details and proofs.
I suggest you create a python virtual environment. Then within that environment you can install an editable installation with
python -m pip install -e .
a regular install would remove the -e term.
The unit tests are still under development. However, the current version of the tests should still pass without any issues. You should be able to execute
python -m unittest tests/main_test.py -v
and see all tests pass. Please report through an issue if you have any problems.
Feel free to request/suggest new functionalities to the package. There is a plan to combine this repository with the TT-ICE repository to create a holistic incremental tensor decomposition package. However, the development plan is still TBD.
If you want to contribute to the package, feel free to create your branch and open a PR. I will do my best to review any PRs in a timely manner.
Please see CONTRIBUTING.md for details on setting up your development environment and contributing to this project.
To run linting manually:
make lint
This repository uses pre-commit hooks to ensure code quality. To set up:
# Install pre-commit
pip install pre-commit
# Set up pre-commit hooks
pre-commit installWe provide several scripts to help with development:
scripts/run-pre-commit-staged.sh- Run pre-commit only on staged filesscripts/demo-pre-commit.sh- Demonstrate the differences between running pre-commit on all files vs. staged filesscripts/troubleshoot-pre-commit.sh- Diagnose and fix common pre-commit issues
For detailed information about pre-commit, see docs/pre-commit-guide.md.
- Tensor Decomposition Algorithms: HT, BHT, incremental HT implemented in a modular library (
htucker/). - Incremental & Batch Processing: Scripts for both incremental and batch tensor compression, suitable for large datasets.
- Experimentation & Benchmarking: Ready-to-use scripts for running experiments and generating results for scientific publications.
- Reproducibility: Integration with Weights & Biases (wandb) for experiment tracking and reproducibility.
- Install dependencies:
pip install -r requirements.txt
- Run an example experiment:
To run the experiments showcased in the paper
Incremental Hierarchical Tucker Decomposition, please check theREADMEfile located under the./paper_experimentsfolder.python paper_experiments/compress_CatGel_TT.py --help
- Explore the library:
See
examples/for example usages in your own projects.
- Main documentation:
README.org - Scientific paper: Incremental Hierarchical Tucker Decomposition
If you use this codebase in your research, please cite the accompanying paper using the following bibtex entry in your papers:
@article{aksoy2024incremental,
title={Incremental Hierarchical Tucker Decomposition},
author={Aksoy, Doruk and Gorodetsky, Alex A},
journal={arXiv preprint arXiv:2412.16544},
year={2024}
}This project is licensed under the MIT License. See the LICENSE file for details.