Playback Emulator
The playback emulator replays a scripted sequence of decoder calls (a schedule) against one or more realtime decoders, on a precise timing loop that does not need a quantum processor (QPU). Each line of the schedule says when to call a decoder and what to send it. The emulator records when each call was made, when its reply arrived, and what came back, so it can be used to measure decoder latency or check decoder output.
Note
The playback emulator is only built when CUDA-Q QEC is built against a
CUDA-Q install with cudaq-realtime enabled.
A schedule is a text file, where each line is a single event representing a decoder call, or sequence of decoder calls. For example, the following schedule resets decoder 0, enqueues three rounds of syndromes, and asks for a one-bit correction:
# <trigger> <op> [key=value...]
0 reset session=0
1 stream session=0 source=0 rounds=3 every=2
- get_corrections session=0 return_size=1
Save it to a file (e.g. schedule.txt) and run it from the command line or
from Python:
import cudaq_qec as qec
decoders = qec.multi_decoder_config.from_yaml_str(open("config.yaml").read())
result = qec.playback.run(open("schedule.txt").read(),
tick_ns=1000,
sources={0: {"type": "static",
"rounds": [[0, 1]] * 3}},
decoders=decoders)
print(result.write_csv())
# syndromes.txt holds one 0/1 bit string per round, one round per line.
playback-emulator --schedule=schedule.txt --config=config.yaml \
--source=0:syndromes.txt --tick=1us --out=result.csv
config.yaml is a decoder configuration, as described in
Getting Started with Realtime Decoding.
Both entry points produce the same result: one record per schedule line,
written as CSV by write_csv() (Python) or --out (command line); see
Output Format. Run playback-emulator --help for
all command-line options.
Schedule Format
Each line is <trigger> <op> [key=value...]. Blank lines are ignored, and
# starts a comment.
Timing is tracked in ticks, where one tick is defined by the tick_ns run option (default 1 µs). The trigger says when the line runs:
N(an integer): at tickNfrom the start of the run. One tick defaults to 1 µs (see Run Options).+N:Nticks after the previous line finished sending.-: same as+0, i.e. execute immediately.
Lines run in file order. Plain tick numbers must not decrease, and once a line
uses +N or -, every later line must too.
The operations are listed below. Arguments in [brackets] are optional.
Operation |
Description |
|---|---|
|
Resets the decoder. |
|
Sends syndromes from |
|
Shorthand for a one-round |
|
Like |
|
Requests corrections. |
source= sets the syndrome source by its integer ID (see below), or gives one
round of bits inline, e.g. enqueue source=0b0110.
Every operation also takes these optional keys:
[session=N]: the decoder ID to call (default0).[signal=NAME]: raise signalNAMEonce all of this line’s replies have arrived.[after=NAME]: wait for signalNAMEbefore running this line.
A signal must be raised by an earlier line than any line that waits on it. Signals let one decoder’s schedule react to another’s, e.g. stream syndromes to decoder 0 until decoder 1 has replied.
If a decoder reply reports an error other than 4 (not ready), the run
stops. Lines that never ran have status -1, and the reason is in
result.warnings.
Output Format
The output has one CSV row per schedule line, in schedule order. Times are in
nanoseconds from the start of the run. Columns that list one value per request
(one per round for stream) are space-separated.
Column |
Description |
|---|---|
|
The schedule line (0-based), the decoder it called, and its operation. |
|
When the line was due, when it started sending, and when its last reply arrived. |
|
|
|
Rounds actually sent ( |
|
|
|
Bits sent and bits received, as |
|
|
|
Each request’s ID, for matching against decoder server logs. |
|
|
|
When each request was sent, and when its reply arrived ( |
|
Each request’s status: the decoder status codes above ( |
In Python, result.records holds one dict per CSV row, keyed by the column
names above.
Syndrome Sources
A syndrome source produces one round of syndrome bits at a time. Each source
has an integer ID, which source= refers to. Any source can be used with
until=; a stream whose source runs out first stops early with status
101.
Type |
Description |
How to create |
|---|---|---|
|
Replays fixed rounds in order. |
Python: CLI: |
|
Generates rounds on demand from a Stim memory circuit ( |
Python: CLI: |
|
Raw measurements from a CUDA-Q QEC |
Python only: |
Sessions
A session connects the emulator to one decoder, chosen by session=N in
the schedule.
Session |
Description |
How to select |
|---|---|---|
|
Runs the decoders from a decoder configuration in the same process. |
Python: CLI: |
|
Sends calls over UDP to a running decoding server. |
Python: CLI: |
|
Sends calls over RDMA (CPU RoCE) to a decoding server started with
|
Python: CLI: |
|
Discards every call. Measures the emulator’s own overhead. |
Python: CLI: |
Run Options
These options behave the same in Python and on the command line. Python takes
whole nanoseconds (_ns) or milliseconds (_ms). The command line takes a
duration with a unit (ns, us, ms, or s); timeouts must be a
whole number of milliseconds. The tick and every timeout must be positive.
Python |
Command line |
Default |
Description |
|---|---|---|---|
|
|
1 µs |
Length of one schedule tick. |
|
|
20 ms |
Setup time between starting the run and tick 0. |
|
|
200 ms |
How long a UDP request waits for its reply. |
|
|
200 ms |
How long a CPU RoCE request waits for its reply. |
|
|
5 s |
How long to wait for the connection to a CPU RoCE server. |
|
|
8, 256 |
CPU RoCE ring size, in slots and bytes per slot. Must match the
server’s |
A request with no reply within its timeout is an error, which stops the run.
Example
The example below configures a lookup-table decoder for a distance-3
repetition code, then plays back ten fixed shots against it, alternating
between no error and a flipped data qubit. It prints each shot’s correction
(0, then 1) and decoding latency.
import cudaq
import cudaq_qec as qec
code, rounds = qec.get_code("repetition", distance=3), 3
noise = cudaq.NoiseModel()
noise.add_all_qubit_channel("x", cudaq.Depolarization2(0.01), 1)
# Configure one lookup-table decoder (id 0) for this memory experiment.
ctx = qec.decoder_context_from_memory_circuit(code, qec.operation.prep0, rounds,
noise)
dem, m2d, _ = ctx.full_component()
config = qec.decoder_config()
config.id, config.type = 0, "multi_error_lut"
config.syndrome_size, config.block_size = dem.detector_error_matrix.shape
config.H_sparse = qec.pcm_to_sparse_vec(dem.detector_error_matrix)
config.O_sparse = qec.pcm_to_sparse_vec(dem.observables_flips_matrix)
config.D_sparse = qec.d_sparse(m2d)
decoders = qec.multi_decoder_config()
decoders.decoders = [config]
# One shot: reset, 3 stabilizer rounds, data readout, then decode. Each shot
# starts 100 ticks (100 us) after the previous one finished sending.
shot = """\
+100 reset
- stream source=0 rounds=3
- enqueue_data source=0
- get_corrections return_size=1
"""
schedule = shot * 10
# Raw measurements for one shot: 3 rounds of 2 ancilla bits, then 3 data bits.
# Shots alternate between no error and a flip of data qubit 0.
clean = [[0, 0]] * 3 + [[0, 0, 0]]
flipped = [[1, 0]] * 3 + [[1, 0, 0]]
source = dict(type="static", rounds=(clean + flipped) * 5)
result = qec.playback.run(schedule,
tick_ns=1000,
sources={0: source},
decoders=decoders)
for r in result.records[3::4]: # The get_corrections records
print(f"status={r['status']} correction={r['correction_bits']} "
f"latency={(r['return_ns'] - r['call_ns'])/1000:4.1f} us")
To play the same schedule against a decoding server instead, save the decoders
with decoders.to_yaml_str() to config.yaml, start the server, and pass
udp_endpoints={0: "127.0.0.1:50000"} to run() in place of decoders=:
decoding_server --config=config.yaml --transport=udp --port=50000