DAGCircuit._copy_circuit_metadata is widely used and it should be public (Qiskit#7803)

* dag._copy_circuit_metadata is not internal anymore

* reno

* docstring

* copy_empty_like

* reno

* Update qiskit/dagcircuit/dagcircuit.py

Co-authored-by: Julien Gacon <[email protected]>

* Update test/python/dagcircuit/test_dagcircuit.py

Co-authored-by: Julien Gacon <[email protected]>

* keeping _copy_circuit_metadata

Co-authored-by: [email protected]

* docstring

* tests and linting

* ups

Co-authored-by: Julien Gacon <[email protected]>
Co-authored-by: Jake Lishman <[email protected]>

Author: 3 people

qiskit/dagcircuit/dagcircuit.py

@@ -36,6 +36,7 @@
 from qiskit.dagcircuit.exceptions import DAGCircuitError
 from qiskit.dagcircuit.dagnode import DAGNode, DAGOpNode, DAGInNode, DAGOutNode
 from qiskit.utils import optionals as _optionals
+from qiskit.utils.deprecation import deprecate_function
 
 
 class DAGCircuit:
@@ -491,8 +492,28 @@ def _add_op_node(self, op, qargs, cargs):
         self._increment_op(op)
         return node_index
 
+    @deprecate_function(
+        """The DAGCircuit._copy_circuit_metadata method is deprecated as of 0.20.0. It will be removed
+        no earlier than 3 months after the release date. You should use the DAGCircuit.copy_empty_like
+        method instead, which acts identically.
+        """
+    )
     def _copy_circuit_metadata(self):
-        """Return a copy of source_dag with metadata but empty."""
+        """DEPRECATED"""
+        return self.copy_empty_like()
+
+    def copy_empty_like(self):
+        """Return a copy of self with the same structure but empty.
+
+        That structure includes:
+            * name and other metadata
+            * global phase
+            * duration
+            * all the qubits and clbits, including the registers.
+
+        Returns:
+            DAGCircuit: An empty copy of self.
+        """
         target_dag = DAGCircuit()
         target_dag.name = self.name
         target_dag._global_phase = self._global_phase
@@ -1550,7 +1571,7 @@ def layers(self):
                 return
 
             # Construct a shallow copy of self
-            new_layer = self._copy_circuit_metadata()
+            new_layer = self.copy_empty_like()
 
             for node in op_nodes:
                 # this creates new DAGOpNodes in the new_layer
@@ -1570,7 +1591,7 @@ def serial_layers(self):
         same structure as in layers().
         """
         for next_node in self.topological_op_nodes():
-            new_layer = self._copy_circuit_metadata()
+            new_layer = self.copy_empty_like()
 
             # Save the support of the operation we add to the layer
             support_list = []

qiskit/transpiler/passes/routing/basic_swap.py

@@ -55,7 +55,7 @@ def run(self, dag):
         if self.fake_run:
             return self.fake_run(dag)
 
-        new_dag = dag._copy_circuit_metadata()
+        new_dag = dag.copy_empty_like()
 
         if len(dag.qregs) != 1 or dag.qregs.get("q", None) is None:
             raise TranspilerError("Basic swap runs on physical circuits only")

qiskit/transpiler/passes/routing/lookahead_swap.py

@@ -141,7 +141,7 @@ def run(self, dag):
             return dag
 
         # Preserve input DAG's name, regs, wire_map, etc. but replace the graph.
-        mapped_dag = dag._copy_circuit_metadata()
+        mapped_dag = dag.copy_empty_like()
 
         for node in mapped_gates:
             mapped_dag.apply_operation_back(op=node.op, qargs=node.qargs, cargs=node.cargs)

qiskit/transpiler/passes/routing/sabre_swap.py

@@ -161,7 +161,7 @@ def run(self, dag):
         # Preserve input DAG's name, regs, wire_map, etc. but replace the graph.
         mapped_dag = None
         if not self.fake_run:
-            mapped_dag = dag._copy_circuit_metadata()
+            mapped_dag = dag.copy_empty_like()
 
         canonical_register = dag.qregs["q"]
         current_layout = Layout.generate_trivial_layout(canonical_register)

qiskit/transpiler/passes/routing/stochastic_swap.py

@@ -275,7 +275,7 @@ def _mapper(self, circuit_graph, coupling_graph, trials=20):
         # qregs and cregs as the input circuit
         dagcircuit_output = None
         if not self.fake_run:
-            dagcircuit_output = circuit_graph._copy_circuit_metadata()
+            dagcircuit_output = circuit_graph.copy_empty_like()
 
         logger.debug("trivial_layout = %s", layout)
 

qiskit/transpiler/passes/utils/merge_adjacent_barriers.py

@@ -69,7 +69,7 @@ def run(self, dag):
             return dag
 
         # add the merged barriers to a new DAG
-        new_dag = dag._copy_circuit_metadata()
+        new_dag = dag.copy_empty_like()
 
         # go over current nodes, and add them to the new dag
         for node in dag.topological_op_nodes():

releasenotes/notes/_copy_circuit_metadata-a9d03e699118dba2.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    
+    The a new method :meth:`qiskit.dagcircuit.DAGCircuit.copy_empty_like` allows to create a new
+    :class:`qiskit.dagcircuit.DAGCircuit` with the same structure but empty.
+    This method is the same as the previously internal method `_copy_circuit_metadata`.

test/python/dagcircuit/test_dagcircuit.py

@@ -254,6 +254,8 @@ class TestDagWireRemoval(QiskitTestCase):
     def setUp(self):
         super().setUp()
         self.dag = DAGCircuit()
+        self.dag.name = "Name"
+        self.dag.metadata = "Metadata"
         qreg = QuantumRegister(3, "qr")
         creg0 = ClassicalRegister(2, "c0")
         creg1 = ClassicalRegister(2, "c1")
@@ -346,6 +348,18 @@ def test_remove_idle_clbit(self):
         self.assert_cregs_equal(self.original_cregs)
         self.assert_clbits_equal(self.original_clbits, excluding={self.individual_clbit})
 
+    def test_copy_circuit_metadata(self):
+        """Copy dag circuit metadata with copy_empty_like."""
+        result_dag = self.dag.copy_empty_like()
+        self.assertEqual(self.dag.name, result_dag.name)
+        self.assertEqual(self.dag.metadata, result_dag.metadata)
+        self.assertEqual(self.dag.clbits, result_dag.clbits)
+        self.assertEqual(self.dag.qubits, result_dag.qubits)
+        self.assertEqual(self.dag.cregs, result_dag.cregs)
+        self.assertEqual(self.dag.qregs, result_dag.qregs)
+        self.assertEqual(self.dag.duration, result_dag.duration)
+        self.assertEqual(self.dag.unit, result_dag.unit)
+
     def test_remove_busy_clbit(self):
         """Classical bit removal of busy classical bits raises."""
         self.dag.apply_operation_back(Measure(), [self.qreg[0]], [self.individual_clbit])