Skip to content

Add triangular color code plugin with superdense memory circuit#658

Draft
kvmto wants to merge 2 commits into
NVIDIA:mainfrom
kvmto:color-code-plugin
Draft

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

Conversation

@kvmto

@kvmto kvmto commented Jul 7, 2026

Copy link
Copy Markdown
Collaborator

Description

Adds the triangular color code to CUDA-QX as a Python QEC code plugin, together with a superdense memory circuit built directly on CUDA-Q's detector annotations.

color_code plugin (plugins/codes/color_code.py):

  • ColorCodeGeometry: triangular color code with a rectangular-grid embedding (data-qubit grid, algorithmic plaquette generation, syndrome-to-grid mapping, physical circuit layout, superdense plaquette labeling), ported from an internal reference implementation.
  • CSS stabilizers/observables and patch-based prep0/prep1/prepp/prepm + stabilizer_round kernels, registered via @qec.code('color_code') (required option: distance, odd ≥ 3). Parity/observable matrices are provided through the standard code API (get_parity_x/z, get_observables_x/z).

Superdense memory circuit (same module):

  • The paired-ancilla, depth-8 CNOT schedule measures both stabilizer bases of every plaquette each round. The measurement feedforward of the superdense readout is absorbed analytically into explicit cudaq.detector / cudaq.logical_observable annotations, so the circuit is straight-line Clifford and cudaq.dem_from_kernel accepts it (stim's detector-determinism analysis passes, d ≤ 11 checked).
  • SuperdensePlan exposes the detector record layout and per-detector coordinates (including the color annotation scheme used by color-code decoders such as Chromobius) for upcoming decoder integration; superdense_dem / superdense_sample provide DEM extraction and detector-ordered sampling.

Validation

  • Geometry pinned against reference plaquette tables (d = 3/5/7) and structural invariants up to d = 13.
  • Detector/observable record sets pinned against literals extracted from the reference construction.
  • Golden-oracle test: the DEM of the CUDA-Q kernel is equivalent to the reference stim construction of the same circuit under matched noise — identical error mechanisms and probabilities, both memory bases (golden files under tests/data/).
  • Decoding sanity check (single_error_lut) shows the expected logical-error reduction.
  • 98 new test items, ~5 s wall clock on the stim target.

Notes for reviewers

  • ColorCodeGeometry.superdense_plaquette contains an intentional unreachable return kept for consistency with the reference implementation.
  • Framework-path E2E tests (qec.sample_memory_circuit on this plugin) are prepared but intentionally not included: Python-defined codes currently hit test_code.py::test_python_code disabled by #636 #646 (root cause upstream, fix validated locally against cuda-quantum#4861). They will follow once the CUDA-Q pin includes that fix.
  • Open question: whether the superdense functionality should stay in plugins/codes/ or move elsewhere / become framework-level API once test_code.py::test_python_code disabled by #636 #646 is resolved.

Status

Draft: decoder (Chromobius) integration on top of SuperdensePlan.detector_coords is planned as the next step.

kvmto added 2 commits July 7, 2026 18:16
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant