Task Graph Reference
Details of task-graph execution, for tuning and for writing new node kinds. Start with Decoding Task Graphs.
Asynchronous streaming options
Set these in the task_graph block, or on
TaskGraphOptions in code. The other options apply only
with async_streaming, and each graph gets threads of its own.
Option |
Meaning |
|---|---|
|
|
|
Worker threads that decode. Default: enough for everything that may
decode at once (independent branches and |
|
CPUs to pin the workers to, one worker per CPU (Linux). With fewer CPUs than workers, the pool shrinks to match. Default: none. |
|
CPU to pin the thread that schedules decodes to (Linux). Default
|
|
How long an idle coordinator polls before it sleeps. Default |
|
Records that may be queued or decoding before |
Each
enqueue_syndromecall is queued as a record; a windowed graph may split a long call into several. Records overlap: a later record runs on nodes that have finished earlier ones, up to 16 orasync_queue_capacityat once, whichever is smaller, but each node still sees records in order.A windowed graph that falls behind takes the rounds queued for it together, to catch up. A
FINALround returns only after the queue drains, so a deeper queue helps a graph that falls behind but lengthens its tail.Keep producer threads, workers and the coordinator on separate cores for low latency. Configuring decoders warns when two graphs pin the same CPU or together need more threads than the machine has.
Fire pools
max_in_flight on a node builds that many copies of it, so several records
can decode on it at once. Results equal one-at-a-time decoding: each record
uses one copy, and corrections fold in record order.
Only kinds that keep no state between decodes take
max_in_flightabove one.sliding_window,single_window,streaming,predecoder,ingestandlogical_readoutdo not.While streaming, a fire pool cannot take raw measurements, so it must be fed by another node, as
decode_windowis fed byingest.Each copy builds its own inner decoder, so the node needs a decoder type, not an already-built decoder.
Copies decode at once only with
async_streaming. Each copy beyond the first adds a worker to the default pool.
Streaming results in detail
streaming_result() returns the values of every output with their
progress:
statusandclosure, per output and for the graph.coverage_begin_roundandcoverage_end_roundper output: the rounds its latest update committed.generation: a counter that advances each time an output publishes, once every node that feeds it has updated. Fed only by native streaming nodes, it advances whenever coverage grows. The graph’s generation advances once every output but the logical one has.clear_corrections()keeps it, so usestatus, notgeneration, to decide whether a value can be read.result_revision: advances on any change of value or status.shot_epoch: advances onreset_decoder().error: why the graph failed, whenstatusisfailed. Reset to continue.
With async_streaming, streaming_result() first waits for every
queued round, then returns a snapshot. Without it, the C++ result is a live
reference owned by the graph; copy it to keep it across later calls. Python
always returns a copy.
Staged outputs
Nodes that feed one output normally decode on the same schedule, and the
output’s coverage follows that schedule. Window nodes such as
decode_window instead finish arbitrary round intervals in any order. An
output fed only by such nodes is staged: the graph holds each result until
every earlier round is done, folds them in round order, and reports coverage
from the frontier at the last clear_corrections() (round 0 in a new shot)
to the current frontier. An output that mixes both kinds of node cannot
stream; wire them to separate outputs. Nodes that commit the same rounds,
such as two parallel_window patterns, cannot share an output either;
building the graph refuses them.
Edge values
Each port declares the type of value it produces or accepts, and building a
graph rejects an edge whose types do not match. The types you wire most are
measurement_results, detection_events and logical_outcome; others
carry values between built-in nodes, such as the corrections one window sends
another. registered_edge_value_types() (C++) lists an installation’s
types.
A node fed by another node decodes that node’s output, as the global decoder
in Decoding Task Graphs’s first figure decodes the predecoder’s
residual.
Logical outputs
A logical_readout node reads the raw logical value through the model’s
m2o_sparse, and an xor applies the corrections to it. The output that
the node reaches, whatever its name, is the graph’s logical output. On a
model whose rounds all have the same width:
nodes:
- {id: sw, type: sliding_window, inner: {type: pymatching}}
- {id: R, type: logical_readout}
- {id: L, type: xor}
edges:
- {from: measurements, to: sw}
- {from: measurements, to: R}
- {from: sw, to: output.corrections}
- {from: sw, to: L.a}
- {from: R, to: L.b}
- {from: L, to: output.logical}
A graph has at most one logical output, and needs a corrections output beside it.
One
logical_readoutnode reaches the logical output, and it reaches no other output.The node joins any stream, whatever the other nodes’ schedules. Here the corrections publish on the window’s schedule, so the logical measurements are released at
FINAL; see Logical measurements.
Native streaming nodes
A streaming node passes each enqueue_syndrome call to its inner
decoder’s own enqueue_syndrome, for decoders that process rounds
incrementally. Its complete-shot path decodes the whole shot at once.
Rounds may differ in width, such as a narrower readout round, if the inner
decoder implements streaming_correction_provider and so ends its own
shots; a shot may then end at any FINAL round. Coverage is the rounds
the decoder has committed, not the node’s schedule:
Mid-shot, the node publishes whenever
committed_round_count()grows. Coverage starts whereclear_corrections()last consumed the corrections. A decoder without the count publishes nothing beforeFINAL.FINALcovers the roundsfinalized_round_count()reports, or else the committed ones.A shot the decoder ends without
FINALcovers the roundsfinalized_round_count()reports, and the stream continues.Several such nodes may feed one output, which covers the rounds all of them have committed. If one reports no count, or they disagree on where the shot begins, the output follows the nodes’ schedule.
- id: native
type: streaming
num_syndromes_per_round: 24
inner: {type: <streaming-decoder>}
Arbitrary-length sliding windows
arbitrary_length: true on a sliding_window node lets a shot end at any
round, not only on a window boundary. FINAL decodes the actual last
rounds, without padding.
The model is
dem_chunkswith one measurement count for every round, a prefix, one repeating phase and one or more final phases. The prefix and final phases together must be fewer thanwindow_sizerounds, andwindow_sizeat least 3.The node needs a trailing guard:
step_sizeequal towindow_size - start_guard - end_guard, withend_guardof at least one. Set no guards andend_guarddefaults towindow_size - step_size. Witht > 1final phases,start_guardmust be at leastt, and results lagtrounds behind.The
FINALround must be a complete round, and a shot must have at least the model’s minimum number of rounds.The inner decoder is named by type, so the node can build one per window shape; all shapes are built when the graph is.
Nodes combined into one output must all set it.
run() still decodes a fixed-length shot. For streams of any length whose
windows decode at the same time, see Task Graph Parallel Window.