Replace TaggedOperation with a proper object proxy

[daxfohl]

Is your design idea/issue related to a use case or problem? Please explain

TaggedOperation and such tend to be troublesome both for users to use (have to remember to unwrap everywhere) and for maintainers to maintain (have to remember to forward any new protocols, implement all new base methods).

Describe your design idea/issue

Make a Tagged object proxy or use a popular third party one like wrapt, and eliminate the manual plumbing and upkeep of forwarding method and protocol calls, have isinstance work how users expect, and allow the same behavior for gates, qubits, moments, etc without needing individual classes for each.

[dstrain115]

Discussion from cirq cync: Doug thinks we should just add tags to Operation adn combine the classes, but has not thought this through at all. In any case, this would require a design. Now is a good time to tackle though, since we are talking about cirq 2.0.

[daxfohl]

Yeah I don't have an ideal answer either. Having looked into this a few times previously, the challenge of Operation.with_tags is the combination of two things: immutability and inheritance. You end up stuck with either:

1. A wrapper class (like TaggedOperation currently) that has to thread every member method through to the wrapped op, or something like wrapt.ObjectProxy that does so reflectively.
2. A virtual with_tags method that every subclass has to implement. (Blech)
3. Use the copy module: have Operation.with_tags use copy to clone the op and then edit the clone's _tags field. (Works, but copy always comes with gotchas. If Operations were all dataclasses using dataclasses.replace might provide fewer surprises, but even that has its own challenges; dataclass.__post_init__ will barf under diamond inheritance, which some current gates/ops use. But still, given these are all immutable classes, copy's gotchas may be pretty minimal). 3b: copy by serializing/deserializing the op, avoiding the copy module. Obviously perf sucks, but it's not a high-frequency call, and it's only serializing a single op.
4. Externalizing it (store _op_tags in Circuit and have Circuit.append(op, tag='tag') do a self._op_tags[op] = 'tag' internally) <-- might actually be a good model if tags genuinely only make sense within the context of a circuit, and ops don't "contain" tags that follow them across circuits. Though troublesome if the latter is desired.
5. Make Operation a dumb record: final dataclass container of { gate, tags, qubits }, i.e. move all "inheritance" to Gate. <-- I think this is ideal, as it makes the "what goes in Gate vs what goes in Operation" question obvious--all logic is in the Gate and the Operation is just the thing that puts it in a circuit. But I tried this and there are lots of demons here. Notably CircuitOperation would need to become CircuitGate, which itself isn't so bad--you just use indexes instead of qubits, but then you also need to have CircuitGate support all the append/insert/delete functionality, it needs to have Moments, which is a circuit-level concept and feels awkward, etc. All of which, probably overcomeable, but not easy. Plausibly if you follow that to its logical end, you find you end up not needing qubits at the core of Cirq at all, only indexes. Which would be great, but then you realize you still have to figure out a way to support qudits, ancillas, etc., and that if there aren't qubits then you don't need Operation, which means tags no longer has a place to live; you have to put it in Gate, meaning you have to add Gate.with_tags and we're right back where we started with immutability and inheritance. 🫤 I still think it's worth exploring, but it's a full rewrite, not an incremental change.
6. Accept tags to be a mutable field, or transition operation/gate/everything wholesale to mutability (qiskit's approach). Not unreasonable, but creates the question of whether serialization preserves op identity or just op value. 6b: an OpBuilder class, which seems like a good idea on the surface, but ultimately ends up meaning you've got to provide two classes for every op type, plus all the conversion methods, so, very heavy.

No option is perfect, but that's just the nature of that combination of immutability, inheritance, and a with_field_value(value) feature. It's why functional languages usually don't offer inheritance, or they split the functional aspect from the OO aspect like OCaml, so this problem can't arise.

Interestingly I've known option 4 existed for a long time, but never gave it real consideration. But now that I put it in writing, it sounds pretty reasonable. Would need to define how circuit.append(op_1, tags=['a']).append(op_1, tags=['b']) behaves (since you're passing op_1 by reference), and how to serialize the mapping if ops don't have an identity when serialized, but nothing immediately self-contradictory.

OTOH wrapt.ObjectProxy may "just work", and you don't have to map anything or limit the scope of the tag to within a circuit. I'd recommend at least investigating it. And if all else fails, option 3 really isn't all that bad. You'd just need to document that with_tags calls copy under the hood, so custom op types need to support copy in order to support tags, and leave it at that. For most op types, it'll just work, and for the ones that don't, they can implement __copy__ manually. Yes, using copy always feels a little dirty, but I think it's better than maintaining TaggedOperation or requiring a virtual with_tags to be implemented everywhere.

Sorry for the wall of text!