{"id":32155994,"url":"https://github.com/stecrotti/tensortrains.jl","last_synced_at":"2026-02-21T15:02:54.119Z","repository":{"id":180651270,"uuid":"665017563","full_name":"stecrotti/TensorTrains.jl","owner":"stecrotti","description":"Tensor Trains, mostly as probability distributions","archived":false,"fork":false,"pushed_at":"2026-01-10T01:51:49.000Z","size":841,"stargazers_count":4,"open_issues_count":10,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-10T23:49:10.443Z","etag":null,"topics":["matrix-product-states","tensor-networks","tensor-trains"],"latest_commit_sha":null,"homepage":"","language":"Julia","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stecrotti.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-11T08:57:32.000Z","updated_at":"2025-12-23T19:35:01.000Z","dependencies_parsed_at":"2023-10-15T03:43:46.227Z","dependency_job_id":"8bc0fa0b-3740-4446-8f97-eb330af2b3c9","html_url":"https://github.com/stecrotti/TensorTrains.jl","commit_stats":null,"previous_names":["stecrotti/tensortrains.jl"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/stecrotti/TensorTrains.jl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrotti%2FTensorTrains.jl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrotti%2FTensorTrains.jl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrotti%2FTensorTrains.jl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrotti%2FTensorTrains.jl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stecrotti","download_url":"https://codeload.github.com/stecrotti/TensorTrains.jl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stecrotti%2FTensorTrains.jl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29684075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T14:31:22.911Z","status":"ssl_error","status_checked_at":"2026-02-21T14:31:22.570Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["matrix-product-states","tensor-networks","tensor-trains"],"created_at":"2025-10-21T12:19:59.960Z","updated_at":"2026-02-21T15:02:54.114Z","avatar_url":"https://github.com/stecrotti.png","language":"Julia","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TensorTrains.jl\n\n[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://stecrotti.github.io/TensorTrains.jl/dev/)\n[![Build Status](https://github.com/stecrotti/TensorTrains.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/stecrotti/TensorTrains.jl/actions/workflows/CI.yml?query=branch%3Amain)\n[![codecov](https://codecov.io/gh/stecrotti/TensorTrains.jl/branch/main/graph/badge.svg?token=eNeXzhhZ5R)](https://codecov.io/gh/stecrotti/TensorTrains.jl)\n\n⚠️ This package is still work in progress, some breaking changes should be expected.\n\n## What is a Tensor Train?\nA [Tensor Train](https://tensornetwork.org/mps/) is a type of tensor factorization involving the product of 3-index tensors organized on a one-dimensional chain. \nIn the context of function approximation and probability, a function of $L$ discrete variables is in Tensor Train format if it is written as\n```math\nf(x^1, x^2, \\ldots, x^L) = \\sum_{a^1,a^2,\\ldots,a^{L-1}} [A^1(x^1)]_{a^1}[A^2(x^2)]_{a^1,a^2}\\cdots [A^{L-1}(x^{L-1})]_{a^{L-2},a^{L-1}}[A^L(x^L)]_{a^{L-1}}\n```\nwhere, for every choice of $x^l$, $A^l(x^l)$ is a real-valued matrix and the matrix sizes must be compatible.\nThe first matrix must have 1 row and the last matrix should have 1 column, such that the product correctly returns a scalar.\n\nThe Tensor Train factorization can be used to parametrize probability distributions, which is the main focus of this package. In this case, $f$ should be properly normalized and always return a non-negative value. \n\n### Tensor Trains with Periodic Boundary Conditions\nA slight generalization, useful to describe systems with periodic boundary conditions is the following:\n```math\nf(x^1, x^2, \\ldots, x^L) = \\sum_{a^1,a^2,\\ldots,a^{L}} [A^1(x^1)]_{a^1,a^2}[A^2(x^2)]_{a^2,a^3}\\cdots [A^{L-1}(x^{L-1})]_{a^{L-1},a^{L}}[A^L(x^L)]_{a^{L},a^1}\n```\nIn other words, to evaluate $f$ one takes the trace of the product of matrices.\n\n## Notation and terminology\nTensor Trains are the most basic type of [Tensor Network](https://tensornetwork.org/). Tensor networks are a large family of tensor factorizations which are often best represented in diagrammatic notation. For this reason, the term _bond_ is used interchangeably as _index_. The indices $a^1,a^2,\\ldots,a^{L-1}$ are usually called the _virtual indices_, while $x^1, x^2, \\ldots, x^L$ are the _physical indices_.\n\nTensor Trains are used to parametrize wavefunctions in many-body quantum physics. The resulting quantum state is called [Matrix Product State](https://en.wikipedia.org/wiki/Matrix_product_state). In such context, the entries are generally complex numbers, and a probability can be obtained for a given state by taking the squared absolute value of the wavefunction.\n\nIn this package we focus on the \"classical\" case where the Tensor Train directly represents a probability distribution $p(x^1, x^2, \\ldots, x^L)$. \n\n## Efficient computations\nGiven a Tensor Train some simple recursive strategies can be employed to do the following operations in time $\\mathcal O (L)$\n\n#### Compute the normalization\n```math\nZ = \\sum_{x^1, x^2, \\ldots, x^L} \\sum_{a^1,a^2,\\ldots,a^{L-1}} [A^1(x^1)]_{a^1}[A^2(x^2)]_{a^1,a^2}\\cdots [A^{L-1}(x^{L-1})]_{a^{L-2},a^{L-1}}[A^L(x^L)]_{a^{L-1}}\n```\nsuch that \n```math\n\\begin{aligned}\n1\u0026=\\sum_{x^1, x^2, \\ldots, x^L}p(x^1, x^2, \\ldots, x^L)\\\\\u0026=\\sum_{x^1, x^2, \\ldots, x^L}\\frac1Z \\sum_{a^1,a^2,\\ldots,a^{L-1}} [A^1(x^1)]_{a^1}[A^2(x^2)]_{a^1,a^2}\\cdots [A^{L-1}(x^{L-1})]_{a^{L-2},a^{L-1}}[A^L(x^L)]_{a^{L-1}}\n\\end{aligned}\n```\n#### Compute marginals\nSingle-variable\n```math\np(x^l=x) = \\sum_{x^1, x^2, \\ldots, x^L} p(x^1, x^2, \\ldots, x^L) \\delta(x^l,x)\n```\nand two-variable\n```math\np(x^l=x, x^m=x') = \\sum_{x^1, x^2, \\ldots, x^L} p(x^1, x^2, \\ldots, x^L) \\delta(x^l,x)\\delta(x^m,x')\n```\n#### Extract samples\nVia hierarchical sampling\n```math\np(x^1, x^2, \\ldots, x^L) = p(x^1)p(x^2|x^1)p(x^3|x^1,x^2)\\cdots p(x^L|x^1,x^2,\\ldots,x^{L-1})\n```\nby first sampling $x^1\\sim p(x^1)$, then $x^2\\sim p(x^2|x^1)$ and so on.\n\n## What can this package do?\nThis small package provides some utilities for creating, manipulating and evaluating Tensor Trains interpreted as functions, with a focus on the probabilistic side. \nEach variable $x^l$ is assumed to be multivariate.\nWhenever performing some probability-related operation, it is responsability of the user to make sure that the Tensor Train always represents a valid probability distribution.\n\nCommon operations are:\n\n- `evaluate` a Tensor Train at a given set of indices\n- `orthogonalize_left!`, `orthogonalize_right!`: bring a Tensor Train to [left/right orthogonal form](https://tensornetwork.org/mps/)\n- `compress!` a Tensor Train using [SVD](https://en.wikipedia.org/wiki/Singular_value_decomposition)-based truncations\n- `normalize!` a Tensor Train in the probability sense (not in the $L_2$ norm sense!), see above\n- `sample` from a Tensor Train intended as a probability ditribution, see above\n- `+`,`-`: take the sum/difference of two TensorTrains\n\n### Example\nLet's construct and initialize at random a Tensor Train of the form\n```math\nf\\left((x^1,y^1), (x^2,y^2), (x^3,y^3)\\right) = \\sum_{a^1,a^2} [A^1(x^1,y^1)]_{a^1}[A^2(x^2,y^2)]_{a^1,a^2}[A^3(x^3,y^3)]_{a^2}\n```\nwhere $x^l\\\\in\\\\{1,2\\\\}, y^l\\\\in\\\\{1,2,3\\\\}$.\n```julia\nusing TensorTrains\nL = 3        # length\nq = (2, 3)   # number of values taken by x, y\nd = 5        # bond dimension\nA = rand_tt(d, L, q...)    # construct Tensor Train with random positive entries\nxy = [[rand(1:qi) for qi in q] for _ in 1:L]    # random set of indices\np = evaluate(A, xy)    # evaluate `A` at `xy`\ncompress!(A; svd_trunc = TruncThresh(1e-8));    # compress `A` to reduce the bond dimension\npnew = evaluate(A, xy)\nε = abs( (p - pnew)/p )\n```\n\n## References\n- https://tensornetwork.org: \"an open-source review article focused on tensor network algorithms, applications, and software\"\n- Oseledets, I.V., 2011. [Tensor-train decomposition](https://sites.pitt.edu/~sjh95/related_papers/tensor_train_decomposition.pdf). SIAM Journal on Scientific Computing, 33(5).\n\n## Related packages\n- [TensorTrains.jl](https://github.com/mbachmayr/TensorTrains.jl): conceived for the application of Tensor Train decomposition to elliptic PDEs, does not cover anything related to probability\n- [Tensor-Train-Julia](https://github.com/msdupuy/Tensor-Train-Julia): less lightweight, mostly designed for quantum applications, still WIP\n- [Itensors.jl](https://github.com/ITensor/ITensors.jl): a full-fledged Tensor Network library, mostly designed for quantum applications. Interface is more intuitive, but likely less efficient if all you need to do is simple operations on 1D Tensor Networks\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstecrotti%2Ftensortrains.jl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstecrotti%2Ftensortrains.jl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstecrotti%2Ftensortrains.jl/lists"}