Add triangular color code plugin with superdense memory circuit

[kvmto]

Description

Adds the triangular color code to CUDA-QX as a Python QEC code plugin. The registered stabilizer_round implements a superdense (paired-ancilla) syndrome-extraction schedule that measures both stabilizer bases of every plaquette in a single depth-8 CNOT pass; the record-conditioned readout byproduct inherent to this scheme is handled through the code-declared inlined-feedback mechanism of #665 rather than by an in-circuit correction gate. The plugin runs end-to-end through the standard framework API (sample_memory_circuit, dem_from_memory_circuit), and the resulting detector error model is validated mechanism-for-mechanism against an independently constructed reference DEM.

Depends on #665 (this branch contains its commits; review the top commit here). The feedback-declaration API (get_inlined_feedback, get_observable_inlined_feedback_z/_x) is defined there.

Design

• ColorCodeGeometry — triangular color code with a rectangular-grid embedding (data-qubit grid, algorithmic plaquette generation, syndrome-to-grid mapping, superdense plaquette labeling), ported from an internal reference implementation. Retains the pre-decoder mapping surface (CNN grid embedding, syndrome-to-grid indices) for upcoming decoder work.
• Schedule builders (z_side_data, superdense_schedule) — host-side construction of the per-round CNOT schedule from the geometry: 8 layers over a unified index space, with the ancilla-pair partition of each plaquette's support determined by plaquette weight and color.
• Registered round as a capturing kernel — the framework passes only flattened parity matrices to stabilizer_round, and the boundary-plaquette partition is color-dependent, i.e. not derivable from parity rows alone. The plugin therefore registers a @cudaq.kernel defined in a factory that captures the host-built schedule; the fixed framework signature is unchanged and the captured lists survive the sub-kernel dispatch from the C++ memory_circuit (multiple instances remain independent). Records are returned in [Z][X] order.
• Declared inlined feedback — the byproduct is a linear function of earlier Z-ancilla records, so it folds into detector definitions as data. With F(S) = {a : |z_side(a) ∩ S| odd}: the detector matrix has fb(j,k) = 1 iff j,k < P and plaquette k ∈ F(supp(plaquette j)); the Z-basis observable row is the indicator of F(logical-operator support); the X basis declares none. Diagonal entries exploit the XOR multiset semantics of cudaq::detector (a duplicated record cancels), which is what allows a detector to exclude its own previous-round record.
• Observable representatives — logical Z is the bottom boundary row (weight d); logical X is the all-data-qubit representative. The asymmetry matches the reference construction, whose Z observable carries herald records while its X observable does not.
• Order invariant — __init__ asserts the minimum data-qubit index is strictly increasing across grid-ordered plaquettes, which guarantees the framework's stabilizer re-sorting is the identity permutation (record k ↔ plaquette k).

Validation

• Framework-path E2E: all four preparations (prep0/1/p/m) are noiseless-deterministic with correct logical readout for d=3 at 2 and 4 rounds; DEM extraction succeeds in both bases under two-qubit depolarizing noise; a decode smoke test shows strict logical-error reduction.
• Golden-oracle DEM equivalence (both bases, d=5, 5 rounds, p=0.01 depolarizing on every CNOT): the framework-produced DEM equals a checked-in reference DEM bit-exactly — identical mechanism sets (detector supports and observable flips, after a documented block-order permutation) and identical probabilities. Z: 2957 mechanisms, X: 2958.
• Evidence chain, stated precisely: the reference DEMs were generated by an independent construction (own kernel with explicit detector rules, not the framework path). That generator byte-reproduces the original reference DEMs under their native convention; the checked-in goldens are the same construction with noise applied to every round. The comparison chain therefore has one inference step: generator ≡ original reference (native convention), framework ≡ generator (all-noisy convention).
• Convention notes (deliberate, documented deviations from the original reference DEMs):
  1. All rounds noisy. The original reference DEMs use a noiseless final stabilizer round. The framework applies the user's noise model to every gate of a matching type and currently has no mechanism for a noiseless region, so the shipped goldens use the all-rounds-noisy convention (a strict superset of the reference mechanisms: with the final-round convention equalized, the diff is empty). A noiseless-region capability would make the original reference DEMs a drop-in second golden; see follow-ups.
  2. All-data logical-X representative, adopted from the reference construction (see Design).

Notes for reviewers

• The capturing-kernel pattern for a registered operation has no in-tree precedent; it was feasibility-tested through the full C++ dispatch path before adoption, and the alternative (deriving the schedule in-kernel from parity rows) is information-theoretically unavailable for boundary plaquettes.
• Geometry code is a fidelity-preserving port (including some conservatively retained unreachable branches) to keep line-level correspondence with the reference implementation.
• Test suite: 81 items, including matrix truth tables (d=3 exact, d=5 spot checks), schedule/geometry invariants, framework E2E, and the two golden tests with exact-equality assertions and mechanism-count guards.

Follow-ups (out of scope here)

• A noiseless-region capability in the noise pipeline (enables the perfect-final-round convention and direct comparison against the original reference DEMs).
• Color-decoder (Chromobius) integration; the geometry retains the required coordinate surface.
• Realtime consumers of the declared feedback layout (see Support code-declared inlined feedback in memory circuits #665 follow-ups).

🤖 Generated with Claude Code

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.