Surface code demo 1 refactor by eliotheinrich · Pull Request #685 · NVIDIA/cudaqx

eliotheinrich · 2026-07-13T14:20:54Z

Description

This PR updates the surface code demo (/libs/qec/unittests/realtime/app_examples/surface_code-1.cpp) to use the new syndrome format and decoder context objects. Semantically, the demo should remain very similar to the original version, but I have aimed to remove the hand-rolled sections and replace them with CUDA-QX features as much as possible. I have also refactored for readability.

Notes for reviewers

The return format of the entry QPU kernel changed; now, the low 32 bits correspond to the values of the logical qubits, and the high 32 bits correspond to the total number of corrections applied by the decoders during the shot. The test can therefore now accommodate up to 32 logical qubits with no restrictions on distance.

Stationary window removed; now either monolithic decoding or sliding window. See the performance note below.

Depends on #656 and #671.

Runtime / performance impact

The removal of the stationary decoding window affected some multi-error-lut tests, as the LUT tables were too large. In particular, I had to reduce the number of rounds in the surface-code-1-quantinuum distance=5 test, although it still represents a performance regression on it and some similar tests. I'm open to re-introducing the decoder window if we want to keep that functionality, but as it doesn't represent a proper decoding flow, I prefer to remove it.

Self-review checklist

Please confirm each item before requesting review. Check [x] or strike
through and explain.

Before requesting review

I reviewed my own full diff in GitHub or my editor.
PR is in Draft if it is not yet ready for review.
Temporary / debugging changes have been removed.
Local test logs reviewed; no unexplained warnings or errors.
CI logs reviewed; no unexplained warnings or errors.
Full CI has been run.

Scope and size

PR is under ~1000 lines, or an exception is justified in the description.
Refactoring-only changes are isolated in their own PR(s).
No existing tests were disabled or modified just to make this PR pass
(if so, an issue has been raised).

Tests

New functionality has new tests.
Tests fail if the new functionality is broken (including crashes), not
just when it is missing.
Negative tests added where exceptions are expected.
Truth data added where simple EXPECT_* / assert checks are
insufficient for algorithmic correctness.
CI runtime impact considered; team notified if significant.

Documentation

Public-facing APIs have Doxygen docs.
User-visible behavior changes have public docs, or a follow-up is
tracked.

Code style

Naming follows the existing convention (snake_case vs camelCase) for
the area being modified.

Dependencies

No new third-party dependencies, or the team has been notified and
OSRB tickets filed.

copy-pr-bot · 2026-07-13T14:20:57Z

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.

Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com>

eliotheinrich · 2026-07-16T18:29:29Z

/ok to test 4b79350

melody-ren

Thanks @eliotheinrich! I think there's a python counter part to this example which should also be updated. But that can come in a follow up to move things along quicker

…D decoding Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com>

bmhowe23

This is gonna be great. I have 1 nit and 1 +1 on one of Melody's comments.

Note: I think GitHub is still showing my BP+OSD comment; I tried to delete it, but I started to make the comment and then didn't hit submit, and now that section of code is gone (good), so just ignore that one.

Signed-off-by: Ben Howe <bhowe@nvidia.com>

bmhowe23 · 2026-07-16T23:51:19Z

/ok to test e63925a

