[Design] Add ability to reason about Circuit structure

It would be a very useful feature to be able to reason about “Circuit structures”. Supporting this feature would mean that we would roughly need to be able create an op to do the following:

my_circuit = cirq.Circuit(cirq.H(q0), cirq.CNOT(q0, q1), cirq.Y(q1) ** beta)
circuit_tensor = tfq.convert_to_tensor([my_circuit])
structure_grid = tfq.circuit_structure(circuit_tensor)

print(structure_grid)
# [[...], ...]  some kind of meaningful 2d description of the circuit. 
# Should maybe be something like [batch_size, ragged on n_qubits, ragged on depth, n_channels] 
# Maybe an additional output to track symbols as well ?

My current thinking is that we do something like this: have the following inputs:

(optional) gate_alphabet where gate_alphabet[gate] = a unique integer value
(optional) symbol_alphabet[symbol_name] = a unique integer value different from any in gate_alphabet
circuits[i] = a serialized cirq.Circuit`
symbol_names = a list of all symbols found in all the circuits in circuits

Outputs:

encoding[i][j][k] = gate_alphabet[operation from circuits[i] at moment j at qubit index k] 

params[i][j][k][l] = symbol_alphabet[parameter l from operation from circuits[i] at moment j at qubit index k]
    or the value of l if it isn't a symbol.

What do people think ?

Going to leave open for discussion with @vprusso and others.

[MichaelBroughton]

Right, those are all good assumptions. What we want ultimately is to have an op that would support the workflows used in places like: https://arxiv.org/pdf/2005.10811.pdf ( see figure 2 ).

Assuming all that is correct, I’m a bit lost on the gate alphabet. So are we storing the gate itself in the array that we create, or are we storing an integer that represents the gate in some lookup table? If the former, I don’t understand the point of the alphabet. And if the latter, would that lookup table be included with the tensor, or is that something that would only be maintained by the user?

Probably the latter. I imagine somewhere the user will have to specify what values they want specific gates to be converted into so they can have some idea of what is in the tensor the op spits out.

Also for e.g. CNOT gates, do we need to store whether q is the control or controlled qubit? Does the design above account for that?

We probably do need a way of distinguishing control vs target for multi qubit gates. The design above does not account for that. Given the complexity of this “encoding problem” it might be worthwhile to tinker with different designs and approaches in pure python and find something that everyone can agree on before moving onto making a full blown C++ op.

As it stands this issue is pretty open ended and we aren’t at the point where we know exactly how things should look yet, so any design proposals or mini-python api designs are more than welcome

[daxfohl]

My initial thought is we’d want to hard code the gate alphabet into an enum so it’s consistent. User doesn’t have to maintain a mapping. The tensor can be serialized and shared without also having to share a mapping. Multi-qubits gates can be accounted for by different enums. So enum gates { NONE=0, X=1, CNOT_CONTROL=2, CNOT_TARGET=3 } etc., and arrange it such that a global bitmask lets you identify all the other parts of the gate easily MASK[X]=0xffff; MASK[CNOT_CONTROL]=MASK[CNOT_TARGET]=0xfffe;. This wouldn’t account for custom gates, but IDK if supporting them is a big need here. They can be decomposed for now, and maybe we add support for an optional custom gate lookup in the future. Thoughts?

For the parameter array, should those all be a specific length, or variable based on the gate? Or, consistent within a circuit based on largest gate, but variable across circuits? Is there a maximum number of parameters we’d expect on any gate? Multi-qubit gates would end up needing those arrays duplicated across all the [moment][qubit] cells they apply, but that’s probably fine.

The other question I have is, should this array representation be alone its own tensor, or should it be packaged with the original proto too? The way I’m picturing it, if these are two separate tensors, then users would have to pass both of them around everywhere: the proto to send to simulators, and the array to analyze. So instead, should it be a single tensor that contains both?