Skip to content

[Docs] Task Graph and Dynamic DEM documentation rewrite - #907

Merged
melody-ren merged 15 commits into
NVIDIA:mainfrom
tlshannon:task_graph_docs
Nov 6, 2026
Merged

[Docs] Task Graph and Dynamic DEM documentation rewrite#907
melody-ren merged 15 commits into
NVIDIA:mainfrom
tlshannon:task_graph_docs

Conversation

@tlshannon

@tlshannon tlshannon commented Nov 3, 2026

Copy link
Copy Markdown
Collaborator

Summary

Rewrites the decoding task graph docs from the user's point of view, adds a page for parallel-window decoding and a reference page, and trims the dynamic DEM docs to the dem_chunks model format. Interfaces that the cudaq-edem library and its composer will replace are either labelled provisional or left out of the API reference.

Task graphs

  • Decoding Task Graphs (rewritten user guide): a sliding-window quick start, complete shots, streaming with a FINAL round, reading streaming_result(), multi-node graphs, node kinds, guarded windows and async streaming.
  • Task Graph Parallel Window (new): how the A and B layers commit rounds, model requirements, configuration, building in code, decoding a shot, serving through the decoding server, and the graph the pattern builds.
  • Task Graph Reference (new): async options and defaults, fire pools, streaming results, staged outputs, edge values, native streaming nodes, arbitrary-length sliding windows and ensembles.
  • Figures: block diagrams in assets/docs/.
  • Examples: a parallel_window YAML and its written-out form, plus Python and C++ examples. The existing example's streaming section now ends the shot with FINAL.
  • Provisional labels: a shared warning marks the windows: requests, data_artifacts and the non-spec parallel-window options. The experimental window types and data_artifact are removed from the C++ API reference.
  • Python API: adds the missing TaskGraph* classes.

Dynamic DEM

  • Page: the Dynamic DEM page documents only the dem_chunks format, which the EDEM chunk adapter will accept.
  • Removed from the docs: the CSS-matrix model builders and the chunk tools (stitch, close, merge and maps). They hadn't shipped in a release; the code is unchanged.
  • Examples: they now build a DemChunksSpec and decode a shot.

Testing

  • The Sphinx build passes with warnings treated as errors.
  • A new unittest, DocsExamples.ParallelWindowYamlMatchesItsLowering, checks that the two YAMLs build identical windows. It also checks that every single data-qubit flip in shots up to 40 rounds gets the correct correction from both graphs.
  • The task_graph_parallel_window, decoding_task_graph and dyn_dem examples (Python and C++) run and check their results. scripts/ci/test_examples.sh picks them up.
  • The YAML snippets in the user guide parse and configure without warnings.

@tlshannon
[Docs] Rewrite the decoding task graph docs and add parallel-window p…
840893d 
…ages

Rewrite the task graph user guide around the minimal user path, and add
two pages: "Task Graph Parallel Window" and a "Task Graph Reference" for
execution details.

- User guide: sliding-window quick start, complete shots, streaming with
  a FINAL round, reading streaming results, multi-node graphs, node kinds,
  guarded windows, and async streaming.
- Parallel window: how layers A and B commit rounds, model requirements,
  configuration, building in code, decoding a shot, serving through the
  decoding server, and the graph the pattern builds.
- Reference: async options and defaults, fire pools, streaming results,
  staged outputs, edge values, native streaming nodes, arbitrary-length
  sliding windows, and ensembles.
- Add block diagrams under assets/docs, a parallel_window YAML and its
  lowered form, and Python and C++ examples. A new test,
  DocsExamples.ParallelWindowYamlMatchesItsLowering, checks that the two
  YAMLs build the same windows and decode every single-qubit flip
  correctly.
- Label the window requests, data_artifacts and the non-spec
  parallel-window options as provisional; cudaq-edem will replace them.
  Remove the experimental window types and data_artifact from the C++ API
  reference.
- Fix the existing example's streaming section to end the shot with FINAL
  and read streaming_result(), and its per-round measurement count.
- Add the missing task-graph classes to the Python API reference.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
[Docs] Trim the dynamic DEM docs to the dem_chunks model format
7c285b3 
The dem_chunks model format stays when task graphs move to cudaq-edem:
the EDEM library's chunk adapter accepts it. The tools that build models
out of chunks do not: cudaq-edem and its composer replace them. Document
only the format.

- Rewrite the Dynamic DEM page: phases and connections, seam_specs
  (prev_round and next_round rows), the H_sparse shorthand, num_rounds,
  and the optional D_sparse, m2o_sparse and observable_names fields. The
  model comes from the tested parallel-window YAML.
- Replace the dyn_dem Python and C++ examples: build the model as a
  DemChunksSpec and decode a shot with PyMatching. Both exit non-zero on
  a wrong correction.
