Skip to content

Import networkx eagerly, fix false "Type:" fields, and document the caps of the fault search - #909

Merged
perlinm merged 9 commits into
mainfrom
fix/library-cleanups
Nov 16, 2026
Merged

perlinm merged 9 commits into
mainfrom
fix/library-cleanups

Conversation

@perlinm

@perlinm perlinm commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Motivation

This pull request gathers three small cleanups of the library.

  • qldpc._utils loaded networkx lazily, through _lazy_import. But TannerGraph subclasses networkx.DiGraph, and import qldpc imports TannerGraph, so every import of qldpc already loaded networkx, and the lazy loader saved nothing while making each use of networkx indirect.
  • Sphinx renders a property docstring whose first line contains a colon as a description followed by a "Type:" field. Eight property docstrings had such a first line, so the API reference showed false types for them.
  • The fault search of certify_bounded_fault_propagation keeps two tables within memory_limit: a closing map of pairs of fault classes, and a table of the syndromes that it has listed. Neither may grow past 2^31 entries, since its hash map numbers slots with 32 bits, but neither the guide nor the docstrings said so for both, so a reader could expect a larger memory_limit always to help. Separately, the docstring of BoundedFaultPropagationCounterexample said that its residual bound can change between versions for every method, though the method "connected_cluster" documents its bound, fault_weight + 1.

Changes

  • networkx is imported directly (import networkx as nx) wherever the lazy loader was used, and _lazy_import, its loader, and their tests are removed. docs/source/conf.py links networkx.DiGraph under its own name, and the code standard no longer lists lazy imports among the contents of _utils.py.
  • The eight property docstrings are reworded so that their first lines have no colon.
  • fault_propagation.md and the docstrings of FaultLister state the 2^31 caps of both tables and what the search does without the table of pairs. The class docstring of BoundedFaultPropagationCounterexample limits "can change between versions" to the method "brouwer_zimmermann", and points to method in certify_bounded_fault_propagation for each method's bound.
  • FaultLister splits its memory limit between the two tables in a new pure helper, _split_memory_limit, so that a test can check the caps without building tables of 2^31 entries.

Validation

test_memory_limit_is_split_within_the_caps checks the split at both caps: 2^16 classes have 2^31 - 2^15 pairs, which the map of pairs may hold, and one more class has more than 2^31, which it may not, however large the limit. test_listing_matches_brute_force now also checks that the memory limit leaves unchanged the order in which faults are listed, not only the set of faults, and that some of its listings use a map of pairs; no test checked either before. Dropping either cap, never building the map of pairs, or reversing the order in which faults are listed when the map of pairs is in use, fails these tests.

perlinm and others added 9 commits November 16, 2026 14:17
TannerGraph subclasses networkx.DiGraph, so every import of qLDPC loads networkx, and its lazy loader in _utils.py deferred nothing.  Modules now import networkx directly; _utils.py drops _lazy_import, its loader proxy, and their tests, and the docs configuration links networkx.DiGraph under its own name.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…types

Napoleon reads the text before a colon on the first line of a property's docstring as its type, so the API pages showed a false "Type:" field for QuaternionGroup.generators, GroupRing.dim and lift_dim, ClassicalCode.generator, and ErrorRateFunc.infidelities.  Their first lines now have no colon, and so do those of GroupRing.group_trace_matrix and two private properties, which do not render as properties but would read the same way if they did.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The search keeps the table of closing pairs only if it fits within the memory limit and has at most 2**31 pairs, and its table of syndromes holds at most 2**31 syndromes.  The guide now states both caps, and that without the table of pairs the search looks up the closing class of each prefix, which lists the same faults in the same order.  The docstrings of FaultLister and its closing map of pairs agree.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…nge between versions

The class docstring of BoundedFaultPropagationCounterexample now limits the
changes between versions to the method "brouwer_zimmermann", as the method's
docstring and the guide already do; the method "connected_cluster" documents
its bound.  Also clarify three property docstrings and two sentences of the
certification guide.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extract the split of the memory limit between the closing map of pairs and
the table of syndromes into _split_memory_limit, and test its caps of 2**31
pairs and 2**31 syndromes.  Check that the memory limit does not change the
order in which faults are listed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
State what _split_memory_limit returns: room for syndromes, which
_table_should_grow takes as max_syndromes.  Test the exact byte boundary
of the map of pairs, and that some listings build a map of pairs.  Say
why the fourth set of flags is there, and which table the guide means.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Split a sentence of _split_memory_limit's docstring, and say what the
split test's caps and the recorded sizes of closing maps mean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@perlinm
perlinm merged commit e54c58e into main Nov 16, 2026
9 checks passed
@perlinm
perlinm deleted the fix/library-cleanups branch November 16, 2026 20:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant