Port control-flow operations to Rust.

[kevinhartman]

Summary

Ports control flow operations to Rust with automatic conversion of blocks into and out of DAGCircuit.

Control flow instructions can be accessed by calling a view method of an instruction type, which provides the following view:

pub enum ControlFlowView<'a, T> {
    Box(Option<&'a Duration>, &'a T),
    BreakLoop,
    ContinueLoop,
    ForLoop {
        indexset: &'a [usize],
        loop_param: Option<&'a PyObject>,
        body: &'a T,
    },
    IfElse {
        condition: &'a Condition,
        true_body: &'a T,
        false_body: Option<&'a T>,
    },
    Switch {
        target: &'a Target,
        cases_specifier: Vec<(&'a Vec<CaseSpecifier>, &'a T)>,
    },
    While {
        condition: &'a Condition,
        body: &'a T,
    },
}

The block type T is dependent on the source of the instruction, namely whether it's a PackedInstruction or a DAGInstruction (new).

Details and comments

There are a lot of changes here in support of this. The big ones are:

• A new Parameters enum type to represent parameter lists specific to the operation in question. Previously, we used duck-typing per-parameter, which has been a pain-point for us. The Param type still exists for use with gates, but we should be able to remove the Obj catch-all type from it so that it's purely numeric.
• The DAGCircuit now uses its own instruction type DAGInstruction instead of PackedInstruction. This is to accommodate the storage requirements of DAG instructions storing their blocks as DAGCircuits, but it seems likely we'll want custom storage for DAG instructions in the future anyways.
• There's now an Instruction trait which represents something that is equivalent/convertible to our Python-space instruction. It is implemented for CircuitInstruction, PackedInstruction, OperationFromPython and NormalOperation. The circuit_instruction mod provides a blanket implementation of create_py_op for all of these via the CreatePythonOperation trait, which sits next to FromPythonOperation.
• Similar to OperationRef, there is now an InstructionView enum that provides an ergonomic immutable view of our instruction types. The benefit of this is obvious for control flow (shown above), but it's also the thing that will allow us to get rid of duck-typing for gates. The trait IntoInstructionView is implemented for all of our (&)instruction types, and provides all of these views.
• Methods like matrix and definition have been moved out of Operation and thus no longer need the duck-typed params to be threaded in.

To-do

• I can't port DAGCircuit::compose's use of control flow to Rust until Oxidize VariableMapper and uses. #14361 merges. I also need this to merge before I can implement semantic equality for Condition and Target (I believe this is responsible for the majority of the still-failing tests).
• Add more context to this description to cover alternatives considered. This probably isn't the simplest approach we could take implementation-wise, but it seemed like the right direction to me and I'd like others to have that context before reading a 4K diff.
• Address clean-up TODOs scattered throughout.

[raynelfss]

I was snooping around the code just to take a look at what's up ahead. No big suggestions here, if anything just questions.

[raynelfss]

What's the difference between this and OperationRef? I assume that this one having a specific lifetime attached to it at all times allows something that OperationRef doesn't.

[kevinhartman]

The difference is pretty much that this represents an operation alongside its parameters, whereas an OperationRef is just the operation. All of these variants have references to the data they need from their parameter list baked in.

It's called InstructionView instead of InstructionRef because it's a heavier-weight thing—the variants here typically hold references to more than just one thing, e.g. ControlfFlowView::IfElse holds references to its condition (which happens to come from the underlying operation) and to its true and false blocks.

[raynelfss]

If this already Derefs into a UnitaryGate, meaning that it inherits the methods, is there any need for the inner part to still be pub?

[kevinhartman]

The UnitaryGateView in its current form is mostly just here as an example, and isn't really something that needs to be present in the final version of this PR (we can put a UnitaryGate ref here instead).

When we added native support for UnitaryGate, we ended up putting its parameter (the matrix) directly into the operation to avoid needing another variant on Param that would seldom be applicable. But with the changes in this PR, we could potentially move the matrix to Parameters and still have the same nice interface via UnitaryGateView.

[raynelfss]

Is this going to stay like this once #14207 merges?

[kevinhartman]

Yeah, this shouldn't need to change. These are different from ParameterExpression and the Python-side Parameter (which inherits from ParameterExpression).

This is more like an enumeration of the various parameter lists that we support for a given instruction.

[raynelfss]

I'm assuming that PyObject is a placeholder until #14207 has merged

[kevinhartman]

It is indeed a placeholder, but this is for the block type of control flow operations. So eventually, this would be Parameters<CircuitData> (once a CircuitData can losslessly represent a control flow block).