{"id":13737757,"url":"https://github.com/rballester/tntorch","last_synced_at":"2025-05-08T15:31:16.176Z","repository":{"id":38417783,"uuid":"149003551","full_name":"rballester/tntorch","owner":"rballester","description":"Tensor Network Learning with PyTorch","archived":false,"fork":false,"pushed_at":"2024-05-23T10:41:00.000Z","size":2261,"stargazers_count":295,"open_issues_count":8,"forks_count":42,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-20T18:18:39.413Z","etag":null,"topics":["cp-decomposition","data-science","learning","pytorch","tensor-decomposition","tensor-networks","tensor-train","tensors","tucker-decomposition"],"latest_commit_sha":null,"homepage":"https://tntorch.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rballester.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-16T14:28:55.000Z","updated_at":"2025-04-07T15:33:41.000Z","dependencies_parsed_at":"2024-01-07T06:00:16.615Z","dependency_job_id":"30b4b4b0-bfb4-49f8-ab98-a5854191eab8","html_url":"https://github.com/rballester/tntorch","commit_stats":{"total_commits":227,"total_committers":8,"mean_commits":28.375,"dds":"0.40528634361233484","last_synced_commit":"3af563a42794ba169e7902198d1edd919617a958"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rballester%2Ftntorch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rballester%2Ftntorch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rballester%2Ftntorch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rballester%2Ftntorch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rballester","download_url":"https://codeload.github.com/rballester/tntorch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253095944,"owners_count":21853515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cp-decomposition","data-science","learning","pytorch","tensor-decomposition","tensor-networks","tensor-train","tensors","tucker-decomposition"],"created_at":"2024-08-03T03:01:59.878Z","updated_at":"2025-05-08T15:31:15.733Z","avatar_url":"https://github.com/rballester.png","language":"Python","funding_links":[],"categories":["Python","Toolboxes"],"sub_categories":["Basic Tensor Operation"],"readme":"[![Documentation Status](https://readthedocs.org/projects/tntorch/badge/?version=latest)](https://tntorch.readthedocs.io/en/latest/?badge=latest)\n\n# tntorch - Tensor Network Learning with PyTorch\n\n**[Read the Docs site: *http://tntorch.readthedocs.io/*](http://tntorch.readthedocs.io/)**\n\n[Welcome to *tntorch*](https://github.com/rballester/tntorch/blob/main/docs/tutorials/introduction.ipynb), a PyTorch-powered modeling and learning library using tensor networks. Such networks are unique in that [they use *multilinear* neural units](https://arxiv.org/abs/1711.00811) (instead of non-linear activation units). Features include:\n\n- Basic and fancy **indexing** of tensors, **broadcasting**, **assignment**, etc.\n- Tensor **decomposition** and **reconstruction**\n- Element-wise and tensor-tensor **arithmetics**\n- Building tensors from black-box functions using **cross-approximation**\n- Finding global **maxima** and **minima** from tensors\n- **Statistics** and **sensitivity analysis**\n- **Optimization** using autodifferentiation\n- **Misc. operations** on tensors: stacking, unfolding, sampling, derivating, etc.\n- **Batch operations** (work in progress)\n\nIf you use this package, please cite our paper:\n\n```\n@article{UBS:22,\n  author  = {Mikhail Usvyatsov and Rafael Ballester-Ripoll and Konrad Schindler},\n  title   = {tntorch: Tensor Network Learning with {PyTorch}},\n  journal = {Journal of Machine Learning Research},\n  year    = {2022},\n  volume  = {23},\n  number  = {208},\n  pages   = {1--6},\n  url     = {http://jmlr.org/papers/v23/21-1197.html}\n}\n```\n\n## Example Use Cases\n\nAvailable [tensor formats](https://github.com/rballester/tntorch/blob/main/docs/tutorials/main_formats.ipynb) include:\n\n- [CANDECOMP/PARAFAC (CP)](https://epubs.siam.org/doi/pdf/10.1137/07070111X)\n- [Tucker](https://epubs.siam.org/doi/pdf/10.1137/S0895479898346995) (implemented as TT with increasing ranks, which has equal expressive power. Tucker factors are unconstrained matrices, unlike unitary/orthogonal matrices in some implementations.)\n- [Tensor train (TT)](https://epubs.siam.org/doi/abs/10.1137/090752286?journalCode=sjoce3)\n- Hybrids: CP-Tucker, TT-Tucker, etc. \n- [Partial support](https://github.com/rballester/tntorch/blob/main/docs/tutorials/other_formats.ipynb) for other decompositions such as [INDSCAL, CANDELINC, DEDICOM, PARATUCK2](https://epubs.siam.org/doi/pdf/10.1137/07070111X), and custom formats\n\nFor example, the following networks both represent a 4D tensor (i.e. a real function that can take I1 x I2 x I3 x I4 possible values) in the TT and TT-Tucker formats:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/rballester/tntorch/blob/main/images/tensors.jpg\" width=\"600\" title=\"TT-Tucker\"\u003e\u003c/p\u003e\n\nIn *tntorch*, **all tensor decompositions share the same interface**. You can handle them in a transparent form, as if they were plain NumPy arrays or PyTorch tensors:\n\n```\n\u003e import tntorch as tn\n\u003e t = tn.randn(32, 32, 32, 32, ranks_tt=5)  # Random 4D TT tensor of shape 32 x 32 x 32 x 32 and TT-rank 5\n\u003e print(t)\n\n4D TT tensor:\n\n 32  32  32  32\n  |   |   |   |\n (0) (1) (2) (3)\n / \\ / \\ / \\ / \\\n1   5   5   5   1\n\n\u003e print(tn.mean(t))\n\ntensor(8.0388)\n\n\u003e print(tn.norm(t))\n\ntensor(9632.3726)\n```\n\nDecompressing tensors is easy:  \n\n```\n\u003e print(t.torch().shape)\ntorch.Size([32, 32, 32, 32])\n```\n\nThanks to PyTorch's automatic differentiation, you can easily define all sorts of loss functions on tensors:\n\n```\ndef loss(t):\n    return torch.norm(t[:, 0, 10:, [3, 4]].torch())  # NumPy-like \"fancy indexing\" for arrays\n```\n\nMost importantly, loss functions can be defined on **compressed** tensors as well:\n\n```\ndef loss(t):\n    return tn.norm(t[:3, :3, :3, :3] - t[-3:, -3:, -3:, -3:])\n```\n\nCheck out the [introductory notebook](https://github.com/rballester/tntorch/blob/master/docs/tutorials/introduction.ipynb) for all the details on the basics.\n\n## Tutorial Notebooks\n\n- [Introduction](https://github.com/rballester/tntorch/blob/master/docs/tutorials/introduction.ipynb)\n- [Active subspaces](https://github.com/rballester/tntorch/blob/master/docs/tutorials/active_subspaces.ipynb)\n- [ANOVA decomposition](https://github.com/rballester/tntorch/blob/master/docs/tutorials/anova.ipynb)\n- [Boolean logic](https://github.com/rballester/tntorch/blob/master/docs/tutorials/logic.ipynb)\n- [Classification](https://github.com/rballester/tntorch/blob/master/docs/tutorials/classification.ipynb)\n- [Cross-approximation](https://github.com/rballester/tntorch/blob/master/docs/tutorials/cross.ipynb)\n- [Differentiable cross-approximation](https://github.com/rballester/tntorch/blob/master/docs/tutorials/diffcross.ipynb)\n- [Differentiation](https://github.com/rballester/tntorch/blob/master/docs/tutorials/derivatives.ipynb)\n- [Discrete/weighted finite automata](https://github.com/rballester/tntorch/blob/master/docs/tutorials/automata.ipynb)\n- [Exponential machines](https://github.com/rballester/tntorch/blob/master/docs/tutorials/exponential_machines.ipynb)\n- [Main tensor formats available](https://github.com/rballester/tntorch/blob/master/docs/tutorials/main_formats.ipynb)\n- [Other custom formats](https://github.com/rballester/tntorch/blob/master/docs/tutorials/other_formats.ipynb)\n- [Polynomial chaos expansions](https://github.com/rballester/tntorch/blob/master/docs/tutorials/pce.ipynb)\n- [Tensor arithmetics](https://github.com/rballester/tntorch/blob/master/docs/tutorials/arithmetics.ipynb)\n- [Tensor completion and regression](https://github.com/rballester/tntorch/blob/master/docs/tutorials/completion.ipynb)\n- [Tensor decomposition](https://github.com/rballester/tntorch/blob/master/docs/tutorials/decompositions.ipynb)\n- [Sensitivity analysis](https://github.com/rballester/tntorch/blob/master/docs/tutorials/sobol.ipynb)\n- [Vector field data](https://github.com/rballester/tntorch/blob/master/docs/tutorials/vector_fields.ipynb)\n\n## Installation\n\nYou can install *tntorch* using *pip*:\n\n```\npip install tntorch\n```\n\nAlternatively, you can install from the source:\n\n```\ngit clone https://github.com/rballester/tntorch.git\ncd tntorch\npip install .\n```\n\nFor functions that use cross-approximation, the optional package [*maxvolpy*](https://bitbucket.org/muxas/maxvolpy) is required (it can be installed via `pip install maxvolpy`).\n\n## Testing\n\nWe use [*pytest*](https://docs.pytest.org/en/latest/). Simply run:\n\n```\ncd tests/\npytest\n```\n\n## Contributing\n\nPull requests are welcome! \n\nBesides using the [issue tracker](https://github.com/rballester/tntorch/issues), feel also free to contact me at \u003crafael.ballester@ie.edu\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frballester%2Ftntorch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frballester%2Ftntorch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frballester%2Ftntorch/lists"}