v0.4.0

qLDPC v0.4.0

qLDPC v0.4.0 is a large release.
It adds a typed decoder API, new code families and groups, exact and GPU-accelerated distance methods, more flexible circuit and noise tooling, and an experimental lattice-surgery package.
It also fixes many correctness bugs.

Changes marked ⚠️ may need updates to code written for v0.3.3.

Major changes

Python 3.11 or later required

• ⚠️ qLDPC now requires Python 3.11 or later, because Python 3.10 reaches end of life in October 2026.

New decoder API

• Decoders are now chosen with typed specs:
  • decoders.bp_osd, bp_lsd, bf, mwpm, relay_bp, min_sum_bp, lookup_table, ilp, and guf.
  • Pass a spec as decoder=..., or call .build(pcm_or_dem) to get a decoder.
  • For example, decoder=decoders.bp_lsd(max_iter=30) replaces with_BP_LSD=True, max_iter=30.
• Observable decoders predict logical-observable flips directly. Code-capacity estimation also supports them.
• Correlated matching through PyMatching: decoders.mwpm(enable_correlations=True).
• LookupDecoder uses much less memory and decodes faster under Sinter.
• qldpc.decoders is reorganized into subpackages: adapters, construction, custom, external, and sinter.
• ⚠️ The v0.3.3 keyword API still works but emits a DeprecationWarning that names the replacement. This covers with_<NAME>=True, decoder_x_kwargs/decoder_z_kwargs, and the uppercase builders such as get_decoder_BP_OSD.
• ⚠️ These changes take effect without a deprecation period:
  • static_decoder is removed, except from the deprecated decoders.get_decoder and decoders.decode. Pass a prebuilt decoder as decoder= instead.
  • decoder_x_kwargs and decoder_z_kwargs now take precedence over shared keyword arguments.
  • A SinterDecoder built from mwpm, relay_bp, min_sum_bp, or lookup_table settings now uses native observable prediction. For mwpm and lookup_table, its .decoder attribute is therefore an observable decoder.
  • The internal module qldpc.decoders.retrieval no longer exists. Import its functions from qldpc.decoders.

See "Migrating from qLDPC 0.3.3" in the decoder documentation for the full mapping.

Code distance

• Exact Brouwer–Zimmermann distance for CSS codes (codes.get_distance_css_brouwer_zimmermann), with substantial speedups.
• CSSCode.get_distance_bound takes a typed backend= selector: "auto", "gap", "sqetch", or "decoder".
• An optional GPU-accelerated random-ISD backend through sqetch.
  sqetch is not on PyPI, so install it separately as described in the README.
• ⚠️ Numba acceleration is removed, along with all use_numba arguments.
  Exact binary distance calculations always use NumPy bit counting.

New code families and algebra

• New codes:
  • GALACode.
  • QuantumReedMullerCode: self-orthogonal CSS Reed–Muller codes with closed-form distance.
• New groups:
  • GeneralLinearGroup (GL).
  • ProjectiveGeneralLinearGroup (PGL).
  • WreathProductGroup.
• Groups gain tensor-product lifts, natural permutation lifts, and Group.degree. Group.lift now normalizes member degrees.
• RingArray moved to the new abstract.ring_array module, and its matrix multiplication is faster. The old import paths still work.
• ⚠️ qldpc.abstract.GF2 is removed. Use galois.GF2.

Circuits and noise models

• Circuit utilities accept any stim-wrapping circuit through circuits.StimCircuitLike and StimCircuitProtocol. This includes tsim circuits.
• Explicit idle markers can carry configurable noise.
• Operation immunity and qubit immunity are now separate controls (DEFAULT_IMMUNE_OP_TAG, DEFAULT_IMMUNE_QUBIT_TAG).
• New circuits.validate_syndrome_qubit_ids.
• ⚠️ The qldpc[tsim] extra is removed. Install bloqade-tsim directly if you need it.

GAP integration

• New qldpc[gap] extra that runs GAP in-process through PassageMath libgap. It is not available on Windows or on Python 3.15 and later.
• If GUAVA or QDistRnd is missing, qLDPC can install it through GAP's PackageManager.
  If that fails, qLDPC falls back to a separate GAP executable.
• GAP now encodes extension-field elements correctly.

Experimental lattice surgery

• New qldpc.experimental package, starting with qLDPC lattice surgery.
• Everything under qldpc.experimental is unstable and may change without a deprecation period.
• Lattice-surgery support has not yet had independent expert review.
  Validate its results independently, and pin the qLDPC version if you depend on it.

Minor changes

API additions and conveniences

• AbstractCode accepts boolean inputs.
• Pauli-valued X/Z parameters also accept strings.
• New codes.DistanceBackend, DistanceMethod, validate_distance_backend, and validate_distance_method.
• Deprecation warnings for old code aliases.

Bug fixes

• Codes:
  • Logical operators for non-CSS subsystem codes.
  • conjugated() over odd characteristic, which now goes through symplectic_conjugate.
  • Quasi-cyclic codes with trivial cyclic order or coinciding monomials.
  • Code constructions in degenerate and non-binary regimes.
  • Trivial parity checks now get a Tanner-graph vertex.
  • The graph product no longer drops qudits.
• Algebra:
  • Howell duals over commutative and non-commutative rings, which affected canonical logicals of LPCode/SLPCode.
  • Group-algebra tensor products.
  • Parsing of qudit operators.
• Code-capacity estimation: the logical-error-rate estimation was reworked and its error bars fixed.
• Decoders:
  • Unsupported erasure-bit requests are rejected consistently.
  • Validation of decoder and algebraic inputs.
• Circuits: correctness and robustness fixes.

Packaging and dependencies

• New core dependency: tqdm.
• pymatching>=2.3 (previously >=2.1).
• relay-bp is pinned to 0.2.2.
• Packaging hardened, with license files included in distributions.

Documentation and tooling

• New library map and contributor/agent guide.
• Rewritten README.
• Improved example notebooks, plus a new example on the logical error rates of individual observables.
• Fixed API-docstring rendering.
• Stricter quality gates: focused lint rules, a modular 100% statement-coverage gate, and a strict documentation build.
• Lighter CI dependency installation.