Fix exact-distance bugs, report a missing distance with one sentinel, and merge duplicated coset kernels

docs/source/library_map.rst

@@ -133,6 +133,7 @@ Distances across packages
 Exact distances of binary codes use an optimized `Brouwer--Zimmermann search <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/brouwer_zimmermann.md>`_, and nonbinary codes use exhaustive enumeration.
 Binary codes with sparse parity checks can instead use ``method="connected_support"``, a `search over supports that are connected in the Tanner graph <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/connected_support.md>`_.
 All exact methods can take exponential time.
+A code that encodes nothing, or a circuit with no undetected logical fault, has no distance, and distance methods then return :data:`~qldpc.codes.distance.core.NO_DISTANCE`, a float ``nan`` (see :class:`~qldpc.codes.distance.core.NoDistance`).
 ``get_distance_exact(cutoff=c)`` stops once it finds a nontrivial word of weight at most ``c``.
 A result of at most ``c`` is therefore only an upper bound, while a larger result, or any result with ``cutoff <= 1`` (the default is 1), is exact.
 Exact searches choose their routes by cost models whose settings and constants :doc:`exact_search_tuning` maps and documents.

src/qldpc/circuits/certification/fault_distance.py

@@ -4,12 +4,14 @@
 
 from __future__ import annotations
 
+from typing import Literal
+
 import galois
 import numpy as np
 import stim
 
 from qldpc import codes, decoders
-from qldpc.codes.distance import DistanceMethod
+from qldpc.codes.distance import DistanceMethod, NoDistance
 from qldpc.objects import Pauli
 
 ####################################################################################################
@@ -18,7 +20,7 @@
 
 def get_fault_distance(
     circuit: stim.Circuit, *, method: DistanceMethod = "brouwer_zimmermann"
-) -> int | float:
+) -> int | Literal[NoDistance.NAN]:
     r"""Compute the exact fault distance of a noisy circuit.
 
     Consider a noisy Stim circuit annotated with detectors and logical observables.  Calling
@@ -71,8 +73,8 @@ def get_fault_distance(
             detectors (see :meth:`qldpc.codes.CSSCode.get_distance_exact`).
 
     Returns:
-        The minimum number of DEM error mechanisms causing an undetected observable flip, or np.nan
-        if no such fault exists.
+        The minimum number of DEM error mechanisms causing an undetected observable flip, or
+        ``NO_DISTANCE`` (see :class:`~qldpc.codes.distance.NoDistance`) if no such fault exists.
     """
     dem_arrays = decoders.DetectorErrorModelArrays(circuit)
     detectors = galois.GF2(dem_arrays.detector_flip_matrix.toarray())

src/qldpc/circuits/certification/fault_distance_test.py

@@ -4,11 +4,10 @@
 
 from __future__ import annotations
 
-import numpy as np
 import pytest
 import stim
 
-from qldpc import circuits
+from qldpc import circuits, codes
 from qldpc.codes.distance import DistanceMethod
 
 
@@ -32,6 +31,6 @@ def test_fault_distance(measurement: int, expected_distance: int, method: Distan
 
 
 def test_fault_distance_without_logical_faults() -> None:
-    """No undetected observable flip has the code distance convention np.nan."""
+    """Without an undetected observable flip, a circuit has no distance, and gives NO_DISTANCE."""
     circuit = stim.Circuit("R 0\nX_ERROR(0.01) 0\nM 0\nDETECTOR rec[-1]")
-    assert np.isnan(circuits.get_fault_distance(circuit))
+    assert circuits.get_fault_distance(circuit) is codes.NO_DISTANCE

src/qldpc/codes/__init__.py

@@ -27,11 +27,13 @@
     QuditCode,
 )
 from .distance import (
+    NO_DISTANCE,
     CSSLogicalCounter,
     CSSLogicalCounts,
     DistanceBackend,
     DistanceMethod,
     LogicalCountMethod,
+    NoDistance,
     count_logical_ops_css,
     get_distance_classical,
     get_distance_quantum,
@@ -74,6 +76,7 @@
 )
 
 __all__ = [
+    "NO_DISTANCE",
     "AbstractCode",
     "BBCode",
     "BCHCode",
@@ -106,6 +109,7 @@
     "LogicalCountMethod",
     "MBCode",
     "ManyHypercubeCode",
+    "NoDistance",
     "PairPartitionCode",
     "QTCode",
     "QuantumGolayCode",