qLDPC

qLDPC is a Python toolkit for constructing and analyzing finite-size quantum low-density parity-check codes, as well as stabilizer and subsystem codes more broadly. The goal is simple: make the quantum error-correction literature easier to explore, reproduce, and build on. Codes can start from parity-check matrices or from higher-level ingredients such as polynomials, group rings, Tanner graphs, and chain complexes. Once a code is built, you can inspect its logical operators, compute or bound its distance, plug in a decoder, estimate logical error rates, and—for qubit codes—build stim circuits.

Most code-level tools work over arbitrary finite fields. Circuit tools currently only support qubit codes.

✨ A taste of qLDPC

• From textbook codes to the research frontier.

• Go beyond binary.

• Ask more of a code than [[n, k, d]].

• Move from codes to circuits.

• Use the algebra that modern constructions need.

• Steal from the examples.

qLDPC is still research software, and it is honest about the tradeoffs. Some searches are expensive, some bounds are heuristic, experimental APIs can change, and optional tools may have side effects.

📦 Installation

Standard installation

qLDPC requires Python 3.11 or later:

python -m pip install qldpc

Optional extras

Decoders

qLDPC installs ldpc and pymatching by default, which include a host of decoders. Install the optional decoder integrations published as qLDPC extras for your platform with:

python -m pip install 'qldpc[decoders]'

You can also use individual extras to install a specific optional decoder:

python -m pip install 'qldpc[relay-bp]'
python -m pip install 'qldpc[tesseract]'

The Tesseract decoder requires CPython 3.12–3.14 on macOS arm64 or Linux x86-64. Frontier is not published on PyPI and is not included in an extra; see the decoder guide for availability and build-time installation guidance.

GAP integration

Some algebra tools, code lookups, and distance estimates require GAP. For the recommended in-process integration, install qLDPC with its maintained libgap extra:

python -m pip install 'qldpc[gap]'

qLDPC uses passagemath-gap when available, so supported GAP operations do not launch a separate process. The in-process binding requires Python 3.13 on a non-Windows platform. If passagemath-gap is unavailable, qLDPC relies on a GAP executable in your PATH (possibly obtainable with conda install -c conda-forge gap), and a manual copy/paste fallback. GAP integration on Windows remains limited; see issue #294.

sqetch distance estimation

You can install the optional sqetch distance-estimation backend with:

python -m pip install 'sqetch[gpu] @ git+https://github.com/a7b/yarn.git@e9ce9d0fcecc973988558bfee27fab6d6b8d7f97#subdirectory=sqetch'

This command installs the upstream version of sqetch that qLDPC is tested against, with GPU support. sqetch is not published on PyPI, so it is not available as a qLDPC extra. For binary CSS codes, you can select this backend with code.get_distance_bound(backend="sqetch").

Troubleshooting

On macOS, you may need to install cvxpy manually by following its installation instructions before installing qLDPC. If you use Conda to manage your Python environment, install cvxpy with:

conda install -c conda-forge cvxpy

Development installation

For a development installation:

git clone https://github.com/qLDPCOrg/qLDPC.git
cd qLDPC
python -m pip install -e '.[dev]'

🚀 Quickstart

from sympy.abc import x, y
from qldpc import codes
The [[144, 12, 12]] bivariate bicycle "gross code".
code = codes.BBCode({x: 12, y: 6}, x3 + y + y2, y3 + x + x2)
print(code)
print("physical qubits:", len(code))
print("logical qubits:", code.dimension)

Go deeper: a subsystem lifted-product code

The next example builds a parity-check matrix over the group algebra GF(2)[C₅], lifts each group-ring entry to a 5×5 binary block, and hands the result to SLPCode. The subsystem lifted-product construction produces an 80-qubit CSS subsystem code with 5 logical qubits and 45 gauge qubits.

from qldpc import abstract, codes
group = abstract.CyclicGroup(5)
ring = abstract.GroupRing(group)
x = ring.generators[0]
repetition = abstract.RingArray.build(
    [[1, 1, 0, 0], [0, 1, 1, 0], [0, 0, 1, 1]],
    ring,
)
connections = abstract.RingArray.build(
    [[0, x, 0, 0], [0, 0, x, 0], [0, 0, 0, x]],
    ring,
)
code = codes.SLPCode(repetition + connections)
print("physical qubits:", len(code))            # 80
print("logical qubits:", code.dimension)        # 5
print("gauge qubits:", code.gauge_dimension)    # 45

Continue with the library map for the data model and package structure, or open the example notebooks for complete workflows.

🧭 Find your way around

| Goal | Start here | | --- | --- | | Understand code representations and how packages fit together | Library map | | Learn by running complete workflows | Examples | | Browse code families, functions, and exact signatures | API reference | | Construct and analyze a first code | qLDPC basics | | Estimate logical error rates | Logical-error-rate examples | | Build memory circuits or noise models | Circuit examples | | Change or extend qLDPC safely | Agent and contributor guide |

For the complete list of classes and functions, including construction-specific literature, use the API reference and source docstrings. This README focuses on getting started and finding the right documentation.

⚠️ Limitations and caveats

• Circuit and tableau tools only work with qubit codes, even though other parts of qLDPC support prime-power-dimensional qudits.
• Circuits returned by get_encoding_circuit are not fault-tolerant.

• Exact distance calculations and transversal-gate searches can be exponential.

• Features that use GAP may start subprocesses, use local disk caches, access online resources, or ask for manual input or permission to install a package.
• Everything under qldpc.experimental has an unstable public API and may change without deprecation.

📚 Documentation and support

• Documentation
• Examples
• API reference
• Agent and contributor guide
• Issue tracker

⚓ Attribution

If you use this software in your work, please cite with:

@misc{perlin2023qldpc,
  author = {Perlin, Michael A.},
  title = {{qLDPC}},
  year = {2023},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/qLDPCOrg/qLDPC}},
}

This may require adding \usepackage{url} to your LaTeX file header. Alternatively:

Michael A. Perlin. qLDPC. https://github.com/qLDPCOrg/qLDPC, 2023.

qLDPC is distributed under the Apache License 2.0.