circuit.convert_to_stim_tableau() fails for circuits with general qubit labels

[tjproct]

circuit.convert_to_stim_tableau() does not work when the qubits in the circuit are not labelled by integers from 0 to N.

This works

c = pygsti.circuits.Circuit('Gcphase:0:1@(0,1)')
c.convert_to_stim_tableau()

This does not

c = pygsti.circuits.Circuit('Gcphase:2:3@(2,3)')
c.convert_to_stim_tableau()

Neither does this

c = pygsti.circuits.Circuit('Gcphase:Q0:Q1@(Q0,Q1)')
c.convert_to_stim_tableau()

This was tested on develop. All cases should give the same tableau.

[coreyostrove]

Yeah, this rings a bell. The issue, as I recall it, is the following:

• When instantiating at stim Tableau you need to specify the total number of qubits that the Tableau acts upon.
• When appending to a Tableau (i.e. adding each of the cliffords for a given gate layer) you need to specify which qubit indices the operation acts upon. And stim only supports integers indices assumed to run from 0 to N-1 where N is the number of qubits.
• On the pyGSTi side there is both flexibility on the labeling convention (strings or integers) and ambiguity in interpreting the action of a circuit based on the line labels.

This means we need to canonicalize the mapping from qubit labels into the range from 0 to N-1, and we also need a convention for identifying the correct number of qubits. Some cases are fairly easy. E.g. 'Q1', 'Q2', ..., 'QN' -> 0,1,..., N-1. Others would be hard, 'Qupperleft', 'Qlowerright' etc. There is also can be a bit of ambiguity on the qubit count, for example in your second example:

c = pygsti.circuits.Circuit('Gcphase:2:3@(2,3)')

This circuit could in different contexts could reasonably be interpretted as a 2 or 4 qubit circuit. This part actually has an obvious solution, just require that the user specify the number of qubits in tricky cases, but it looks like the num_qubits argument for Circuit.convert_to_stim_tableau_layers wasn't plumbed up to convert_to_stim_tableau (this is a quick fix).

Anyway, I didn't feel like resolving the canonicalization problems at the time, but I think what we can do is add in logic that handles the obvious cases (which should be simple enough to detect) and then just nope out on the hard ones. I can add in logic for a custom label mapping too for tricky cases to give more flexibility.

[tjproct]

FWIW, my interpretation of a pyGSTi circuit is that there is not any ambiguity in the qubits it acts on and what order they are in: it is specified by the @(...) at the end of the circuit, i.e., the line labels. A circuit with line labels @(2,3) is unambiguously a 2-qubit circuit, its outputs (assuming no MCMs) are 2-bit strings, and the first bit corresponds to qubit 2 and the second to qubit 3. All other objects one might associate with a circuit -- like a unitary or a tableau -- have exactly the same behavior. The i'th qubit is the i'th qubit in line labels.

According to this understanding, there is one and only one correct behavior for .convert_to_stim_tableau() --> the i'th qubit in line labels gets mapped to the stim qubit with integer i.

Maybe I'm wrong about how pyGSTi circuits are interpreted, but there are various things in pyGSTi that rely on this interpretation I think?

[coreyostrove]

This has been patched in PR #625. For 99% of use cases the default mapping logic should work, and for all other cases we have an option for a user to specify a custom mapping into a stim Tableau's qubits.