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 provides shared implementations and scientific conventions that researchers and their AI assistants can inspect, combine, and extend.
Most code-level tools work over arbitrary finite fields. Circuit tools currently only support qubit codes.
- Enable exploration. Favor small, composable tools and extension points that let users quickly investigate and prototype new ideas.
- Make scientific meaning explicit. Expose conventions, assumptions, and limitations, and distinguish exact results, bounds, estimates, and trusted inputs.
- Support checking and reproduction. Provide independent evidence for maintained behavior and make the configuration needed to interpret and reproduce experiments clear.
- Support learning. Use small examples and explanations to connect computations to ideas, literature, and implementations.
- Code families. Construct surface, toric, Hamming, and Reed–Muller codes, along with hypergraph-product, lifted-product, balanced-product, bivariate-bicycle, quantum Tanner, SHYPS, GALA, and other families.
- Distance calculations.
Compute exact distances of binary codes with an optimized Brouwer–Zimmermann search.
Codes with sparse checks can instead use a search over Tanner-connected supports.
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; certify fault distances and bounded fault propagation exactly; or search for transversal Clifford gates.
- Algebraic tools. Work with finite groups, group algebras, rings generated by matrices, lifted matrices, Cayley complexes, chain complexes, and optional GAP integration.
The example notebooks cover (among other things) code construction, custom noise models, circuit-level logical error rates, and fault-tolerance certificates.
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().
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) # 45The library map explains the data model and package structure.
qLDPC requires Python 3.11 or later:
python -m pip install qldpcThe standard installation includes the ldpc and pymatching decoders.
See the installation guide for optional decoders, GAP integration, GPU distance estimation with sqetch, and troubleshooting.
For a development checkout, follow the development installation instructions.
| Goal | Start here |
|---|---|
| Understand code representations and how packages fit together | Library map |
| Learn the concepts through runnable examples | 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 | Contributing guide |
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, fault-tolerance certificates, and transversal-gate searches can take exponential time. 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.
Questions, feedback, and ideas are welcome through GitHub issues or by email at mika.perlin@gmail.com.
AI assistants are used in qLDPC's development and maintenance. Human maintainers direct and approve changes, but may rely on AI-assisted review and automated checks rather than reviewing every implementation detail. AI-assisted contributions are held to the same standards for scientific correctness, testing, documentation, and compatibility as other contributions. Project maintainers remain responsible for accepting contributions and communicating their assumptions and limitations.
If you use qLDPC in your work, please follow the citation instructions.
qLDPC is distributed under the Apache License 2.0.