Rebase realtime_decoding_demo onto the refactored surface_code-1 app

Replace the example source with the surface_code-1.cpp from #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>

Author: cketcham2333

.github/workflows/lib_qec.yaml

@@ -164,8 +164,7 @@ jobs:
             --install-prefix "$HOME/.cudaqx" \
             --cudaq-prefix /cudaq-install \
             --realtime-lib-dir "$RT" \
-            --example-build-dir /tmp/rtdemo-build \
-            --num-shots 50
+            --example-build-dir /tmp/rtdemo-build
 
       # ========================================================================
       # Upload build artifacts for GPU tests
@@ -175,8 +174,6 @@ jobs:
           tar czf /tmp/qec-build-artifacts.tar.gz \
             /cudaq-install \
             /tmp/cudaq-realtime \
-            "$HOME/.cudaqx" \
-            /tmp/rtdemo-build \
             $GITHUB_WORKSPACE/libs/qec/unittests/decoders/realtime/data \
             $GITHUB_WORKSPACE/${{ steps.build.outputs.build-dir }}
 
@@ -274,29 +271,6 @@ jobs:
           PYTHONPATH="/cudaq-install:$GITHUB_WORKSPACE/build_qec/python" \
             pytest -v libs/qec/python/tests/
 
-      # ========================================================================
-      # Realtime decoding demo: trt_decoder THROUGH the decoding server over UDP.
-      # This is the only CI coverage of trt_decoder via the decoding server (the
-      # TRTDecoder unit tests exercise the decoder standalone, not the server).
-      # Reuses the example binaries + SDK install prebuilt in build-and-test
-      # (from the artifact). Needs a GPU (TensorRT inference runs server-side)
-      # plus python onnx (the script generates the identity predecoder model).
-      # Gated on TensorRT availability, matching the TensorRT installs above.
-      # ========================================================================
-      - name: Realtime decoding demo (trt_decoder, qpu-kernel over UDP)
-        if: matrix.platform != 'arm64' || !startsWith(matrix.cuda_version, '12')
-        shell: bash
-        run: |
-          pip install onnx
-          RT="${CUDAQ_REALTIME_ROOT:-/tmp/cudaq-realtime}"
-          bash docs/sphinx/examples/qec/realtime_decoding_demo/run_realtime_decoding.sh \
-            --source qpu-kernel --decoder trt_decoder \
-            --install-prefix "$HOME/.cudaqx" \
-            --cudaq-prefix /cudaq-install \
-            --realtime-lib-dir "$RT" \
-            --example-build-dir /tmp/rtdemo-build \
-            --num-shots 50
-
   # ==========================================================================
   # Multi-GPU tests - decoder placement across >= 2 GPUs (uses build artifacts
   # from build-and-test).

docs/sphinx/examples/qec/realtime_decoding_demo/CMakeLists.txt

