qLDPC

This library contains tools for constructing and analyzing quantum low density parity check (qLDPC) codes. At least, that was the original motivation for this library. In practice, the tools here work just as well for stabilizer and subsystem codes more broadly.

In a nutshell, qLDPC provides methods to build a variety of built-in and custom codes, represented under the hood by a parity check matrix. Once a code is constructed, qLDPC automates various tasks of common interest, integrating with a variety of external tools (including ldpc, stim, sinter, QDistRnd, and MAGMA, among others). Automated tasks include:

• constructing a code from a variety of code families,
• constructing a canonical basis of logical Pauli operators,
• computing (or upper-bounding) code distance,
• computing logical error rates in a code-capacity model,
• computing the logical error rates and post-selection rates of state preparation circuits,
• constructing circuits of interest, such as memory experiments and logical encoding circuits,
• defining custom Pauli noise models,
• using a decoder of your choice for any of the above (or other, unlisted) tasks.

See the examples directory for some demonstrations and use-cases.

Where possible, this library strives to support codes over arbitrary finite (Galois) fields -- that is, for Galois qudits of any prime power dimension. Circuit-related utilities are, however, limited to qubit codes.

📦 Installation

This library requires Python>=3.10, and can be installed from the Python Package Index (PyPI) with

pip install qldpc

To install a local version of qLDPC from source:

git clone https://github.com/qLDPCOrg/qLDPC.git
pip install -e qLDPC

You can also pip install -e 'qLDPC[dev]' to additionally install some development tools.

GAP

Some features in qLDPC require an installation of the GAP computer algebra system. If you (a) use linux or macOS, and (b) use a conda to manage your python environment, then you can obtain GAP by running

conda install -c conda-forge gap

or conda install -c conda-forge gap-core. Installations without conda should also work, as long as gap is a recognized command in the command line. Unfortunately, GAP integration is clunky in Windows because I have not figured out how to call GAP from the Windows command prompt. If you figure this out, please let me know!

macOS

If you use macOS you may need to install cvxpy manually by following the instructions here before installing qLDPC. If you use conda to manage your python environment, you can obtain cvxpy by running

conda install -c conda-forge cvxpy

🚀 Features

Notable features include:

• ClassicalCode: class for representing classical linear error-correcting codes over finite fields.
  • Various pre-defined classical code families, including RepetitionCode, HammingCode, SimplexCode, ReedMullerCode, ReedSolomonCode, TannerCode, and more.
  • Communication with the GAP/GUAVA package for even more codes.
• QuditCode: class for constructing Galois-qudit codes, including both stabilizer and subsystem codes.
  • QuditCode.get_logical_ops: method to construct a complete basis of nontrivial logical Pauli operators for a QuditCode.
  • QuditCode.get_distance: method to compute the exact code distance of a QuditCode (i.e., the minimum weight of a nontrivial logical operator). Includes options to compute an upper bound on code distance using QDistRnd or (for CSS codes) a decoder-based method introduced in arXiv:2308.07915.
  • QuditCode.concatenate: method to concatenate QuditCodes in various ways.
• CSSCode: subclass of QuditCode for the special case of constructing a quantum CSS code out of two mutually compatible ClassicalCodes. Special cases (subclasses) with specialized constructors and helper methods include:
  • Common codes such as the SteaneCode and TetrahedralCode.
  • Common code families such as the SurfaceCode, ToricCode, BaconShorCode, and QuantumHammingCode.
  • TBCode: two-block quantum codes.
  • QCCode: quasi-cyclic two-block codes (also known as multivariate bicycle codes, generalizing the BBCode below).
  • BBCode: bivariate bicycle codes, as in arXiv:2308.07915 and arXiv:2311.16980. See also examples/bivariate_bicycle_codes.ipynb.
  • HGPCode: hypergraph product codes, first introduced in arXiv:0903.0566.
  • CHGPCode / CRCode: cyclic hypergraph product and repeated cyclic hypergraph product codes, as in arXiv:2511.09683.
  • SHPCode: subsystem hypergraph product codes, as in arXiv:2002.06257.
  • SHYPSCode: subsystem hypergraph product simplex codes, as in arXiv:2502.07150.
  • LPCode: lifted product codes, as in arXiv:2012.04068 and arXiv:2202.01702.
  • SLPCode: subsystem lifted product codes, as in arXiv:2404.18302.
  • QTCode: quantum Tanner codes, as in arXiv:2202.13641, arXiv:2206.07571, and arXiv:2508.05095.
• qldpc.decoders: module for decoding code and circuit errors.
  • BP-OSD, BP-LSD, and belief-find (via ldpc), Relay-BP (via relay-bp), minimum-weight perfect matching (via pymatching), lookup-table decoding, and others. Includes an interface for using custom decoders.
  • SinterDecoder: class to construct circuit-level decoders that are usable by sinter.
  • SlidingWindowDecoder: the overlapping-recovery sliding-window decoder of arXiv:quant-ph/0110143 and arXiv:2209.08552.
  • SequentialWindowDecoder: a generalization of the SlidingWindowDecoder for arbitrary decoding and commit regions.
  • DetectorErrorModelArrays: representation of a stim.DetectorErrorModel with scipy.sparse and numpy arrays (detector_flip_matrix, observable_flip_matrix, error_probs).
• qldpc.circuits: module for stim circuits and circuit utilities, including:
  • get_memory_experiment: circuit to test the performance of a code as a quantum memory (using various pre-built syndrome measurement strategies), appropriately annotated with detectors and observables.
  • get_state_prep_diagnostic_circuit, get_state_prep_diagnostic_tasks, get_logical_error_and_discard_rate: helper methods for computing the logical error rates and post-selection rates of state preparation circuits.
  • NoiseModel: class for constructing expressive Pauli noise models, which map noiseless circuits to noisy circuits. Built-in subclasses include a single-parameter DepolarizingNoiseModel and a superconducting-inspired SI1000NoiseModel.
  • get_encoding_circuit: circuit to encode physical states of qubits into logical states of a code, for example to prepare a logical all-|0> state. (Warning: current encoding circuits are not fault-tolerant. The construction of fault-tolerant encoding circuits is an open issue.)
  • get_transversal_ops: logical tableaus and physical circuits for the SWAP-transversal logical Clifford gates of a code, constructed via the code automorphism method of arXiv:2409.18175. (Warning: exponential complexity.)
  • get_transversal_circuit: find a SWAP-transversal physical circuit (if any) that implements a given logical Clifford operation in a code. (Warning: exponential complexity.)
• qldpc.abstract: module for abstract algebra (groups, rings, modules, and representations thereof).
  • Various pre-defined groups (mostly borrowed from SymPy).
  • Communication with the GAP computer algebra system and GroupNames.org for constructing even more groups.
• qldpc.objects: module for constructing helper objects such as Cayley complexes and chain complexes, which are instrumental for the construction of various quantum codes.

🤔 Questions and issues

This project aspires to one day have a proper documentation page. In the meantime, I recommend looking at source code and the detailed comments therein, as well as help(qldpc.object_of_interest). qLDPC requires every file (such as qldpc/codes/quantum.py) to be covered by its own test file (such as qldpc/codes/quantum_test.py), so test files are a good place to look for example usage of any function, class, etc. Finally, the examples directory has some helpful notebooks to get you started.

If you have any questions, feedback, or requests, please open an issue on GitHub or email me 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, you can cite

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