docs(cookbook): Add section on generating data for realtime predecoder

bmhowe23 · bmhowe23 · commit 3ce4379fa6cf · 2026-04-12T18:12:05.000-07:00
Signed-off-by: Ben Howe &lt;bhowe@nvidia.com&gt;
diff --git a/cookbook/predecoder.ipynb b/cookbook/predecoder.ipynb
@@ -1063,6 +1063,54 @@
     "\n",
     "# Load a pre-built engine file:\n",
     "ONNX_WORKFLOW=3 WORKFLOW=inference bash code/scripts/local_run.sh\n",
+    "```\n",
+    "\n",
+    "### Generating data for CUDA-Q QEC realtime predecoder test application\n",
+    "\n",
+    "When evaluating the neural pre-decoder in an end-to-end downstream system like\n",
+    "CUDA-Q Realtime, you will need a test harness with valid inputs—both the\n",
+    "exported neural network model and the corresponding syndrome data.\n",
+    "\n",
+    "The utility script `code/export/generate_test_data.py` is provided to generate\n",
+    "this exact data (both an `.onnx` file and several `.bin` files) so you can\n",
+    "easily consume it in the CUDA-Q QEC realtime AI decoder.\n",
+    "\n",
+    "> **Important:** The `--distance` and `--n-rounds` arguments provided to this\n",
+    "script **must match** the values used in the preceding section when running the\n",
+    "ONNX export (e.g. `ONNX_WORKFLOW=2`).\n",
+    "\n",
+    "For a detailed walkthrough on how to ingest these files into the CUDA-Q Realtime\n",
+    "C++ pipeline, see the downstream documentation here: [Realtime AI Predecoder\n",
+    "Pipeline](https://nvidia.github.io/cudaqx/examples_rst/qec/realtime_predecoder_pymatching.html).\n",
+    "\n",
+    "```text\n",
+    "python3 code/export/generate_test_data.py --distance 13 --n-rounds 104 --num-samples 10000 --basis X --p-error=0.003 --simple-noise\n",
+    "```\n",
+    "\n",
+    "**Example output:**\n",
+    "\n",
+    "```text\n",
+    "Building circuit: D=13, T=104, basis=X, rotation=XV, p=0.003\n",
+    "  Circuit built in 0.007s\n",
+    "Building detector error model and PyMatching matcher...\n",
+    "  DEM + matcher built in 0.083s\n",
+    "  Detectors: 17472, Observables: 1\n",
+    "Extracting check matrices (beliefmatching)...\n",
+    "  H shape: (17472, 93864), O shape: (1, 93864), priors shape: (93864,)\n",
+    "Sampling 10000 shots...\n",
+    "  Sampled in 1.006s\n",
+    "Decoding with PyMatching (baseline)...\n",
+    "  Errors: 30/10000, LER: 0.0030\n",
+    "  Decode time: 5.439s (543.9 µs/shot)\n",
+    "Writing outputs to test_data/d13_T104_X/\n",
+    "Done.\n",
+    "  H_csr.bin                           808,944 bytes\n",
+    "  O_csr.bin                             2,932 bytes\n",
+    "  detectors.bin                   698,880,008 bytes\n",
+    "  metadata.txt                            162 bytes\n",
+    "  observables.bin                      40,008 bytes\n",
+    "  priors.bin                          750,916 bytes\n",
+    "  pymatching_predictions.bin           40,008 bytes\n",
     "```"
    ]
   },
