mdopt: A code-agnostic tensor-network decoder for quantum error-correcting codes

mdopt: A code-agnostic tensor-network decoder for quantum error-correcting codes - Published in JOSS (2025)

https://github.com/quicophy/mdopt

Science Score: 95.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 1 DOI reference(s) in JOSS metadata
○
Academic publication links
✓
Committers with academic emails
1 of 12 committers (8.3%) from academic institutions
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

discrete-optimization matrix-product-states tensor-networks

Keywords from Contributors

unit-test labels

Last synced: 3 months ago · JSON representation

Repository

Discrete optimisation in the tensor-network (specifically, MPS-MPO) language.

Basic Info

Host: GitHub
Owner: quicophy
License: mit
Language: Python
Default Branch: main
Homepage: http://mdopt.readthedocs.io/
Size: 11.9 MB

Statistics

Stars: 51
Watchers: 2
Forks: 5
Open Issues: 7
Releases: 1

Topics

discrete-optimization matrix-product-states tensor-networks

Created almost 5 years ago · Last pushed 4 months ago

Metadata Files

Readme Contributing License Code of conduct

`mdopt` — Discrete Optimisation in the MPS-MPO Language

`mdopt` is a python package built on top of `numpy` for discrete optimisation (mainly for classical and quantum decoding) in the tensor-network (specifically, Matrix Product States / Operators) language. The intended audience includes physicists, quantum information / error correction researchers, and those interested in exploring tensor-network methods beyond traditional applications.

Installation

To install the current release, use the package manager pip.

bash pip install mdopt

Otherwise, you can clone the repository and use poetry.

bash poetry install

Minimal example

```python import numpy as np import qecstruct as qec from examples.decoding.decoding import decode_css

Define a small instance of the surface code

LATTICESIZE = 3 surfacecode = qec.hypergraphproduct( qec.repetitioncode(LATTICESIZE), qec.repetitioncode(LATTICE_SIZE), )

Input an error and choose decoder controls

logicals, success = decodecss( code=surfacecode, error="IIXIIIIIIIIII", biasprob=0.01, biastype="Bitflip", chimax=64, renormalise=True, contractionstrategy="Optimised", tolerance=1e-12, silent=False, ) ```

Examples

The examples folder contains full workflows that demonstrate typical use cases, such as quantum / classical LDPC code decoding, ground state search for the quantum Ising model and random quantum curcuit simulation. Each example is fully documented and serves as a starting point for building your own experiments. The package has been tested on macOS and Linux (Compute Canada clusters) and does not currently support Windows.

Cite

If you happen to find mdopt useful in your work, please consider supporting development by citing it. @software{mdopt2022, author = {Aleksandr Berezutskii}, title = {mdopt: Discrete optimisation in the tensor-network (specifically, MPS-MPO) language.}, url = {https://github.com/quicophy/mdopt}, year = {2022}, }

Contribution guidelines

If you want to contribute to mdopt, be sure to follow GitHub's contribution guidelines. This project adheres to our code of conduct. By participating, you are expected to uphold this code.

We use GitHub issues for tracking requests and bugs, please direct specific questions to the maintainers.

The mdopt project strives to abide by generally accepted best practices in open-source software development, such as:

apply the desired changes and resolve any code conflicts,
run the tests and ensure they pass,
build the package from source.

Developers may find the following guidelines useful:

Running tests. Tests are executed using pytest: bash pytest tests
Building documentation. Documentation is built with Sphinx. A convenience script is provided:

bash ./generate_docs.sh

Coding style. The project follows the Black code style. Please run Black before submitting a pull request:

bash black .

Pre-commit hooks. Pre-commit hooks are configured to enforce consistent style automatically. To enable them:

bash pre-commit install

License

This project is licensed under the MIT License.

Documentation

Full documentation is available at mdopt.readthedocs.io.

Owner

Name: QuICoPhy Lab
Login: quicophy
Kind: organization

Website: https://www.physique.usherbrooke.ca/kourtis/
Repositories: 3
Profile: https://github.com/quicophy

Theoretical and computational physics lab in the Department of Physics and Institut Quantique of Université de Sherbrooke.

JOSS Publication

mdopt: A code-agnostic tensor-network decoder for quantum error-correcting codes

Published

November 10, 2025

DOI

10.21105/joss.09125

Volume 10, Issue 115, Page 9125

Authors

Aleksandr Berezutskii

Institut Quantique & Département de Physique, Université de Sherbrooke, Sherbrooke, QC J1K 2R1, Canada

Editor

Daniel S. Katz

GitHub Events

Total

Create event: 77
Release event: 1
Issues event: 4
Watch event: 26
Delete event: 83
Issue comment event: 132
Push event: 274
Pull request review comment event: 1
Pull request review event: 105
Pull request event: 155
Fork event: 1

Last Year

Create event: 68
Release event: 1
Issues event: 4
Watch event: 24
Delete event: 75
Issue comment event: 117
Push event: 249
Pull request review comment event: 1
Pull request event: 137
Pull request review event: 100
Fork event: 1

Committers

Last synced: 5 months ago

All Time

Total Commits: 1,071
Total Committers: 12
Avg Commits per committer: 89.25
Development Distribution Score (DDS): 0.529

Past Year

Commits: 386
Committers: 4
Avg Commits per committer: 96.5
Development Distribution Score (DDS): 0.228

Top Committers

Name	Email	Commits
meandmytram	b**i@p**u	504
dependabot[bot]	4**]@u**m	263
Aleksandr Berezutskii	a**i@s**u	134
Aleksandr Berezutskii	a**i@u**a	124
pre-commit-ci[bot]	6**]@u**m	26
maxtremblay	m**m@p**m	8
Maxime Tremblay	5**y@u**m	4
Aleksandr Berezutskii	a**i@s**l	2
Aleksandr Berezutskii	b**a@c**a	2
Aleksandr Berezutskii	b**a@c**a	2
MoiseRousseau	4**u@u**m	1
Samiod131	s**s@h**m	1

