docs(qec): document Decoding Server deployment with Docker

docs/sphinx/components/qec/decoders.rst

@@ -133,6 +133,8 @@ basis; composition infrastructure uses ``decoder_output_request`` to request
 standardized auxiliary outputs from a compatible decoder. See the PyMatching
 API for the migration from its former ``O``-implies-observables behavior.
 
+.. _qec-custom-decoder:
+
 Implementing a New Decoder in C++
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/sphinx/components/qec/index.rst

@@ -18,6 +18,9 @@ These types are meant to be extended by developers to provide new error correcti
 
 The pages below document each of these interfaces in depth — the abstraction, how to extend it, and what ships built in. For runnable, copy-pasteable programs, see the :doc:`CUDA-Q QEC examples </examples_rst/qec/examples>`.
 
+For configuration, client integration and examples, see the
+:doc:`Decoding Server User Guide </examples_rst/qec/decoding_server>`.
+
 .. toctree::
    :maxdepth: 2
 

docs/sphinx/components/qec/realtime_decoding.rst

@@ -118,6 +118,7 @@ partial output file, which must be removed before retrying.
 See Also
 ^^^^^^^^
 
+* :doc:`Decoding Server User Guide </examples_rst/qec/decoding_server>`: configuration, playback and client integration
 * :ref:`Pre-built QEC Decoders <prebuilt_qec_decoders>` — decoders available for realtime use
 * :doc:`Realtime Decoding examples </examples_rst/qec/realtime_decoding>` — runnable end-to-end examples
 * :doc:`Playback Emulator </examples_rst/qec/playback_emulator>` — replay timed decoder calls without a QPU

docs/sphinx/examples/qec/color_code_demo/color_code_demo.py

@@ -92,6 +92,8 @@
 
 # Shots in flight: shot i starts once shot i - DEPTH has its correction.
 DEPTH = 4
+# Playback requires a positive tick duration; use one microsecond.
+PLAYBACK_TICK_NS = 1000
 MEASURE_OPS = {"M", "MZ", "MX", "MY", "MR", "MRX", "MRY", "MRZ"}
 
 
@@ -244,12 +246,12 @@ def per_round(ler, rounds):
 
 def run_checked(schedule, shots, **session):
     """Runs `schedule`; fails unless every shot returned its correction."""
-    result = pb.run(schedule, tick_ns=0, sources={}, **session)
-    gc = [r for r in result.records if r.op == pb.operation.get_corrections]
+    result = pb.run(schedule, tick_ns=PLAYBACK_TICK_NS, sources={}, **session)
+    records = result.records
+    gc = [r for r in records if r["op"] == "get_corrections"]
     bad = [
-        str(r.status)
-        for r in gc
-        if str(r.status) != "OK" or r.correction_count == 0
+        str(r["status"]) for r in gc if r["status"] != 0 or
+        not r["read_completed"] or not r["correction_bits"]
     ]
     if len(gc) != shots or bad:
         raise RuntimeError("%d/%d corrections returned, failures: %s" %
@@ -320,8 +322,8 @@ def run_session(name, mdc, schedule, shots):
             # Runtime per round: the time until the last reply, divided by
             # the rounds decoded.
             runtime = max(
-                r.return_ns for r in result.records) / 1e3 / args.shots / d
-            errors = sum(r.correction_mismatch for r in gc)
+                r["return_ns"] for r in result.records) / 1e3 / args.shots / d
+            errors = sum(r["correction_mismatch"] for r in gc)
             # Per-round rate from the d-round rate, with a binomial error
             # bar.
             total = min(max(errors / args.shots, 0.5 / args.shots), 1 - 1e-12)

docs/sphinx/examples/qec/decoding_server/memory_schedule.txt

@@ -0,0 +1,6 @@
+# Synthetic distance-3 Z-memory smoke test: 26 extraction rounds plus readout.
+# Not sampled circuit data or an accuracy/performance benchmark.
+0 reset
+1 stream source=0b00000000 rounds=26 every=1
+- enqueue_data source=0b000000000
+- get_corrections 0 return_size=1

docs/sphinx/examples_rst/qec/color_code_demo.rst

@@ -24,7 +24,11 @@ once per path between the emulator and the decoder (``session``):
    :doc:`/examples_rst/qec/realtime_decoding_demo` serves the surface-code Ising
    predecoder from ``decoding_server``, with syndromes sourced from a QPU kernel or an
    FPGA. Here, the playback emulator replays the pre-sampled shots of the superdense color-code
-   memory circuit to every the decoder on a fixed timing loop using the playback emulator.
+   memory circuit to each decoder on a fixed timing loop.
+
+   For starting the prebuilt Docker server and connecting clients, see
+   :ref:`decoding-server-color-code`. The model preparation and benchmark on
+   this page require the software listed below.
 
 Prerequisites
 -------------
@@ -84,14 +88,18 @@ records:
 - The LER per round: the fraction of shots whose correction differs from
   Stim's true observable flip, converted to a per-round rate.
 
-In the figure, grey is raw Chromobius and green is the Ising predecoder.
+The generated figure uses grey for Chromobius and green for the Ising
+predecoder. Points with no logical errors are not drawn. The figure below
+shows example output from an earlier run with 100,000 shots per distance at
+:math:`p = 0.001`.
 
 .. image:: ../../../../assets/docs/color_code_demo.png
    :align: center
-   :alt: Logical error rate per round versus runtime per round for raw Chromobius and the Ising predecoder, for distances 5 to 13, in process and over UDP
+   :alt: Example logical error rate per round versus runtime per round for Chromobius and the Ising predecoder, for distances 5 to 13, in process and over UDP
 
-The figure above is from a run with the default options (100,000 shots per
-distance at :math:`p = 0.001`). Points with no logical errors are not drawn.
+Current runs use one-microsecond ticks; reported runtime includes scheduling,
+transport, and decoding. Use the figure generated by your run when comparing
+configurations.
 
 The example source
 ------------------