What is OBSERVABLE_INCLUDE in Stim and what is usefulness Pymatching

Question

I have a question about the role of OBSERVABLE_INCLUDE within Stim circuits and how Pymatching uses it in order to decode syndromes. As far as I have understood from the documentation, OBSERVABLE_INCLUDE contains the value of the logical operator of the code. For example, for a distance-3 surface code which is measured in the Z-basis, the $X_L$ operator. Nevertheless, upon observing some of the circuits facilitated by Stim, I do not find it to be the case. Consider the aforementioned Stim circuit which can be constructed as:

circuit = stim.Circuit.generated("surface_code:rotated_memory_z", 
                             distance=3, 
                             rounds=3, 
                             after_clifford_depolarization=0.005)

For this circuit, the OBSERVABLE_INCLUDE considers the overall parity of the measurements of the qubits 1, 3 and 5 (figure attached). Why is that the case? For such a code, the $X_L$ operator can be constructed by any vertical set of $X$ operators going from the bottom boundary to the top one.

I have thought that maybe it was so as to aid the absence of pairs of non-trivial syndrome elements. Nevertheless, were that to be the case, the overall parity of the top three data qubits should also be measured, since only considering the bottom one may produce logical errors. For example, consider in the surface code from the figure, an $X$-error in data qubit 15 which triggers the check 14. Provided that the decoder only considers the qubits from the bottom to be on the boundary, it may recover an error consisting in $X$ errors in 8 and 1, producing a logical error and not being able to successfully decode syndromes produced from all weight 1 errors.

Either if the motive of OBSERVABLE_INCLUDE is to include a logical operator or to consider boundary data qubits, I also do not understand how can Pymatching only use this value so as to check if the decoding algorithm was correct. I understand the process of Pymatching for measurement error syndromes consists in receiving the detector error model upon which a Tanner graph is built and used for reweighting the detector graph upon which the Blossom algorithm is implemented given a syndrome, which returns the flipped data qubits. I do not understand why we can assume that the decoding process has been successful when the overall parity of qubits 1, 3 and 5 is correct.

$X$-checks and $Z$-checks respectively. " />

Answer 1

For this circuit, the OBSERVABLE_INCLUDE considers the overall parity of the measurements of the qubits 1, 3 and 5 (figure attached). Why is that the case?

Writing down a whole topological class of observables sounds hard. Stim simplifies this task by asking for one representative, instead of asking for the entire class.

the overall parity of the top three data qubits should also be measured, since only considering the bottom one may produce logical errors

The OBSERVABLE_INCLUDE instruction doesn't decide which qubits are measured. The circuit measures all the qubits, regardless of what OBSERVABLE_INCLUDE says.

how can Pymatching only use this value so as to check if the decoding algorithm was correct.

The decoder knows about the other measurements via the DETECTOR annotations that refer to them. The decoder is given each detector's value.

I do not understand why we can assume that the decoding process has been successful when the overall parity of qubits 1, 3 and 5 is correct.

The decoding process, by its very nature of explaining detection events using a small number of Pauli flips, removes those detection events from the system. When there are no detection events, all observables that are topologically equivalent become actually equivalent (up to some product of stabilizers). As a result, all choices of observable end up equivalent. If A and B are topologically equivalent observables, then you will get B wrong exactly when you get A wrong and vice versa.

One way to verify this is to declare two equivalent observables, and then do some Monte Carlo sampling. You'll notice their failures are always perfectly correlated.