qLDPC 0.4.2.dev20261004__tar.gz → 0.4.2.dev20261023__tar.gz

{qldpc-0.4.2.dev20261004 → qldpc-0.4.2.dev20261023}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qldpc
-Version: 0.4.2.dev20261004
+Version: 0.4.2.dev20261023
 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
@@ -18,20 +18,21 @@ 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: galois>=0.4.11
 Requires-Dist: ldpc>=2.4.1
-Requires-Dist: networkx>=2.6.2
-Requires-Dist: numpy>=1.24
+Requires-Dist: networkx>=2.7
+Requires-Dist: numba>=0.61.2
+Requires-Dist: numpy>=2.1
 Requires-Dist: platformdirs>=4
 Requires-Dist: pymatching>=2.3
 Requires-Dist: pyperclip>=1.11
-Requires-Dist: scipy>=1.14.1
+Requires-Dist: scipy>=1.16
 Requires-Dist: sinter>=1.16
 Requires-Dist: stim>=1.16
-Requires-Dist: sympy>=1.12
+Requires-Dist: sympy>=1.12.1
 Requires-Dist: tqdm>=4
+Requires-Dist: qldpc[ilp] ; extra == 'decoders'
 Requires-Dist: qldpc[relay-bp] ; extra == 'decoders'
 Requires-Dist: qldpc[tesseract] ; (python_full_version < '3.15' and platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'decoders') or (python_full_version < '3.15' and platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'decoders')
 Requires-Dist: checks-superstaq>=0.5.67 ; extra == 'dev'
@@ -49,6 +50,7 @@ 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.13.*' and sys_platform != 'win32' and extra == 'gap'
+Requires-Dist: cvxpy>=1.5.3 ; extra == 'ilp'
 Requires-Dist: relay-bp[stim]==0.2.2 ; extra == 'relay-bp'
 Requires-Dist: tesseract-decoder==0.1.1.dev20260910235247 ; python_full_version >= '3.12' and extra == 'tesseract'
 Requires-Python: >=3.11
@@ -59,6 +61,7 @@ Provides-Extra: decoders
 Provides-Extra: dev
 Provides-Extra: docs
 Provides-Extra: gap
+Provides-Extra: ilp
 Provides-Extra: relay-bp
 Provides-Extra: tesseract
 Description-Content-Type: text/markdown
