Metadata-Version: 2.4
Name: qldpc
Version: 0.4.0
Summary: Tools for constructing and analyzing quantum low density parity check (qLDPC) codes.
Keywords: LDPC,low density parity check codes,quantum computing,quantum error correction
Author: Michael A. Perlin
Author-email: Michael A. Perlin <mika.perlin@gmail.com>
License-Expression: Apache-2.0
License-File: COPYRIGHT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: cvxpy>=1.3.2
Requires-Dist: diskcache>=5
Requires-Dist: galois>=0.4.2
Requires-Dist: ldpc>=2.4.1
Requires-Dist: networkx>=2.6.2
Requires-Dist: numpy>=1.24
Requires-Dist: platformdirs>=4
Requires-Dist: pymatching>=2.3
Requires-Dist: pyperclip>=1.11
Requires-Dist: scipy>=1.14.1
Requires-Dist: sinter>=1.16
Requires-Dist: stim>=1.16
Requires-Dist: sympy>=1.12
Requires-Dist: tqdm>=4
Requires-Dist: checks-superstaq>=0.5.67 ; extra == 'dev'
Requires-Dist: jupyter>=1.1.1 ; extra == 'dev'
Requires-Dist: pypandoc-binary>=1.13 ; extra == 'dev'
Requires-Dist: pyproject-fmt>=2 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: pytest-randomly>=3.10 ; extra == 'dev'
Requires-Dist: pytest-socket>=0.7 ; extra == 'dev'
Requires-Dist: python-lsp-server[all]>=1.14 ; extra == 'dev'
Requires-Dist: qldpc[docs,gap,relay-bp] ; extra == 'dev'
Requires-Dist: ipython>=8 ; extra == 'docs'
Requires-Dist: nbsphinx>=0.9 ; extra == 'docs'
Requires-Dist: sphinx>=7 ; extra == 'docs'
Requires-Dist: sphinx-autoapi>=3 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2 ; extra == 'docs'
Requires-Dist: passagemath-gap==10.8.12 ; python_full_version < '3.15' and sys_platform != 'win32' and extra == 'gap'
Requires-Dist: relay-bp[stim]==0.2.2 ; extra == 'relay-bp'
Requires-Python: >=3.11
Project-URL: Documentation, https://qldpc.readthedocs.io/
Project-URL: Issues, https://github.com/qLDPCOrg/qLDPC/issues
Project-URL: Repository, https://github.com/qLDPCOrg/qLDPC
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: gap
Provides-Extra: relay-bp
Description-Content-Type: text/markdown

# qLDPC