@@ -131,7 +131,8 @@ set_target_properties(surface_code_realtime_decoding PROPERTIES LINKER_LANGUAGE
 # DT_NEEDED and the process would crash at startup with no platform.
 target_link_libraries(surface_code_realtime_decoding PRIVATE
   -Wl,--no-as-needed
-  cudaq-qec cudaq-qec-realtime-decoding-simulation ${_cudaq_core_libs}
+  cudaq-qec cudaq-qec-realtime-decoding
+  cudaq-qec-realtime-decoding-simulation ${_cudaq_core_libs}
   -Wl,--as-needed
   "${CUDAQ_REALTIME_DISPATCH_LIB}")
 target_link_options(surface_code_realtime_decoding PRIVATE
@@ -143,7 +144,7 @@ target_link_options(surface_code_realtime_decoding PRIVATE
 # (nvcc -dlink) that resolves the dispatch archive's RDC registration symbols.
 # ---------------------------------------------------------------------------- #
 _add_nvqpp_object(_cqr_obj generator-cqr
-  --target stim -frealtime-lowering -DQEC_APP_EXTERNAL_DECODING_SERVER)
+  --target stim -frealtime-lowering -DQEC_APP_CQR)
 add_executable(surface_code_realtime_decoding-cqr "${_cqr_obj}")
 set_target_properties(surface_code_realtime_decoding-cqr PROPERTIES
   CUDA_SEPARABLE_COMPILATION ON
@@ -152,7 +153,13 @@ set_target_properties(surface_code_realtime_decoding-cqr PROPERTIES
   LINKER_LANGUAGE CUDA)
 target_link_libraries(surface_code_realtime_decoding-cqr PRIVATE
   -Wl,--no-as-needed
-  cudaq-qec cudaq-qec-realtime-decoding-simulation-cqr cudaq-device-call-runtime
+  cudaq-qec cudaq-qec-realtime-decoding
+  cudaq-qec-realtime-decoding-simulation-cqr
+  # The in-process decoding service; also exports
+  # cudaqx_qec_device_call_dispatch_count, which the app prints as evidence
+  # that an external server (not the in-process service) did the decoding.
+  cudaq-qec-realtime-decoding-server-cqr
+  cudaq-device-call-runtime
   ${_cudaq_core_libs}
   -Wl,--as-needed
   "${CUDAQ_REALTIME_DISPATCH_LIB}" CUDA::cudart)

docs/sphinx/examples/qec/realtime_decoding_demo/README.md

@@ -46,27 +46,29 @@ toolchain; override the device-link architecture with
 
 ```bash
 ./run_realtime_decoding.sh --source qpu-kernel --decoder pymatching        --install-prefix <prefix>
-./run_realtime_decoding.sh --source qpu-kernel --decoder trt_decoder       --install-prefix <prefix>
+./run_realtime_decoding.sh --source qpu-kernel --decoder multi_error_lut   --install-prefix <prefix>
 ./run_realtime_decoding.sh --source qpu-kernel --decoder nv-qldpc-decoder --gpu 0 --install-prefix <prefix>
 ```
 
 The lowered kernel runs the surface-code memory experiment and streams each
 shot's syndromes to the server over UDP; the server decodes and returns
-corrections. No NIC, no FPGA, no network setup.
+corrections. No NIC, no FPGA, no network setup. Runs are seeded (`--seed`,
+default 42), so the reported counts are reproducible.
 
-PASS/FAIL uses the same criteria as the in-tree surface_code-4 tests: the run
+PASS/FAIL uses the same criteria as the in-tree surface-code tests: the run
 must complete without decoder errors, the residual logical-error count must
 stay at or under `num_shots/50` (a decoder that is connected but decoding
-wrong produces far more), the kernel must report server-owned decoders, and
-the server must have dispatched at least `num_shots * (num_rounds + 3)` RPCs.
+wrong produces far more), the kernel's in-process dispatch count must be 0
+(proof the decode stayed in the external server), and the server must have
+dispatched at least `num_shots * (num_rounds + 3)` RPCs.
 
 ### FPGA source (real FPGA; needs a ConnectX NIC)
 
 ```bash
 ./run_realtime_decoding.sh --source fpga --decoder pymatching \
     --setup-network --device <nic> --bridge-ip <host-ip> --fpga-ip <fpga-ip> \
     --install-prefix <prefix>
-#   --decoder trt_decoder / --decoder nv-qldpc-decoder --gpu 0 likewise
+#   --decoder multi_error_lut / --decoder nv-qldpc-decoder --gpu 0 likewise
 ```
 
 The delivered playback tool streams pre-generated syndromes over RoCE from the
@@ -80,14 +82,11 @@ testing lives in the unittests `hsb_fpga_decoding_server_test.sh`.)
 | decoder | qpu-kernel (UDP) | fpga (real FPGA) | extra requirement |
 |---|---|---|---|
 | `pymatching` | CPU, no hardware | NIC | none |
-| `trt_decoder` | GPU (server-side TensorRT) | NIC + GPU | python `onnx` + GPU |
+| `multi_error_lut` | CPU, no hardware | NIC | none |
 | `nv-qldpc-decoder` | GPU (host-call path) | NIC + GPU (device path) | plugin + `--gpu` |
 
 - **`pymatching`** — CPU matching decoder; nothing extra.
-- **`trt_decoder`** — a TensorRT predecoder feeding a PyMatching global decoder.
-  TensorRT inference runs server-side on a GPU (both sources). The script
-  generates a tiny identity-predecoder ONNX at runtime (needs the python
-  `onnx` module); override with `--onnx <model>`.
+- **`multi_error_lut`** — CPU lookup-table decoder; nothing extra.
 - **`nv-qldpc-decoder`** — GPU relay-BP. Needs the prebuilt plugin
   (auto-found in the install prefix, else pass `--nv-qldpc-plugin <path.so>`)
   and a GPU selected with `--gpu <id>`. If the plugin is unavailable the script