@@ -66,30 +69,73 @@ 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.
+It aims to make constructions and algorithms from the quantum error-correction literature easier to explore, reproduce, and build on.
+You can define codes using parity-check matrices or higher-level ingredients such as polynomials, group rings, Tanner graphs, and chain complexes.
+From there, you can inspect logical operators, compute or bound code distance, choose 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.
+## ✨ A few things to try
+
+- **Code families.**
+  Construct surface, toric, Hamming, and Reed–Muller codes, along with hypergraph-product, lifted-product, bivariate-bicycle, quantum Tanner, SHYPS, GALA, and other families.
+- **Distance calculations.**
+  Compute exact distances of binary codes with an [optimized Brouwer–Zimmermann search](src/qldpc/codes/distance/brouwer_zimmermann.md), or bound code distance using [QDistRnd](https://arxiv.org/abs/2308.15140) or [`sqetch`](https://github.com/a7b/yarn/tree/main/sqetch).
+- **Code structure and analysis.**
+  Work with check matrices, Tanner graphs, canonical logical operators, subsystem gauge operators, and code-capacity error estimates.
+- **Circuits and decoding workflows.**
+  Build memory experiments, encoding circuits, Pauli noise models, and state-preparation diagnostics; use Sinter and sliding-window decoders, or search for transversal Clifford gates.
+- **Algebraic tools.**
+  Work with finite groups, group rings, lifted matrices, Cayley complexes, chain complexes, and optional GAP integration.
+
+The [example notebooks](https://qldpc.readthedocs.io/examples/index.html) cover (among other things) code construction, custom noise models, and circuit-level logical error rates.
+
+## 🚀 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)
+```
+
+The gross code is also available as the named construction, `codes.GrossCode()`.
+
+### A subsystem lifted-product code
+
+This example builds a parity-check matrix over the group algebra `GF(2)[C₅]`, lifts each group-ring entry to a 5×5 binary block, and passes the result to `SLPCode`.
+The [subsystem lifted-product construction](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
+```
+
+The [library map](https://qldpc.readthedocs.io/library_map.html) explains the data model and package structure.
 
 ## 📦 Installation
 
@@ -105,7 +151,7 @@ python -m pip install qldpc
 
 #### Decoders
 
-qLDPC installs `ldpc` and `pymatching` by default, which include a host of decoders.
+qLDPC installs `ldpc` and `pymatching` by default, which provide several decoding algorithms.
 Install the optional decoder integrations published as qLDPC extras for your platform with:
 
 ```bash
@@ -115,6 +161,7 @@ python -m pip install 'qldpc[decoders]'
 You can also use individual extras to install a specific optional decoder:
 
 ```bash
+python -m pip install 'qldpc[ilp]'
 python -m pip install 'qldpc[relay-bp]'
 python -m pip install 'qldpc[tesseract]'
 ```
@@ -150,7 +197,7 @@ For binary CSS codes, you can select this backend with `code.get_distance_bound(
 
 ### Troubleshooting
 
-On macOS, you may need to install `cvxpy` manually by following its [installation instructions](https://www.cvxpy.org/install) before installing qLDPC.
+On macOS, you may need to install `cvxpy`, which the ILP decoder requires, manually by following its [installation instructions](https://www.cvxpy.org/install) before installing `qldpc[ilp]` or `qldpc[decoders]`.
 If you use Conda to manage your Python environment, install `cvxpy` with:
 
 ```bash
@@ -167,50 +214,6 @@ 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)
-```
-
-### Go deeper: a subsystem lifted-product code
-
-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 |
@@ -218,24 +221,26 @@ Continue with the [library map](https://qldpc.readthedocs.io/library_map.html) f
 | 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) |
+| Construct and analyze a 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
 
+qLDPC is research software.
+Some searches are expensive, some bounds are heuristic, experimental APIs can change, and optional tools may have side effects.
+
 - Circuit and tableau tools only work with qubit codes, even though other parts of qLDPC support prime-power-dimensional qudits.
 - Circuits returned by `get_encoding_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.
+- Features that use GAP may start subprocesses, access online resources, or ask for manual input or permission to install a package.
+- Code lookups such as `QuditCode.from_qecdb_id` access online resources and cache results on disk; pass `refresh=True` to fetch the latest data.
 - 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.
+- Lattice-surgery support in `qldpc.experimental.surgery` is experimental and unstable, and its implementation is still pending careful expert review.
+  Validate its results independently, and pin the qLDPC version if you depend on it.
 
 ## 📚 Documentation and support
 

{qldpc-0.4.2.dev20261004 → qldpc-0.4.2.dev20261023}/README.md

@@ -1,30 +1,73 @@
 # 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.
+It aims to make constructions and algorithms from the quantum error-correction literature easier to explore, reproduce, and build on.
+You can define codes using parity-check matrices or higher-level ingredients such as polynomials, group rings, Tanner graphs, and chain complexes.
+From there, you can inspect logical operators, compute or bound code distance, choose 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.
+## ✨ A few things to try
+
+- **Code families.**
+  Construct surface, toric, Hamming, and Reed–Muller codes, along with hypergraph-product, lifted-product, bivariate-bicycle, quantum Tanner, SHYPS, GALA, and other families.
+- **Distance calculations.**
+  Compute exact distances of binary codes with an [optimized Brouwer–Zimmermann search](src/qldpc/codes/distance/brouwer_zimmermann.md), or bound code distance using [QDistRnd](https://arxiv.org/abs/2308.15140) or [`sqetch`](https://github.com/a7b/yarn/tree/main/sqetch).
+- **Code structure and analysis.**
+  Work with check matrices, Tanner graphs, canonical logical operators, subsystem gauge operators, and code-capacity error estimates.
+- **Circuits and decoding workflows.**
+  Build memory experiments, encoding circuits, Pauli noise models, and state-preparation diagnostics; use Sinter and sliding-window decoders, or search for transversal Clifford gates.
+- **Algebraic tools.**
+  Work with finite groups, group rings, lifted matrices, Cayley complexes, chain complexes, and optional GAP integration.
+
+The [example notebooks](https://qldpc.readthedocs.io/examples/index.html) cover (among other things) code construction, custom noise models, and circuit-level logical error rates.
+
+## 🚀 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)
+```
+
+The gross code is also available as the named construction, `codes.GrossCode()`.
+
+### A subsystem lifted-product code
+
+This example builds a parity-check matrix over the group algebra `GF(2)[C₅]`, lifts each group-ring entry to a 5×5 binary block, and passes the result to `SLPCode`.
+The [subsystem lifted-product construction](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
+```
+
+The [library map](https://qldpc.readthedocs.io/library_map.html) explains the data model and package structure.
 
 ## 📦 Installation
 
@@ -40,7 +83,7 @@ python -m pip install qldpc
 
 #### Decoders
 
-qLDPC installs `ldpc` and `pymatching` by default, which include a host of decoders.
+qLDPC installs `ldpc` and `pymatching` by default, which provide several decoding algorithms.
 Install the optional decoder integrations published as qLDPC extras for your platform with:
 
 ```bash
@@ -50,6 +93,7 @@ python -m pip install 'qldpc[decoders]'
 You can also use individual extras to install a specific optional decoder:
 
 ```bash
+python -m pip install 'qldpc[ilp]'
 python -m pip install 'qldpc[relay-bp]'
 python -m pip install 'qldpc[tesseract]'
 ```
@@ -85,7 +129,7 @@ For binary CSS codes, you can select this backend with `code.get_distance_bound(
 
 ### Troubleshooting
 
-On macOS, you may need to install `cvxpy` manually by following its [installation instructions](https://www.cvxpy.org/install) before installing qLDPC.
+On macOS, you may need to install `cvxpy`, which the ILP decoder requires, manually by following its [installation instructions](https://www.cvxpy.org/install) before installing `qldpc[ilp]` or `qldpc[decoders]`.
 If you use Conda to manage your Python environment, install `cvxpy` with:
 
 ```bash
@@ -102,50 +146,6 @@ 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)
-```
-
-### Go deeper: a subsystem lifted-product code
-
-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 |
@@ -153,24 +153,26 @@ Continue with the [library map](https://qldpc.readthedocs.io/library_map.html) f
 | 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) |
+| Construct and analyze a 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
 
+qLDPC is research software.
+Some searches are expensive, some bounds are heuristic, experimental APIs can change, and optional tools may have side effects.
+
 - Circuit and tableau tools only work with qubit codes, even though other parts of qLDPC support prime-power-dimensional qudits.
 - Circuits returned by `get_encoding_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.
+- Features that use GAP may start subprocesses, access online resources, or ask for manual input or permission to install a package.
+- Code lookups such as `QuditCode.from_qecdb_id` access online resources and cache results on disk; pass `refresh=True` to fetch the latest data.
 - 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.
+- Lattice-surgery support in `qldpc.experimental.surgery` is experimental and unstable, and its implementation is still pending careful expert review.
+  Validate its results independently, and pin the qLDPC version if you depend on it.
 
 ## 📚 Documentation and support
 

{qldpc-0.4.2.dev20261004 → qldpc-0.4.2.dev20261023}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["uv-build>=0.9.18,<0.13"]
 
 [project]
 name = "qldpc"
-version = "0.4.2.dev20261004"
+version = "0.4.2.dev20261023"
 description = "Tools for constructing and analyzing quantum low density parity check (qLDPC) codes."
 readme = "README.md"
 keywords = [
@@ -32,19 +32,19 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Physics",
 ]
 dependencies = [
-    "cvxpy>=1.3.2",
     "diskcache>=5",
-    "galois>=0.4.2",
+    "galois>=0.4.11",
     "ldpc>=2.4.1",
-    "networkx>=2.6.2",
-    "numpy>=1.24",
+    "networkx>=2.7",
+    "numba>=0.61.2",
+    "numpy>=2.1",
     "platformdirs>=4",
     "pymatching>=2.3",
     "pyperclip>=1.11",
-    "scipy>=1.14.1",
+    "scipy>=1.16",
     "sinter>=1.16",
     "stim>=1.16",
-    "sympy>=1.12",
+    "sympy>=1.12.1",
     "tqdm>=4",
 ]
 
@@ -54,6 +54,7 @@ email = "mika.perlin@gmail.com"
 
 [project.optional-dependencies]
 decoders = [
+    "qldpc[ilp]",
     "qldpc[relay-bp]",
     "qldpc[tesseract]; ((sys_platform=='darwin' and platform_machine=='arm64') or (sys_platform=='linux' and platform_machine=='x86_64')) and python_version<'3.15'",
 ]
@@ -76,6 +77,7 @@ docs = [
     "sphinx-rtd-theme>=2",
 ]
 gap = ["passagemath-gap==10.8.12; python_version=='3.13' and sys_platform!='win32'"]
+ilp = ["cvxpy>=1.5.3"]
 relay-bp = ["relay-bp[stim]==0.2.2"]
 tesseract = ["tesseract-decoder==0.1.1.dev20260910235247; python_version>='3.12'"]
 

{qldpc-0.4.2.dev20261004 → qldpc-0.4.2.dev20261023}/pyproject.toml.orig

@@ -4,7 +4,7 @@ requires = [ "uv-build>=0.9.18,<0.13" ]
 
 [project]
 name = "qldpc"
-version = "0.4.2.dev20261004"
+version = "0.4.2.dev20261023"
 description = "Tools for constructing and analyzing quantum low density parity check (qLDPC) codes."
 readme = "README.md"
 keywords = [
@@ -30,22 +30,23 @@ classifiers = [
   "Topic :: Scientific/Engineering :: Physics",
 ]
 dependencies = [
-  "cvxpy>=1.3.2",
   "diskcache>=5",
-  "galois>=0.4.2",
+  "galois>=0.4.11",
   "ldpc>=2.4.1",
-  "networkx>=2.6.2",
-  "numpy>=1.24",
+  "networkx>=2.7",
+  "numba>=0.61.2",   # floor tested with Python 3.11 and NumPy 2.1
+  "numpy>=2.1",
   "platformdirs>=4",
   "pymatching>=2.3",
   "pyperclip>=1.11",
-  "scipy>=1.14.1",
+  "scipy>=1.16",     # earlier MILP solvers can return non-solutions to ILP decoding
   "sinter>=1.16",
   "stim>=1.16",
-  "sympy>=1.12",
+  "sympy>=1.12.1",   # 1.12 accepts mpmath 1.4, which it cannot import
   "tqdm>=4",
 ]
 optional-dependencies.decoders = [
+  "qldpc[ilp]",
   "qldpc[relay-bp]",
   """\
   qldpc[tesseract]; ((sys_platform=='darwin' and platform_machine=='arm64') or (sys_platform=='linux' and \
@@ -73,6 +74,9 @@ optional-dependencies.docs = [
 optional-dependencies.gap = [
   "passagemath-gap==10.8.12; python_version=='3.13' and sys_platform!='win32'",
 ]
+optional-dependencies.ilp = [
+  "cvxpy>=1.5.3", # earlier releases do not import with NumPy 2
+]
 optional-dependencies.relay-bp = [ "relay-bp[stim]==0.2.2" ]
 optional-dependencies.tesseract = [
   "tesseract-decoder==0.1.1.dev20260910235247; python_version>='3.12'",
@@ -150,8 +154,8 @@ run.include = [ "./*" ]
 run.parallel = true
 run.patch = [ "subprocess" ]
 # Statement coverage only.  Branch coverage is deliberately not gated: a handful of arcs flip with
-# the pytest-randomly seed and with the installed numpy version, so gating it would make pass/fail
-# nondeterministic.  Audit it on demand with "checks/coverage_.py --branch".
+# the pytest-randomly seed, so gating it would make pass/fail nondeterministic.  Audit it on demand
+# with "checks/coverage_.py --branch".
 report.fail_under = 100
 report.skip_covered = true
 report.show_missing = true

qldpc-0.4.2.dev20261023/src/qldpc/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tools for constructing and analyzing quantum low density parity check (qLDPC) codes."""
+
+import importlib.metadata
+
+from . import (
+    _deprecations,
+    abstract,
+    cache,
+    circuits,
+    codes,
+    decoders,
+    experimental,
+    external,
+    math,
+    objects,
+)
+
+__version__ = importlib.metadata.version("qldpc")
+
+__all__ = [
+    "__version__",
+    "abstract",
+    "cache",
+    "circuits",
+    "codes",
+    "decoders",
+    "experimental",
+    "external",
+    "math",
+    "objects",
+]
+
+_deprecations.install_deprecated_methods()

qldpc-0.4.2.dev20261023/src/qldpc/_deprecations/__init__.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Deprecated names, methods, arguments, and decoder construction of qLDPC.
+
+All deprecation code lives in this private package.  The core module registers deprecated names,
+defines deprecated methods, and provides the helpers that inline deprecated-argument blocks call.
+The decoders module holds deprecated decoder construction, which qldpc.decoders serves through the
+registry.  Modules with deprecated decoder arguments import it directly, and
+install_deprecated_methods imports it when it runs, so this package does not import it when it is
+imported.  The lookup module holds the deprecated direct construction of LookupDecoder and
+WeightedLookupDecoder, and the lookup decoders that the deprecated predict_observable_flips=True
+option builds.  It imports qldpc.decoders, so it is imported only within the functions that use it.
+"""
+
+from .core import (
+    ALIASES,
+    SILENT_ALIASES,
+    defunct,
+    get_deprecated_attribute,
+    install_deprecated_methods,
+    warn_deprecated,
+)
+
+__all__ = [
+    "ALIASES",
+    "SILENT_ALIASES",
+    "defunct",
+    "get_deprecated_attribute",
+    "install_deprecated_methods",
+    "warn_deprecated",
+]