Committer Domains (Top 20 + Academic)

cedar5.cedar.computecanada.ca: 1 cedar1.cedar.computecanada.ca: 1 usherbrooke.ca: 1 skoltech.ru: 1 phystech.edu: 1

Issues and Pull Requests

Last synced: 3 months ago

All Time

Total issues: 6
Total pull requests: 160
Average time to close issues: 24 days
Average time to close pull requests: 25 days
Total issue authors: 4
Total pull request authors: 2
Average comments per issue: 2.33
Average comments per pull request: 1.33
Merged pull requests: 89
Bot issues: 2
Bot pull requests: 160

Past Year

Issues: 1
Pull requests: 67
Average time to close issues: 4 days
Average time to close pull requests: 13 days
Issue authors: 1
Pull request authors: 2
Average comments per issue: 2.0
Average comments per pull request: 0.91
Merged pull requests: 30
Bot issues: 0
Bot pull requests: 67

View more stats

Top Authors

Issue Authors

twobombs (3)
HectorMozo3110 (1)
dependabot[bot] (1)
pre-commit-ci[bot] (1)

Pull Request Authors

dependabot[bot] (145)
pre-commit-ci[bot] (15)

Top Labels

Issue Labels

dependencies (1) python (1) bug (1)

Pull Request Labels

dependencies (145) python (133) github_actions (12)

Packages

Total packages: 1
Total downloads:
- pypi 513 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 8
Total maintainers: 1

pypi.org: mdopt

Discrete optimisation in the tensor-network (specifically, MPS-MPO) language.

Documentation: https://mdopt.readthedocs.io/
License: mit
Latest release: 1.1.1
published 4 months ago

Versions: 8
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 513 Last month

Rankings

Dependent packages count: 4.8%

Dependent repos count: 6.3%

Average: 8.2%

Downloads: 13.4%

Maintainers (1)

meandmytram

Last synced: 4 months ago

Dependencies

.github/workflows/codeql-analysis.yml actions

actions/checkout v3 composite
github/codeql-action/analyze v2 composite
github/codeql-action/autobuild v2 composite
github/codeql-action/init v2 composite

.github/workflows/dependency-review.yml actions

actions/checkout v3 composite
actions/dependency-review-action v3 composite

.github/workflows/lint.yml actions

actions/checkout v3 composite
actions/setup-python v4.5.0 composite

.github/workflows/tests.yml actions

actions/checkout v3 composite
actions/setup-python v4.5.0 composite
codecov/codecov-action v3 composite

poetry.lock pypi

