Dynamic DEM
A dem_chunks model describes a detector error model one round at a time.
Each kind of round is a phase, with its own faults; connections say which
phase follows which. A phase that follows itself repeats, so the same model
describes shots of any length. Task graphs and streaming decoders read their
models in this form (see Decoding Task Graphs).
For surface-code memory experiments, memory-experiment-generator writes
the model for you; see Realtime Decoding.
A model
This model is a distance-5 repetition-code memory experiment with measurement errors:
dem_chunks:
seam: {from: next_round, to: prev_round}
measurements_per_round: 4 # one per check
connections:
- {from: init, to: bulk}
- {from: bulk, to: bulk} # bulk repeats
- {from: bulk, to: final}
phases:
# Faults 0-4 flip data qubits 0-4; faults 5-8 are errors in measuring
# checks 0-3. Check i reads data qubits i and i + 1. Observable 0 reads
# data qubit 0.
- name: init # first round of checks
spec:
num_faults: 9
seam_specs:
- name: prev_round # detectors of this round
spec: {H_sparse: [0, 1, 5, -1, 1, 2, 6, -1, 2, 3, 7, -1,
3, 4, 8, -1]}
- name: next_round # detectors of the next round
spec: {H_sparse: [5, -1, 6, -1, 7, -1, 8, -1]}
D_sparse: [0, -1, 1, -1, 2, -1, 3, -1]
O_sparse: [0, -1]
error_rates: [0.02, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02]
- name: bulk
spec:
num_faults: 9
seam_specs:
- name: prev_round
spec: {H_sparse: [0, 1, 5, -1, 1, 2, 6, -1, 2, 3, 7, -1,
3, 4, 8, -1]}
- name: next_round
spec: {H_sparse: [5, -1, 6, -1, 7, -1, 8, -1]}
# Detector i: check i in the previous round (index i) and in
# this one (index 4 + i).
D_sparse: [0, 4, -1, 1, 5, -1, 2, 6, -1, 3, 7, -1]
O_sparse: [0, -1]
error_rates: [0.02, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02, 0.02]
- name: final # data-qubit readout
spec:
num_faults: 5
num_measurements: 5 # data qubits 0-4
seam_specs:
- name: prev_round
spec: {H_sparse: [0, 1, -1, 1, 2, -1, 2, 3, -1, 3, 4, -1]}
# Detector i: check i in the previous round and data qubits i
# and i + 1 in this one.
D_sparse: [0, 4, 5, -1, 1, 5, 6, -1, 2, 6, 7, -1, 3, 7, 8, -1]
m2o_sparse: [0, -1] # observable 0 reads data qubit 0
O_sparse: [0, -1]
error_rates: [0.02, 0.02, 0.02, 0.02, 0.02]
phaseslists each kind of round.num_faultsanderror_ratesgive its faults and their probabilities, andO_sparselists, for each logical observable, the faults that flip it.connectionsorder the phases.initstarts the shot,bulkfollows itself, so it repeats, andfinalends the shot.num_roundssets the shot length for decoders that decode complete shots. Leave it out, as here, to stream shots of any length.
H_sparse and O_sparse hold one row per detector or observable: the
indices of the faults that flip it, ended by -1.
Detectors and seams
A fault can flip detectors of its own round and of the next one, as a
measurement error does. seam_specs say which:
prev_roundrows are this round’s detectors. Each lists the phase’s faults that flip it.next_roundrows are the next round’s detectors, listing the faults of this phase that flip them too.
seam: {from: next_round, to: prev_round} joins each round’s
next_round rows to the next round’s prev_round rows. The last phase
needs no next_round rows.
When every seam has the same rows, one H_sparse per phase replaces
seam_specs.
Measurements and readout
By default, each round measures one value per detector, and a detector compares its measurement with the round before; in the first round, with zero. The model above instead ends with a readout of the data qubits, which takes these optional fields:
D_sparseon every phase lists each detector’s measurements. Indices count the previous round’s measurements first, then this round’s. The first round has no previous round, so the model starts with aninitphase.measurements_per_roundsets each round’s measurement count, andnum_measurementsa phase’s own, such asfinal’s five data qubits.m2o_sparselists, for each observable, the measurements of the phase’s round that it reads; a logical value is the parity of all its readouts. Any phase but a repeating one may read observables, so a mid-circuit readout can, too. No later phase may flip an observable it has read. Task graphs use it to return logical measurements (see Logical measurements).observable_namesnames the observables.
Building a model in code
The same model, decoding a fixed-length shot:
def phase(name,
num_faults,
seams,
D_sparse,
num_measurements=None,
m2o_sparse=None):
"""A phase whose faults flip the rows each seam lists, and whose detectors
read the measurements D_sparse lists."""
spec = qec.DemChunkSpec()
spec.num_faults = num_faults
entries = []
for seam, rows in seams:
entry = qec.SeamSpecEntry()
entry.id = seam
entry.spec.H_sparse = rows
entries.append(entry)
spec.seam_specs = entries # assign the list; appending edits a copy
spec.D_sparse = D_sparse
if num_measurements is not None:
spec.num_measurements = num_measurements
if m2o_sparse is not None:
spec.m2o_sparse = m2o_sparse
spec.O_sparse = [0, -1] # observable 0 reads data qubit 0
spec.error_rates = [0.02] * num_faults
entry = qec.PhaseSpecEntry()
entry.id = qec.SeamId(name)
entry.spec = spec
return entry
def connection(from_phase, to_phase):
c = qec.PhaseConnection()
c.from_phase = qec.SeamId(from_phase)
c.to_phase = qec.SeamId(to_phase)
return c
# Faults 0-4 flip data qubits 0-4; faults 5-8 are errors in measuring checks
# 0-3. Check i reads data qubits i and i + 1. The final round reads the data
# qubits.
prev_round, next_round = qec.seam_name.prev_round, qec.seam_name.next_round
checks_seams = [
(prev_round, [0, 1, 5, -1, 1, 2, 6, -1, 2, 3, 7, -1, 3, 4, 8, -1]),
(next_round, [5, -1, 6, -1, 7, -1, 8, -1]),
]
seam = qec.SeamConnection()
seam.from_seam = next_round # this round's next_round rows...
seam.to_seam = prev_round # ...are the next round's prev_round rows
model = qec.DemChunksSpec()
model.seam = seam
model.measurements_per_round = 4 # one per check
model.phases = [
phase("init", 9, checks_seams, [0, -1, 1, -1, 2, -1, 3, -1]),
phase("bulk", 9, checks_seams, [0, 4, -1, 1, 5, -1, 2, 6, -1, 3, 7, -1]),
phase("final",
5, [(prev_round, [0, 1, -1, 1, 2, -1, 2, 3, -1, 3, 4, -1])],
[0, 4, 5, -1, 1, 5, 6, -1, 2, 6, 7, -1, 3, 7, 8, -1],
num_measurements=5,
m2o_sparse=[0, -1]),
]
model.connections = [
connection("init", "bulk"),
connection("bulk", "bulk"),
connection("bulk", "final"),
]
# Fix the shot length to decode complete shots: 5 rounds of checks and the
# final readout.
model.num_rounds = 6
graph = qec.DecodingTaskGraph.from_spec(model, "pymatching")
# Data qubit 0 flips in round 2: from then on, check 0 reads 1, and the final
# readout reads it as 1.
bits = [int(r >= 2 and i == 0) for r in range(5) for i in range(4)]
bits += [1, 0, 0, 0, 0]
shot = qec.MeasurementResults()
shot.bits = bits
corrections = list(graph.run(shot).bits)
print(f"corrections: {corrections}")
// A phase whose faults flip the rows each seam lists, and whose detectors read
// the measurements D_sparse lists; observable 0 reads data qubit 0.
static phase_spec_entry
phase(const char *name, std::uint64_t num_faults,
std::vector<std::pair<seam_id, std::vector<std::int64_t>>> seams,
std::vector<std::int64_t> D_sparse) {
phase_spec_entry entry;
dem_chunk_spec spec;
spec.num_faults = num_faults;
for (auto &[seam, rows] : seams) {
seam_spec_entry seam_entry;
seam_entry.id = seam;
seam_entry.spec.H_sparse = std::move(rows);
spec.seam_specs.push_back(std::move(seam_entry));
}
spec.D_sparse = std::move(D_sparse);
spec.O_sparse = {0, -1};
spec.error_rates.assign(num_faults, 0.02);
entry.id = seam_id{name};
entry.spec = std::move(spec);
return entry;
}
int main() {
// Faults 0-4 flip data qubits 0-4; faults 5-8 are errors in measuring checks
// 0-3. Check i reads data qubits i and i + 1. The final round reads the
// data qubits.
const std::vector<std::pair<seam_id, std::vector<std::int64_t>>> checks{
{seam_name::prev_round,
{0, 1, 5, -1, 1, 2, 6, -1, 2, 3, 7, -1, 3, 4, 8, -1}},
{seam_name::next_round, {5, -1, 6, -1, 7, -1, 8, -1}}};
dem_chunks_spec model;
model.seam = {seam_name::next_round, seam_name::prev_round};
model.measurements_per_round = 4; // one per check
model.phases = {
phase("init", 9, checks, {0, -1, 1, -1, 2, -1, 3, -1}),
phase("bulk", 9, checks, {0, 4, -1, 1, 5, -1, 2, 6, -1, 3, 7, -1}),
phase("final", 5,
{{seam_name::prev_round, {0, 1, -1, 1, 2, -1, 2, 3, -1, 3, 4, -1}}},
{0, 4, 5, -1, 1, 5, 6, -1, 2, 6, 7, -1, 3, 7, 8, -1}),
};
model.phases[2].spec.num_measurements = 5; // data qubits 0-4
model.phases[2].spec.m2o_sparse = {0, -1}; // observable 0 reads qubit 0
model.connections = {{seam_id{"init"}, seam_id{"bulk"}},
{seam_id{"bulk"}, seam_id{"bulk"}},
{seam_id{"bulk"}, seam_id{"final"}}};
// Fix the shot length to decode complete shots: 5 rounds of checks and the
// final readout.
model.num_rounds = 6;
auto graph = decoding_task_graph::from_spec(model, "pymatching");
// Data qubit 0 flips in round 2: from then on, check 0 reads 1, and the
// final readout reads it as 1.
measurement_results shot;
for (std::size_t r = 0; r < 5; ++r)
for (std::size_t i = 0; i < 4; ++i)
shot.bits.push_back(r >= 2 && i == 0);
shot.bits.insert(shot.bits.end(), {1, 0, 0, 0, 0});
const auto corrections = graph->run(shot).bits;
std::cout << "corrections: [" << int(corrections.at(0)) << "]\n";
Compile and run with
nvq++ -lcudaq-qec -lcudaq-qec-decoders dyn_dem.cpp
./a.out
corrections: [1]
In Python, assign whole lists, such as spec.seam_specs = [...]: appending
to a field changes a copy.
See also
Dynamic DEM and Dynamic DEM: the model types.
Task Graph Parallel Window: decoding streams of any length.