Add infrastructure for gates, instruction, and operations in Rust

[mtreinish]

Summary

This commit adds a native representation of Gates, Instruction, and Operations to rust's circuit module. At a high level this works by either wrapping the Python object in a rust wrapper struct that tracks metadata about the operations (name, num_qubits, etc) and then for other details it calls back to Python to get dynamic details like the definition, matrix, etc. For standard library gates like Swap, CX, H, etc this replaces the on-circuit representation with a new rust enum StandardGate. The enum representation is much more efficient and has a minimal memory footprint (just the enum variant and then any parameters or other mutable state stored in the circuit instruction). All the gate properties such as the matrix, definiton, name, etc are statically defined in rust code based on the enum variant (which represents the gate).

The use of an enum to represent standard gates does mean a change in what we store on a CircuitInstruction. To represent a standard gate fully we need to store the mutable properties of the existing Gate class on the circuit instruction as the gate by itself doesn't contain this detail. That means, the parameters, label, unit, duration, and condition are added to the rust side of circuit instrucion. However no Python side access methods are added for these as they're internal only to the Rust code. In Qiskit 2.0 to simplify this storage we'll be able to drop, unit, duration, and condition from the api leaving only label and parameters. But for right now we're tracking all of the fields.

To facilitate working with circuits and gates full from rust the setting the operation attribute of a CircuitInstruction object now transltates the python object to an internal rust representation. For standard gates this translates it to the enum form described earlier, and for other circuit operations 3 new Rust structs: PyGate, PyInstruction, and PyOperation are used to wrap the underlying Python object in a Rust api. These structs cache some commonly accessed static properties of the operation, such as the name, number of qubits, etc. However for dynamic pieces, such as the definition or matrix, callback to python to get a rust representation for those.

Similarly whenever the operation attribute is accessed from Python it converts it back to the normal Python object representation. For standard gates this involves creating a new instance of a Python object based on it's internal rust representation. For the wrapper structs a reference to the wrapped PyObject is returned.

