Measurement bitstrings to detection event bitstrings in stim

Question

Does Stim have exposed functionality for converting a measurement outcome string into a detection event string?

I.e. I feed stim a string of 0,1's corresponding to measurements in a circuit along with the circuit itself, and it spits out a string of 0,1's corresponding to the detection events in that circuit? Of course this functionality exists under the hood, but just wondering where and how it's accessible.

Answer 1

You can use stim.Circuit.compile_m2d_converter to get an object that converts measurements into detection event data (and optionally also observable flip data). The actual conversion is then done with the method stim.CompiledMeasurementsToDetectionEventsConverter.convert for in-memory results or stim.CompiledMeasurementsToDetectionEventsConverter.convert_file for on-disk results.

This functionality is also available from the command line using stim m2d.

Example:

import stim

circuit = stim.Circuit("""
    X 0
    X_ERROR(0.1) 0 1
    M 0 1
    DETECTOR rec[-1]
    DETECTOR rec[-2]
    OBSERVABLE_INCLUDE(0) rec[-1] rec[-2]
""")
measurements = circuit.compile_sampler().sample(shots=100)

#############################################
#### Convert from measurements to detection events and observable flips.
#############################################
converter = circuit.compile_m2d_converter()
dets_and_obs = converter.convert(measurements=measurements, append_observables=True)

mes0 = measurements[:, 0]
mes1 = measurements[:, 1]
det0 = dets_and_obs[:, 0]
det1 = dets_and_obs[:, 1]
obs0 = dets_and_obs[:, 2]
print("mes0: ", "".join("01"[int(e)] for e in mes0))
print("mes1: ", "".join("01"[int(e)] for e in mes1))
print("det0: ", "".join("_!"[int(e)] for e in det0))
print("det1: ", "".join("_!"[int(e)] for e in det1))
print("obs0: ", "".join("_!"[int(e)] for e in obs0))

Example output:

mes0:  1111111111111001011111101010111111111111101101110111111111111111111111111111110111111011111111111011
mes1:  0000000100010000110000000000000000000100000000000000000001000000000000100100000000000000000000001100
det0:  _______!___!____!!___________________!___________________!____________!__!______________________!!__
det1:  _____________!!_!______!_!_!_____________!__!___!_____________________________!______!___________!__
obs0:  _______!___!_!!__!_____!_!_!_________!___!__!___!________!____________!__!____!______!__________!___

Note that creating the converter is as expensive as sampling measurements; it involves performing a stabilizer simulation of the circuit to get a reference sample (because otherwise it's unknown if the measurement set defining a detector is supposed to have even or odd parity).