Deprecate circuit.combine and circuit.extend

qiskit/circuit/quantumcircuit.py

@@ -278,7 +278,7 @@ def inverse(self):
         return inverse_circ
 
     def combine(self, rhs):
-        """Append rhs to self if self contains compatible registers.
+        """DEPRECATED - Append rhs to self if self contains compatible registers.
 
         Two circuits are compatible if they contain the same registers
         or if they contain different registers with unique names. The
@@ -299,23 +299,13 @@ def combine(self, rhs):
         # Check registers in LHS are compatible with RHS
         self._check_compatible_regs(rhs)
 
-        # Make new circuit with combined registers
-        combined_qregs = copy.deepcopy(self.qregs)
-        combined_cregs = copy.deepcopy(self.cregs)
-
-        for element in rhs.qregs:
-            if element not in self.qregs:
-                combined_qregs.append(element)
-        for element in rhs.cregs:
-            if element not in self.cregs:
-                combined_cregs.append(element)
-        circuit = QuantumCircuit(*combined_qregs, *combined_cregs)
-        for instruction_context in itertools.chain(self.data, rhs.data):
-            circuit._append(*instruction_context)
-        return circuit
+        warnings.warn("The QuantumCircuit.combine() method is being deprecated."
+                      "Use the compose() method which is more flexible w.r.t "
+                      "circuit register compatibility.", DeprecationWarning)
+        return self.compose(rhs)
 
     def extend(self, rhs):
-        """Append QuantumCircuit to the right hand side if it contains compatible registers.
+        """DEPRECATED - Append QuantumCircuit to the RHS if it contains compatible registers.
 
         Two circuits are compatible if they contain the same registers
         or if they contain different registers with unique names. The
@@ -336,22 +326,44 @@ def extend(self, rhs):
         # Check registers in LHS are compatible with RHS
         self._check_compatible_regs(rhs)
 
