Add infrastructure for gates, instruction, and operations in Rust

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 enum
StandardGate. The enum representation is much more efficient and has a
minimal memory footprint as all the gate properties are defined in 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 and hopefully in Qiskit 2.0 we'll be able to drop, unit, duration,
and condition from the api leaving only label and parameters.

When an object is added to a CircuitInstruction the operation field is
translated to it's internal representation automatically. For standard
gates this translates it to the enum form, and for Python defined gates
this involves just wrapping them. Then whenever the operation field of
a circuit instruction object is read from python it converts it back to
the normal Python object representation.

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.

TODO:

- [ ] Fix parameter handling on copy (might involve moving parameter
  table to rust)
- [ ] Handle global phase in definitions (might mean moving a
  QuantumCircuit struct to rust instead of just CircuitData)
- [ ] Add definitions for gates migrated so far

Fixes: Qiskit#12205

Author: mtreinish

Cargo.lock

@@ -16,6 +16,11 @@ license = "Apache-2.0"
 [workspace.dependencies]
 indexmap.version = "2.2.6"
 hashbrown.version = "0.14.0"
+num-complex = "0.4"
+ndarray = "^0.15.6"
+numpy = "0.21.0"
+smallvec = "1.13"
+
 # Most of the crates don't need the feature `extension-module`, since only `qiskit-pyext` builds an
 # actual C extension (the feature disables linking in `libpython`, which is forbidden in Python
 # distributions).  We only activate that feature when building the C extension module; we still need

Cargo.toml

@@ -11,29 +11,29 @@ doctest = false
 
 [dependencies]
 rayon = "1.10"
-numpy = "0.21.0"
+numpy.workspace = true
 rand = "0.8"
 rand_pcg = "0.3"
 rand_distr = "0.4.3"
 ahash = "0.8.11"
 num-traits = "0.2"
-num-complex = "0.4"
+num-complex.workspace = true
 num-bigint = "0.4"
 rustworkx-core = "0.14"
 faer = "0.18.2"
 itertools = "0.12.1"
 qiskit-circuit.workspace = true
 
 [dependencies.smallvec]
-version = "1.13"
+workspace = true
 features = ["union"]
 
 [dependencies.pyo3]
 workspace = true
 features = ["hashbrown", "indexmap", "num-complex", "num-bigint", "smallvec"]
 
 [dependencies.ndarray]
-version = "^0.15.6"
+workspace = true
 features = ["rayon", "approx-0_5"]
 
 [dependencies.approx]

crates/accelerate/Cargo.toml

@@ -11,4 +11,15 @@ doctest = false
 
 [dependencies]
 hashbrown.workspace = true
-pyo3.workspace = true
+num-complex.workspace = true
+ndarray.workspace = true
+numpy.workspace = true
+lazy_static = "1.4"
+
+[dependencies.pyo3]
+workspace = true
+features = ["hashbrown", "indexmap", "num-complex", "num-bigint", "smallvec"]
+
+[dependencies.smallvec]
+workspace = true
+features = ["union"]

crates/circuit/Cargo.toml

@@ -10,9 +10,14 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
-use crate::circuit_instruction::CircuitInstruction;
+use crate::circuit_instruction::{
+    convert_py_to_operation_type, operation_type_and_data_to_py, CircuitInstruction,
+};
 use crate::intern_context::{BitType, IndexType, InternContext};
 use crate::SliceOrInt;
+use smallvec::SmallVec;
+
+use crate::operations::{OperationType, Param};
 
 use hashbrown::HashMap;
 use pyo3::exceptions::{PyIndexError, PyKeyError, PyRuntimeError, PyValueError};
@@ -25,11 +30,16 @@ use std::hash::{Hash, Hasher};
 #[derive(Clone, Debug)]
 struct PackedInstruction {
     /// The Python-side operation instance.
-    op: PyObject,
+    op: OperationType,
     /// The index under which the interner has stored `qubits`.
     qubits_id: IndexType,
     /// The index under which the interner has stored `clbits`.
     clbits_id: IndexType,
+    params: Option<SmallVec<[Param; 3]>>,
+    label: Option<String>,
+    duration: Option<PyObject>,
+    unit: Option<String>,
+    condition: Option<PyObject>,
 }
 
 /// Private wrapper for Python-side Bit instances that implements
@@ -154,6 +164,71 @@ pub struct CircuitData {
     clbits: Py<PyList>,
 }
 
