Add triangular color code plugin with superdense memory circuit by kvmto · Pull Request #658 · NVIDIA/cudaqx

kvmto · 2026-07-07T16:20:39Z

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 · 2026-07-11T10:39:30Z

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.

Codes may declare record->detector feedback corrections as data via two new virtuals (get_inlined_feedback / get_observable_inlined_feedback, empty default = existing behavior); memory_circuit folds the declared records into its detector and observable definitions, so measurement schemes with readout byproducts get deterministic detectors through sample_memory_circuit without a physical correction gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: kvmto <kmato@nvidia.com>

…d_feedback The record->detector composition rule now lives in detector_error_model as a CSR layout builder; the memory_circuit kernel is a thin emitter walking the layout. Behavior is bit-identical; all suites pass unchanged. Signed-off-by: kvmto <kmato@nvidia.com>

…amed device helpers The kernel keeps its flat-matrix signature; all record-composition logic lives in reusable __qpu__ functions in device/inlined_feedback.h. The host CSR layout builder (build_inlined_feedback_layout) is retained for record-stream consumers and pinned to the kernel by an M2D conformance test Signed-off-by: kvmto <kmato@nvidia.com>

Signed-off-by: kvmto <kmato@nvidia.com>

Validate feedback matrices before conversion, clarify raw sampling semantics, reject unsupported qpp-cpu Python sampling, and expand detector/observable conformance coverage. Signed-off-by: kvmto <kmato@nvidia.com>

…ry circuit Registers the triangular color code as the Python plugin 'color_code' (geometry, CSS stabilizers/observables, patch kernels) and adds a superdense memory circuit for it: the paired-ancilla 8-CNOT-layer schedule with the measurement feedforward absorbed into explicit cudaq.detector / cudaq.logical_observable annotations. DEM extraction and detector-ordered sampling via cudaq.dem_from_kernel / cudaq.sample; validated against a reference stim construction (identical error mechanisms, both bases). Signed-off-by: kvmto <kmato@nvidia.com>

Signed-off-by: kvmto <kmato@nvidia.com>

with the structure of the existing code plugins; the plugin is used through the standard qec.sample_memory_circuit / dem_from_memory_circuit API. The geometry retains the pre-decoder mapping surface (CNN grid embedding, syndrome-to-grid indices, superdense plaquette labels) for upcoming work. Signed-off-by: kvmto <kmato@nvidia.com>

The registered stabilizer_round now implements the reference superdense CX schedule (captured host-built layers) with the readout byproduct handled via the code-declared inlined-feedback matrices instead of an in-circuit correction. The framework-path DEM matches the reference construction mechanism-for-mechanism (golden tests, both bases, exact probabilities). Signed-off-by: kvmto <kmato@nvidia.com>

Signed-off-by: kvmto <kmato@nvidia.com>

eliotheinrich

Looks great, Kevin! I left some suggestions, the only thing I would consider blocking is the input validation on the distance and some hint for reproducing the golden values in the .dem files if possible.

eliotheinrich · 2026-07-13T21:40:09Z

+# Reference superdense color-code DEM, d=5, 5 rounds, DEPOLARIZE2(0.01)
+# per CX, ALL ROUNDS NOISY (physically stricter convention).
+# Generator: reference superdense construction (superdense_memory kernel,
+# cudaq.dem_from_kernel). The perfect-final-round originals are
+# byte-reproduced by the same generator with its two noise guards restored
+# (R > 1 and r < R - 1); here both are relaxed to p_cx > 0.0 so every
+# stabilizer round is noisy.


Would it be feasible to add a reproduction script for this DEM in the header comments here so that if anyone needs to rebuild this golden value down the road are able to? (ditto for the *_Z.dem)

eliotheinrich · 2026-07-13T21:41:03Z

+            f"Unsupported w4 geometry for plaq_idx={plaq_idx}: distinct_rows={len(rows)}, distinct_cols={len(cols)}, coords={coords}"
+        )
+
+        return out


This is unreachable; any reason for it to be here?

eliotheinrich · 2026-07-13T21:41:57Z

+            raise RuntimeError(
+                "[color_code] distance not provided. distance must be "
+                "provided via qec.get_code('color_code', distance=d).")
+        self.distance = kwargs['distance']


Should add some kind of input validation (i.e. make sure that distance is a positive integer)

eliotheinrich · 2026-07-13T21:44:57Z

