qLDPC 0.3.2__tar.gz → 0.3.3__tar.gz

{qldpc-0.3.2 → qldpc-0.3.3}/PKG-INFO

@@ -1,39 +1,51 @@
 Metadata-Version: 2.4
-Name: qLDPC
-Version: 0.3.2
+Name: qldpc
+Version: 0.3.3
 Summary: Tools for constructing and analyzing quantum low density parity check (qLDPC) codes.
-Keywords: quantum computing,quantum error correction,low density parity check codes,LDPC
+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.0.0
+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.0
-Requires-Dist: platformdirs>=4.0.0
-Requires-Dist: pymatching>=2.1.0
-Requires-Dist: pyperclip>=1.11.0
+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.0
-Requires-Dist: stim>=1.16.0
+Requires-Dist: sinter>=1.16
+Requires-Dist: stim>=1.16
 Requires-Dist: sympy>=1.12
-Requires-Dist: bloqade-tsim>=0.1.4 ; extra == 'dev'
 Requires-Dist: checks-superstaq>=0.5.62 ; extra == 'dev'
 Requires-Dist: jupyter>=1.1.1 ; extra == 'dev'
-Requires-Dist: python-lsp-server[all]>=1.14.0 ; extra == 'dev'
-Requires-Dist: relay-bp[stim]==0.2.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
@@ -72,7 +84,7 @@ You can also `pip install -e 'qLDPC[dev]'` to additionally install some developm
 
 ### GAP
 
-Some features in `qLDPC` require an installation of the [GAP](https://www.gap-system.org) computer algebra system.  If you (a) use linux or macOS, and (b) use a `conda` to manage your python environment, then you can obtain GAP by running
+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
 ```
@@ -111,7 +123,7 @@ Notable features include:
 - `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/pdf/2209.08552).
+  - `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:
@@ -128,7 +140,7 @@ Notable features include:
 
 ## 🤔 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 [`qldpc/codes/quantum.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/qldpc/codes/quantum.py)) to be covered by its own test file (such as [`qldpc/codes/quantum_test.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/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.
+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)!
 

{qldpc-0.3.2 → qldpc-0.3.3}/README.md

@@ -32,7 +32,7 @@ You can also `pip install -e 'qLDPC[dev]'` to additionally install some developm
 
 ### GAP
 
-Some features in `qLDPC` require an installation of the [GAP](https://www.gap-system.org) computer algebra system.  If you (a) use linux or macOS, and (b) use a `conda` to manage your python environment, then you can obtain GAP by running
+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
 ```
@@ -71,7 +71,7 @@ Notable features include:
 - `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/pdf/2209.08552).
+  - `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:
@@ -88,7 +88,7 @@ Notable features include:
 
 ## 🤔 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 [`qldpc/codes/quantum.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/qldpc/codes/quantum.py)) to be covered by its own test file (such as [`qldpc/codes/quantum_test.py`](https://github.com/qLDPCOrg/qLDPC/blob/main/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.
+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)!
 

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/_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.2 → qldpc-0.3.3}/src/qldpc/abstract/__init__.py

@@ -14,6 +14,7 @@ from .groups import (
     SymmetricGroup,
     TrivialGroup,
     get_coefficient_and_exponents,
+    iter_monomial_terms,
     resolve_field,
 )
 from .linalg import (
@@ -42,25 +43,26 @@ __all__ = [
     "AlternatingGroup",
     "CyclicGroup",
     "DihedralGroup",
+    "Element",
     "Group",
     "GroupMember",
+    "GroupRing",
     "ProjectiveSpecialLinearGroup",
+    "Protograph",
     "QuaternionGroup",
+    "RingArray",
+    "RingMember",
     "SmallGroup",
     "SpecialLinearGroup",
     "SymmetricGroup",
     "TrivialGroup",
-    "get_coefficient_and_exponents",
-    "resolve_field",
+    "WedderburnArtinComponentTransformer",
+    "WedderburnArtinTransformer",
     "block_diag",
+    "get_coefficient_and_exponents",
     "get_howell_dual",
+    "iter_monomial_terms",
     "kron",
     "matmul",
-    "Element",
-    "GroupRing",
-    "Protograph",
-    "RingArray",
-    "RingMember",
-    "WedderburnArtinComponentTransformer",
-    "WedderburnArtinTransformer",
+    "resolve_field",
 ]