- Keep the spec types, SeamId, seam_name, phase_name and
  memory_dem_chunks_from_decoder_inputs in the API references. Remove the
  CSS-matrix functions, ExtendedDem, stitch/close/merge,
  PriorCombineMode, the unique-column checks, the dem_chunks_to_* maps and
  the compact chain forms. The code is unchanged.
- Shorten the decoders guide section to a pointer, and ignore the doxygen
  links that now point at functions left out of the docs.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
tlshannon marked this pull request as ready for review November 3, 2026 17:23
@tlshannon tlshannon changed the title [Docs] Task graph and dynamic DEM documentation rewrite [Docs] Task Graph and Dynamic DEM documentation rewrite Nov 3, 2026
@tlshannon
Merge remote-tracking branch 'origin/main' into task_graph_docs
1b2e818 
Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
[Docs] Describe staged coverage and mixed-width streaming from NVIDIA…
f84b24c 
…#898

Staged coverage now starts where clear_corrections() last consumed the
value, and a streaming node can stream rounds of different widths when
its decoder implements streaming_correction_provider.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
Merge remote-tracking branch 'origin/main' into task_graph_docs
59603c0 
Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
[Docs] Document logical measurements in the task graph docs
298bd22 
Bring in NVIDIA#906's get_logical_measurements across the task graph pages.
The example model now ends with a data-qubit readout and uses
output: corrections_and_logical, so both results are shown and tested.
Also drop the async closure caveat now that NVIDIA#912 is merged.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@bmhowe23
bmhowe23 requested a review from justinlietz November 4, 2026 22:32
@tlshannon
[Docs] Fix task graph doc details found in audit
b9897f4 
Correct the async enqueue_syndrome return value and the YAML mapping
of decoder_type, mark C++-only helpers, and say when
get_logical_measurements reads are refused or consume the shot.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon tlshannon mentioned this pull request Nov 5, 2026
Open
18 tasks
@tlshannon
[Docs] Set the quick-start window size explicitly
0378820 
The quick start said a streaming graph decodes once per round. It
decodes only after its 3-round window fills, then once per round.
Write the quick-start YAML as one node with window_size and
step_size, point fixed-length shots to single_window, say which
window from_spec picks, and fix the same claim in the example
comments.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
[Docs] Show a predecoder pipeline in the first task graph figure
865b645 
The guide's first figure XORed two decoder nodes named x and z, which
read as adding corrections to unrelated observables. It now shows a
predecoder that passes the detectors it did not explain to a global
decoder, with an xor adding both nodes' corrections to the same
observables. The figure labels each edge with what it carries rather
than the xor's port names.

The figure's YAML moves to a file that a new test loads, streams and
checks. The reference page now points to the figure instead of
repeating the same edges, and a test comment no longer says the docs
show the x/z graph.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
Merge remote-tracking branch 'origin/main' into task_graph_docs
1b9bceb 
Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
tlshannon enabled auto-merge (squash) November 6, 2026 18:13
@tlshannon
Merge remote-tracking branch 'origin/main' into task_graph_docs
26a2d06 
Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
[Docs] Document committed-round coverage for native streaming nodes
1f287b7 
Native streaming nodes now report only the rounds their decoder has
committed (NVIDIA#926). The reference page says when such a node publishes,
what FINAL and a shot the decoder ends itself cover, and that several
such nodes may feed one output. It drops the old claim that they
cannot, and says when an output's generation advances with them.

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
Merge branch 'task_graph_docs' of https://github.com/tlshannon/cudaqx …
4dd510d 
…into task_graph_docs

Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@tlshannon
Merge remote-tracking branch 'origin/main' into task_graph_docs
6ca8220 
Signed-off-by: Tracy Shannon <tshannon@nvidia.com>
@melody-ren
melody-ren disabled auto-merge November 6, 2026 21:21
@melody-ren
melody-ren merged commit 0c6e793 into NVIDIA:main Nov 6, 2026
63 checks passed
melody-ren added a commit to eliotheinrich/cudaq-qec that referenced this pull request Nov 6, 2026
@melody-ren
Merge main into ensemble documentation branch
4a6a766 
Resolve the documentation conflicts after PR NVIDIA#907 was squash-merged.
Keep the ensemble API entries, navigation, and dedicated guide while
retaining main's corrected native-streaming coverage documentation.

Apply repository formatting to the changed Python configuration line
and remove trailing whitespace from the ensemble guide.

Signed-off-by: Melody Ren <melodyr@nvidia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@justinlietz justinlietz justinlietz approved these changes

Assignees

No one assigned

Labels

releases/v0.9.0

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@tlshannon @justinlietz @bmhowe23 @melody-ren