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.

[perlinm]

I'm slowly coming to terms with my lack of time to give this PR the review it deserves.

One consideration on my mind for reviewing this PR is that the field of surgery is rapidly evolving, so I want to be careful with the choice of names and abstractions that we commit to in the API. I also want to ensure that the API and implementations are flexible enough to accommodate future developments in the field. It would be helpful to find an independent surgery expert to review this PR.

In the meantime, what if we merged this material into an experimental module of qldpc? We can then add a warning that triggers on the first call of an experimental feature, letting the user know that the experimental surgery API is subject to change (and that we recommend any code relying on experimental features to pin its version of qldpc).

Surgery seems like a big enough module that it makes sense to pull it out of circuits, into src/qldpc/surgery (or, for now, src/qldpc/experimental/surgery).

[tiangangzhou]

This PR might be too large, since it bundles several pieces of implementation together. I think we could start from the easiest case and begin the design there.

For a single logical Pauli-$X$ measurement via lattice surgery, the end goal is to construct the merged check matrices

$$\tilde{H}_X = \begin{pmatrix} H_X & 0 \\\ f_1^T & \partial_1 \end{pmatrix}, \qquad \tilde{H}_Z=\begin{pmatrix} H_Z & f_0 \\\ 0 & \partial_0 \end{pmatrix}.$$

For a concrete construction, we can choose

$$\tilde{H}_X = \begin{pmatrix} H_X & 0 \\\ \pi_{V_0} & \pi_{V_0} H_Z^{T} \pi_{C_0}^{T} \end{pmatrix}, \qquad \tilde{H}_Z = \begin{pmatrix} H_Z & \pi_{C_0}^{T} \\\ 0 & \ker\left(\pi_{V_0} H_Z^{T} \pi_{C_0}^{T}\right) \end{pmatrix}$$

where $V_0$ is the set of physical qubits on which the logical operator $\bar{X}$ has support,

$$V_0 = \mathrm{supp}(x) = (v_0,\dots ,v_{|V_0|-1})$$

and $C_0$ is the set of dual stabilizer checks ($S_Z$) that overlap with $V_0$,

$$C_0 = \{j : (H_Z)_{j,V_0} \neq 0 \} = (c_0,\dots,c_{|C_0|-1}).$$

For any ordered subset $S=(s_0,\dots,s_{|S|-1})$, we define the projection $\pi_S \in \mathbb{F}_2^{|S|\times N}$ by

$$(\pi_S)_{i,j} = \delta_{j,s_i},\ (\pi_S^T)_{i,j} = \delta_{i, s_j}.$$

We can verify that the product of the newly introduced $X$ stabilizers (the second row block of $\tilde{H}_X$) reproduces the original logical $X$:

$$\prod_{i=0}^{|V_0|-1}(S_X')_i = \prod_{l=0}^{|V_0|-1} X_{v_l} = \bar{X}$$

A further improvement would be to ask how we can obtain better $f_1$, $\partial_1$, $f_0$, $\partial_0$ to achieve a larger merged code distance (via some graph theory boost). I think we can expose this as an input API while keeping the standard construction above as the default. We can then design a protocol to translate these stabilizers into Stim circuits. This is essentially why I designed build_single_ppm_circuit.

What do you think about opening a separate PR that deals only with the single Pauli-$X$/$Z$ PPM, so we can keep it clean and review it?

[perlinm]

@tiangangzhou I appreciate the thoughtfulness of breaking this into more manageable chunks! That may make sense to do independently of my comments below.

It is a very busy time for me at work, so I will regardless not be able to review parts of this PR in the near term. I therefore want to re-surface my proposal to merge this into an experimental module, which I would be comfortable merging without detailed review. What do you think?

(By the way, I invited you @tiangangzhou to be a collaborator with write access to qldpc. Let me know if the invitation got lost, and I can re-send it.)

[tiangangzhou]

Thanks @perlinm. I think an experimental module is a good idea. As of today, graph-based surgery is still under rapid development, and the choice of the $f_1, \partial_1, f_0, \partial_0$ gadgets is generally non-standard. It can be optimized for different hardware or codes. However, we can always build circuit-level simulations using $f_1, \partial_1, f_0, \partial_0$ as input. Users can write their own class methods to propose new sets of gadgets, though of course some default constructions would be provided.

Btw, the link has expired. Could you please resend the invitation?