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]
  • phases lists each kind of round. num_faults and error_rates give its faults and their probabilities, and O_sparse lists, for each logical observable, the faults that flip it.

  • connections order the phases. init starts the shot, bulk follows itself, so it repeats, and final ends the shot.

  • num_rounds sets 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_round rows are this round’s detectors. Each lists the phase’s faults that flip it.

  • next_round rows 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_sparse on 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 an init phase.

  • measurements_per_round sets each round’s measurement count, and num_measurements a phase’s own, such as final’s five data qubits.

  • m2o_sparse lists, 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_names names 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