feat(circuits): qLDPC lattice surgery module

[tiangangzhou]

Summary

Adds qldpc.circuits.surgery — a lattice-surgery gadget builder for CSS qLDPC codes, together with circuit synthesis for single- and joint-Pauli-product measurements (PPM).

Components:

• gadget.py — Lattice surgery gadget construction (Webster): given a logical operator L̄ = ∏_v A_v, builds the merged CSS code (Q', S_X', S_Z') that exposes L̄ as the product of new meas-checks.
• bridge.py — Swaroop universal-adapter bridge between gadgets sharing a logical qubit (SkipTree basis transform + boundary identification).
• cheeger.py — Cheeger-constant boost: distance-verifying random ancilla rows raising h(F) to a chosen target, with two strategies (combinatorial, distance).
• circuit.py — Single- and joint-PPM circuits:

Public API

All from qldpc.circuits.surgery:

Symbol	Purpose
build_gadget(code, operator, basis) → GadgetLayout	Webster gadget: merged CSS (Q', S_X', S_Z') exposing L̄ = ∏_v A_v
boost_gadget(g, method, target, ...) → GadgetLayout	Cheeger boost (combinatorial / distance strategy) raising h(F) to target
cheeger_constant(g) → float	Reports h(F) of a gadget boundary
build_bridge(g1, g2, ...) → Bridge	Swaroop universal adapter between two gadgets sharing a logical qubit
build_single_ppm_circuit(g, rounds, basis, ...) → stim.Circuit	single-PPM measurement circuit; obs0 = last-round meas-checks
build_joint_ppm_circuit(g1, bridge, g2, rounds, ...) → stim.Circuit	Joint-PPM with bridge superposition
keep_only_observable(circuit, obs_index) → stim.Circuit	Strip all observables except one (useful for stim sampling)
logical_state_init(code, basis, ...)	Prep circuit for `

Minimal use:

from qldpc.circuits.surgery import build_gadget, build_single_ppm_circuit
from qldpc.objects import Pauli

g = build_gadget(code, x_logical, basis=Pauli.X)
circuit = build_single_ppm_circuit(g, rounds=10, basis=Pauli.X)

Example

examples/lattice_surgery.ipynb walks through:

1. Single-PPM true table (Steane or BB code)
2. Joint-PPM with bridge true table (Steane | BB code joint measurement)
3. Exact gadget dimension (|Q'|, |S_X'|, |S_Z'|) match (Webster Appendix A Table I)
4. BB18 surgery LER (distance confirmed)

Tests

149 tests under src/qldpc/circuits/surgery/. Naming follows qLDPC's <module>_test.py convention (renamed from _test_<module>.py). Shared Webster JSON fixture lives in _webster_fixture.py.

References

• Webster, Smith, Cohen — arXiv:2511.15989 §II.A — gadget construction + single-round identity Z̄ = ∏_v A_v
• Cain et al. — arXiv:2603.28627 §B.1 — single-PPM measurement protocol (last-round readout)
• Swaroop, Jochym-O'Connor, Yoder — arXiv:2410.03628 §III / §IV / §VII — SkipTree basis transform + universal-adapter bridge
• Cross, He, Rall, Yoder — arXiv:2407.18393 — Cheeger-based distance preservation (h(F) ≥ 1)
• Williamson, Yoder — arXiv:2410.02213 — distance-verifying random ancilla boost

Test plan

• pytest src/qldpc/circuits/surgery/ -v — 149 pass
• jupyter nbconvert --execute examples/lattice_surgery.ipynb — runs end-to-end

[perlinm]

Thank you for opening a PR! This looks like an exciting capability to have. Please allow me time to review it carefully 🙂

[tiangangzhou]

In the concrete implementation of the BB code lattice surgery gadget system, it naturally supports the PPMs X, Y, Z, X′, Y′, Z′, XX′, and ZZ′ (see Improved QLDPC Surgery: Logical Measurements and Bridging Codes, page 31). Through these together with the automorphisms, it can support all $4^{12-1}$ Pauli measurements of the gross code.

The current implementation only supports X, Z, X′, Z′, XX′, and ZZ′. The next step is to implement the Y-gadget system.