-        # Add new registers
-        for element in rhs.qregs:
-            if element not in self.qregs:
-                self.qregs.append(element)
-        for element in rhs.cregs:
-            if element not in self.cregs:
-                self.cregs.append(element)
-
-        # Copy the circuit data if rhs and self are the same, otherwise the data of rhs is
-        # appended to both self and rhs resulting in an infinite loop
-        data = rhs.data.copy() if rhs is self else rhs.data
-
-        # Add new gates
-        for instruction_context in data:
-            self._append(*instruction_context)
-        return self
+        warnings.warn("The QuantumCircuit.extend() method is being deprecated."
+                      "Use the compose() method which is more flexible w.r.t "
+                      "circuit register compatibility.", DeprecationWarning)
+        return self.compose(rhs)
+
+    def compose(self, other, qubits=None, clbits=None, front=False, inplace=False):
+        """Compose circuit with ``other`` circuit, optionally permuting wires.
+
+        ``other`` can be narrower or of equal width to ``self``.
+
+        Args:
+            other (QuantumCircuit): circuit to compose with self.
+            qubits (list[Qubit|int]): qubits of self to compose onto.
+            clbits (list[Clbit|int]): clbits of self to compose onto.
+            front (bool): If True, front composition will be performed (not implemented yet).
+            inplace (bool): If True, modify the object. Otherwise return composed circuit.
+
+        Returns:
+            QuantumCircuit: the composed circuit (returns None if inplace==True).
+
+        Raises:
+            CircuitError: if composing on the front.
+            QiskitError: if ``other`` is wider or there are duplicate edge mappings.
+        """
+        from qiskit.converters.circuit_to_dag import circuit_to_dag
+        from qiskit.converters.dag_to_circuit import dag_to_circuit
+        if front:
+            raise CircuitError("Front composition of QuantumCircuit not supported yet.")
+
+        dag_self = circuit_to_dag(self)
+        dag_other = circuit_to_dag(other)
+        dag_self.compose(dag_other, qubits=qubits, clbits=clbits, front=front)
+        composed_circuit = dag_to_circuit(dag_self)
+        if inplace:  # FIXME: this is just a hack for inplace to work. Still copies.
+            self.__dict__.update(composed_circuit.__dict__)
+            return None
+        else:
+            return dag_to_circuit(dag_self)
 
     def compose(self, other, qubits=None, clbits=None, front=False, inplace=False):
         """Compose circuit with ``other`` circuit or instruction, optionally permuting wires.
@@ -436,12 +448,13 @@ def clbits(self):
         return [cbit for creg in self.cregs for cbit in creg]
 
     def __add__(self, rhs):
-        """Overload + to implement self.combine."""
-        return self.combine(rhs)
+        """Overload + to compose two circuits and return resulting circuit."""
+        return self.compose(rhs, inplace=False)
 
     def __iadd__(self, rhs):
-        """Overload += to implement self.extend."""
-        return self.extend(rhs)
+        """Overload += to compose with another circuit inplace."""
+        self.compose(rhs, inplace=True)
+        return self
 
     def __len__(self):
         """Return number of operations in circuit."""

qiskit/dagcircuit/dagcircuit.py

@@ -531,6 +531,7 @@ def compose(self, other, edge_map=None, qubits=None, clbits=None, front=False, i
                           "Use qubits and clbits args to specify a list of "
                           "self edges to compose onto.", DeprecationWarning,
                           stacklevel=2)
+
         if qubits is None:
             qubits = []
         if clbits is None:

releasenotes/notes/circuit-compose-c320c4057cd2bb8f.yaml

@@ -0,0 +1,13 @@
+---
+features:
+  - |
+    A new ``compose`` method is added to ``QuantumCircuit``. It allows
+    composition of two quantum circuits without having to turn one into
+    a gate or instruction. It also allows permutations of qubits/clbits
+    at the point of composition, as well as optional inplace modification.
+deprecations:
+  - |
+    The ``DAGCircuit.compose()`` method now takes a list of qubits/clbits
+    that specify the positional order of bits to compose onto. The
+    dictionary-based method of mapping using ``edge_map`` arg is
+    deprecated.

releasenotes/notes/deprecate-circuit-combine-extend-ffc6a073ed114890.yaml

@@ -0,0 +1,7 @@
+---
+deprecations:
+  - |
+    Two ``QuantumCircuit`` methods ``combine()`` and ``extend()`` are deprecated,
+    in favor of ``QuantumCircuit.compose()``. The latter allows more flexibility
+    in composing two circuits that do not have matching registers. It does not,
+    however, automatically add qubits/clbits unlike the deprecated methods.

test/python/basicaer/test_multi_registers_convention.py

@@ -29,7 +29,7 @@ def test_circuit_multi(self):
         creg0 = ClassicalRegister(2, 'c0')
         qreg1 = QuantumRegister(2, 'q1')
         creg1 = ClassicalRegister(2, 'c1')
-        circ = QuantumCircuit(qreg0, qreg1)
+        circ = QuantumCircuit(qreg0, qreg1, creg0, creg1)
         circ.x(qreg0[1])
         circ.x(qreg1[0])
 

test/python/circuit/test_circuit_multi_registers.py

@@ -30,7 +30,7 @@ def test_circuit_multi(self):
         creg0 = ClassicalRegister(2, 'c0')
         qreg1 = QuantumRegister(2, 'q1')
         creg1 = ClassicalRegister(2, 'c1')
-        circ = QuantumCircuit(qreg0, qreg1)
+        circ = QuantumCircuit(qreg0, qreg1, creg0, creg1)
         circ.x(qreg0[1])
         circ.x(qreg1[0])
 
@@ -43,6 +43,8 @@ def test_circuit_multi(self):
         circ2 = QuantumCircuit()
         circ2.add_register(qreg0)
         circ2.add_register(qreg1)
+        circ2.add_register(creg0)
+        circ2.add_register(creg1)
         circ2.x(qreg0[1])
         circ2.x(qreg1[0])
 

test/python/circuit/test_circuit_operations.py

@@ -18,6 +18,7 @@
 from qiskit import BasicAer
 from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
 from qiskit import execute
+from qiskit import QiskitError
 from qiskit.circuit.exceptions import CircuitError
 from qiskit.test import QiskitTestCase
 
@@ -60,24 +61,6 @@ def test_combine_circuit_common(self):
         threshold = 0.04 * shots
         self.assertDictAlmostEqual(counts, target, threshold)
 
-    def test_combine_circuit_different(self):
-        """Test combining two circuits with different registers.
-        """
-        qr = QuantumRegister(2)
-        cr = ClassicalRegister(2)
-        qc1 = QuantumCircuit(qr)
-        qc1.x(qr)
-        qc2 = QuantumCircuit(qr, cr)
-        qc2.measure(qr, cr)
-        new_circuit = qc1 + qc2
-        backend = BasicAer.get_backend('qasm_simulator')
-        shots = 1024
-        result = execute(new_circuit, backend=backend, shots=shots,
-                         seed_simulator=78).result()
-        counts = result.get_counts()
-        target = {'11': shots}
-        self.assertEqual(counts, target)
-
     def test_combine_circuit_fail(self):
         """Test combining two circuits fails if registers incompatible.
 
