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

.github/workflows/lib_qec.yaml

@@ -135,6 +135,37 @@ jobs:
       - name: Run example tests
         run: bash scripts/ci/test_examples.sh qec
 
+      # ========================================================================
+      # Realtime decoding demo example
+      #
+      # Build the two example binaries against the INSTALLED SDK -- this is what
+      # enforces the installed-headers-only rule: a build-tree-only include
+      # would fail to compile here. Then drive the delivered decoding_server
+      # over UDP loopback with a real pymatching decode (the qpu-kernel source).
+      # No hardware: the FPGA source needs a ConnectX NIC and is not run in CI.
+      # ========================================================================
+      - name: Build & run realtime_decoding_demo (qpu-kernel, UDP loopback)
+        shell: bash
+        run: |
+          export PATH=/cudaq-install/bin:$PATH
+          # Mirror build_qec.sh: it builds+installs cudaq-realtime to
+          # $CUDAQ_REALTIME_ROOT, defaulting to /tmp/cudaq-realtime when unset
+          # (the case for this workflow). Track the same value so this step
+          # stays correct if the job ever sets CUDAQ_REALTIME_ROOT.
+          RT="${CUDAQ_REALTIME_ROOT:-/tmp/cudaq-realtime}"
+          EX=docs/sphinx/examples/qec/realtime_decoding_demo
+          cmake -S "$EX" -B /tmp/rtdemo-build -G Ninja \
+            -DCUDAQ_INSTALL_DIR=/cudaq-install \
+            -DCUDAQX_INSTALL_DIR="$HOME/.cudaqx" \
+            -DCUDAQ_REALTIME_DIR="$RT"
+          cmake --build /tmp/rtdemo-build -j
+          bash "$EX/run_realtime_decoding.sh" \
+            --source qpu-kernel --decoder pymatching \
+            --install-prefix "$HOME/.cudaqx" \
+            --cudaq-prefix /cudaq-install \
+            --realtime-lib-dir "$RT" \
+            --example-build-dir /tmp/rtdemo-build
+
       # ========================================================================
       # Upload build artifacts for GPU tests
       # ========================================================================

docs/sphinx/conf.py.in

@@ -93,7 +93,10 @@ master_doc = 'index'
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_templates']
+# Example-directory READMEs are for the shipped example tree (rendered on
+# GitHub), not standalone doc pages -- without this they are ingested via the
+# '.md' source suffix and warn as toctree orphans.
+exclude_patterns = ['_templates', 'examples/**/README.md']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 default_role = 'code'  # NOTE: the following may be a better choice to error on the side of flagging anything that is referenced but but not declared

docs/sphinx/examples/qec/realtime_decoding_demo/.gitignore

@@ -0,0 +1,2 @@
+# Build output (the two example binaries + CMake cache)
+build/

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

