Error correction turns measurements of checks into an interpretation of logical information. The decoder receives evidence about faults, not a complete account of what physically happened. Its proposal depends on a code, a noise model, and an optimization procedure. An operating system must keep that proposal associated with the right measurements and logical state.
The project contains two decoder demonstrations with different output meanings. One uses a small check matrix and returns physical X-correction bits. The other uses a Stim detector error model and returns predicted logical-observable flips. Treating these arrays as interchangeable would produce incorrect results.
Follow the restricted repetition trace
For the three-data-qubit bit-flip example, the checks are Z0Z1 and Z1Z2. Vectors use [q0,q1,q2] order. A check result of one means the corresponding parity is negative. The simulator can show the injected error, but a hardware decoder would receive the check evidence rather than that hidden truth.
"""Simulated surface-code memory; not a universal fault-tolerance benchmark."""
import json
import platform
import time
from importlib.metadata import version
from pathlib import Path
import numpy as np
import stim
import pymatching
from scipy.stats import beta
def interval(failures, shots, alpha=.05):
"""Two-sided exact Clopper-Pearson interval, including zero/all failures."""
if type(shots) is not int or type(failures) is not int or shots<=0 or not 0<=failures<=shots or not 0<alpha<1: raise ValueError("Invalid binomial sample")
lo=0.0 if failures==0 else float(beta.ppf(alpha/2,failures,shots-failures+1))
hi=1.0 if failures==shots else float(beta.ppf(1-alpha/2,failures+1,shots-failures))
return [lo,hi]
def repetition_trace(error):
H=np.array([[1,1,0],[0,1,1]],dtype=np.uint8)
raw=np.array(error,dtype=np.uint8)
syndrome=(H@raw)%2
frame=pymatching.Matching.from_check_matrix(H,weights=1.0).decode(syndrome).astype(np.uint8)
return {"error":raw.tolist(),"syndrome":syndrome.tolist(),"frame":frame.tolist(),"interpreted":(raw^frame).tolist()}
def experiment(distance=3,p=.005,shots=10000,seed=7):
if type(distance) is not int or distance<3 or distance>9 or distance%2==0 or type(shots) is not int or not 1<=shots<=100000 or not 0<=p<=.1 or type(seed) is not int or seed<0: raise ValueError("Invalid bounded QEC configuration")
circuit=stim.Circuit.generated("surface_code:rotated_memory_x",distance=distance,rounds=distance,after_clifford_depolarization=p)
matching=pymatching.Matching.from_detector_error_model(circuit.detector_error_model(decompose_errors=True))
detectors,actual=circuit.compile_detector_sampler(seed=seed).sample(shots=shots,separate_observables=True)
# Sampling time is excluded. This is host batch decoding throughput, not tail latency.
start=time.perf_counter();predicted=matching.decode_batch(detectors);elapsed=time.perf_counter()-start
failures=int(np.any(predicted!=actual,axis=1).sum())
return {"distance":distance,"rounds":distance,"p":p,"shots":shots,"seed":seed,"failures":failures,"rate":failures/shots,"interval":interval(failures,shots),"hostDecodeSeconds":elapsed,"hostSecondsPerShot":elapsed/shots,"noise":"after_clifford_depolarization only; reset, idle and measurement noise omitted","circuit":str(circuit)}
def capture():
return {"simulated":True,"scope":"Rotated surface-code X-memory, rounds=distance, restricted circuit noise; no universal fault-tolerance claim","engine":{"stim":version('stim'),"pymatching":version('pymatching'),"python":platform.python_version(),"numpy":version("numpy"),"scipy":version("scipy"),"host":platform.machine()},"runs":[experiment(d,p) for p in (0.0,.005,.015) for d in (3,5)],"traces":[repetition_trace([1,0,0]),repetition_trace([0,1,1])]}
if __name__=='__main__':print(json.dumps(capture(),indent=2))
An injected error [1,0,0] yields syndrome [1,0]. A minimum-weight decoder proposes X0, represented by [1,0,0]. With an initial logical zero and perfect readout, the raw bits are [1,0,0]. Reinterpreting them with XOR against the frame gives [0,0,0].
The error [0,1,1] produces the same syndrome. The decoder again proposes X0, but the reinterpreted output becomes [1,1,1], a logical failure. The decoder has selected a lower-weight explanation, not learned the actual error. This example protects a restricted bit-flip model; it does not protect arbitrary quantum information against every single-qubit fault.
Distinguish syndrome from detection events
Repeated measurements add a time dimension. In a simple setting with unchanged checks, a detection event can be the difference between consecutive syndrome bits. Suppose the raw syndrome sequence is [0,0], then [1,0], then [1,0]. The changes are [1,0] followed by [0,0].
That sequence can describe a persistent fault with no new fault in the last interval. Treating the repeated [1,0] syndrome as a new instruction to toggle X0 every round would undo the intended frame tracking. Real detector definitions can combine several measurements and boundary conditions; use the circuit's declared detector parities rather than assuming every detector is a single raw check bit.
Noisy measurement circuits require a model that distinguishes data faults, measurement-related faults, and their time structure. The perfect-check repetition trace does not supply that model. The generated surface-code experiment provides a separate detector error model for its explicitly restricted circuit noise.
A frame changes interpretation
A Pauli frame can represent a tracked correction using x and z bits. Ignoring global phase, x changes the interpretation of a Z measurement, z changes an X measurement, and x XOR z changes a Y measurement. The physical quantum state has not been restored merely because the software updated these bits.
Clifford operations transform the frame. A Hadamard swaps x and z. An S gate updates z to z XOR x. For a controlled-X, propagate x from control to target and z from target to control. Non-Clifford operations can require additional adaptation, so these simple updates are not a universal replacement for control logic. Research on Pauli and Clifford frames develops that distinction.
Apply a correction physically or account for it in the frame with a consistent convention. Doing both without updating the record can double-correct the same fault and corrupt the interpretation.
Worked example: know what the decoder returns
In the check-matrix trace, the decoder output has three physical correction bits. In the project's Stim/PyMatching memory experiment, the output instead predicts the logical-observable flips declared in the detector error model. The program counts a failed trial when that prediction disagrees with the simulator's actual logical outcome.
Counting fired detectors would answer a different question. A trial can contain detection events and still decode successfully. Conversely, an undetected logical fault can preserve check consistency while changing the logical outcome. The failure denominator is the number of whole memory experiments, with the configured rounds and noise model.
The timed decode_batch call measures host batch processing. It does not establish that syndrome data can traverse a hardware control path before a required deadline. Scheduling must account for when the frame or logical decision is actually needed, including communication and latency tails.
Exercise: propagate a frame
A qubit has frame bits x = 1 and z = 0. It passes through H and is then measured in X. Which bit determines whether to reinterpret the measurement? Must a physical correction pulse have occurred?
Answer. H swaps the frame bits, producing x = 0 and z = 1. The X measurement is reinterpreted using z, so its bit is flipped. No physical correction pulse is implied; the frame accounts for the correction classically under the stated propagation rules.
The resource-estimation chapter uses these control requirements as constraints alongside qubit counts and logical failure budgets.