# Tensor Toolbox for MATLAB

Tensors (also known as multidimensional arrays or N-way arrays) are used in a variety of applications ranging from chemometrics to network analysis.

- Because it helps show the relevance of this work, please cite this software and associated papers.
- If you are new, see getting started; otherwise, see the functionality below.
- Your bug reports and code contributions are warmly welcomed.
- This is open source software. Please see `LICENSE.txt` for the terms of the license (2-clause BSD).
- For more information or for feedback on this project, please contact us.

## Functionality

The Tensor Toolbox provides the following classes and functions for manipulating dense, sparse, and structured tensors using MATLAB's object-oriented features. This documention is provided via the MATLAB help interface under "Supplemental Software".

- Tensor Types - The Tensor Toolbox supports multiple tensor types, including dense, sparse, and symmetric tensors as well as specially structured tensors, such as Tucker format (core tensor plus factor matrices), Krusal format (stored as factor matrices), sum format (sum of differnt types of tensors such as sparse plus rank-1 tensor in Kruskal format), and so.
- Converting Tensors and Matrices - The Tensor Toolbox includes special matrix classes to enable conversion to/from tensors.
- Working with Tensors - Creating test problems, tensor multiplication, and more.
- CP Decompositions - CP methods such as alternating least squares, direct optimization, and weighted optimization (for missing data). Also alternative decompositions such as Poisson Tensor Factorization via alternating Poisson regression and symmetric CP tensor factorization.
- Tucker Decomposition - Tucker methods including as the higher-order SVD (HOSVD), the sequentially-truncated HOSVD (ST-HOSVD), and the higher-order orthognal interation (HOOI).
- Eigenproblems - Methods to solve the tensor eigenproblem including the shifted higher-order power method (SSHOPM) and the adaptive shift version (GEAP).

## How to Cite

Because it helps us to show the relevance of this work, if you use the Tensor Toolbox in your work in any way, please cite the software itself along with at least one publication or preprint. The help and documentation will generally suggest the appropriate reference, but the three primary references are given below. We provide BibTeX source for each suggested citation. Thanks very much for your support.

- General software: Brett W. Bader, Tamara G. Kolda and others. MATLAB Tensor Toolbox, Version [VERSION]. Available online at https://www.tensortoolbox.org, 20XX. [`TTB_Software`]
- Dense tensors: B. W. Bader and T. G. Kolda. Algorithm 862: MATLAB tensor classes for fast algorithm prototyping, ACM Transactions on Mathematical Software 32(4):635-653, December 2006. DOI: 10.1145/1186785.1186794. [`TTB_Dense`]
- Sparse, Kruskal, and Tucker tensors: B. W. Bader and T. G. Kolda. Efficient MATLAB computations with sparse and factored tensors, SIAM Journal on Scientific Computing 30(1):205-231, December 2007. DOI: 10.1137/060676489. [`TTB_Sparse`]

Consider adding the short hash for the exact version that was used. If you clone the repository, use the command `git log --pretty=format:'%h' -n 1`. If you download, the long hash is baked into the filename, but you need only use the first 8 characters.

## How to Contribute

This is an open-source project hosted on GITLAB at http://gitlab.com/tensors/tensor_toolbox. Visit this website to submit bug reports and suggestions for improvement.

- Report issues here: https://gitlab.com/tensors/tensor_toolbox/issues
- Please see the `CONTRIBUTION_GUIDE.md` for information on contributing to the project.
- Thanks to all contributors, listed in `CONTRIBUTORS.md`.

## Contact

Please email tensortoolbox@sandia.gov with any questions about the toolbox that cannot be resolved via issue reporting. Stories of its usefulness are especially welcome. We will try to respond to every email may not always be successful due to the volume of emails.