ttrecipes

ttrecipes is a Python library for working with, visualizing and understanding tensors (multiway arrays) compressed using the tensor train format. We make heavy use of many key possibilities offered by the TT model (many are provided by the great ttpy toolbox):

• Compressing/decompressing full and sparse tensors (compression.py, sparse.py)
• Operations on tensors: stacking, transposing, computing moments, etc. (util.py, analysis.py)
• Recompressing existing tensors (TT-round algorithm) (compression.py)
• Cross-approximation wrapper for building tensors and surrogate modeling (cross.py)
• Completion and regression (completion.py)
• Sampling schemes for parameter spaces (sampling.py)
• Variance-based sensitivity analysis: Sobol indices, Shapley values, effective dimensions, etc. (sensitivity_indices.py, sensitivity_analysis.py)
• Mask tensors and TTs that behave like deterministic finite automata (masks.py, sets.py)
• Visualization of TT tensors (mpl.py, tikz.py)
• A library of analytical models from physics, engineering, and computational science (models.py)

Examples

Example of surrogate modeling interactive navigation (a gradient boosting regressor trained on the UCI Airfoil Self-Noise Data Set, converted to the TT format via cross-approximation):

Sobol-based sensitivity analysis of a 10-dimensional fire-spread model (~10 seconds were needed to compute these and more higher-order indices):

See the examples/ folder for some sample scripts. Check out this Jupyter Notebook for the examples used in our paper Tensor Approximation of Advanced Metrics for Sensitivity Analysis. You can also run and interact with the notebook online using Binder

Installation

ttrecipes depends on ttpy and other common scientific computation packages (SciPy, NumPy, etc). The provided environment.yml, requirements.txt and ttpy_repo.txt files collect these dependencies for an easy installation using conda or pip respectively. As usual, it is recommended to create a new Python environment for the project.

Basic dependencies

If you use conda, you can create an environment (called ttrecipes by default) with the required dependencies already installed with the following command:

conda env create --file environment.yml

Or, if you prefer, you can also use pip to install the required packages:

pip install -r requirements.txt

Do not forget to activate the newly created environment with 'conda activate' or 'source activate'.

ttpy

ttpy needs to be explicitly installed after the basic dependencies. To install a version compatible with ttrecipes, run the following pip command:

pip install -r ttpy_repo.txt

Important: due to a bug in some releases of the gfortran compiler in versions 5.0-8.0, the installation of ttpy may fail (issue #60). If this is your case, try to use a different gfortran version (e.g. gfortran-4.8) or a different compiler (e.g. ifort).

ttrecipes

Once the dependencies are ready, install ttrecipes by cloning this repository and running 'pip install' with the current version in editable mode:

git clone https://github.com/rballester/ttrecipes.git
cd ttrecipes
pip install -e .

Project Structure

• There is a core folder containing all lower-level utilities to work with TTs. They are all imported with a horizontal structure:

import ttrecipes as tr
tr.core.anyfunction()

• Higher-level functions are grouped as modules that have to be imported explicitly. Currently, there are:
  • mpl.py: TT visualization using matplotlib
  • tikz.py: TT visualization using TikZ
  • models.py: analytical functions for surrogate modeling, sensitivity analysis, etc.
  • sensitivity_analysis.py: high-level querying of Sobol indices, displaying and tabulating Sobol and other sensitivity metrics, etc.

For instance, use the following to visualize a TT tensor (tt.vector object from ttpy):

import ttrecipes.mpl
tr.mpl.navigation(t)

Acknowledgment

This work was partially supported by the UZH Forschungskredit "Candoc", grant number FK-16-012.

References

• I. Oseledets. Tensor-train decomposition (2011)
• I. Oseledets, E. Tyrtyshnikov. TT-cross approximation for multidimensional arrays (2010)
• A. Cichocki, N. Lee, I. Oseledets, A.-H. Phan, Q. Zhao, D. P. Mandic. Tensor Networks for Dimensionality Reduction and Large-scale Optimization: Part 1 (Low-Rank Tensor Decompositions) (2016)
• A. Cichocki, A.-H. Phan, Q. Zhao, N. Lee, I. V. Oseledets, M. Sugiyama, D. P. Mandic. Tensor Networks for Dimensionality Reduction and Large-Scale Optimizations. Part 2 Applications and Future Perspectives (2017)
• R. Ballester-Ripoll, E. G. Paredes, R. Pajarola. A Surrogate Visualization Model Using the Tensor Train Format (2016)
• R. Ballester-Ripoll, E. G. Paredes, R. Pajarola. Sobol Tensor Trains for Global Sensitivity Analysis (2017)
• R. Ballester-Ripoll, E. G. Paredes, R. Pajarola. Tensor Approximation of Advanced Metrics for Sensitivity Analysis (2017)
• G. Rabusseau. A Tensor Perspective on Weighted Automata, Low-Rank Regression and Algebraic Mixtures (2016)