+        for tt in range(1, 9):
+            edges: List[Tuple[int, int]] = []
+
+            if tt == 1 or tt == 8:
+                # CNOT between the two ancilla qubits: control |+> (a1),
+                # target |0> (a2)
+                index = num_data
+                for _ in range(num_plaquettes):
+                    a1 = index
+                    a2 = index + 1
+                    edges.append((a1, a2))
+                    index += 2
+
+            elif tt == 2:
+                # First sequence (data = control)
+                data_qubit_index = d
+                index_ancilla = num_data
+                cols = d - 1
+                for rr in range(num_rows_data_qubits - 1):
+                    if rr % 3 == 0:
+                        for _ in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 1
+                    elif rr % 3 == 1:
+                        for cc in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            if cc == cols - 1:
+                                index_ancilla += 3
+                            else:
+                                index_ancilla += 1
+                    else:  # rr % 3 == 2
+                        for _ in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 1
+
+            elif tt == 3:
+                # Second sequence (data = control)
+                data_qubit_index = 0
+                index_ancilla = num_data
+                cols = d - 1
+                for rr in range(num_rows_data_qubits - 1):
+                    if rr % 3 == 0:
+                        for cc in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            index_ancilla += 1
+                            if cc == cols - 1:
+                                data_qubit_index += 3
+                            else:
+                                data_qubit_index += 1
+                        cols -= 1
+                    elif rr % 3 == 1:
+                        for cc in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            if cc == cols - 1:
+                                index_ancilla += 3
+                            else:
+                                index_ancilla += 1
+                    else:  # rr % 3 == 2
+                        for _ in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 1
+
+            elif tt == 4:
+                # Third sequence (data = control)
+                data_qubit_index = 1
+                index_ancilla = num_data + d - 1
+                cols = d - 1
+                for rr in range(num_rows_data_qubits - 2):
+                    if rr % 3 == 0:
+                        for _ in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                    elif rr % 3 == 1:
+                        for _ in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 2
+                    else:  # rr % 3 == 2
+                        for cc in range(cols):
+                            edges.append((data_qubit_index, index_ancilla))
+                            index_ancilla += 1
+                            if cc == cols - 1:
+                                data_qubit_index += 3
+                            else:
+                                data_qubit_index += 1
+
+            elif tt == 5:
+                # First sequence (data = target) => ancilla is control
+                data_qubit_index = d
+                index_ancilla = num_data
+                cols = d - 1
+                for rr in range(num_rows_data_qubits - 1):
+                    if rr % 3 == 0:
+                        for _ in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 1
+                    elif rr % 3 == 1:
+                        for cc in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            if cc == cols - 1:
+                                index_ancilla += 3
+                            else:
+                                index_ancilla += 1
+                    else:  # rr % 3 == 2
+                        for _ in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 1
+
+            elif tt == 6:
+                # Second sequence (data = target) => ancilla is control
+                data_qubit_index = 0
+                index_ancilla = num_data
+                cols = d - 1
+                for rr in range(num_rows_data_qubits - 1):
+                    if rr % 3 == 0:
+                        for cc in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            index_ancilla += 1
+                            if cc == cols - 1:
+                                data_qubit_index += 3
+                            else:
+                                data_qubit_index += 1
+                        cols -= 1
+                    elif rr % 3 == 1:
+                        for cc in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            if cc == cols - 1:
+                                index_ancilla += 3
+                            else:
+                                index_ancilla += 1
+                    else:  # rr % 3 == 2
+                        for _ in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 1
+
+            else:  # tt == 7
+                # Third sequence (data = target) => ancilla is control
+                data_qubit_index = 1
+                index_ancilla = num_data + d - 1
+                cols = d - 1
+                for rr in range(num_rows_data_qubits - 2):
+                    if rr % 3 == 0:
+                        for _ in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                    elif rr % 3 == 1:
+                        for _ in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            data_qubit_index += 1
+                            index_ancilla += 1
+                        cols -= 2
+                    else:  # rr % 3 == 2
+                        for cc in range(cols):
+                            edges.append((index_ancilla, data_qubit_index))
+                            index_ancilla += 1
+                            if cc == cols - 1:
+                                data_qubit_index += 3
+                            else:
+                                data_qubit_index += 1
+
+            layers.append(sorted(edges))


