Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

extend the documentation for qiskit.circuit.QuantumCircuit.measure #9698

Merged
merged 22 commits into from
Mar 14, 2023
Merged
Changes from 11 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
87 changes: 84 additions & 3 deletions qiskit/circuit/quantumcircuit.py
Original file line number Diff line number Diff line change
Expand Up @@ -2265,17 +2265,98 @@ 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).
"""Measure quantum bit (qubit) into classical bit (cbit).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""Measure quantum bit (qubit) into classical bit (cbit).
"""Measure one or more quantum bits (qubit) into classical bits (cbit).

(or "measure a quantum bit into a classical bit", depending on whether you want to stress the broadcasting or not)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went for the singular option in daaed65


When a qubit is measured, its state collapses to a classical bit and copied to a
classical wire.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't strictly physically correct, and it's missing a bit of information. I don't know how you want to present it to less informed users, but for knowledgable ones, we should mention that measure is specifically a projective measurement in the computational (Pauli Z) basis, and the classical bit indicates whether the result is the $\lvert1\rangle$ state (1) or the $\lvert0\rangle$ state (0).

It feels a bit off to say a quantum state "collapses to a classical bit" - the global wavefunction collapses such that the measured qubit(s) are in an eigenstate of the projective measurement. In a general entangled state, it's also not super precise to imply that a single qubit can have a state independent of the others ("its state" - it isn't guaranteed to be separable before the measurement). I think I'd avoid talking about the quantum state too much here - if a user doesn't already know what a "projective measurement" is, they'll be better served by an intro to QC rather than us trying to fit a miniature version into API documentation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about the explanation in e3bc46a . It would be great to keep it simple while technically correct.


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 in.
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved

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 of the same size:

.. code-block::

circuit = QuantumCircuit(2,2)
circuit.measure([0,1], [0,1]) # same as "circuit.measure(0,0); circuit.measure(1,1);"


.. parsed-literal::

┌─┐
q_0: ┤M├───
└╥┘┌─┐
q_1: ─╫─┤M├
║ └╥┘
c: 2/═╩══╩═
0 1
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The example here wouldn't actually produce the given output, because it doesn't have a draw (not sure how precise you care about being, though).

I'd maybe change the comment to be a proper construction of a second circuit, with the comment explaining "these two forms produce identical output", just to be a bit clearer (and not to have long code lines in the rendered docs).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I understood you correctly, I moved away from the drawings into an equivalence approach in 1a474f6


It is also possible to do a one-to-many readout:

.. code-block::

circuit = QuantumCircuit(2,2)
circuit.measure(0, [0,1]) # same as "circuit.measure(0,0); circuit.measure(0,1);"


.. parsed-literal::

┌─┐┌─┐
q_0: ┤M├┤M├
└╥┘└╥┘
q_1: ─╫──╫─
║ ║
c: 2/═╩══╩═
0 1
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is technically possible, but a bit useless haha.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added because I think it is in the specification. Do you think would be better not to have it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't feel particularly strongly, though I'd probably at least mention that there's little reason to do it. Similarly, I think it's technically possible to use the broadcast to measure several qubits into the same classical bit, but that's even more useless, and I definitely wouldn't mention it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking over it, it is getting long and there is no real benefit. So I removed that case in 7bc4849

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking over it, it is getting long and there is no real benefit. So I removed that case in 7bc4849


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(1, "qreg")
creg = ClassicalRegister(2, "creg")
circuit = QuantumCircuit(qreg, creg)
circuit.measure(qreg, creg)

HuangJunye marked this conversation as resolved.
Show resolved Hide resolved

.. parsed-literal::

┌─┐┌─┐
qreg: ┤M├┤M├
└╥┘└╥┘
creg: 2/═╩══╩═
0 1

"""
return self.append(Measure(), [qubit], [cbit])

Expand Down