Return fault operator that was placed within a specific instance of a noisy circuit

[saschaheussen]

When I sample from a circuit that contains noise channels, it would be great to be able to access the specific operators that were chosen by the random number generator for each shot. For example, in a circuit that contains a DEPOLARIZE1 instruction, I would like to access for each shot, if the instruction has placed X, Y or Z; I should be omitted. It would help me a lot in debugging FT circuit constructions in order to scrutinize which circuit-level faults propagate to logical failures. There seems to be no workaround currently.

[Strilanc]

Yeah this is a common request. I keep not doing it because the indexing of the errors would be pretty non-trivial.

Consider: you get back an array of bits where the 0 means error didn't occur and 1 means it did occur. There's a single 1 at index 1201. But what error is error 1201? To figure it out you start iterating over the circuit, adding 1 for each error you encounter. But for multi-case errors you add things other than 1 (e.g. DEPOLARIZE1 adds 3, DEPOLARIZE2 adds 15). For highly custom errors like PAULI_CHANNEL_2 it's unclear if you add 15 or if you add 1 for each non-zero probability in its argument list. Clearly M(0.1) ... counts as an error, but does M(0) ...? And would that imply M ... counts as an error? Clearly there at least needs to be a stim.CircuitInstruction.num_errors helper method.

At the moment the workaround is to use the dem sampler. You can tag every error mechanism in the circuit with a unique tag in order to create a dem with easily identified circuit errors, and now the only remaining ambiguity is which of the DEPOLARIZE cases triggered.

[saschaheussen]

thanks for the quick reply! wouldn't the format be relatively easy to standardize? any single fault can be described as a (timestep: int, wires: tuple, pauli: str). a list of all possible individual circuit-level faults, including your "DEPOLARIZE1 adds 3, DEPOLARIZE2 adds 15" example, can be pre-computed. then, the array of bits where the 0 means error didn't occur and 1 means it did occur can just map 1:1 to this pre-computed fault list.

[Strilanc]

I agree you can "just pick a format", but it does matter how hard it is for people to consume it. Having a method list out what each bit means would in fact be helpful; I like that idea.

I do legitimately think what to do with M is ambiguous. The internal implementation currently treats M as if it were M(0), but probably users don't want that.

Keep in mind this is not a small code change. This would be editing the most performance sensitive part of the entire simulator, which is the sparse error sampling code. It's a big ask and I'm not sure it's worth the effort.

It does also bug me that this information is kinda cheating. On hardware, we don't get to know which errors happened.

[saschaheussen]

tbh I didn't quite get your M example from the first message. I am only considering the faults, not the instructions themselves (although of course the faults are linked to the instructions via the noise model), so I wouldn't really care if the instruction is DEPOL1(p) or M(p). Whenever p == 0, the instruction should be ignored and when p > 0 the associated faults to that instruction should be written to the pre-computed fault list; the only special thing about M is that faults happen before, not after. If this is hard to implement for another reason, as you say M is always M(0), one could just place an identity gate before any M and apply DEPOL1 to it as a workaround.

I feared that it would require a lot of work on the code base and therefore didn't dare to try myself :D

regarding the cheating: well, in this sense all of the simulation business is cheating anyways, no? the experiment also doesn't allow us to .peek_observable_expectation( 🙃

[matti-sarjala]

A smaller intermediate API might be useful before exposing sampled faults directly from the performance-critical sampler.

Possible split:

1. Static fault catalog

   • A method that returns the ordered list of possible fault events for a circuit.
   • Each entry could describe enough metadata for debugging: instruction location, targets, fault case, and Pauli effect.
   • This would answer “what does bit k mean?” without changing sampling performance.

2. Dynamic sampled fault bits

   • A later optional sampler mode could return the bit-vector over that catalog for each shot.
   • This can be treated as debug/diagnostic mode rather than the default fast path.

This split might avoid making the first PR touch the hottest sparse-error sampling path. It would also force the ambiguous cases to be specified first:

• Does M count as M(0)?
• Does M(0) create zero catalog entries?
• Does PAULI_CHANNEL_2 allocate one entry per nonzero probability term or one entry for the whole instruction?
• Are zero-probability cases omitted?

A static catalog seems independently useful for users who already use the DEM/tagging workaround, because it makes the indexing convention explicit before adding per-shot sampled fault output.