Two comments:
1.) Nesting conditionals inside a for-loop doesn't make much sense since this is just a sequence; just push each conditional up one layer of scope
2.) The final three layers are a mirror image of the three layers before them under exchange of target and control qubits. Can make this explicit in the code

eliotheinrich · 2026-07-13T21:51:34Z

+    (qec.operation.prepp, 'x', 'get_observables_x', 0),
+    (qec.operation.prepm, 'x', 'get_observables_x', 1),
+])
+@pytest.mark.parametrize("nRounds", [2, 4])


nRounds == 1 is a bit of an edge case since no inter-round detectors are formed. Easy and IMO worthwhile to add to the parametrized test here

eliotheinrich · 2026-07-13T21:54:25Z

+        # x_stabilizers / z_stabilizers arrive from the framework but are
+        # unused: the captured schedule alone drives the gate sequence.


It might be reasonable to add some checks that the *_stabilizers passed correspond correctly to the stabilizers of the code, even if they aren't used. If bad stabilizers are passed to _round, then something has gone wrong, and we should probably throw.

Signed-off-by: kvmto <kmato@nvidia.com>

jolle-ag · 2026-07-14T21:00:42Z

Looks great! I would just recommend to test it (at least some spot tests) at d=7 since there are lattice configurations that won't have been previously encountered at d=3 and d=5. Mostly the "deep bulk" where multiple weight-6 plaquettes are neighboring

kvmto mentioned this pull request Jul 9, 2026

Support code-declared inlined feedback in memory circuits #665

Open

kvmto force-pushed the color-code-plugin branch from 0f745c9 to b7ed9a7 Compare July 11, 2026 10:39

kvmto requested a review from eliotheinrich July 13, 2026 11:04

kvmto marked this pull request as ready for review July 13, 2026 11:04

kvmto requested review from bmhowe23, ivanbasov and justinlietz July 13, 2026 11:13

kvmto and others added 4 commits July 13, 2026 16:50

split between two types of stabiizer

453df00

Signed-off-by: kvmto <kmato@nvidia.com>

kvmto force-pushed the color-code-plugin branch from b7ed9a7 to a57f603 Compare July 13, 2026 15:03

kvmto added 5 commits July 13, 2026 17:36

fix(qec): harden inlined feedback handling

74e25a5

Validate feedback matrices before conversion, clarify raw sampling semantics, reject unsupported qpp-cpu Python sampling, and expand detector/observable conformance coverage. Signed-off-by: kvmto <kmato@nvidia.com>

improved testing

e469ff3

Signed-off-by: kvmto <kmato@nvidia.com>

kvmto force-pushed the color-code-plugin branch from a57f603 to 5e12b72 Compare July 13, 2026 16:52

docs(qec): clarify color code usage

bee485d

Signed-off-by: kvmto <kmato@nvidia.com>

eliotheinrich reviewed Jul 13, 2026

View reviewed changes

kvmto added 2 commits July 14, 2026 16:38

fix(qec): address color code review feedback

3026f5b

Signed-off-by: kvmto <kmato@nvidia.com>

Merge remote-tracking branch 'upstream/main' into color-code-plugin

f861155

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add triangular color code plugin with superdense memory circuit#658

Add triangular color code plugin with superdense memory circuit#658
kvmto wants to merge 12 commits into
NVIDIA:mainfrom
kvmto:color-code-plugin

kvmto commented Jul 7, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Jul 11, 2026

Uh oh!

eliotheinrich left a comment

Uh oh!

eliotheinrich Jul 13, 2026

Uh oh!

eliotheinrich Jul 13, 2026

Uh oh!

eliotheinrich Jul 13, 2026

Uh oh!

eliotheinrich Jul 13, 2026

Uh oh!

eliotheinrich Jul 13, 2026

Uh oh!

eliotheinrich Jul 13, 2026

Uh oh!

jolle-ag commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		# x_stabilizers / z_stabilizers arrive from the framework but are
		# unused: the captured schedule alone drives the gate sequence.

Uh oh!

Conversation

kvmto commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Design

Validation

Notes for reviewers

Follow-ups (out of scope here)

Uh oh!

copy-pr-bot Bot commented Jul 11, 2026

Uh oh!

eliotheinrich left a comment

Choose a reason for hiding this comment

Uh oh!

eliotheinrich Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

eliotheinrich Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

eliotheinrich Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

eliotheinrich Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

eliotheinrich Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

eliotheinrich Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

jolle-ag commented Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kvmto commented Jul 7, 2026 •

edited

Loading