[perlinm]

Motivation

The review of qldpc.codes.distance that led to #841 also looked at how the package is organized. The package had one _search/ subpackage that mixed the drivers of three methods, the information-set machinery that they share, and compiled kernels. Its order was a convention that no test checked. Two hub modules each held several concepts: information_sets.py (1,199 lines) held basis families, certificates, step planning, and the support stepping of every scan, and coset_leader_search.py (2,210 lines) held the coset-leader query, the Brouwer–Zimmermann coset searches, their tables and tails, the connected-support coset searches, and the helpers they share. Modules outside the package imported the coset-leader search from that deep private path. This PR changes no behavior. It moves code so that each concept that a user or a change request names has one obvious module, and the layers of the package are checked by its layering test.

Changes

• Layout. The top level of distance/ holds the entry modules (core.py, logical_counts.py, and the private _coset_leader_search.py, which circuits/certification and the experimental residual-weight estimator import), _brute_force.py, _cosets.py, _tuning.py, and _binary.py. The machinery goes into private subpackages:

  • _brouwer_zimmermann/: the distance search (distance.py), the coset searches (coset.py) with their tables and tails (coset_tables.py) and routes (coset_routes.py), and the packed instances and compiled scans that both share;
  • _connected_support/: the search (search.py) and its coset searches (coset.py);
  • _information_sets/: information_sets.py split into basis_families.py, certificates.py, and support_stepping.py, beside the existing automorphism-family, completion-bound, and matroid-partition modules;
  • _counting/: unchanged.

  The README of the package gains a short account of the layout, and its map and dependency levels follow it.

• Layers. The layering test of the package, now _layering_test.py, orders _binary, _tuning, (_brute_force, _information_sets, _cosets), (_brouwer_zimmermann, _connected_support, _counting), (_coset_leader_search, core), and logical_counts. A unit may import only from itself and lower layers, so the test also records that the methods are independent of each other, and the two entry modules too.

• Commits 1 and 2 are moves. Moved objects keep their names and bodies, so git diff -M --color-moved=dimmed-zebra shows them as moves. Imports, string patch targets, and test helpers follow the code.

• Commit 3 adds tests so that each new module is fully covered by its own test file, as the coverage gate requires. Commit 4 updates the guides, docstrings, and module.name references.

• Commit 5 renames. The code standard asks private modules to use plain names for what other modules use, so the 23 underscore names that now cross module boundaries lose their underscore, such as get_stopping_step and WORK_CAP. Three get clearer names: the Brouwer–Zimmermann coset search becomes BrouwerZimmermannCosetSearch, beside ConnectedSupportCosetSearch; _get_inverse becomes get_unit_syndrome_words, since its rows are the transpose of a right inverse; and _packed_row_int becomes words_to_int, the inverse of int_to_words. The test helpers that several test files now share get plain names too.

• Commit 6 holds the revisions after review: references that the splits left pointing into other modules now give their paths, a few test helpers and private attributes get names that say what they do, the README and guides are tidied, and new cases test the order in which the tables of single errors keep their words.

• Commit 7 renames the layering tests of qldpc.circuits, qldpc.decoders, and qldpc.codes.distance to _layering_test.py, like _code_style_test.py, since they test no module of their own.

Validation

• Each move commit was checked for pure moves by listing every added line that matches no removed line of the same commit, after normalizing module qualifiers. What remains is imports, module docstrings, rewrapped lines, and the manual edits named above. Undoing the renames of commit 5 on its tree leaves only the move of one function, lines rewrapped for longer names, and the docstrings of the renamed functions.
• Each commit passes on its own the tests of distance/, circuits/certification, the residual-weight estimator, and the style and compilation tests.
• The object graph of the package, recomputed on the new layout, has the same 357 objects and 760 references. The largest module shrinks from 2,210 lines to about 1,100, and no module outside the package imports anything but core.py or _coset_leader_search.py.

Notes

• Left as they are, on purpose: _connected_support/search.py keeps its distance driver, which is about 110 lines over the shared search; the basis-family transport stays in _counting/scan.py; CosetRoutes keeps its generic parameters, which let its tests use light stand-ins for the tables and tails; and _coset_leader_search.py still builds the cache keys of the Brouwer–Zimmermann coset searches itself, which factories in _brouwer_zimmermann/coset.py could hide in a later change.
• Four connected-support coset tests move to _connected_support/coset_test.py, whose module defines no compiled functions, so the --compiled-module-tests run no longer collects them. They still run compiled in the --compile-search-setup run of the distance tests, which compiles all compiled code.