Add custom DAGCircuit.__deepcopy__ implementation (Qiskit#14965)

Previously we were relying on the pickling behaviour.  This was
desperately slow, and gets slower over time as more of our data is Rust
native and need to be serialised to and from Python in order to interact
with pickle.

Instead, we can use the `Clone` implementation of `StableGraph`, which
preserves node and edge ids (including holes), then only thread through
the deepcopy nature to the few parts of the data model where we still
store Python objects.  In casual testing, this sped up a microbenchmark:

```python
import copy
from qiskit.converters import circuit_to_dag
from qiskit.circuit.library import quantum_volume

qv = quantum_volume(100, 100, seed=1).decompose()
dag = circuit_to_dag(qv)
%timeit copy.deepcopy(dag)
```

from about 1.05s to 6ms on my machine.

This is directly relevant for the performance of `optimization_level=3`,
which needs to deepcopy as part of its `MinimumPoint` check in the
optimisation loop.

Author: jakelishman

crates/circuit/src/dag_circuit.rs

@@ -984,6 +984,34 @@ impl DAGCircuit {
         Ok(())
     }
 
+    pub fn __copy__(&self) -> Self {
+        self.clone()
+    }
+
+    pub fn __deepcopy__<'py>(
+        &self,
+        py: Python<'py>,
+        memo: Option<&Bound<'py, PyDict>>,
+    ) -> PyResult<Self> {
+        let mut out = self.clone();
+        let deepcopy = imports::DEEPCOPY.get_bound(py);
+        // We only need to pass the deep-copying nature on to places where we store Python objects.
+        out.metadata = out
+            .metadata
+            .map(|dict| deepcopy.call1((dict, memo)).map(|ob| ob.unbind()))
+            .transpose()?;
+        out.duration = out
+            .duration
+            .map(|dict| deepcopy.call1((dict, memo)).map(|ob| ob.unbind()))
+            .transpose()?;
+        for node in out.dag.node_weights_mut() {
+            if let NodeType::Operation(inst) = node {
+                inst.py_deepcopy_inplace(py, memo)?;
+            };
+        }
+        Ok(out)
+    }
+
     /// Returns the current sequence of registered :class:`.Qubit` instances as a list.
     ///
     /// .. warning::

crates/circuit/src/operations.rs

@@ -213,6 +213,20 @@ impl Param {
             Param::Obj(obj) => Param::Obj(obj.clone_ref(py)),
         }
     }
+
+    pub fn py_deepcopy<'py>(
+        &self,
+        py: Python<'py>,
+        memo: Option<&Bound<'py, PyDict>>,
+    ) -> PyResult<Self> {
+        match self {
+            Param::Float(f) => Ok(Param::Float(*f)),
+            _ => DEEPCOPY
+                .get_bound(py)
+                .call1((self.clone(), memo))?
+                .extract(),
+        }
+    }
 }
 
 // This impl allows for shared usage between [Param] and &[Param].

crates/circuit/src/packed_instruction.rs

@@ -14,7 +14,7 @@
 use std::sync::OnceLock;
 
 use pyo3::prelude::*;
-use pyo3::types::PyType;
+use pyo3::types::{PyDict, PyType};
 
 use ndarray::Array2;
 use num_complex::Complex64;
@@ -24,8 +24,8 @@ use crate::circuit_data::CircuitData;
 use crate::imports::{get_std_gate_class, BARRIER, DELAY, MEASURE, RESET, UNITARY_GATE};
 use crate::interner::Interned;
 use crate::operations::{
-    Operation, OperationRef, Param, PyGate, PyInstruction, PyOperation, StandardGate,
-    StandardInstruction, UnitaryGate,
+    Operation, OperationRef, Param, PyGate, PyInstruction, PyOperation, PythonOperation,
+    StandardGate, StandardInstruction, UnitaryGate,
 };
 use crate::{Clbit, Qubit};
 
@@ -767,4 +767,24 @@ impl PackedInstruction {
             _ => Ok(false),
         }
     }
+
+    pub fn py_deepcopy_inplace<'py>(
+        &mut self,
+        py: Python<'py>,
+        memo: Option<&Bound<'py, PyDict>>,
+    ) -> PyResult<()> {
+        match self.op.view() {
+            OperationRef::Gate(gate) => self.op = gate.py_deepcopy(py, memo)?.into(),
+            OperationRef::Instruction(inst) => self.op = inst.py_deepcopy(py, memo)?.into(),
+            OperationRef::Operation(op) => self.op = op.py_deepcopy(py, memo)?.into(),
+            _ => (),
+        };
+        for param in self.params_mut() {
+            *param = param.py_deepcopy(py, memo)?;
+        }
+        #[cfg(feature = "cache_pygates")]
+        self.py_op.take();
+
+        Ok(())
+    }
 }

releasenotes/notes/dag-deepcopy-db6e6823b0f5fb56.yaml

@@ -0,0 +1,6 @@
+---
+features_transpiler:
+  - |
+    :class:`.DAGCircuit` now has a manual implementation of :meth:`~object.__deepcopy__`.  This is
+    orders of magnitude faster than the previous implicit implementation from the pickle protocol,
+    especially for large circuits, and directly benefits compilation at `optimization_level=3`.