mdopt — code-agnostic tensor-network (MPS-MPO) decoder for quantum error-correcting codes.

mdopt is a python package built on top of numpy for discrete optimisation (with the main application to 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.

pip install mdopt

Otherwise, you can clone the repository and use poetry.

poetry install

Minimal example

import numpy as np
import qecstruct as qec
from mdopt.examples.decoding.decoding import decode_css

# Define a small instance of the surface code
LATTICE_SIZE = 3
surface_code = qec.hypergraph_product(
    qec.repetition_code(LATTICE_SIZE),
    qec.repetition_code(LATTICE_SIZE),
)

# Input an error and choose decoder controls
logicals, success = decode_css(
    code=surface_code,
    error="IIXIIIIIIIIII",
    bias_prob=0.01,
    bias_type="Bitflip",
    chi_max=64,
    renormalise=True,
    contraction_strategy="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.

@article{berezutskii2025mdopt,
  title={mdopt: A code-agnostic tensor-network decoder for quantum error-correcting codes},
  author={Berezutskii, Aleksandr},
  journal={Journal of Open Source Software},
  volume={10},
  number={115},
  pages={9125},
  year={2025}
}

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:

  pytest tests
  

• Building documentation. Documentation is built with Sphinx. A convenience script is provided:

  ./generate_docs.sh
  

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

  black .
  

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

  pre-commit install
  

License

This project is licensed under the MIT License.

Documentation

Full documentation is available at mdopt.readthedocs.io.