PyYAML 6.0 develop
astroid 2.12.10 develop
attrs 22.1.0 develop
black 22.8.0 develop
click 8.1.3 develop
coverage 6.4.4 develop
dill 0.3.5.1 develop
iniconfig 1.1.1 develop
isort 5.10.1 develop
lazy-object-proxy 1.7.1 develop
markdown-it-py 2.1.0 develop
mccabe 0.7.0 develop
mdit-py-plugins 0.3.1 develop
mdurl 0.1.2 develop
mypy-extensions 0.4.3 develop
myst-parser 0.18.1 develop
pathspec 0.10.1 develop
platformdirs 2.5.2 develop
pluggy 1.0.0 develop
pockets 0.9.1 develop
py 1.11.0 develop
pylint 2.15.3 develop
pytest 7.1.3 develop
pytest-cov 3.0.0 develop
sphinxcontrib-napoleon 0.7 develop
tomlkit 0.11.4 develop
wrapt 1.14.1 develop
Babel 2.10.3
Jinja2 3.1.2
MarkupSafe 2.1.1
Pillow 9.2.0
Pygments 2.13.0
Sphinx 5.2.3
alabaster 0.7.12
certifi 2022.9.14
charset-normalizer 2.1.1
colorama 0.4.5
contourpy 1.0.5
cycler 0.11.0
docutils 0.17.1
fonttools 4.37.3
idna 3.4
imagesize 1.4.1
importlib-metadata 4.12.0
kiwisolver 1.4.4
matplotlib 3.6.0
more-itertools 8.14.0
numpy 1.23.3
opt-einsum 3.3.0
packaging 21.3
pyparsing 3.0.9
python-dateutil 2.8.2
pytz 2022.2.1
qecstruct 0.2.9
requests 2.28.1
scipy 1.9.1
setuptools 65.3.0
setuptools-scm 7.0.5
six 1.16.0
snowballstemmer 2.2.0
sphinx-rtd-theme 1.0.0
sphinxcontrib-applehelp 1.0.2
sphinxcontrib-devhelp 1.0.2
sphinxcontrib-htmlhelp 2.0.0
sphinxcontrib-jsmath 1.0.1
sphinxcontrib-qthelp 1.0.3
sphinxcontrib-serializinghtml 1.1.5
threadpoolctl 3.1.0
tomli 2.0.1
tqdm 4.64.1
typing-extensions 4.3.0
urllib3 1.26.12
zipp 3.8.1

pyproject.toml pypi

Sphinx ^5.2.3
matplotlib ^3.6.0
more-itertools ^8.12.0
numpy ^1.20.1
opt-einsum ^3.3.0
python >=3.8,<3.10
qecstruct ^0.2.2
scipy ^1.6.1
sphinx-rtd-theme ^1.0.0
threadpoolctl ^3.1.0
tqdm ^4.62.3

requirements.txt pypi

alabaster ==0.7.12
babel ==2.10.3
certifi ==2022.9.14
charset-normalizer ==2.1.1
colorama ==0.4.5
contourpy ==1.0.5
cycler ==0.11.0
docutils ==0.17.1
fonttools ==4.37.3
idna ==3.4
imagesize ==1.4.1
importlib-metadata ==4.12.0
jinja2 ==3.1.2
kiwisolver ==1.4.4
markupsafe ==2.1.1
matplotlib ==3.6.0
more-itertools ==8.14.0
numpy ==1.23.3
opt-einsum ==3.3.0
packaging ==21.3
pillow ==9.2.0
pygments ==2.13.0
pyparsing ==3.0.9
python-dateutil ==2.8.2
pytz ==2022.2.1
requests ==2.28.1
scipy ==1.9.1
setuptools ==65.3.0
setuptools-scm ==7.0.5
six ==1.16.0
snowballstemmer ==2.2.0
sphinx ==5.1.1
sphinx-rtd-theme ==1.0.0
sphinxcontrib-applehelp ==1.0.2
sphinxcontrib-devhelp ==1.0.2
sphinxcontrib-htmlhelp ==2.0.0
sphinxcontrib-jsmath ==1.0.1
sphinxcontrib-qthelp ==1.0.3
sphinxcontrib-serializinghtml ==1.1.5
tomli ==2.0.1
tqdm ==4.64.1
typing-extensions ==4.3.0
urllib3 ==1.26.12
zipp ==3.8.1

.github/workflows/mypy.yml actions

actions/checkout v4 composite
actions/setup-python v4.7.0 composite

.devcontainer/Dockerfile docker

mcr.microsoft.com/devcontainers/base jammy build

docs/source/requirements.txt pypi

ipykernel *
ipython *
mdopt *
myst-parser ==0.18.1
nbsphinx *
sphinx ==5.3.0
sphinx-rtd-theme ==1.3.0
sphinxcontrib-napoleon ==0.7

mdopt: A code-agnostic tensor-network decoder for quantum error-correcting codes

Science Score: 95.0%

Keywords

Keywords from Contributors

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

mdopt — Discrete Optimisation in the MPS-MPO Language

Installation

Minimal example

Define a small instance of the surface code

Input an error and choose decoder controls

Examples

Cite

Contribution guidelines

License

Documentation

Owner

JOSS Publication

mdopt: A code-agnostic tensor-network decoder for quantum error-correcting codes

Authors

Editor

Tags

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: mdopt

Rankings

Maintainers (1)

Dependencies

`mdopt` — Discrete Optimisation in the MPS-MPO Language