qldpc 0.3.3__tar.gz

qldpc-0.3.3/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: qldpc
+Version: 0.3.3
+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
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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.1
+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: checks-superstaq>=0.5.62 ; 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: python-lsp-server[all]>=1.14 ; extra == 'dev'
+Requires-Dist: qldpc[docs,relay-bp,tsim] ; 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: relay-bp[stim]==0.2.1 ; extra == 'relay-bp'
+Requires-Dist: bloqade-tsim>=0.1.4 ; extra == 'tsim'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/qLDPCOrg/qLDPC
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: relay-bp
+Provides-Extra: tsim
+Description-Content-Type: text/markdown
+
+# 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 [stabilizer](https://errorcorrectionzoo.org/c/stabilizer) and [subsystem](https://errorcorrectionzoo.org/c/oecc) 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`](https://github.com/quantumgizmos/ldpc), [`stim`](https://github.com/quantumlib/Stim), [`sinter`](https://pypi.org/project/sinter), [`QDistRnd`](https://docs.gap-system.org/pkg/qdistrnd/doc/chap1_mj.html), and [`MAGMA`](https://magma.maths.usyd.edu.au/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`](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 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](https://www.gap-system.org) computer algebra system.  If you (a) use Linux or macOS, and (b) use `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](https://www.gap-system.org) integration is clunky in Windows because I have not figured out how to call [GAP](https://www.gap-system.org) from the Windows command prompt.  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, including `RepetitionCode`, `HammingCode`, `SimplexCode`, `ReedMullerCode`, `ReedSolomonCode`, `TannerCode`, and more.
+  - 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:
+  - Common codes such as the `SteaneCode` and `TetrahedralCode`.
+  - Common code families such as the `SurfaceCode`, `ToricCode`, `BaconShorCode`, and `QuantumHammingCode`.
+  - `TBCode`: [two-block quantum codes](https://errorcorrectionzoo.org/c/two_block_quantum).
+  - `QCCode`: quasi-cyclic two-block codes (also known as [multivariate bicycle codes](https://arxiv.org/abs/2406.19151), generalizing the `BBCode` below).
+  - `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 also [`examples/bivariate_bicycle_codes.ipynb`](https://github.com/qLDPCOrg/qLDPC/blob/main/examples/bivariate_bicycle_codes.ipynb).
+  - `HGPCode`: [hypergraph product codes](https://errorcorrectionzoo.org/c/hypergraph_product), first introduced in [arXiv:0903.0566](https://arxiv.org/abs/0903.0566).
+  - `CHGPCode` / `CRCode`: cyclic hypergraph product and repeated cyclic hypergraph product codes, as in [arXiv:2511.09683](https://arxiv.org/abs/2511.09683).
+  - `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), [arXiv:2206.07571](https://arxiv.org/abs/2206.07571), and [arXiv:2508.05095](https://arxiv.org/abs/2508.05095).
+- `qldpc.decoders`: module for decoding code and circuit errors.
+  - 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)), lookup-table decoding, and others.  Includes an interface for using custom decoders.
+  - `SinterDecoder`: class to construct circuit-level decoders that are usable by [`sinter`](https://pypi.org/project/sinter).
+  - `SlidingWindowDecoder`: the overlapping-recovery sliding-window decoder of [arXiv:quant-ph/0110143](https://arxiv.org/abs/quant-ph/0110143) and [arXiv:2209.08552](https://arxiv.org/abs/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`](https://github.com/quantumlib/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](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_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](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).
+- `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](https://qldpc.readthedocs.io/en/latest).  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 [`src/qldpc/codes/quantum.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/quantum.py)) to be covered by its own test file (such as [`src/qldpc/codes/quantum_test.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/src/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`](https://github.com/qLDPCOrg/qLDPC/tree/main/examples) directory has some helpful notebooks to get you started.
+
+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.
+```

qldpc-0.3.3/README.md

@@ -0,0 +1,111 @@
+# 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 [stabilizer](https://errorcorrectionzoo.org/c/stabilizer) and [subsystem](https://errorcorrectionzoo.org/c/oecc) 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`](https://github.com/quantumgizmos/ldpc), [`stim`](https://github.com/quantumlib/Stim), [`sinter`](https://pypi.org/project/sinter), [`QDistRnd`](https://docs.gap-system.org/pkg/qdistrnd/doc/chap1_mj.html), and [`MAGMA`](https://magma.maths.usyd.edu.au/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`](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 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](https://www.gap-system.org) computer algebra system.  If you (a) use Linux or macOS, and (b) use `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](https://www.gap-system.org) integration is clunky in Windows because I have not figured out how to call [GAP](https://www.gap-system.org) from the Windows command prompt.  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, including `RepetitionCode`, `HammingCode`, `SimplexCode`, `ReedMullerCode`, `ReedSolomonCode`, `TannerCode`, and more.
+  - 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:
+  - Common codes such as the `SteaneCode` and `TetrahedralCode`.
+  - Common code families such as the `SurfaceCode`, `ToricCode`, `BaconShorCode`, and `QuantumHammingCode`.
+  - `TBCode`: [two-block quantum codes](https://errorcorrectionzoo.org/c/two_block_quantum).
+  - `QCCode`: quasi-cyclic two-block codes (also known as [multivariate bicycle codes](https://arxiv.org/abs/2406.19151), generalizing the `BBCode` below).
+  - `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 also [`examples/bivariate_bicycle_codes.ipynb`](https://github.com/qLDPCOrg/qLDPC/blob/main/examples/bivariate_bicycle_codes.ipynb).
+  - `HGPCode`: [hypergraph product codes](https://errorcorrectionzoo.org/c/hypergraph_product), first introduced in [arXiv:0903.0566](https://arxiv.org/abs/0903.0566).
+  - `CHGPCode` / `CRCode`: cyclic hypergraph product and repeated cyclic hypergraph product codes, as in [arXiv:2511.09683](https://arxiv.org/abs/2511.09683).
+  - `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), [arXiv:2206.07571](https://arxiv.org/abs/2206.07571), and [arXiv:2508.05095](https://arxiv.org/abs/2508.05095).
+- `qldpc.decoders`: module for decoding code and circuit errors.
+  - 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)), lookup-table decoding, and others.  Includes an interface for using custom decoders.
+  - `SinterDecoder`: class to construct circuit-level decoders that are usable by [`sinter`](https://pypi.org/project/sinter).
+  - `SlidingWindowDecoder`: the overlapping-recovery sliding-window decoder of [arXiv:quant-ph/0110143](https://arxiv.org/abs/quant-ph/0110143) and [arXiv:2209.08552](https://arxiv.org/abs/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`](https://github.com/quantumlib/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](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_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](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).
+- `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](https://qldpc.readthedocs.io/en/latest).  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 [`src/qldpc/codes/quantum.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/quantum.py)) to be covered by its own test file (such as [`src/qldpc/codes/quantum_test.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/src/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`](https://github.com/qLDPCOrg/qLDPC/tree/main/examples) directory has some helpful notebooks to get you started.
+
+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.
+```

qldpc-0.3.3/pyproject.toml

@@ -0,0 +1,109 @@
+[build-system]
+build-backend = "uv_build"
+requires = [ "uv-build>=0.9.18,<0.10" ]
+
+[project]
+name = "qldpc"
+version = "0.3.3"
+description = "Tools for constructing and analyzing quantum low density parity check (qLDPC) codes."
+readme = "README.md"
+keywords = [
+  "LDPC",
+  "low density parity check codes",
+  "quantum computing",
+  "quantum error correction",
+]
+license = "Apache-2.0"
+authors = [ { name = "Michael A. Perlin", email = "mika.perlin@gmail.com" } ]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Natural Language :: English",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "cvxpy>=1.3.2",
+  "diskcache>=5",
+  "galois>=0.4.2",
+  "ldpc>=2.4.1",
+  "networkx>=2.6.2",
+  "numpy>=1.24",
+  "platformdirs>=4",
+  "pymatching>=2.1",
+  "pyperclip>=1.11",
+  "scipy>=1.14.1",
+  "sinter>=1.16",
+  "stim>=1.16",
+  "sympy>=1.12",
+]
+optional-dependencies.dev = [
+  "checks-superstaq>=0.5.62",
+  "jupyter>=1.1.1",
+  "pypandoc-binary>=1.13",        # bundles pandoc for building the notebook docs locally
+  "pyproject-fmt>=2",             # pyproject.toml formatting, run by checks/format_.py
+  "python-lsp-server[all]>=1.14",
+  "qldpc[docs,relay-bp,tsim]",
+]
+optional-dependencies.docs = [
+  "ipython>=8",          # for nbsphinx's IPython.sphinxext.ipython_console_highlighting extension
+  "nbsphinx>=0.9",
+  "sphinx>=7",
+  "sphinx-autoapi>=3",
+  "sphinx-rtd-theme>=2",
+]
+optional-dependencies.relay-bp = [ "relay-bp[stim]==0.2.1" ]
+optional-dependencies.tsim = [ "bloqade-tsim>=0.1.4" ]
+urls.Repository = "https://github.com/qLDPCOrg/qLDPC"
+
+# Check script configuration:
+[tool.ruff]
+line-length = 100
+lint.extend-select = [
+  "ANN204", # return-type annotations on special methods (e.g. __init__)
+  "D205",   # blank line between a docstring's summary and its body
+  "D212",   # multi-line docstring summary starts on the first line
+  "D415",   # docstring summary ends with punctuation (. ? !)
+  "D417",   # a documented function documents all of its arguments
+  "I",      # sorted / grouped imports (isort)
+  "RUF022", # sorted __all__ in __init__.py files
+  "W505",   # docstring & comment line length (see max-doc-length below)
+]
+lint.pycodestyle.max-doc-length = 100
+lint.pydocstyle.convention = "google"
+
+[tool.pyproject-fmt]
+# Cap the auto-generated "Programming Language :: Python" classifiers at the highest supported/tested
+# Python, so the set stays accurate and stable across pyproject-fmt versions.
+max_supported_python = "3.13"
+
+[tool.mypy]
+ignore_missing_imports = true
+disallow_any_generics = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+warn_unused_ignores = true
+pretty = true
+install_types = true
+no_implicit_optional = true
+non_interactive = true
+show_error_codes = true
+
+[tool.pytest]
+ini_options.addopts = "--disable-socket"  # forbid tests from making network calls
+ini_options.filterwarnings = [
+  "ignore:(?s).*The problem is either infeasible or unbounded.*:UserWarning", # from cvxpy
+]
+
+[tool.coverage]
+run.include = [ "./*" ]
+report.exclude_lines = [ "if TYPE_CHECKING:", "pragma: no cover" ]
+report.fail_under = 100
+report.show_missing = true
+report.skip_covered = true

qldpc-0.3.3/src/qldpc/__init__.py

@@ -0,0 +1,17 @@
+import importlib.metadata
+
+from . import abstract, cache, circuits, codes, decoders, external, math, objects
+
+__version__ = importlib.metadata.version("qldpc")
+
+__all__ = [
+    "__version__",
+    "abstract",
+    "cache",
+    "circuits",
+    "codes",
+    "decoders",
+    "external",
+    "math",
+    "objects",
+]

qldpc-0.3.3/src/qldpc/_util.py

@@ -0,0 +1,68 @@
+"""Miscellaneous internal utilities.
+
+Copyright 2023 The qLDPC Authors and Infleqtion Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from collections.abc import Callable
+from types import ModuleType
+from typing import TYPE_CHECKING, TypeVar
+
+CallableType = TypeVar("CallableType", bound=Callable[..., object])
+
+
+def lazy_import(name: str) -> ModuleType:
+    """Import a module lazily, deferring its execution until its first attribute access.
+
+    Uses importlib.util.LazyLoader so a heavy but rarely-used dependency stays out of ``import
+    qldpc`` while call sites keep using ``module.attr`` exactly as if it had been imported eagerly.
+    """
+    if (module := sys.modules.get(name)) is not None:
+        return module
+    spec = importlib.util.find_spec(name)
+    assert spec is not None and spec.loader is not None
+    spec.loader = importlib.util.LazyLoader(spec.loader)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+# networkx is loaded lazily to keep it and its ~110 ms import out of ``import qldpc``.
+# Call sites import it as ``from qldpc._util import networkx as nx``.
+if TYPE_CHECKING:
+    import networkx
+else:
+    networkx = lazy_import("networkx")
+
+
+def format_docstring(**substitutions: object) -> Callable[[CallableType], CallableType]:
+    """Substitute named values into a function's docstring via str.format.
+
+    This lets a docstring reference values (such as module-level constants) by name, for example
+    "Default: {error_rate}.", without making the docstring an f-string.  An f-string cannot be used
+    as a docstring: Python evaluates it as an ordinary expression and leaves __doc__ set to None,
+    silently discarding the documentation.
+    """
+
+    def decorator(func: CallableType) -> CallableType:
+        if func.__doc__ is not None:
+            func.__doc__ = func.__doc__.format(**substitutions)
+        return func
+
+    return decorator

qldpc-0.3.3/src/qldpc/_util_test.py

@@ -0,0 +1,54 @@
+"""Unit tests for _util.py.
+
+Copyright 2023 The qLDPC Authors and Infleqtion Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import sys
+from types import ModuleType
+
+from qldpc._util import format_docstring, lazy_import
+
+
+def test_lazy_import() -> None:
+    """A lazily imported module is only executed on first attribute access."""
+    name = "colorsys"  # a small stdlib module not otherwise imported by the test suite
+    sys.modules.pop(name, None)
+
+    module = lazy_import(name)  # uncached path
+    assert isinstance(module, ModuleType)
+    assert callable(module.rgb_to_hls)  # force the deferred execution
+
+    assert lazy_import(name) is module  # cached path returns the same module
+
+
+def test_format_docstring() -> None:
+    """Named values are substituted into a docstring."""
+
+    @format_docstring(value=1e-3, name="tag")
+    def func() -> None:
+        """A docstring with a {value} and a {name}."""
+
+    assert func.__doc__ == "A docstring with a 0.001 and a tag."
+
+
+def test_format_docstring_without_docstring() -> None:
+    """A function without a docstring is left untouched."""
+
+    @format_docstring(value=1)
+    def func() -> None:
+        return None
+
+    assert func.__doc__ is None
+    assert func() is None

qldpc-0.3.3/src/qldpc/abstract/__init__.py

@@ -0,0 +1,68 @@
+from .groups import (
+    PSL,
+    SL,
+    AbelianGroup,
+    AlternatingGroup,
+    CyclicGroup,
+    DihedralGroup,
+    Group,
+    GroupMember,
+    ProjectiveSpecialLinearGroup,
+    QuaternionGroup,
+    SmallGroup,
+    SpecialLinearGroup,
+    SymmetricGroup,
+    TrivialGroup,
+    get_coefficient_and_exponents,
+    iter_monomial_terms,
+    resolve_field,
+)
+from .linalg import (
+    block_diag,
+    get_howell_dual,
+    kron,
+    matmul,
+)
+from .rings import (
+    Element,
+    GroupRing,
+    Protograph,
+    RingArray,
+    RingMember,
+)
+from .wedderburn_artin import (
+    WedderburnArtinComponentTransformer,
+    WedderburnArtinTransformer,
+)
+
+__all__ = [
+    "GF2",
+    "PSL",
+    "SL",
+    "AbelianGroup",
+    "AlternatingGroup",
+    "CyclicGroup",
+    "DihedralGroup",
+    "Element",
+    "Group",
+    "GroupMember",
+    "GroupRing",
+    "ProjectiveSpecialLinearGroup",
+    "Protograph",
+    "QuaternionGroup",
+    "RingArray",
+    "RingMember",
+    "SmallGroup",
+    "SpecialLinearGroup",
+    "SymmetricGroup",
+    "TrivialGroup",
+    "WedderburnArtinComponentTransformer",
+    "WedderburnArtinTransformer",
+    "block_diag",
+    "get_coefficient_and_exponents",
+    "get_howell_dual",
+    "iter_monomial_terms",
+    "kron",
+    "matmul",
+    "resolve_field",
+]