https://github.com/google-research/tnco
TNCO is a heuristic tool that optimizes tensor network contraction paths.
https://github.com/google-research/tnco
google-quantum optimization python quantum-circuits tensor-networks
Last synced: 4 days ago
JSON representation
TNCO is a heuristic tool that optimizes tensor network contraction paths.
- Host: GitHub
- URL: https://github.com/google-research/tnco
- Owner: google-research
- License: apache-2.0
- Created: 2025-10-20T23:25:17.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-25T00:40:39.000Z (3 months ago)
- Last Synced: 2026-04-30T08:27:27.512Z (about 1 month ago)
- Topics: google-quantum, optimization, python, quantum-circuits, tensor-networks
- Language: Python
- Homepage:
- Size: 341 KB
- Stars: 33
- Watchers: 1
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Security: .github/SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# Tensor Network Contraction Optimizer (TNCO)
A High-performance tensor network contraction path optimizer for C++ and Python.
[](https://github.com/quantumlib/qsim/blob/main/LICENSE)
[](https://www.python.org/downloads/)
[](https://github.com/google-research/tnco/actions/workflows/run_tests.yml)
[](https://github.com/google-research/tnco/actions/workflows/cpp_linter.yml)
[](https://github.com/google-research/tnco/actions/workflows/github-code-scanning/codeql)
[](https://doi.org/10.1038/s41586-025-09526-6)
Try `TNCO` now with: [](https://mybinder.org/v2/gh/google-research/tnco/main?urlpath=%2Fdoc%2Ftree%2Fexamples%2FOptimization.ipynb)
`TNCO` is a heuristic tool that optimizes tensor network contraction paths. It
represents the contraction as a tree – with the initial tensors as leaves and
the final tensor as the root – and explores possible paths by manipulating
this tree's structure. While the optimization is performed using simulated
annealing, the framework is extensible to other methods. `TNCO` supports
optimization with or without memory constraints, and can automatically
parallelize runs on multiple threads.
`TNCO` was used to demonstrate the first verifiable quantum advantage in 2025
(Abanin et al., "Observation of constructive interference at the edge of
quantum ergodicity", [Nature vol. 646, 2025](https://doi.org/10.1038/s41586-025-09526-6)).
## Installation
### Prerequisites
Before installing `TNCO`, you must have the following system-level dependencies:
* C++17 compiler (`gcc >= 11`, `clang >= 13`)
* CMake (`cmake >= 3.5`)
* Python >= 3.8
* [boost::dynamic_bitset](https://github.com/boostorg/dynamic_bitset)
* GMP and MPFR (optional, for `float1024`)
### Install `TNCO` using `pip`
`TNCO` can be easily installed using `pip`:
```
pip install "tnco @ git+https://github.com/google-research/tnco"
```
for the latest development version, or
```
pip install "tnco @ git+https://github.com/google-research/tnco@version"
```
where `version` is one of the available
[versions](https://github.com/google-research/tnco/tags). `TNCO` can also be installed
from a [zip](https://github.com/google-research/tnco/archive/refs/heads/main.zip) file:
```
pip install tnco-main.zip
```
`TNCO` uses `joblib` to parallelize runs on multiple CPUs. This is an optional
dependency and is not installed by default. To install TNCO with joblib, use
the `[parallel]` extra:
```
pip install "tnco[parallel] @ git+https://github.com/google-research/tnco"
```
### Install `TNCO` using `conda`
`TNCO` can also be installed using `conda` environments. Clone the `TNCO`
repository and execute the following from the project's root folder:
```
conda env create
```
### Install `TNCO` using `docker`
Finally, `TNCO` can also be installed in a `docker` container. Clone the `TNCO`
repository and execute the following from the project's root folder:
```
docker build . -t tnco
```
## How To Use
The library provides a user-friendly Python front-end for most common use
cases:
```
from tnco.app import Optimizer
tn = """
2 a b
2 b c
2 c d
"""
# Load optimizer
opt = Optimizer(method='sa')
# Perform the optimization
tn, res = opt.optimize(tn, betas=(0, 100), n_steps=100, n_runs=8)
```
Multiple input formats are supported; see `tnco.app.load_tn` for further details. For
a more detailed example, see
[examples/Optimization.ipynb](examples/Optimization.ipynb).
The same front-end can be used from command line:
```
$ tnco optimize '[(2, "a", "b"), (2, "b", "c"), (2, "c", "d")]' \
--betas='(0, 100)' \
--n-steps=100 \
--n-runs=8 \
--verbose=10
```
For all the possible options run:
```
$ tnco --help
```
## Contact
TNCO was developed by [Salvatore Mandrà](https://github.com/s-mandra) in 2024.
For any questions or concerns not addressed here, please email
[smandra@google.com](mailto:smandra@google.com).
## Disclaimer
This is not an officially supported Google product. This project is not
eligible for the [Google Open Source Software Vulnerability Rewards
Program](https://bughunters.google.com/open-source-security).
Copyright 2025 Google LLC.
