This release is a pre-release and may not be stable for production use.
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.
It aims to make constructions and algorithms from the quantum error-correction literature easier to explore, reproduce, and build on.
You can define codes using parity-check matrices or higher-level ingredients such as polynomials, group rings, Tanner graphs, and chain complexes.
From there, you can inspect logical operators, compute or bound code distance, choose 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 few things to try
- Code families. Construct surface, toric, Hamming, and Reed–Muller codes, along with hypergraph-product, lifted-product, bivariate-bicycle, quantum Tanner, SHYPS, GALA, and other families.
- Distance calculations.
Compute exact distances of binary codes with an optimized Brouwer–Zimmermann search, or bound code distance using QDistRnd or
sqetch. - Code structure and analysis. Work with check matrices, Tanner graphs, canonical logical operators, subsystem gauge operators, and code-capacity error estimates.
- Circuits and decoding workflows. Build memory experiments, encoding circuits, Pauli noise models, and state-preparation diagnostics; use Sinter and sliding-window decoders, or search for transversal Clifford gates.
- Algebraic tools. Work with finite groups, group rings, lifted matrices, Cayley complexes, chain complexes, and optional GAP integration.
The example notebooks cover (among other things) code construction, custom noise models, and circuit-level logical error rates.
🚀 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}, x**3 + y + y**2, y**3 + x + x**2)
print(code)
print("physical qubits:", len(code))
print("logical qubits:", code.dimension)
The gross code is also available as the named construction, codes.GrossCode().
A subsystem lifted-product code
This 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 passes 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
The library map explains the data model and package structure.
📦 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 provide several decoding algorithms.
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[ilp]'
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, which the ILP decoder requires, manually by following its installation instructions before installing qldpc[ilp] or qldpc[decoders].
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]'
🧭 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 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 |
⚠️ Limitations and caveats
qLDPC is research software. Some searches are expensive, some bounds are heuristic, experimental APIs can change, and optional tools may have side effects.
- 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_circuitare not fault-tolerant. Fault-tolerant encoding is tracked in issue #327. - Exact distance calculations and transversal-gate searches can be exponential. When a method returns a bound rather than an exact distance, its docstring explains what kind of bound it is.
- Features that use GAP may start subprocesses, access online resources, or ask for manual input or permission to install a package.
- Code lookups such as
QuditCode.from_qecdb_idaccess online resources and cache results on disk; passrefresh=Trueto fetch the latest data. - Everything under
qldpc.experimentalhas an unstable public API and may change without deprecation. - Lattice-surgery support in
qldpc.experimental.surgeryis experimental and unstable, and its implementation is still pending careful expert review. Validate its results independently, and pin the qLDPC version if you depend on it.
📚 Documentation and support
Questions, feedback, and ideas are welcome through GitHub issues or by email at mika.perlin@gmail.com.
⚓ 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.
1 maintainer
Metadata
1 maintainer
Release files for qldpc 0.4.2.dev20261023
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| qldpc-0.4.2.dev20261023.tar.gz | 656.1 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| qldpc-0.4.2.dev20261023-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / qldpc-0.4.2.dev20261023.tar.gz
| Download URL | qldpc-0.4.2.dev20261023.tar.gz |
|---|---|
| Size | 656.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1ef2c2b9738c958b8cfb7e8d903d8d640b5dfee73ac3c8f0b419f92ba051105f
|
|
BLAKE2b-256 checksum How to use checksums |
fd565d7f10bc1a7a6caee901efa9dffd6475dcdbf80aa06b58a84fe86760dae1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.12
|
Release files / qldpc-0.4.2.dev20261023-py3-none-any.whl
| Download URL | qldpc-0.4.2.dev20261023-py3-none-any.whl |
|---|---|
| Size | 766.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5883c4654652951b8ca7e4b0eb8e74003c4fe58249836d15ee4555f0e6092e76
|
|
BLAKE2b-256 checksum How to use checksums |
776639b796c49ad02edb4927214ecccb17bb9af29740b015aa999c387aaf7e77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.12
|
Security for qldpc 0.4.2.dev20261023
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