@@ -0,0 +1,167 @@
+# ============================================================================ #
+# Copyright (c) 2026 NVIDIA Corporation & Affiliates.                          #
+# All rights reserved.                                                         #
+#                                                                              #
+# This source code and the accompanying materials are made available under     #
+# the terms of the Apache License 2.0 which accompanies this distribution.     #
+# ============================================================================ #
+
+# Realtime-decoding example.
+#
+# This builds ONE source (surface_code_realtime_decoding.cpp) two ways, against
+# the *installed* CUDA-Q / CUDA-QX SDK -- nothing here reaches into a build tree:
+#
+#   surface_code_realtime_decoding       generator: --target stim; writes the
+#                                        decoder config + syndrome files.
+#   surface_code_realtime_decoding-cqr   lowered kernel: adds -frealtime-lowering
+#                                        -DQEC_APP_EXTERNAL_DECODING_SERVER; the
+#                                        live QPU kernel that streams syndromes to
+#                                        the delivered decoding_server over UDP.
+#
+# The decoding_server and the FPGA playback tool are DELIVERABLES (installed,
+# not built here); run_realtime_decoding.sh resolves them from --install-prefix.
+
+cmake_minimum_required(VERSION 3.23)
+
+# The lowered-kernel binary links the realtime dispatch archive (relocatable
+# CUDA device code), so the project enables CUDA and needs an architecture for
+# the device-link step. Default to 80 (A100) -- an architecture the shipped
+# SDK's dispatch archive includes; override to match your GPU, e.g.
+# -DCMAKE_CUDA_ARCHITECTURES=90 for Hopper / GB200.
+if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
+  set(CMAKE_CUDA_ARCHITECTURES 80)
+endif()
+
+project(realtime_decoding_demo LANGUAGES CXX CUDA)
+
+# ---------------------------------------------------------------------------- #
+# Locate the installed SDK.
+# ---------------------------------------------------------------------------- #
+# CUDA-Q: provides nvq++, cudaq/*.h, cudaq/realtime.h and the core runtime libs.
+if(NOT CUDAQ_INSTALL_DIR)
+  if(DEFINED ENV{CUDA_QUANTUM_PATH})
+    set(CUDAQ_INSTALL_DIR "$ENV{CUDA_QUANTUM_PATH}")
+  else()
+    set(CUDAQ_INSTALL_DIR "/usr/local/cudaq")
+  endif()
+endif()
+if(NOT EXISTS "${CUDAQ_INSTALL_DIR}/bin/nvq++")
+  message(FATAL_ERROR
+    "nvq++ not found under CUDAQ_INSTALL_DIR=${CUDAQ_INSTALL_DIR}. "
+    "Pass -DCUDAQ_INSTALL_DIR=<cuda-quantum install prefix>.")
+endif()
+
+# CUDA-QX: provides cudaq/qec/*.h and the QEC + realtime-decoding libs/plugins.
+if(NOT CUDAQX_INSTALL_DIR)
+  if(DEFINED ENV{CUDAQX_INSTALL_DIR})
+    set(CUDAQX_INSTALL_DIR "$ENV{CUDAQX_INSTALL_DIR}")
+  else()
+    message(FATAL_ERROR
+      "Set -DCUDAQX_INSTALL_DIR=<cuda-qx install prefix> (the directory that "
+      "holds include/cudaq/qec and lib/libcudaq-qec.so).")
+  endif()
+endif()
+if(NOT EXISTS "${CUDAQX_INSTALL_DIR}/include/cudaq/qec/code.h")
+  message(FATAL_ERROR
+    "CUDAQX_INSTALL_DIR=${CUDAQX_INSTALL_DIR} does not look like a CUDA-QX "
+    "install (missing include/cudaq/qec/code.h).")
+endif()
+
+set(NVQPP "${CUDAQ_INSTALL_DIR}/bin/nvq++")
+find_package(CUDAToolkit REQUIRED)
+
+# The realtime dispatch archive carries relocatable (RDC) device code, so the
+# -cqr executable must be linked with a CUDA device-link step (see below).
+find_library(CUDAQ_REALTIME_DISPATCH_LIB cudaq-realtime-dispatch
+  PATHS "${CUDAQ_INSTALL_DIR}" "${CUDAQ_REALTIME_DIR}" PATH_SUFFIXES lib REQUIRED)
+
+link_directories(
+  "${CUDAQX_INSTALL_DIR}/lib"
+  "${CUDAQX_INSTALL_DIR}/lib/decoder-plugins"
+  "${CUDAQ_INSTALL_DIR}/lib"
+  "${CUDAQ_INSTALL_DIR}/lib/plugins")
+
+set(_src "${CMAKE_CURRENT_SOURCE_DIR}/surface_code_realtime_decoding.cpp")
+
+# Only the CUDA-QX headers need an explicit -I; nvq++ already knows its own
+# CUDA-Q include dir (cudaq/*.h, cudaq/realtime.h, common/*.h).
+set(_nvqpp_includes "-I${CUDAQX_INSTALL_DIR}/include")
+
+# CUDA-Q core libraries, listed AFTER the qec + simulation libs on purpose.
+# The simulation backend's static initializer registers into a global map owned
+# by libcudaq-common; ELF runs initializers in reverse DT_NEEDED (link) order,
+# so the qec/simulation libs must be listed FIRST (they initialize last) and the
+# cudaq core libs LAST (they initialize first) or the registration dereferences
+# a not-yet-constructed map and segfaults at startup.
+set(_cudaq_core_libs
+  cudaq-mlir-runtime nvqir nvqir-stim
+  cudaq-qec-realtime-decoding cudaq-qec-decoders
+  cudaq cudaq-platform-default cudaq-em-default
+  cudaq-common cudaq-operator cudaq-logger)
+
+# ---------------------------------------------------------------------------- #
+# Helper: compile the source with nvq++ into an object, in an isolated working
+# directory (nvq++ drops intermediates named after the source, so two compiles
+# of the same file must not share a cwd).
+# ---------------------------------------------------------------------------- #
+function(_add_nvqpp_object out_var obj_name)
+  set(_obj "${CMAKE_CURRENT_BINARY_DIR}/${obj_name}.o")
+  set(_wd  "${CMAKE_CURRENT_BINARY_DIR}/${obj_name}.nvqpp")
+  file(MAKE_DIRECTORY "${_wd}")
+  add_custom_command(
+    OUTPUT "${_obj}"
+    COMMAND ${NVQPP} ${ARGN} -c -fPIC "${_src}" -o "${_obj}" ${_nvqpp_includes}
+    DEPENDS "${_src}"
+    WORKING_DIRECTORY "${_wd}"
+    COMMENT "Compiling surface_code_realtime_decoding.cpp with nvq++ (${obj_name})"
+    VERBATIM)
+  set_source_files_properties("${_obj}" PROPERTIES EXTERNAL_OBJECT TRUE GENERATED TRUE)
+  set(${out_var} "${_obj}" PARENT_SCOPE)
+endfunction()
+
+# ---------------------------------------------------------------------------- #
+# Generator (plain): writes the decoder config + syndrome files.
+# ---------------------------------------------------------------------------- #
+_add_nvqpp_object(_gen_obj generator --target stim)
+add_executable(surface_code_realtime_decoding "${_gen_obj}")
+set_target_properties(surface_code_realtime_decoding PROPERTIES LINKER_LANGUAGE CXX)
+# --no-as-needed: nvqir-stim (the --target stim simulator) and
+# cudaq-platform-default are pulled in at runtime by registration, not by a
+# direct symbol reference, so the default --as-needed would drop them from
+# 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
+  cudaq-qec-realtime-decoding-simulation ${_cudaq_core_libs}
+  -Wl,--as-needed
+  "${CUDAQ_REALTIME_DISPATCH_LIB}")
+target_link_options(surface_code_realtime_decoding PRIVATE
+  LINKER:--allow-shlib-undefined LINKER:--export-dynamic)
+
+# ---------------------------------------------------------------------------- #
+# Lowered kernel (-cqr): the live syndrome source over UDP.
+# LINKER_LANGUAGE CUDA + CUDA_RESOLVE_DEVICE_SYMBOLS runs the device-link
+# (nvcc -dlink) that resolves the dispatch archive's RDC registration symbols.
+# ---------------------------------------------------------------------------- #
+_add_nvqpp_object(_cqr_obj generator-cqr
+  --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
+  CUDA_RESOLVE_DEVICE_SYMBOLS ON
+  CUDA_STANDARD 17
+  LINKER_LANGUAGE CUDA)
+target_link_libraries(surface_code_realtime_decoding-cqr PRIVATE
+  -Wl,--no-as-needed
+  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)
+target_link_options(surface_code_realtime_decoding-cqr PRIVATE
+  LINKER:--allow-shlib-undefined LINKER:--export-dynamic)

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

