diff --git a/qiskit/circuit/quantumcircuit.py b/qiskit/circuit/quantumcircuit.py index 0642496a087..6ea21edd66d 100644 --- a/qiskit/circuit/quantumcircuit.py +++ b/qiskit/circuit/quantumcircuit.py @@ -2262,17 +2262,77 @@ def reset(self, qubit: QubitSpecifier) -> InstructionSet: return self.append(Reset(), [qubit], []) def measure(self, qubit: QubitSpecifier, cbit: ClbitSpecifier) -> InstructionSet: - """Measure quantum bit into classical bit (tuples). + r"""Measure a quantum bit (``qubit``) in the Z basis into a classical bit (``cbit``). + + When a quantum state is measured, a qubit is projected in the computational (Pauli Z) basis + to either :math:`\lvert 0 \rangle` or :math:`\lvert 1 \rangle`. The classical bit ``cbit`` + indicates the result + of that projection as a ``0`` or a ``1`` respectively. This operation is non-reversible. Args: - qubit: qubit to measure. - cbit: classical bit to place the measurement in. + qubit: qubit(s) to measure. + cbit: classical bit(s) to place the measurement result(s) in. Returns: qiskit.circuit.InstructionSet: handle to the added instructions. Raises: CircuitError: if arguments have bad format. + + Examples: + In this example, a qubit is measured and the result of that measurement is stored in the + classical bit (usually expressed in diagrams as a double line): + + .. code-block:: + + from qiskit import QuantumCircuit + circuit = QuantumCircuit(1, 1) + circuit.h(0) + circuit.measure(0, 0) + circuit.draw() + + + .. parsed-literal:: + + ┌───┐┌─┐ + q: ┤ H ├┤M├ + └───┘└╥┘ + c: 1/══════╩═ + 0 + + It is possible to call ``measure`` with lists of ``qubits`` and ``cbits`` as a shortcut + for one-to-one measurement. These two forms produce identical results: + + .. code-block:: + + circuit = QuantumCircuit(2, 2) + circuit.measure([0,1], [0,1]) + + .. code-block:: + + circuit = QuantumCircuit(2, 2) + circuit.measure(0, 0) + circuit.measure(1, 1) + + Instead of lists, you can use :class:`~qiskit.circuit.QuantumRegister` and + :class:`~qiskit.circuit.ClassicalRegister` under the same logic. + + .. code-block:: + + from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister + qreg = QuantumRegister(2, "qreg") + creg = ClassicalRegister(2, "creg") + circuit = QuantumCircuit(qreg, creg) + circuit.measure(qreg, creg) + + This is equivalent to: + + .. code-block:: + + circuit = QuantumCircuit(qreg, creg) + circuit.measure(qreg[0], creg[0]) + circuit.measure(qreg[1], creg[1]) + """ return self.append(Measure(), [qubit], [cbit])