`qLDPC` is a Python toolkit for constructing and analyzing finite-size [quantum low-density parity-check codes](https://errorcorrectionzoo.org/c/qldpc), 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`](https://github.com/quantumlib/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.**
  Build familiar surface, toric, Hamming, and Reed–Muller codes alongside hypergraph-product, lifted-product, bivariate-bicycle, quantum Tanner, SHYPS, GALA, and other modern families.
- **Go beyond binary.**
  Many constructions and core algorithms work over arbitrary prime-power finite fields, not just qubits.
- **Ask more of a code than `[[n, k, d]]`.**
  Work with check matrices, Tanner graphs, canonical logical operators, subsystem gauges, exact distances, upper bounds, and code-capacity error estimates.
- **Move from codes to circuits.**
  Build memory experiments, encoding circuits, Pauli noise models, state-preparation diagnostics, Sinter decoders, sliding-window decoders, and transversal Clifford searches.
- **Use the algebra that modern constructions need.**
  qLDPC includes finite groups, group rings, lifted matrices, Cayley complexes, chain complexes, and optional GAP integration.
- **Steal from the examples.**
  The notebooks progress from the basics to circuit-level logical error rates, custom noise, transversal gates, and experimental lattice surgery.

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:

```bash
python -m pip install qldpc
```

### Optional extras

#### Relay-BP decoder

Install the optional Relay-BP decoder with:

```bash
python -m pip install 'qldpc[relay-bp]'
```

#### GAP integration

Some algebra tools, code lookups, and distance estimates require [GAP](https://www.gap-system.org).
For the recommended in-process integration, install qLDPC with its maintained libgap extra:

```bash
python -m pip install 'qldpc[gap]'
```

qLDPC uses `passagemath-gap` when it is installed, so supported GAP operations do not launch a separate process.
If the extra is unavailable, qLDPC still supports a GAP executable on `PATH` (`conda install -c conda-forge gap` is one option) and retains its documented manual copy/paste fallback.
If a package such as GUAVA or QDistRnd is absent from the in-process binding, qLDPC asks for permission to install it through GAP's PackageManager.
If that attempt fails and a separate GAP executable is available, qLDPC prints instructions for installing the package for libgap before using the executable instead.
GAP integration on Windows remains limited; see [issue #294](https://github.com/qLDPCOrg/qLDPC/issues/294).

#### `sqetch` distance estimation

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

```bash
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, select it with `code.get_distance_bound(backend="sqetch")`.

### Troubleshooting

On macOS, you may need to install `cvxpy` manually by following its [installation instructions](https://www.cvxpy.org/install) before installing qLDPC.
If you use Conda to manage your Python environment, install `cvxpy` with:

```bash
conda install -c conda-forge cvxpy
```

### Development installation

For a development installation:

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

## 🚀 Quickstart

```python
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)
```

That object is ready for more than a parameter check: inspect its parity checks and logical operators, choose a decoder, estimate a logical error rate, or use it in a memory experiment.

### Go deeper: a subsystem lifted-product code

For a more technical taste, 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](https://arxiv.org/abs/2404.18302) produces an 80-qubit CSS subsystem code with 5 logical qubits and 45 gauge qubits.

```python
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](https://qldpc.readthedocs.io/library_map.html) for the data model and package structure, or open the [example notebooks](https://qldpc.readthedocs.io/examples/index.html) for complete workflows.

## 🧭 Find your way around

| Goal | Start here |
| --- | --- |
| Understand code representations and how packages fit together | [Library map](https://qldpc.readthedocs.io/library_map.html) |
| Learn by running complete workflows | [Examples](https://qldpc.readthedocs.io/examples/index.html) |
| Browse code families, functions, and exact signatures | [API reference](https://qldpc.readthedocs.io/autoapi/index.html) |
| Construct and analyze a first code | [qLDPC basics](https://qldpc.readthedocs.io/examples/basics.html) |
| Estimate logical error rates | [Logical-error-rate examples](https://qldpc.readthedocs.io/examples/index.html#logical-error-rates) |
| Build memory circuits or noise models | [Circuit examples](https://qldpc.readthedocs.io/examples/index.html) |
| Change or extend qLDPC safely | [Agent and contributor guide](https://github.com/qLDPCOrg/qLDPC/blob/main/AGENTS.md) |

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.
  Fault-tolerant encoding is tracked in [issue #327](https://github.com/qLDPCOrg/qLDPC/issues/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, 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.
  In particular, lattice-surgery support has not yet received independent expert review; validate its results independently and pin the qLDPC version if you depend on it.

## 📚 Documentation and support

- [Documentation](https://qldpc.readthedocs.io/)
- [Examples](https://github.com/qLDPCOrg/qLDPC/tree/main/examples)
- [API reference](https://qldpc.readthedocs.io/autoapi/index.html)
- [Agent and contributor guide](https://github.com/qLDPCOrg/qLDPC/blob/main/AGENTS.md)
- [Issue tracker](https://github.com/qLDPCOrg/qLDPC/issues)

Questions, feedback, and ideas are welcome through [GitHub issues](https://github.com/qLDPCOrg/qLDPC/issues/new) or by email at [mika.perlin@gmail.com](mailto:mika.perlin@gmail.com).

## ⚓ Attribution

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

```bibtex
@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:

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

qLDPC is distributed under the [Apache License 2.0](https://github.com/qLDPCOrg/qLDPC/blob/main/LICENSE).
