qLDPC 0.3.2__tar.gz → 0.4.0__tar.gz

qldpc-0.4.0/COPYRIGHT

@@ -0,0 +1,11 @@
+qLDPC Copyright Notice
+
+Portions of qLDPC authored before June 2024 are:
+
+    Copyright 2023-2024 The qLDPC Authors and Infleqtion Inc.
+
+Portions authored on or after June 2024 are:
+
+    Copyright 2024-present The qLDPC Authors.
+
+Individual files and third-party components may carry additional or different copyright notices.

qldpc-0.4.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

qldpc-0.4.0/PKG-INFO

@@ -0,0 +1,259 @@
+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).

qldpc-0.4.0/README.md

@@ -0,0 +1,199 @@
+# 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).