+impl CircuitData {
+    /// A helper method to build a new CircuitData from an owned definition
+    /// as a slice of OperationType, parameters, and qubits.
+    pub fn build_new_from(
+        py: Python,
+        num_qubits: usize,
+        num_clbits: usize,
+        instructions: &[(OperationType, &[Param], &[u32])],
+    ) -> PyResult<Self> {
+        let mut res = CircuitData {
+            data: Vec::with_capacity(instructions.len()),
+            intern_context: InternContext::new(),
+            qubits_native: Vec::with_capacity(num_qubits),
+            clbits_native: Vec::with_capacity(num_clbits),
+            qubit_indices_native: HashMap::with_capacity(num_qubits),
+            clbit_indices_native: HashMap::with_capacity(num_clbits),
+            qubits: PyList::empty_bound(py).unbind(),
+            clbits: PyList::empty_bound(py).unbind(),
+        };
+        if num_qubits > 0 {
+            let qubit_mod = py.import_bound("qiskit.circuit.quantumregister")?;
+            let qubit_cls = qubit_mod.getattr("Qubit")?;
+            for _i in 0..num_qubits {
+                let bit = qubit_cls.call0()?;
+                res.add_qubit(py, &bit, true)?;
+            }
+        }
+        if num_clbits > 0 {
+            let clbit_mod = py.import_bound("qiskit.circuit.classicalregister")?;
+            let clbit_cls = clbit_mod.getattr("Clbit")?;
+            for _i in 0..num_clbits {
+                let bit = clbit_cls.call0()?;
+                res.add_clbit(py, &bit, true)?;
+            }
+        }
+        for (operation, params, qargs) in instructions {
+            let qubits = PyTuple::new_bound(
+                py,
+                qargs
+                    .iter()
+                    .map(|x| res.qubits_native[*x as usize].clone_ref(py))
+                    .collect::<Vec<PyObject>>(),
+            )
+            .unbind();
+            let empty: [u8; 0] = [];
+            let clbits = PyTuple::new_bound(py, empty);
+            let inst = res.pack_owned(
+                py,
+                &CircuitInstruction {
+                    operation: operation.clone(),
+                    qubits,
+                    clbits: clbits.into(),
+                    params: Some(params.iter().cloned().collect()),
+                    label: None,
+                    duration: None,
+                    unit: None,
+                    condition: None,
+                },
+            )?;
+            res.data.push(inst);
+        }
+        Ok(res)
+    }
+}
+
 #[pymethods]
 impl CircuitData {
     #[new]
@@ -366,7 +441,15 @@ impl CircuitData {
     #[pyo3(signature = (func))]
     pub fn foreach_op(&self, py: Python<'_>, func: &Bound<PyAny>) -> PyResult<()> {
         for inst in self.data.iter() {
-            func.call1((inst.op.bind(py),))?;
+            match &inst.op {
+                OperationType::Standard(op) => {
+                    let op = op.into_py(py);
+                    func.call1((op,))
+                }
+                OperationType::Instruction(op) => func.call1((op.instruction.clone_ref(py),)),
+                OperationType::Gate(op) => func.call1((op.gate.clone_ref(py),)),
+                OperationType::Operation(op) => func.call1((op.operation.clone_ref(py),)),
+            }?;
         }
         Ok(())
     }
@@ -380,7 +463,15 @@ impl CircuitData {
     #[pyo3(signature = (func))]
     pub fn foreach_op_indexed(&self, py: Python<'_>, func: &Bound<PyAny>) -> PyResult<()> {
         for (index, inst) in self.data.iter().enumerate() {
-            func.call1((index, inst.op.bind(py)))?;
+            match &inst.op {
+                OperationType::Standard(op) => {
+                    let op = op.into_py(py);
+                    func.call1((index, op))
+                }
+                OperationType::Instruction(op) => func.call1((index, op.instruction.clone_ref(py))),
+                OperationType::Gate(op) => func.call1((index, op.gate.clone_ref(py))),
+                OperationType::Operation(op) => func.call1((index, op.operation.clone_ref(py))),
+            }?;
         }
         Ok(())
     }
@@ -395,7 +486,30 @@ impl CircuitData {
     #[pyo3(signature = (func))]
     pub fn map_ops(&mut self, py: Python<'_>, func: &Bound<PyAny>) -> PyResult<()> {
         for inst in self.data.iter_mut() {
-            inst.op = func.call1((inst.op.bind(py),))?.into_py(py);
+            let new_op = match &inst.op {
+                OperationType::Standard(_op) => {
+                    let op = operation_type_and_data_to_py(
+                        py,
+                        &inst.op,
+                        &inst.params,
+                        &inst.label,
+                        &inst.duration,
+                        &inst.unit,
+                    )?;
+                    func.call1((op,))
+                }
+                OperationType::Instruction(op) => func.call1((op.instruction.clone_ref(py),)),
+                OperationType::Gate(op) => func.call1((op.gate.clone_ref(py),)),
+                OperationType::Operation(op) => func.call1((op.operation.clone_ref(py),)),
+            }?;
+
+            let new_inst_details = convert_py_to_operation_type(py, new_op.into())?;
+            inst.op = new_inst_details.operation;
+            inst.params = new_inst_details.params;
+            inst.label = new_inst_details.label;
+            inst.duration = new_inst_details.duration;
+            inst.unit = new_inst_details.unit;
+            inst.condition = new_inst_details.condition;
         }
         Ok(())
     }
@@ -666,9 +780,14 @@ impl CircuitData {
                     .collect::<PyResult<Vec<BitType>>>()?;
 
                 self.data.push(PackedInstruction {
-                    op: inst.op.clone_ref(py),
+                    op: inst.op.clone(),
                     qubits_id: self.intern_context.intern(qubits)?,
                     clbits_id: self.intern_context.intern(clbits)?,
+                    params: inst.params.clone(),
+                    label: inst.label.clone(),
+                    duration: inst.duration.clone(),
+                    unit: inst.unit.clone(),
+                    condition: inst.condition.clone(),
                 });
             }
             return Ok(());
@@ -720,7 +839,7 @@ impl CircuitData {
 
     fn __traverse__(&self, visit: PyVisit<'_>) -> Result<(), PyTraverseError> {
         for packed in self.data.iter() {
-            visit.call(&packed.op)?;
+            visit.call(&packed.duration)?;
         }
         for bit in self.qubits_native.iter().chain(self.clbits_native.iter()) {
             visit.call(bit)?;
@@ -820,17 +939,51 @@ impl CircuitData {
                 self.intern_context.intern(args)
             };
         Ok(PackedInstruction {
-            op: inst.operation.clone_ref(py),
+            op: inst.operation.clone(),
+            qubits_id: interned_bits(&self.qubit_indices_native, inst.qubits.bind(py))?,
+            clbits_id: interned_bits(&self.clbit_indices_native, inst.clbits.bind(py))?,
+            params: inst.params.clone(),
+            label: inst.label.clone(),
+            duration: inst.duration.clone(),
+            unit: inst.unit.clone(),
+            condition: inst.condition.clone(),
+        })
+    }
+
+    fn pack_owned(&mut self, py: Python, inst: &CircuitInstruction) -> PyResult<PackedInstruction> {
+        let mut interned_bits =
+            |indices: &HashMap<BitAsKey, BitType>, bits: &Bound<PyTuple>| -> PyResult<IndexType> {
+                let args = bits
+                    .into_iter()
+                    .map(|b| {
+                        let key = BitAsKey::new(&b)?;
+                        indices.get(&key).copied().ok_or_else(|| {
+                            PyKeyError::new_err(format!(
+                                "Bit {:?} has not been added to this circuit.",
+                                b
+                            ))
+                        })
+                    })
+                    .collect::<PyResult<Vec<BitType>>>()?;
+                self.intern_context.intern(args)
+            };
+        Ok(PackedInstruction {
+            op: inst.operation.clone(),
             qubits_id: interned_bits(&self.qubit_indices_native, inst.qubits.bind(py))?,
             clbits_id: interned_bits(&self.clbit_indices_native, inst.clbits.bind(py))?,
+            params: inst.params.clone(),
+            label: inst.label.clone(),
+            duration: inst.duration.clone(),
+            unit: inst.unit.clone(),
+            condition: inst.condition.clone(),
         })
     }
 
     fn unpack(&self, py: Python<'_>, inst: &PackedInstruction) -> PyResult<Py<CircuitInstruction>> {
         Py::new(
             py,
             CircuitInstruction {
-                operation: inst.op.clone_ref(py),
+                operation: inst.op.clone(),
                 qubits: PyTuple::new_bound(
                     py,
                     self.intern_context
@@ -849,6 +1002,11 @@ impl CircuitData {
                         .collect::<Vec<_>>(),
                 )
                 .unbind(),
+                params: inst.params.clone(),
+                label: inst.label.clone(),
+                duration: inst.duration.clone(),
+                unit: inst.unit.clone(),
+                condition: inst.condition.clone(),
             },
         )
     }