Replace the example source with the surface_code-1.cpp from NVIDIA#685 (new syndrome format, decoder_context_from_memory_circuit, seeded runs) and adapt the driver script, build, docs, and CI to its interface. The example copy differs from the in-tree file only in the header comment, the usage line, and the --save_syndrome capture, which now emits true-width groups (the packed bytes are byte-padded; the FPGA playback tool sets each replayed frame's num_syndromes from the group's line count, and the decoder's per-shot measurement capacity is the exact sum, so padded groups overran it). - run_realtime_decoding.sh: --p-cnot replaces --p-spam (two-qubit depolarizing on the CNOTs, default 0.001); new --seed (default 42 -- runs and pass/fail counts are reproducible); config/kernel phases use --save_dem / --load_dem; the kernel needs only QEC_DECODING_SERVER_PORT (the app brings up the udp channel itself in its QEC_APP_CQR build). Decoders: pymatching, nv-qldpc-decoder, multi_error_lut (trt_decoder is not supported by the new app and is dropped; sliding_window exists in the app but is not exposed -- over device calls it needs matching updates to the proprietary cudevice archive). - Pass/fail criteria keep the surface-code test checks (hard decoder-failure greps, corrections-line completion proof, num_shots/50 residual ceiling, num_shots*(num_rounds+3) server dispatch floor) and adopt the two-process test's server-ownership proof: the app's in-process dispatch count must be 0. - CMakeLists.txt: -DQEC_APP_CQR; link cudaq-qec-realtime-decoding + cudaq-qec-realtime-decoding-server-cqr (exports the dispatch-count symbol). - Docs: decoder tables/text updated (3 decoders, --p-cnot/--seed, criteria); the FPGA-predecoder page's pointer at this example is removed (trt dropped). - CI (lib_qec.yaml): the gpu-test trt step and its artifact plumbing are removed (trt dropped); the CPU job's pymatching decode now runs the seeded 200-shot default, making the ceiling check deterministic (the 50-shot unseeded run could statistically exceed a ceiling of 1 -- the amd64-12.6 failure on the previous run). Signed-off-by: Chuck Ketcham <cketcham@nvidia.com>

This PR is a follow-up to #685, addressing the issues in #704 as well as adding a few new CLI args. These new args are purely additive, so this PR should otherwise have identical behavior on the happy paths of #685. --------- Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com> Co-authored-by: Ben Howe <141149032+bmhowe23@users.noreply.github.com>

eliotheinrich closed this Jul 16, 2026

eliotheinrich force-pushed the pr-surface-code-demo branch from b0d6ec4 to 0859cc0 Compare July 16, 2026 18:14

Refactored surface-code-1 demo

4b79350

Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com>

eliotheinrich reopened this Jul 16, 2026

eliotheinrich marked this pull request as ready for review July 16, 2026 18:29

eliotheinrich requested review from bmhowe23, cketcham2333 and melody-ren July 16, 2026 18:30

melody-ren reviewed Jul 16, 2026

View reviewed changes

Addressed reviewer feedback, added pymatching decoding, removed BP+OS…

b191511

…D decoding Signed-off-by: Eliot Heinrich <eheinrich@nvidia.com>

bmhowe23 reviewed Jul 16, 2026

View reviewed changes

Comment thread libs/qec/unittests/realtime/app_examples/surface_code-1.cpp Outdated

Comment thread docs/sphinx/examples_rst/qec/realtime_relay_bp.rst

Comment thread libs/qec/unittests/realtime/app_examples/surface_code-1.cpp Outdated

bmhowe23 added 2 commits July 16, 2026 22:48

Merge branch 'main' into pr-surface-code-demo

1faa3ed

Use get_stabilizer_schedule_x/z and update comments

e63925a

Signed-off-by: Ben Howe <bhowe@nvidia.com>

bmhowe23 mentioned this pull request Jul 16, 2026

Followups for #685 #704

Open

3 tasks

bmhowe23 approved these changes Jul 16, 2026

View reviewed changes

bmhowe23 enabled auto-merge (squash) July 17, 2026 00:42

bmhowe23 merged commit 291aa7f into NVIDIA:main Jul 17, 2026
33 of 36 checks passed

cketcham2333 mentioned this pull request Jul 17, 2026

Add realtime_decoding_demo example: drive the delivered decoding server from an FPGA or a QPU kernel #703

Open

eliotheinrich mentioned this pull request Jul 20, 2026

Surface code 1 demo refactor followup #712

Merged

18 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Surface code demo 1 refactor#685

Surface code demo 1 refactor#685
bmhowe23 merged 4 commits into
NVIDIA:mainfrom
eliotheinrich:pr-surface-code-demo

eliotheinrich commented Jul 13, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Jul 13, 2026

Uh oh!

eliotheinrich commented Jul 16, 2026

Uh oh!

melody-ren left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmhowe23 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmhowe23 commented Jul 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

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

Uh oh!

Description

Notes for reviewers

Runtime / performance impact

Self-review checklist

Before requesting review

Scope and size

Tests

Documentation

Code style

Dependencies

Uh oh!

copy-pr-bot Bot commented Jul 13, 2026

Uh oh!

eliotheinrich commented Jul 16, 2026

Uh oh!

melody-ren left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmhowe23 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bmhowe23 commented Jul 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

eliotheinrich commented Jul 13, 2026 •

edited

Loading