fix GAP field-element encoding over extension fields + other minor fixes

[perlinm]

What & why

get_classical_code and _gap_define_sparse_matrix assumed GAP's integer encoding of finite-field elements (Int(x) / f*One(F)) matches the one galois uses. That holds only over prime fields. Over GF(p^k) with k > 1, f*One(F) collapses to (f mod p)*One(F), so matrices sent to GAP were silently corrupted (get_distance_bound returned a wrong distance), and Int(x) raised IntFFE: <z> must lie in prime field when reading extension-field elements back.

Each element is now mapped through the discrete logarithm of the field's primitive root instead: Z(q)^log when writing to GAP, LogFFE(x, z) when reading back (rebuilt in Python as primitive_element ** log). GAP and galois share that primitive element (both use Conway polynomials for the field orders that arise here), so the encoding is byte-identical over prime fields and correct over extension fields.

Verified against live GAP: a GF(4) hypergraph-product code with true Z-distance 2 previously received a bound of 1 (impossible for a correct upper bound) and now receives 2; reading a GF(4) GUAVA code no longer raises.

Other fixes

• get_output now treats a nonzero GAP exit code as an error, not only nonempty stderr.
• Removed a duplicate, unguarded pyperclip.copy that crashed the manual copy/paste fallback on headless machines instead of printing instructions.
• codes.py imports urllib.request / urllib.error explicitly rather than relying on another module to import them first.
• The GroupNames lookups pass a urlopen timeout and catch connection failures, so an unreachable server degrades gracefully instead of hanging or raising uncaught.
• get_quantum_code catches TimeoutError alongside urllib.error.URLError, so a socket read-timeout during the qecdb fetch becomes the intended Cannot access {url} error instead of propagating raw, matching the GroupNames lookups.
• get_classical_code parses only lines that begin with [ as check-matrix rows, so a stray GAP diagnostic line falls through to the descriptive "Could not determine the base field" / "Code has no parity checks" errors instead of an opaque SyntaxError from ast.literal_eval.
• get_small_group_number raises a clear error instead of ValueError: max() arg is an empty sequence when the index page has no matching entries.
• parse_gap_permutations skips blank lines instead of emitting a spurious identity generator.

Documentation

Documented the modules' side effects (subprocess, network fetch, clipboard write, git clone, blocking stdin) and the randomized-upper-bound semantics of get_distance_bound (and its maxav argument); linked the GAP, GUAVA, Wedderga, SmallGrp, GroupNames, and qecdb references.

Testing

Passes the project checks (./checks/all_.py: mypy, ruff lint + format, 100% coverage). The extension-field encode/decode round trip was additionally checked against a live GAP + QDistRnd install.

🤖 Generated with Claude Code