Skip to content
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ Circuit tools currently only support qubit codes.
- **Code families.**
Construct surface, toric, Hamming, and Reed-Muller codes, along with hypergraph-product, lifted-product, balanced-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).
Codes with sparse checks can instead use a [connected-cluster search](src/qldpc/codes/distance/connected_cluster.md).
Compute exact distances of binary codes with an [optimized Brouwer-Zimmermann search](src/qldpc/codes/distance/brouwer_zimmermann.md) or a [connected-cluster search](src/qldpc/codes/distance/connected_cluster.md), which can be much faster on quantum codes with sparse checks.
By default, each search chooses its method, and enumerates every word if that is cheap.
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.
Expand Down
16 changes: 14 additions & 2 deletions docs/source/exact_search_tuning.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,15 @@ Start from a symptom
- What to try first, then measure
* - A distance search of a classical code of low dimension, whose distance is a large fraction of its length, is slow
- Pass ``method="brute_force"`` to enumerate every word instead.
* - A distance search of a quantum LDPC code is slow
- Pass ``method="connected_cluster"``, which is often much faster on such codes, though not on all of them (`Section 2 <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/connected_cluster.md#2-what-the-cost-of-the-search-depends-on>`__ of the connected-cluster guide).
* - A distance search of a quantum LDPC code by ``method="brouwer_zimmermann"`` is slow
- Pass ``method="connected_cluster"``, which is often much faster on such codes, though not on all of them (`Section 2 <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/connected_cluster.md#2-what-the-cost-of-the-search-depends-on>`__ of the connected-cluster guide), or ``method="auto"``, the default, which starts with that search and may switch to the Brouwer-Zimmermann method.
* - A distance search by ``method="auto"``, the default, is slow
- Time the search with ``method="brouwer_zimmermann"`` and with ``method="connected_cluster"``, and pass the faster method.
With a large ``cutoff``, ``"auto"`` cannot switch to the Brouwer-Zimmermann method before it has searched past the cutoff, and with one near the distance it may never switch, so pass ``method="brouwer_zimmermann"``.
To make ``"auto"`` stay longer with a connected-cluster search, lower :attr:`~SearchTuning.connected_cluster_state_evaluations`, and to make it switch to the Brouwer-Zimmermann method sooner, raise that field.
Raise :attr:`~SearchTuning.auto_free_work` to decide later, with better estimates of growth, or lower it to decide sooner (`Choosing a method <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/README.md#choosing-a-method>`__ in the guide to the distance package).
Raise :attr:`~SearchTuning.auto_probe_work` to let the short Brouwer-Zimmermann search that ``"auto"`` runs before it decides, its probe, finish more searches, or find a lighter word for the connected-cluster search to stop at, at a higher fixed cost.
Lower :attr:`~SearchTuning.auto_brute_force_max_words` if ``"auto"`` enumerates every word for too long.
* - A hard distance search spends its time in its last, costliest layers
- Raise :attr:`~SearchTuning.completion_bound_max_cost_percent` or lower :attr:`~SearchTuning.completion_bound_minimum_layer_work` to use completion tables in more layers.
For a basis too large for its tables, raise :attr:`~SearchTuning.completion_bound_max_table_bytes` or lower :attr:`~SearchTuning.completion_bound_block_bits`.
Expand All @@ -42,6 +49,7 @@ Start from a symptom
* - A keyboard interrupt takes long to take effect
- Lower :attr:`~SearchTuning.enumeration_batch_exponent`, :attr:`~SearchTuning.information_set_batch_exponent`, :attr:`~SearchTuning.scan_chunk_size`, :attr:`~SearchTuning.scan_chunks_per_call`, or :attr:`~SearchTuning.macwilliams_chunk_size`.
A connected-cluster search takes an interrupt only between its weight limits, or between coset queries, and no value changes that.
``method="auto"``, the default, runs one for the distances of quantum codes and the fault distances of circuits; pass ``method="brouwer_zimmermann"`` for prompt interrupts.
* - A cheap connected-cluster search spends its time finding automorphisms
- Raise :attr:`~SearchTuning.automorphism_minimum_states`.
Searches ask for them before a first limit that ``cutoff`` sets, unless the field is ``MAX_VALUE``.
Expand All @@ -67,6 +75,10 @@ Routes and the names that control them
- :attr:`SearchTuning.enumeration_batch_exponent`
-
- `Section 3.6 <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/brouwer_zimmermann.md#36-work-estimates-and-exhaustive-enumeration>`__
* - Choosing a method, which ``method="auto"`` does for each distance search
- :attr:`SearchTuning.auto_brute_force_max_words`, :attr:`SearchTuning.auto_free_work`, :attr:`SearchTuning.auto_probe_work`, :attr:`SearchTuning.connected_cluster_state_evaluations`
-
- `Choosing a method <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/README.md#choosing-a-method>`__ in the guide to the distance package
* - Estimating the work of searches of information sets, which chooses between their routes
-
- :data:`BINOMIAL_CACHE_SIZE`
Expand Down
22 changes: 11 additions & 11 deletions docs/source/library_map.rst
Original file line number Diff line number Diff line change
Expand Up @@ -132,8 +132,8 @@ Distances across packages
``get_distance()`` computes an exact distance and ``get_distance_bound`` a randomized upper bound, and CSS codes also have separate X and Z distances.
The distance of a subsystem code is dressed: its logical operators may be multiplied by gauge operators.
For a binary subsystem code, :func:`~qldpc.codes.distance.get_distance_from_checks` says how to find the bare distance: the minimum weight of a nontrivial logical operator that commutes with every gauge operator.
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_cluster"``, a `search over supports that are connected in the Tanner graph <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/connected_cluster.md>`_.
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>`_ or, for sparse parity checks, a `search over supports that are connected in the Tanner graph <https://github.com/qLDPCOrg/qLDPC/blob/main/src/qldpc/codes/distance/connected_cluster.md>`_, and nonbinary codes use exhaustive enumeration.
By default, ``method="auto"`` chooses a method for each search: exhaustive enumeration if it is cheap, the Brouwer-Zimmermann search for a classical code, and, for the checks of a quantum code or a circuit, a connected-cluster search that may switch to the Brouwer-Zimmermann search (see :data:`~qldpc.codes.distance.DistanceMethod`).
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.NO_DISTANCE`, a float ``nan`` (see :class:`~qldpc.codes.distance.NoDistance`).
``get_distance_exact(cutoff=c)`` stops once it finds a nontrivial word of weight at most ``c``.
Expand Down Expand Up @@ -228,15 +228,15 @@ Support and limitations

The following table summarizes support by field; the subsystem column applies to subsystem codes over any field.

=============== ========================================= ============================== =================================== ========================================
Capability :math:`GF(2)` Prime field :math:`GF(p)` Extension field :math:`GF(p^m)` Subsystem codes
=============== ========================================= ============================== =================================== ========================================
Codes Yes Yes Yes Yes, inferred from non-commuting checks
Exact distance Brouwer-Zimmermann, or connected cluster Exhaustive enumeration Exhaustive enumeration Yes
Distance bounds Decoder, GAP, or ``sqetch`` Decoder or GAP Decoder or GAP CSS codes only
Decoders All built-in decoders GUF (default), ILP, and lookup GUF (default) and lookup Yes, in code-capacity estimates
Circuits Yes No No No memory experiments
=============== ========================================= ============================== =================================== ========================================
=============== ===================================================== ============================== =================================== ========================================
Capability :math:`GF(2)` Prime field :math:`GF(p)` Extension field :math:`GF(p^m)` Subsystem codes
=============== ===================================================== ============================== =================================== ========================================
Codes Yes Yes Yes Yes, inferred from non-commuting checks
Exact distance Brouwer-Zimmermann, connected cluster, or enumeration Exhaustive enumeration Exhaustive enumeration Yes
Distance bounds Decoder, GAP, or ``sqetch`` Decoder or GAP Decoder or GAP CSS codes only
Decoders All built-in decoders GUF (default), ILP, and lookup GUF (default) and lookup Yes, in code-capacity estimates
Circuits Yes No No No memory experiments
=============== ===================================================== ============================== =================================== ========================================

Other limitations:

Expand Down
2 changes: 1 addition & 1 deletion examples/logical_error_rates/1_code_capacity.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -284,7 +284,7 @@
"Each qubit of these codes participates in three checks of each type, so a single error can flip more than two checks and decoding is no longer a matching problem.\n",
"We therefore use belief propagation with localized statistics decoding (BP+LSD) instead of MWPM.\n",
"Here we set `compute_distance=True` to include exact distances in the labels.\n",
"The Brouwer-Zimmermann search has exponential worst-case cost and can take a long time for larger codes."
"Exact distance searches have exponential worst-case cost and can take a long time for larger codes."
]
},
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@
"\n",
"A bivariate bicycle (BB) code from [arXiv:2308.07915](https://arxiv.org/abs/2308.07915) provides a higher-rate example with parameters $[[72,12,6]]$: 72 physical qubits, 12 logical qubits, and distance 6.\n",
"Here we set `compute_distance=True` to recompute the exact distance for the plot label.\n",
"The Brouwer-Zimmermann search has exponential worst-case cost and can take a long time for larger codes.\n",
"Exact distance searches have exponential worst-case cost and can take a long time for larger codes.\n",
"The experiment uses six syndrome-measurement rounds and decodes each CSS sector with BP+LSD.\n",
"It tracks 24 logical observables and counts each experiment as a failure if any prediction is wrong."
]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,9 +127,9 @@
"An error mechanism is an error instruction in the circuit's detector error model (DEM).\n",
"Mechanisms with identical detector and observable effects can be merged, so mechanism indices are not physical gate-location indices.\n",
"A fault is a set of error mechanisms, and the weight of a fault is the number of error mechanisms it contains.\n",
"`circuits.get_fault_distance` searches for a minimum-weight fault with no detector flips and at least one observable flip.\n",
"This method converts the problem of finding a minimum-weight fault into that of computing the Z-distance of an auxiliary Calderbank-Shor-Steane (CSS) code, and uses the Brouwer-Zimmermann distance-finding algorithm.\n",
"For a derivation of this reduction, see the documentation [here](https://qldpc.readthedocs.io/autoapi/qldpc/circuits/certification/fault_distance/index.html)."
"`circuits.get_fault_distance` searches exactly for a minimum-weight fault with no detector flips and at least one observable flip.\n",
"It computes this weight with `codes.distance.get_distance_from_checks`, as the distance of a code whose parity checks are the detectors, in which faults that flip no observable do not count.\n",
"For details, see the documentation of `get_fault_distance` [here](https://qldpc.readthedocs.io/autoapi/qldpc/circuits/certification/fault_distance/index.html)."
]
},
{
Expand All @@ -141,7 +141,7 @@
"\n",
"For comparison, we use a bivariate bicycle code from [arXiv:2308.07915](https://arxiv.org/abs/2308.07915) with parameters $[[72,12,6]]$: 72 physical qubits, 12 logical qubits, and distance 6.\n",
"Here each basis has 432 mechanisms after equivalent ones are merged.\n",
"Checking all combinations of up to six would require roughly nine trillion combinations; the code-distance reduction avoids that exhaustive enumeration."
"Checking all combinations of up to six would require roughly nine trillion combinations; this reduction to a code distance avoids that exhaustive enumeration."
]
},
{
Expand Down
2 changes: 1 addition & 1 deletion experiments/distance_tuning/trial.py
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ def warm_up(kind: str) -> None:
elif kind == "hadamard":
hadamard_code = workloads.get_hadamard_code("surface:5")
hadamard_code.forget_distance()
hadamard_code.get_distance_exact()
hadamard_code.get_distance_exact(method="brouwer_zimmermann")
elif kind == "count":
for code, weight in (
(codes.SurfaceCode(5), 5),
Expand Down
26 changes: 15 additions & 11 deletions experiments/distance_tuning/workloads.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,11 @@

A workload name is a kind, then a code name, then the arguments of the kind, separated by ``/``:

- ``distance/<code>/<sector>``: ``get_distance_exact`` of a quantum code, for the sector ``X``,
``Z``, or ``both``, or of a classical code, whose sector must be ``-``;
- ``distance/<code>/<sector>``: ``get_distance_exact``, by the BZ method, of a quantum code, for the
sector ``X``, ``Z``, or ``both``, or of a classical code, whose sector must be ``-``;
- ``ccdistance/<code>/<sector>``: the same, by the connected-cluster method;
- ``hadamard/<code>``: ``get_distance_exact`` of the code that Hadamards on the second half of the
qubits of a CSS code make, which is not CSS;
- ``hadamard/<code>``: ``get_distance_exact``, by the BZ method, of the code that Hadamards on the
second half of the qubits of a CSS code make, which is not CSS;
- ``count/<code>/<weight>``: ``CSSLogicalCounter.count_logical_ops(weight)`` by the BZ method;
- ``ccount/<code>/<weight>``: the same count, in a process whose warm-up first calls
``compile_search_setup`` (see ``trial.py``);
Expand All @@ -52,9 +52,9 @@
- ``certify/<code>/<weighing>/<max_weight>``: ``certify_bounded_fault_propagation`` of the encoding
circuit of ``|0...0>`` of a CSS code under ``DepolarizingNoiseModel(1e-3)``, by ``css`` or
``physical`` weight, whose result is the fault weight of the smallest violation, if any;
- ``faultdist/<code>/<basis>``: ``get_fault_distance`` of one round of a memory experiment of a
CSS code in the basis ``X`` or ``Z``, with noise only on its QEC cycle, as in the notebook of
fault-tolerance certificates.
- ``faultdist/<code>/<basis>``: ``get_fault_distance``, by the BZ method, of one round of a memory
experiment of a CSS code in the basis ``X`` or ``Z``, with noise only on its QEC cycle, as in the
notebook of fault-tolerance certificates.

Each workload returns a short string of its result, which every tuning must reproduce.
"""
Expand Down Expand Up @@ -269,10 +269,13 @@ def run_distance(


def run_hadamard_distance(code_name: str) -> str:
"""The exact distance of a CSS code after Hadamards on the second half of its qubits."""
"""The distance, by the BZ method, of a CSS code after Hadamards.

The Hadamards act on the second half of its qubits.
"""
code = get_hadamard_code(code_name)
code.forget_distance()
return str(code.get_distance_exact())
return str(code.get_distance_exact(method="brouwer_zimmermann"))


@functools.cache
Expand Down Expand Up @@ -426,10 +429,11 @@ def get_noisy_encoding_circuit(code_name: str) -> stim.Circuit:


def run_fault_distance(code_name: str, basis: str) -> str:
"""The fault distance of one round of a memory experiment with a noisy QEC cycle."""
"""The fault distance, by the BZ method, of one memory round with a noisy QEC cycle."""
if basis not in ("X", "Z"):
raise ValueError(f"Unknown basis {basis!r}; choose 'X' or 'Z'")
return str(circuits.get_fault_distance(get_noisy_memory_circuit(code_name, basis)))
circuit = get_noisy_memory_circuit(code_name, basis)
return str(circuits.get_fault_distance(circuit, method="brouwer_zimmermann"))


@functools.cache
Expand Down
4 changes: 2 additions & 2 deletions src/qldpc/_deprecations/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -384,7 +384,7 @@ def get_distance_classical(
*,
cutoff: int = 1,
block_size: int | None = None,
method: DistanceMethod = "brouwer_zimmermann",
method: DistanceMethod = "auto",
max_weight: SupportsIndex | None = None,
) -> int | Literal[NoDistance.NAN]:
"""Deprecated: the distance of a classical linear binary code, from its generator matrix.
Expand All @@ -411,7 +411,7 @@ def get_distance_quantum(
cutoff: int = 1,
block_size: int | None = None,
homogeneous: bool = False,
method: DistanceMethod = "brouwer_zimmermann",
method: DistanceMethod = "auto",
max_weight: SupportsIndex | None = None,
) -> int | Literal[NoDistance.NAN]:
"""Deprecated: the distance of a binary quantum code from its logical operators and stabilizers.
Expand Down
14 changes: 13 additions & 1 deletion src/qldpc/_deprecations/core_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ def test_deprecated_distance_functions() -> None:
):
assert search() == distance

# Both functions pass on their method.
# Both functions pass on their method, which defaults to "auto".
get_distance_classical: Any = codes.get_distance_classical # type: ignore[attr-defined]
get_distance_quantum: Any = codes.get_distance_quantum # type: ignore[attr-defined]
for search in (
Expand All @@ -281,6 +281,18 @@ def test_deprecated_distance_functions() -> None:
):
with pytest.warns(DeprecationWarning), pytest.raises(ValueError, match="from_checks"):
search()
with unittest.mock.patch.object(
codes.distance,
"get_distance_from_generators",
wraps=codes.distance.get_distance_from_generators,
) as get_distance:
for search in (
lambda: get_distance_classical(generator),
lambda: get_distance_quantum(generator[:1], generator[1:], homogeneous=True),
):
with pytest.warns(DeprecationWarning):
assert search() == 3
assert get_distance.call_args.kwargs["method"] == "auto"

# get_distance_quantum required its stabilizers, so it rejects None, and its errors name its own
# arguments.
Expand Down
Loading
Loading