To manage the 4 variants of operation (StandardGate, PyGate, PyInstruction, and PyOperation) a new Rust trait Operation is created that defines a standard interface for getting the properties of a given circuit operation. This common interface is implemented for the 4 variants as well as the OperationType enum which wraps all 4 (and is used as the type for CircuitInstruction.operation in the rust code.

As everything in the QuantumCircuit data model is quite coupled moving the source of truth for the operations to exist in Rust means that more of the underlying QuantumCircuit's responsibility has to move to Rust as well. Primarily this involves the ParameterTable which was an internal class for tracking which instructions in the circuit have a ParameterExpression parameter so that when we go to bind parameters we can lookup which operations need to be updated with the bind value. Since the representation of those instructions now lives in Rust and Python only recieves a ephemeral copy of the instructions the ParameterTable had to be reimplemented in Rust to track the instructions. This new parameter table maps the Parameter's uuid (as a u128) as a unique identifier for each parameter and maps this to a positional index in the circuit data to the underlying instruction using that parameter. This is a bit different from the Python parameter table which was mapping a parameter object to the id of the operation object using that parmaeter. This also leads to a difference in the binding mechanics as the parameter assignment was done by reference in the old model, but now we need to update the entire instruction more explicitly in rust. Additionally, because the global phase of a circuit can be parameterized the ownership of global phase is moved from Python into Rust in this commit as well.

After this commit the only properties of a circuit that are not defined in Rust for the source of truth are the bits (and vars) of the circuit, and when creating circuits from rust this is what causes a Python interaction to still be required.

This commit does not translate the full standard library of gates as that would make the pull request huge, instead this adds the basic infrastructure for having a more efficient standard gate representation on circuits. There will be follow up pull requests to add the missing gates and round out support in rust.

The goal of this pull request is primarily to add the infrastructure for representing the full circuit model (and dag model in the future) in rust. By itself this is not expected to improve runtime performance (if anything it will probably hurt performance because of extra type conversions) but it is intended to enable writing native circuit manipulations in Rust, including transpiler passes without needing involvement from Python. Longer term this should greatly improve the runtime performance and reduce the memory overhead of Qiskit. But, this is just an early step towards that goal, and is more about unlocking the future capability. The next steps after this commit are to finish migrating the standard gate library and also update the QuantumCircuit methods to better leverage the more complete rust representation (which should help offset the performance penalty introduced by this).

Details and comments

Fixes: #12205

TODO:

• Fix last few unit test failures
• Profile and optimize performance (this is currently needlessly inefficient now, especially for some of the python access patterns; imports need to be cached, etc)
• Improve documentation around new rust APIs

[qiskit-bot]

One or more of the following people are relevant to this code:

• @Eric-Arellano
• @Cryoris
• @Qiskit/terra-core
• @ajavadia
• @kevinhartman
• @mtreinish

[mtreinish]

Oh, those neko failures are interesting and unexpected (I was expecting the 6 unit test failures in terra's unit tests). Looking at it I think this is the same case of something I hit in the nlocal parameter tests. The underlying issue is that for the type of the elements of param vector in rust I defined basically the following type:

#[derive(FromPyObject)]
enum Param {
    Float(f64),
    ParameterExpression(PyObject)
}

and the issue is the derive FromPyObject implementation is eagerly trying to cast the input as a float first to determine if it should match that arm. When someone defines a ParameterExpression like:

p = Parameter('p')
expression = p * 0

and then uses expression as a gate parameter, the float check will simplify the expression at circuit insertion time instead of preserving the parameter expression. Prior to this PR that normalization to a float would occur only after binding and not at insertion time. I hit this exact case in the nlocal tests and just worked around it by changing the test to be 1 * param instead of multiplying by zero because I figured it was a pathological edge case and arguably a test bug, because in practice nobody would actually do that, and if they did they wouldn't care that parm disappeared because it was meaningless. But, it appears that the neko tests are doing this too so maybe it's better to fix this for real. The best way would probably to stop deriving FromPyObject and manually implement it for Param to first check if the input is a ParameterExpression, then try a float, lastly fall back to a PyObject (this is necessary for custom instruction types that define their own parameter types, UnitaryGate being an example). I guess this has the advantage of being able to distinguish between a ParameterExpression and a generic object at insertion time which will simplify the parameter table logic (which was doing this differentiation explicitly).

[coveralls]

Pull Request Test Coverage Report for Build 9496969108

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 1625 of 1931 (84.15%) changed or added relevant lines in 38 files are covered.
• 138 unchanged lines in 12 files lost coverage.
• Overall coverage decreased (-0.2%) to 89.415%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/circuit/quantumcircuit.py	97	99	97.98%
crates/circuit/src/interner.rs	0	3	0.0%
crates/circuit/src/imports.rs	38	45	84.44%
crates/circuit/src/parameter_table.rs	90	100	90.0%
crates/circuit/src/circuit_instruction.rs	452	470	96.17%
crates/circuit/src/circuit_data.rs	480	538	89.22%
crates/circuit/src/operations.rs	298	506	58.89%

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/two_qubit_decompose.rs	1	88.51%
crates/qasm2/src/lex.rs	2	92.62%
qiskit/circuit/parameterexpression.py	2	96.54%
qiskit/circuit/parametervector.py	3	94.44%
qiskit/transpiler/passmanager.py	8	94.15%
qiskit/user_config.py	8	88.54%
qiskit/providers/providerutils.py	10	48.48%
qiskit/synthesis/one_qubit/one_qubit_decompose.py	11	79.52%
crates/qasm2/src/parse.rs	18	96.69%
qiskit/visualization/circuit/circuit_visualization.py	23	73.43%

Totals
Change from base Build 9418156791:	-0.2%
Covered Lines:	63821
Relevant Lines:	71376

---

💛 - Coveralls