# qLDPC
This library contains tools for constructing and analyzing [quantum low density parity check (qLDPC) codes](https://errorcorrectionzoo.org/c/qldpc). At least, that was the original motivation for this library. In practice, the tools here work just as well for error-correcting stabilizer and subsystem codes more broadly.
In a nutshell, `qLDPC` provides supports a variety of built-in codes and custom codes constructed from parity check matrices that represent stabilizer or gauge group generators. Once a code is constructed, `qLDPC` automates various tasks of common interest, and integrates with external tools for analyzing error-correcting codes (including [`QDistRnd`](https://docs.gap-system.org/pkg/qdistrnd/doc/chap1_mj.html), [`ldpc`](https://github.com/quantumgizmos/ldpc), [`stim`](https://github.com/quantumlib/Stim), and [`sinter`](https://pypi.org/project/sinter), among others). Automated tasks include:
- constructing a canonical basis logical Pauli operators,
- computing (or upper-bounding) code distance,
- computing logical error rates in a code-capacity model,
- constructing various circuits of interest, such as a quantum memory experiment for obtaining circuit-level logical error rates,
- defining custom Pauli noise models,
- plugging a decoder of choice into your workflow.
See the [`examples`](https://github.com/qLDPCOrg/qLDPC/tree/main/examples) directory for some demonstrations and use-cases.
Where possible, this library strives to support codes over arbitrary finite (Galois) fields -- that is, for 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](https://www.gap-system.org) 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 `gap-core`). Installations without `conda` should also work, as long as `gap` is a recognized command in the command line. Unfortunately, I have not figured out how to install [GAP](https://www.gap-system.org) in a `qLDPC`-compatible way on Windows. If you figure this out, [please let me know](https://github.com/qLDPCOrg/qLDPC/issues/294)!
### macOS
If you use macOS you may need to install `cvxpy` manually by following the instructions [here](https://www.cvxpy.org/install) 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.
- Communication with the [GAP](https://www.gap-system.org)/[`GUAVA`](https://www.gap-system.org/Packages/guava.html) package for [even more codes](https://docs.gap-system.org/pkg/guava/doc/chap5.html).
- `QuditCode`: class for constructing [Galois-qudit codes](https://errorcorrectionzoo.org/c/galois_into_galois), including both [stabilizer](https://errorcorrectionzoo.org/c/galois_stabilizer) and [subsystem](https://errorcorrectionzoo.org/c/oecc) 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`](https://docs.gap-system.org/pkg/qdistrnd/doc/chap1_mj.html) or (for CSS codes) a decoder-based method introduced in [arXiv:2308.07915](https://arxiv.org/abs/2308.07915).
- `QuditCode.concatenate`: method to [concatenate](https://errorcorrectionzoo.org/c/quantum_concatenated) `QuditCode`s in various ways.
- `CSSCode`: subclass of `QuditCode` for the special case of constructing a [quantum CSS code](https://errorcorrectionzoo.org/c/css) out of two mutually compatible `ClassicalCode`s. Special cases (subclasses) with specialized constructors and helper methods include:
- `TBCode`: [two-block quantum codes](https://errorcorrectionzoo.org/c/two_block_quantum).
- `BBCode`: [bivariate bicycle codes](https://errorcorrectionzoo.org/c/quantum_quasi_cyclic), as in [arXiv:2308.07915](https://arxiv.org/abs/2308.07915) and [arXiv:2311.16980](https://arxiv.org/abs/2311.16980). See [`examples/bivariate_bicycle_codes.ipynb`](https://github.com/qLDPCOrg/qLDPC/blob/main/examples/bivariate_bicycle_codes.ipynb) for methods to identify...
- toric layouts of a `BBCode`, in which the code looks like a toric code augmented by some long-distance checks, as in discussed in [arXiv:2308.07915](https://arxiv.org/abs/2308.07915), and
- qubit layouts that minimize the communication distance for neutral atoms, as discussed in [arXiv:2404.18809](https://arxiv.org/abs/2404.18809).
- `HGPCode`: [hypergraph product codes](https://errorcorrectionzoo.org/c/hypergraph_product), first introduced in [arXiv:0903.0566](https://arxiv.org/abs/0903.0566).
- `SHPCode`: [subsystem hypergraph product codes](https://errorcorrectionzoo.org/c/subsystem_quantum_parity), as in [arXiv:2002.06257](https://arxiv.org/abs/2002.06257).
- `SHYPSCode`: [subsystem hypergraph product simplex codes](https://errorcorrectionzoo.org/c/shyps), as in [arXiv:2502.07150](https://arxiv.org/abs/2502.07150).
- `LPCode`: [lifted product codes](https://errorcorrectionzoo.org/c/lifted_product), as in [arXiv:2012.04068](https://arxiv.org/abs/2012.04068) and [arXiv:2202.01702](https://arxiv.org/abs/2202.01702).
- `SLPCode`: [subsystem lifted product codes](https://errorcorrectionzoo.org/c/subsystem_lifted_product), as in [arXiv:2404.18302](https://arxiv.org/abs/2404.18302).
- `QTCode`: [quantum Tanner codes](https://errorcorrectionzoo.org/c/quantum_tanner), as in [arXiv:2202.13641](https://arxiv.org/abs/2202.13641) and [arXiv:2206.07571](https://arxiv.org/abs/2206.07571).
- `decoders.py`: module for decoding errors with various methods, including BP-OSD, BP-LSD, and belief-find (via [`ldpc`](https://github.com/quantumgizmos/ldpc)), Relay-BP (via [`relay-bp`](https://pypi.org/project/relay-bp)), minimum-weight perfect matching (via [`pymatching`](https://github.com/oscarhiggott/PyMatching)), and others. Includes an interface for using custom decoders.
- `qldpc.circuits`: module for [`stim`](https://github.com/quantumlib/Stim) circuits and circuit utilities, including:
- `get_memory_experiment`: circuit for testing the performance of a code as a quantum memory. Accepts both predefined and custom-built `SyndromeMeasurementStrategy`s.
- `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`.
- `SinterDecoder`: class to construct circuit-level decoders that are usable by [`sinter`](https://pypi.org/project/sinter).
- `get_encoding_circuit`: circuit to prepare the all-|0> logical state of a code. (Warning: generally not fault-tolerant. Fault-tolerant encoding circuits [pending](https://github.com/qLDPCOrg/qLDPC/issues/327).)
- `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](https://arxiv.org/abs/2409.18175). (Warning: exponential complexity.)
- `get_transversal_circuits`: find a SWAP-transversal physical circuit (if any) that implements a given logical Clifford operation in a code. (Warning: exponential complexity.)
- `abstract.py`: module for abstract algebra (groups, algebras, modules, and representations thereof).
- Various pre-defined groups (mostly borrowed from [SymPy](https://docs.sympy.org/latest/modules/combinatorics/named_groups.html)).
- Communication with the [GAP](https://www.gap-system.org) computer algebra system and [GroupNames.org](https://people.maths.bris.ac.uk/~matyd/GroupNames) for constructing [even more groups](https://docs.gap-system.org/doc/ref/chap50.html).
- `objects.py`: 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 have a [documentation page](https://qldpc.readthedocs.io/en/latest), but at the moment the documentation is out of date and auto-generated from source code that was written to be human-readable in a plain text editor. For now, I recommend looking at the source code (and comments therein) directly, as well as the [`examples`](https://github.com/qLDPCOrg/qLDPC/tree/main/examples) directory. Test files (such as [`qldpc/codes/quantum_test.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/qldpc/codes/quantum_test.py)) also contain some examples of using the classes and methods in this library.
If you have any questions, feedback, or requests, please [open an issue on GitHub](https://github.com/qLDPCOrg/qLDPC/issues/new) or email me at [mika.perlin@gmail.com](mailto: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.
```
Raw data
{
"_id": null,
"home_page": "https://github.com/qLDPCOrg/qLDPC",
"name": "qLDPC",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "quantum computing, quantum error correction, low density parity check codes, LDPC",
"author": "Michael A. Perlin",
"author_email": "mika.perlin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1d/c4/a3764d08db475d7daed4f71fd50409baa2570e453c4817648699f5c9c937/qldpc-0.2.1.tar.gz",
"platform": null,
"description": "# qLDPC\n\nThis library contains tools for constructing and analyzing [quantum low density parity check (qLDPC) codes](https://errorcorrectionzoo.org/c/qldpc). At least, that was the original motivation for this library. In practice, the tools here work just as well for error-correcting stabilizer and subsystem codes more broadly.\n\nIn a nutshell, `qLDPC` provides supports a variety of built-in codes and custom codes constructed from parity check matrices that represent stabilizer or gauge group generators. Once a code is constructed, `qLDPC` automates various tasks of common interest, and integrates with external tools for analyzing error-correcting codes (including [`QDistRnd`](https://docs.gap-system.org/pkg/qdistrnd/doc/chap1_mj.html), [`ldpc`](https://github.com/quantumgizmos/ldpc), [`stim`](https://github.com/quantumlib/Stim), and [`sinter`](https://pypi.org/project/sinter), among others). Automated tasks include:\n- constructing a canonical basis logical Pauli operators,\n- computing (or upper-bounding) code distance,\n- computing logical error rates in a code-capacity model,\n- constructing various circuits of interest, such as a quantum memory experiment for obtaining circuit-level logical error rates,\n- defining custom Pauli noise models,\n- plugging a decoder of choice into your workflow.\n\nSee the [`examples`](https://github.com/qLDPCOrg/qLDPC/tree/main/examples) directory for some demonstrations and use-cases.\n\nWhere possible, this library strives to support codes over arbitrary finite (Galois) fields -- that is, for qudits of any prime power dimension. Circuit-related utilities are, however, limited to qubit codes.\n\n## \ud83d\udce6 Installation\n\nThis library requires Python>=3.10, and can be installed from the Python Package Index (PyPI) with\n```\npip install qldpc\n```\n\nTo install a local version of qLDPC from source:\n```\ngit clone https://github.com/qLDPCOrg/qLDPC.git\npip install -e qLDPC\n```\nYou can also `pip install -e 'qLDPC[dev]'` to additionally install some development tools.\n\n### GAP\n\nSome features in `qLDPC` require an installation of the [GAP](https://www.gap-system.org) 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 `gap-core`). Installations without `conda` should also work, as long as `gap` is a recognized command in the command line. Unfortunately, I have not figured out how to install [GAP](https://www.gap-system.org) in a `qLDPC`-compatible way on Windows. If you figure this out, [please let me know](https://github.com/qLDPCOrg/qLDPC/issues/294)!\n\n### macOS\n\nIf you use macOS you may need to install `cvxpy` manually by following the instructions [here](https://www.cvxpy.org/install) before installing `qLDPC`. If you use `conda` to manage your python environment, you can obtain `cvxpy` by running `conda install -c conda-forge cvxpy`.\n\n## \ud83d\ude80 Features\n\nNotable features include:\n- `ClassicalCode`: class for representing classical linear error-correcting codes over finite fields.\n - Various pre-defined classical code families.\n - Communication with the [GAP](https://www.gap-system.org)/[`GUAVA`](https://www.gap-system.org/Packages/guava.html) package for [even more codes](https://docs.gap-system.org/pkg/guava/doc/chap5.html).\n- `QuditCode`: class for constructing [Galois-qudit codes](https://errorcorrectionzoo.org/c/galois_into_galois), including both [stabilizer](https://errorcorrectionzoo.org/c/galois_stabilizer) and [subsystem](https://errorcorrectionzoo.org/c/oecc) codes.\n - `QuditCode.get_logical_ops`: method to construct a complete basis of nontrivial logical Pauli operators for a `QuditCode`.\n - `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`](https://docs.gap-system.org/pkg/qdistrnd/doc/chap1_mj.html) or (for CSS codes) a decoder-based method introduced in [arXiv:2308.07915](https://arxiv.org/abs/2308.07915).\n - `QuditCode.concatenate`: method to [concatenate](https://errorcorrectionzoo.org/c/quantum_concatenated) `QuditCode`s in various ways.\n- `CSSCode`: subclass of `QuditCode` for the special case of constructing a [quantum CSS code](https://errorcorrectionzoo.org/c/css) out of two mutually compatible `ClassicalCode`s. Special cases (subclasses) with specialized constructors and helper methods include:\n - `TBCode`: [two-block quantum codes](https://errorcorrectionzoo.org/c/two_block_quantum).\n - `BBCode`: [bivariate bicycle codes](https://errorcorrectionzoo.org/c/quantum_quasi_cyclic), as in [arXiv:2308.07915](https://arxiv.org/abs/2308.07915) and [arXiv:2311.16980](https://arxiv.org/abs/2311.16980). See [`examples/bivariate_bicycle_codes.ipynb`](https://github.com/qLDPCOrg/qLDPC/blob/main/examples/bivariate_bicycle_codes.ipynb) for methods to identify...\n - toric layouts of a `BBCode`, in which the code looks like a toric code augmented by some long-distance checks, as in discussed in [arXiv:2308.07915](https://arxiv.org/abs/2308.07915), and\n - qubit layouts that minimize the communication distance for neutral atoms, as discussed in [arXiv:2404.18809](https://arxiv.org/abs/2404.18809).\n - `HGPCode`: [hypergraph product codes](https://errorcorrectionzoo.org/c/hypergraph_product), first introduced in [arXiv:0903.0566](https://arxiv.org/abs/0903.0566).\n - `SHPCode`: [subsystem hypergraph product codes](https://errorcorrectionzoo.org/c/subsystem_quantum_parity), as in [arXiv:2002.06257](https://arxiv.org/abs/2002.06257).\n - `SHYPSCode`: [subsystem hypergraph product simplex codes](https://errorcorrectionzoo.org/c/shyps), as in [arXiv:2502.07150](https://arxiv.org/abs/2502.07150).\n - `LPCode`: [lifted product codes](https://errorcorrectionzoo.org/c/lifted_product), as in [arXiv:2012.04068](https://arxiv.org/abs/2012.04068) and [arXiv:2202.01702](https://arxiv.org/abs/2202.01702).\n - `SLPCode`: [subsystem lifted product codes](https://errorcorrectionzoo.org/c/subsystem_lifted_product), as in [arXiv:2404.18302](https://arxiv.org/abs/2404.18302).\n - `QTCode`: [quantum Tanner codes](https://errorcorrectionzoo.org/c/quantum_tanner), as in [arXiv:2202.13641](https://arxiv.org/abs/2202.13641) and [arXiv:2206.07571](https://arxiv.org/abs/2206.07571).\n- `decoders.py`: module for decoding errors with various methods, including BP-OSD, BP-LSD, and belief-find (via [`ldpc`](https://github.com/quantumgizmos/ldpc)), Relay-BP (via [`relay-bp`](https://pypi.org/project/relay-bp)), minimum-weight perfect matching (via [`pymatching`](https://github.com/oscarhiggott/PyMatching)), and others. Includes an interface for using custom decoders. \n- `qldpc.circuits`: module for [`stim`](https://github.com/quantumlib/Stim) circuits and circuit utilities, including:\n - `get_memory_experiment`: circuit for testing the performance of a code as a quantum memory. Accepts both predefined and custom-built `SyndromeMeasurementStrategy`s.\n - `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`.\n - `SinterDecoder`: class to construct circuit-level decoders that are usable by [`sinter`](https://pypi.org/project/sinter).\n - `get_encoding_circuit`: circuit to prepare the all-|0> logical state of a code. (Warning: generally not fault-tolerant. Fault-tolerant encoding circuits [pending](https://github.com/qLDPCOrg/qLDPC/issues/327).)\n - `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](https://arxiv.org/abs/2409.18175). (Warning: exponential complexity.)\n - `get_transversal_circuits`: find a SWAP-transversal physical circuit (if any) that implements a given logical Clifford operation in a code. (Warning: exponential complexity.)\n- `abstract.py`: module for abstract algebra (groups, algebras, modules, and representations thereof).\n - Various pre-defined groups (mostly borrowed from [SymPy](https://docs.sympy.org/latest/modules/combinatorics/named_groups.html)).\n - Communication with the [GAP](https://www.gap-system.org) computer algebra system and [GroupNames.org](https://people.maths.bris.ac.uk/~matyd/GroupNames) for constructing [even more groups](https://docs.gap-system.org/doc/ref/chap50.html).\n- `objects.py`: module for constructing helper objects such as Cayley complexes and chain complexes, which are instrumental for the construction of various quantum codes.\n\n## \ud83e\udd14 Questions and issues\n\nThis project aspires to have a [documentation page](https://qldpc.readthedocs.io/en/latest), but at the moment the documentation is out of date and auto-generated from source code that was written to be human-readable in a plain text editor. For now, I recommend looking at the source code (and comments therein) directly, as well as the [`examples`](https://github.com/qLDPCOrg/qLDPC/tree/main/examples) directory. Test files (such as [`qldpc/codes/quantum_test.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/qldpc/codes/quantum_test.py)) also contain some examples of using the classes and methods in this library.\n\nIf you have any questions, feedback, or requests, please [open an issue on GitHub](https://github.com/qLDPCOrg/qLDPC/issues/new) or email me at [mika.perlin@gmail.com](mailto:mika.perlin@gmail.com)!\n\n## \u2693 Attribution\n\nIf you use this software in your work, please cite with:\n```\n@misc{perlin2023qldpc,\n author = {Perlin, Michael A.},\n title = {{qLDPC}},\n year = {2023},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/qLDPCOrg/qLDPC}},\n}\n```\nThis may require adding `\\usepackage{url}` to your LaTeX file header. Alternatively, you can cite\n```\nMichael A. Perlin. qLDPC. https://github.com/qLDPCOrg/qLDPC, 2023.\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Tools for constructing and analyzing quantum low density parity check (qLDPC) codes.",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/qLDPCOrg/qLDPC",
"Repository": "https://github.com/qLDPCOrg/qLDPC"
},
"split_keywords": [
"quantum computing",
" quantum error correction",
" low density parity check codes",
" ldpc"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "096410c2ffecc34be274b9752494bf63070e00acb79fed320e0f29cca0592935",
"md5": "5951579d01963364d382a02cfe54c85a",
"sha256": "bde10960854c31c116be1cb06a2df79c543e1409e614d572b818e26b8bb2c78a"
},
"downloads": -1,
"filename": "qldpc-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5951579d01963364d382a02cfe54c85a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 171462,
"upload_time": "2025-08-20T01:04:26",
"upload_time_iso_8601": "2025-08-20T01:04:26.511205Z",
"url": "https://files.pythonhosted.org/packages/09/64/10c2ffecc34be274b9752494bf63070e00acb79fed320e0f29cca0592935/qldpc-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1dc4a3764d08db475d7daed4f71fd50409baa2570e453c4817648699f5c9c937",
"md5": "a17c8ba44f19610a8822a7c01d93d547",
"sha256": "14eeab4273c0e93c906c6b8dd222aca3d3213c9abe9ebeb1d1d590f35227797f"
},
"downloads": -1,
"filename": "qldpc-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "a17c8ba44f19610a8822a7c01d93d547",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 142877,
"upload_time": "2025-08-20T01:04:27",
"upload_time_iso_8601": "2025-08-20T01:04:27.629709Z",
"url": "https://files.pythonhosted.org/packages/1d/c4/a3764d08db475d7daed4f71fd50409baa2570e453c4817648699f5c9c937/qldpc-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 01:04:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qLDPCOrg",
"github_project": "qLDPC",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "qldpc"
}
JSON
