Reinstate and deprecate loose measure and reset functions (#7376)

Previously, the `QuantumCircuit` methods `.measure` and `.reset` were
defined as regular functions in `circuit/measure.py` (m.m. `reset`) and
monkey-patched onto `QuantumCircuit`.  Commit 2cd42b4 removed the
monkey-patching by defining them as regular methods, but did not
implement a deprecation period for the functions.  This reinstates them,
with the deprecation warning.

qiskit/circuit/measure.py

@@ -13,6 +13,9 @@
 """
 Quantum measurement in the computational basis.
 """
+
+import warnings
+
 from qiskit.circuit.instruction import Instruction
 from qiskit.circuit.exceptions import CircuitError
 
@@ -36,3 +39,32 @@ def broadcast_arguments(self, qargs, cargs):
                 yield qarg, [each_carg]
         else:
             raise CircuitError("register size error")
+
+
+def measure(circuit, qubit, clbit):
+    """Measure a quantum bit into classical bit.
+
+    .. deprecated:: Qiskit Terra 0.19
+        Use :meth:`.QuantumCircuit.measure` instead, either by calling
+        ``circuit.measure(qubit, clbit)``, or if a full function is required, then
+        ``QuantumCircuit.measure(circuit, qubit, clbit)``.
+
+    Args:
+        circuit (QuantumCircuit): the quantum circuit to attach the measurement to.
+        qubit (Union[Qubit, int]): the quantum bit to measure
+        clbit (Union[Clbit, int]): the classical bit to store the measurement result in.
+
+    Returns:
+        .InstructionSet: a handle to the created instruction.
+
+    Raises:
+        CircuitError: if either bit is not in the circuit, or is in a bad format.
+    """
+    warnings.warn(
+        "The loose 'measure' function is deprecated as of Qiskit Terra 0.19, and will be removed"
+        " in a future release.  Instead, you should call 'circuit.measure(qubit, clbit)', or if you"
+        " need a function, you can do `QuantumCircuit.measure(circuit, qubit, clbit)'.",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+    return circuit.measure(qubit, clbit)

qiskit/circuit/reset.py

@@ -13,6 +13,9 @@
 """
 Qubit reset to computational zero.
 """
+
+import warnings
+
 from qiskit.circuit.instruction import Instruction
 
 
@@ -26,3 +29,30 @@ def __init__(self):
     def broadcast_arguments(self, qargs, cargs):
         for qarg in qargs[0]:
             yield [qarg], []
+
+
+def reset(circuit, qubit):
+    """Reset a quantum bit on a circuit.
+
+    .. deprecated:: Qiskit Terra 0.19
+        Use :meth:`.QuantumCircuit.reset` instead, either by calling ``circuit.reset(qubit)``, or if
+        a full function is required, then ``QuantumCircuit.reset(circuit, qubit)``.
+
+    Args:
+        circuit (QuantumCircuit): the quantum circuit to attach the reset operation to.
+        qubit (Union[Qubit, int]): the quantum bit to reset
+
+    Returns:
+        .InstructionSet: a handle to the created instruction.
+
+    Raises:
+        CircuitError: if the qubit is not in the circuit, or is in a bad format.
+    """
+    warnings.warn(
+        "The loose 'reset' function is deprecated as of Qiskit Terra 0.19, and will be removed"
+        " in a future release.  Instead, you should call 'circuit.reset(qubit)', or if you"
+        " need a function, you can do `QuantumCircuit.reset(circuit, qubit)'.",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+    return circuit.reset(qubit)

releasenotes/notes/reinstate-deprecate-loose-measure-reset-11591e35d350aaeb.yaml

@@ -0,0 +1,26 @@
+deprecations:
+  - |
+    The loose functions ``qiskit.circuit.measure.measure()`` and
+    ``qiskit.circuit.reset.reset()`` are deprecated, and will be removed in a
+    future release.  Instead, you should access these as methods on
+    :class:`.QuantumCircuit`::
+
+        from qiskit import QuantumCircuit
+        circuit = QuantumCircuit(1, 1)
+
+        # Replace this deprecated form ...
+        from qiskit.circuit.measure import measure
+        measure(circuit, 0, 0)
+
+        # ... with either of the next two lines:
+        circuit.measure(0, 0)
+        QuantumCircuit.measure(circuit, 0, 0)
+
+fixes:
+  - |
+    Two loose functions ``qiskit.circuit.measure.measure()`` and
+    ``qiskit.circuit.reset.reset()`` were accidentally removed without a
+    deprecation period.  They have been reinstated, but are marked as deprecated
+    in favour of the methods :meth:`.QuantumCircuit.measure` and
+    :meth:`.QuantumCircuit.reset`, respectively, and will be removed in a future
+    release.

test/python/circuit/test_circuit_operations.py

@@ -948,6 +948,32 @@ def test_compare_a_circuit_with_none(self):
 
         self.assertFalse(qc1 == qc2)
 
+    def test_deprecated_measure_function(self):
+        """Test that the deprecated version of the loose 'measure' function works correctly."""
+        from qiskit.circuit.measure import measure
+
+        test = QuantumCircuit(1, 1)
+        with self.assertWarnsRegex(DeprecationWarning, r".*Qiskit Terra 0\.19.*"):
+            measure(test, 0, 0)
+
+        expected = QuantumCircuit(1, 1)
+        expected.measure(0, 0)
+
+        self.assertEqual(test, expected)
+
+    def test_deprecated_reset_function(self):
+        """Test that the deprecated version of the loose 'reset' function works correctly."""
+        from qiskit.circuit.reset import reset
+
+        test = QuantumCircuit(1, 1)
+        with self.assertWarnsRegex(DeprecationWarning, r".*Qiskit Terra 0\.19.*"):
+            reset(test, 0)
+
+        expected = QuantumCircuit(1, 1)
+        expected.reset(0)
+
+        self.assertEqual(test, expected)
+
 
 class TestCircuitPrivateOperations(QiskitTestCase):
     """Direct tests of some of the private methods of QuantumCircuit.  These do not represent