@@ -91,8 +74,8 @@ def test_combine_circuit_fail(self):
         qc2 = QuantumCircuit(qr2)
         qcr3 = QuantumCircuit(cr1)
 
-        self.assertRaises(CircuitError, qc1.__add__, qc2)
-        self.assertRaises(CircuitError, qc1.__add__, qcr3)
+        self.assertRaises(QiskitError, qc1.__add__, qc2)
+        self.assertRaises(QiskitError, qc1.__add__, qcr3)
 
     def test_extend_circuit(self):
         """Test extending a circuit with same registers.
@@ -114,24 +97,6 @@ def test_extend_circuit(self):
         threshold = 0.04 * shots
         self.assertDictAlmostEqual(counts, target, threshold)
 
-    def test_extend_circuit_different_registers(self):
-        """Test extending a circuit with different registers.
-        """
-        qr = QuantumRegister(2)
-        cr = ClassicalRegister(2)
-        qc1 = QuantumCircuit(qr)
-        qc1.x(qr)
-        qc2 = QuantumCircuit(qr, cr)
-        qc2.measure(qr, cr)
-        qc1 += qc2
-        backend = BasicAer.get_backend('qasm_simulator')
-        shots = 1024
-        result = execute(qc1, backend=backend, shots=shots,
-                         seed_simulator=78).result()
-        counts = result.get_counts()
-        target = {'11': shots}
-        self.assertEqual(counts, target)
-
     def test_extend_circuit_fail(self):
         """Test extending a circuits fails if registers incompatible.
 
@@ -145,8 +110,8 @@ def test_extend_circuit_fail(self):
         qc2 = QuantumCircuit(qr2)
         qcr3 = QuantumCircuit(cr1)
 
-        self.assertRaises(CircuitError, qc1.__iadd__, qc2)
-        self.assertRaises(CircuitError, qc1.__iadd__, qcr3)
+        self.assertRaises(QiskitError, qc1.__iadd__, qc2)
+        self.assertRaises(QiskitError, qc1.__iadd__, qcr3)
 
     def test_measure_args_type_cohesion(self):
         """Test for proper args types for measure function.

test/python/circuit/test_parameters.py

@@ -325,7 +325,7 @@ def test_circuit_composition(self):
         theta = Parameter('θ')
         qr = QuantumRegister(1)
         cr = ClassicalRegister(1)
-        qc1 = QuantumCircuit(qr)
+        qc1 = QuantumCircuit(qr, cr)
         qc1.rx(theta, qr)
 
         phi = Parameter('phi')