@@ -0,0 +1,95 @@
+# Realtime decoding demo
+
+Drive the delivered `decoding_server` from two syndrome sources — a real FPGA,
+or a lowered QPU kernel — both decoding through the **same prebuilt server**.
+
+## What this example is
+
+- **Deliverables** (installed, *not* built here): `decoding_server`, the FPGA
+  playback tool `hololink_fpga_syndrome_playback`, the QEC + realtime libraries,
+  and the decoder plugins.
+- **The example** (the only thing you compile): one source,
+  `surface_code_realtime_decoding.cpp`, built two ways by `CMakeLists.txt`
+  against the **installed SDK** (installed headers/libs only):
+  - `surface_code_realtime_decoding` — the **generator** (`--target stim`):
+    writes the decoder config and, for the FPGA source, the syndrome file.
+  - `surface_code_realtime_decoding-cqr` — the **lowered kernel**
+    (`-frealtime-lowering`): the live syndrome source that streams to the server
+    over UDP.
+
+## Build (once)
+
+```bash
+cmake -S . -B build \
+  -DCUDAQ_INSTALL_DIR=<cuda-quantum install prefix> \
+  -DCUDAQX_INSTALL_DIR=<cuda-qx install prefix>
+cmake --build build
+# -> build/surface_code_realtime_decoding      (generator)
+# -> build/surface_code_realtime_decoding-cqr  (lowered kernel)
+```
+
+In a CUDA-QX container `CUDAQ_INSTALL_DIR` defaults to `/usr/local/cudaq` (or
+`$CUDA_QUANTUM_PATH`); point `CUDAQX_INSTALL_DIR` at where the CUDA-QX SDK is
+installed. If the realtime libraries live in a separate prefix, add
+`-DCUDAQ_REALTIME_DIR=<realtime prefix>`. The lowered kernel links the realtime
+dispatch archive (relocatable CUDA device code), so the build needs a CUDA
+toolchain; override the device-link architecture with
+`-DCMAKE_CUDA_ARCHITECTURES=90` (default `80`) to match your GPU.
+
+## Run
+
+`run_realtime_decoding.sh` resolves the deliverables from `--install-prefix`
+(`$PREFIX/bin`, `$PREFIX/lib`) and the two example binaries from
+`--example-build-dir` (default `./build`).
+
+### QPU-kernel source (software, UDP, no NIC)
+
+```bash
+./run_realtime_decoding.sh --source qpu-kernel --decoder pymatching        --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. Runs are seeded (`--seed`,
+default 42), so the reported counts are reproducible.
+
+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'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 multi_error_lut / --decoder nv-qldpc-decoder --gpu 0 likewise
+```
+
+The delivered playback tool streams pre-generated syndromes over RoCE from the
+FPGA into the server's RDMA RX ring. `--spacing` (default 10 µs) paces the
+playback so it does not overrun the FPGA's fixed 64-slot ring. There is **no
+emulator** in this example — `--source fpga` requires a real FPGA. (Emulator
+testing lives in the unittests `hsb_fpga_decoding_server_test.sh`.)
+
+## Decoders
+
+| decoder | qpu-kernel (UDP) | fpga (real FPGA) | extra requirement |
+|---|---|---|---|
+| `pymatching` | CPU, no hardware | NIC | none |
+| `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.
+- **`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
+  exits `77` (skip).
+
+See `./run_realtime_decoding.sh --help` for the full option list.