From 52943793f2d2ae241ca7d2e4595554a2fe22d43c Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Wed, 18 Sep 2024 17:26:19 -0500 Subject: [PATCH 01/11] add measurement information --- docs/guides/measure-qubits.mdx | 96 ++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/guides/measure-qubits.mdx diff --git a/docs/guides/measure-qubits.mdx b/docs/guides/measure-qubits.mdx new file mode 100644 index 00000000000..54c5550f71b --- /dev/null +++ b/docs/guides/measure-qubits.mdx @@ -0,0 +1,96 @@ +--- +title: Measure qubits +description: Learn how to measure qubits, including constraints on where measurements can be used. +--- + +# Measure qubits + +To get information about a qubit's state, you have to _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). This is an irreversible operation, and usually destroys entanglement and phase coherence between the target qubit and the rest of the system. Thus, after a qubit is measured, you can't perform any more instructions on that qubit, and each qubit can only be measured once. Additionally, there must be at least one classical register to store the measurement information. + +## Apply a measurement to a circuit + +There are several ways to apply measurement to a circuit: + +### `Measure` class + +The Qiskit [Measure](/api/qiskit/circuit#qiskit.circuit.Measure) class measures the specified qubits. + +Examples: + +```python +from qiskit import QuantumCircuit + +qc = QuantumCircuit(5, 5) +qc.x(0) +qc.x(1) +qc.x(4) +qc.measure(range(5), range(5)) # Measures all qubits into the corresponding clbit. +``` + +```python +from qiskit import QuantumCircuit + +qc = QuantumCircuit(3, 1) +qc.x([0, 2]) +qc.measure(1, 0) # Measure qubit 1 into the classical bit 0. +``` + +### `measure_all` method + +To measure all qubits into the corresponding classical bits, use the [`measure_all`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_all) method. By default, this method adds new classical bits in a `ClassicalRegister` to store these measurements. + +```python +from qiskit import QuantumCircuit + +qc = QuantumCircuit(3, 1) +qc.x([0, 2]) +qc.measure_all # Measure all qubits. +``` + +****************************************************** +QUESTION: +**WHEN I RUN THE ABOVE CODE AND ADD qc.draw("mpl"), IT DOESN'T LOOK LIKE ANY MEASUREMENTS ARE ACTUALLY ADDED, BUT IF I USE qc.measure(1, 0) INSTEAD, I SEE A MEASUREMENT. WHAT IS HAPPENING?** +******************************************************* + +### `measure_active` method + +To measure all qubits that are not idle, use the [`measure_active`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_active) method. This method creates a new `ClassicalRegister` with a size equal to the number of non-idle qubits being measured. + +```python +from qiskit import QuantumCircuit + +qc = QuantumCircuit(3, 1) +qc.x([0, 2]) +qc.measure_active # Measure qubits that are not idle. +``` + +### Measure a circuit when it's created + +You can add measurements when generating a random circuit. Each qubit is measured, as shown in the following example. For more information, see the [`random_circuit`](/api/qiskit/circuit#random_circuit) method documentation. + +Example: + +```python +from qiskit.circuit.random import random_circuit + +circ = random_circuit(2, 2, measure=True) +circ.draw(output='mpl') +``` + + + +* Qubit measurement must be the last instruction on a qubit. That is, no instructions can come after a measurement on that qubit (unless it's a dynamic circuit). +* Each qubit can be measured only once. +* There must be at least one classical register in order to use measurements. +* The Sampler primitive requires circuit measurements. You can add circuit measurements with the Estimator primitive, but they are ignored. + + + +## Next steps + + +- [`Measure`](/api/qiskit/circuit#qiskit.circuit.Measure) class +- [`measure_all`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_all) method +- [`measure_active`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_active) method +- [`random_circuit`](/api/qiskit/circuit#random_circuit) method + \ No newline at end of file From 1501042e05e4366093598216cd501621cfda99ff Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 19 Sep 2024 10:10:35 -0500 Subject: [PATCH 02/11] add new file to other files --- docs/guides/map-problem-to-circuits.mdx | 1 + qiskit_bot.yaml | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/guides/map-problem-to-circuits.mdx b/docs/guides/map-problem-to-circuits.mdx index e1de24c9230..77150f0b20c 100644 --- a/docs/guides/map-problem-to-circuits.mdx +++ b/docs/guides/map-problem-to-circuits.mdx @@ -28,6 +28,7 @@ The output of this step in a Qiskit pattern is normally a collection of circuits ### Build circuits with the Qiskit SDK * [Circuit library](./circuit-library) * [Construct circuits](./construct-circuits) +* [Measure qubits](./measure-qubits) * [Visualize circuits](./visualize-circuits) * [Classical feedforward and control flow](./classical-feedforward-and-control-flow) * [Synthesize unitary operators](./synthesize-unitary-operators) diff --git a/qiskit_bot.yaml b/qiskit_bot.yaml index c2c0895fbcf..6276e91660a 100644 --- a/qiskit_bot.yaml +++ b/qiskit_bot.yaml @@ -73,6 +73,8 @@ notifications: - "`@lerongil`" - "@jyu00" - "@beckykd" + "docs/guides/measure-qubits": + - "@beckykd" "docs/guides/get-qpu-information": - "@frankharkins" - "@abbycross" From 8f7bab906c6113234a8eaace9eb02d67a74b3039 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 19 Sep 2024 12:01:28 -0500 Subject: [PATCH 03/11] Add to Tools section --- docs/guides/_toc.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index df623ee5c60..94f87004911 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -136,6 +136,10 @@ "title": "Construct circuits", "url": "/guides/construct-circuits" }, + { + "title": "Measure qubits", + "url": "/guides/measure-qubits" + }, { "title": "Classical feedforward and control flow", "url": "/guides/classical-feedforward-and-control-flow" From 0856bfe41cfa70cc7137f89e0490e2e17ab42f54 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Tue, 1 Oct 2024 16:44:58 -0500 Subject: [PATCH 04/11] Apply suggestions from code review Co-authored-by: Julien Gacon --- docs/guides/measure-qubits.mdx | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/docs/guides/measure-qubits.mdx b/docs/guides/measure-qubits.mdx index 54c5550f71b..47029991924 100644 --- a/docs/guides/measure-qubits.mdx +++ b/docs/guides/measure-qubits.mdx @@ -5,7 +5,7 @@ description: Learn how to measure qubits, including constraints on where measure # Measure qubits -To get information about a qubit's state, you have to _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). This is an irreversible operation, and usually destroys entanglement and phase coherence between the target qubit and the rest of the system. Thus, after a qubit is measured, you can't perform any more instructions on that qubit, and each qubit can only be measured once. Additionally, there must be at least one classical register to store the measurement information. +To get information about a qubit's state, you can _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). In Qiskit, measurements are performed in the computational basis, i.e., the single-qubit Pauli-$Z$ basis. A measurement will thus yield 0 or 1 depending on the overlap with the Pauli-$Z$ eigenstates $|0\rangle$ and $|1\rangle$. ## Apply a measurement to a circuit @@ -44,7 +44,7 @@ from qiskit import QuantumCircuit qc = QuantumCircuit(3, 1) qc.x([0, 2]) -qc.measure_all # Measure all qubits. +qc.measure_all() # Measure all qubits. ``` ****************************************************** @@ -61,25 +61,13 @@ from qiskit import QuantumCircuit qc = QuantumCircuit(3, 1) qc.x([0, 2]) -qc.measure_active # Measure qubits that are not idle. +qc.measure_active() # Measure qubits that are not idle. ``` -### Measure a circuit when it's created - -You can add measurements when generating a random circuit. Each qubit is measured, as shown in the following example. For more information, see the [`random_circuit`](/api/qiskit/circuit#random_circuit) method documentation. - -Example: - -```python -from qiskit.circuit.random import random_circuit - -circ = random_circuit(2, 2, measure=True) -circ.draw(output='mpl') -``` -* Qubit measurement must be the last instruction on a qubit. That is, no instructions can come after a measurement on that qubit (unless it's a dynamic circuit). +* Circuits that contain operations _after_ a measurement are called dynamic circuits. Note, that not all backends or simulators might support these. * Each qubit can be measured only once. * There must be at least one classical register in order to use measurements. * The Sampler primitive requires circuit measurements. You can add circuit measurements with the Estimator primitive, but they are ignored. From 9200490300db84dd58371b8c1aef605899d4870a Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 1 Oct 2024 17:30:46 -0500 Subject: [PATCH 05/11] Edits - add equation --- docs/guides/measure-qubits.mdx | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/guides/measure-qubits.mdx b/docs/guides/measure-qubits.mdx index 47029991924..4821a44e8c2 100644 --- a/docs/guides/measure-qubits.mdx +++ b/docs/guides/measure-qubits.mdx @@ -5,15 +5,22 @@ description: Learn how to measure qubits, including constraints on where measure # Measure qubits -To get information about a qubit's state, you can _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). In Qiskit, measurements are performed in the computational basis, i.e., the single-qubit Pauli-$Z$ basis. A measurement will thus yield 0 or 1 depending on the overlap with the Pauli-$Z$ eigenstates $|0\rangle$ and $|1\rangle$. +To get information about a qubit's state, you can _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). In Qiskit, measurements are performed in the computational basis, that is, the single-qubit Pauli-$Z$ basis. A measurement will thus yield 0 or 1, depending on the overlap with the Pauli-$Z$ eigenstates $|0\rangle$ and $|1\rangle$: + +$$ +|q\rangle \xrightarrow{measure}\begin{cases} + |0\rangle (\text{outcome}+1), \text{with probability } p_0=|\langle q|0\rangle|^{2}\text{,} \\ + |1\rangle (\text{outcome}-1), \text{with probability } p_1=|\langle q|1\rangle|^{2}\text{.} + \end{cases} +$$ ## Apply a measurement to a circuit There are several ways to apply measurement to a circuit: -### `Measure` class +### `QuantumCircuit.measure` method -The Qiskit [Measure](/api/qiskit/circuit#qiskit.circuit.Measure) class measures the specified qubits. +Use the [`measure`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure) method to measure a [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit#quantumcircuit-class). Examples: @@ -35,6 +42,17 @@ qc.x([0, 2]) qc.measure(1, 0) # Measure qubit 1 into the classical bit 0. ``` +### `Measure` class + +The Qiskit [Measure](/api/qiskit/circuit#qiskit.circuit.Measure) class measures the specified qubits. + +```python +from qiskit.circuit import Measure + +.... +qc.append(Measure(), [0], [0]) # measure qubit 0 into clbit 0 +``` + ### `measure_all` method To measure all qubits into the corresponding classical bits, use the [`measure_all`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_all) method. By default, this method adds new classical bits in a `ClassicalRegister` to store these measurements. @@ -47,11 +65,6 @@ qc.x([0, 2]) qc.measure_all() # Measure all qubits. ``` -****************************************************** -QUESTION: -**WHEN I RUN THE ABOVE CODE AND ADD qc.draw("mpl"), IT DOESN'T LOOK LIKE ANY MEASUREMENTS ARE ACTUALLY ADDED, BUT IF I USE qc.measure(1, 0) INSTEAD, I SEE A MEASUREMENT. WHAT IS HAPPENING?** -******************************************************* - ### `measure_active` method To measure all qubits that are not idle, use the [`measure_active`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_active) method. This method creates a new `ClassicalRegister` with a size equal to the number of non-idle qubits being measured. @@ -68,7 +81,7 @@ qc.measure_active() # Measure qubits that are not idle. * Circuits that contain operations _after_ a measurement are called dynamic circuits. Note, that not all backends or simulators might support these. -* Each qubit can be measured only once. +* Each qubit can be measured only once, except when using dynamic circuits. * There must be at least one classical register in order to use measurements. * The Sampler primitive requires circuit measurements. You can add circuit measurements with the Estimator primitive, but they are ignored. From e9e507e03fe55047266442aedce8f97497ae6d8a Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Tue, 1 Oct 2024 17:39:17 -0500 Subject: [PATCH 06/11] Add back into TOC --- docs/guides/_toc.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index e44fead232e..08f8e644f12 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -135,6 +135,10 @@ "title": "Classical feedforward and control flow", "url": "/guides/classical-feedforward-and-control-flow" }, + { + "title": "Measure qubits", + "url": "/guides/measure-qubits" + }, { "title": "Synthesize unitary operators", "url": "/guides/synthesize-unitary-operators" From 81bb9c7349772680a95e384ed18d170aee4f5d03 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Wed, 2 Oct 2024 13:54:09 -0400 Subject: [PATCH 07/11] Update checkPatternsIndex.ts --- scripts/js/commands/checkPatternsIndex.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/js/commands/checkPatternsIndex.ts b/scripts/js/commands/checkPatternsIndex.ts index d436964a4b1..8fac25215f2 100644 --- a/scripts/js/commands/checkPatternsIndex.ts +++ b/scripts/js/commands/checkPatternsIndex.ts @@ -36,6 +36,7 @@ const ALLOWLIST_MISSING_FROM_TOC: Set = new Set([ "/guides/post-process-results", "/guides/q-ctrl-optimization-solver", "/guides/qunasys-quri-chemistry", + "/guides/circuit-library", ]); const INDEX_PAGES = [ From dfe43bd8b2c3710ee6b3ccee6903e4a059e6d411 Mon Sep 17 00:00:00 2001 From: ABBY CROSS Date: Wed, 2 Oct 2024 13:57:50 -0400 Subject: [PATCH 08/11] Update _toc.json --- docs/guides/_toc.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/guides/_toc.json b/docs/guides/_toc.json index 08f8e644f12..7b545df4de3 100644 --- a/docs/guides/_toc.json +++ b/docs/guides/_toc.json @@ -126,6 +126,8 @@ "title": "Circuits and operators", "children": [ { + "title": "Circuit library", + "url": "/guides/circuit-library" }, { "title": "Construct circuits", From 2a7ef2c15d7b4147d389cc7a6a1b4935ab07a083 Mon Sep 17 00:00:00 2001 From: Rebecca Dimock <66339736+beckykd@users.noreply.github.com> Date: Thu, 3 Oct 2024 09:08:29 -0500 Subject: [PATCH 09/11] Apply suggestions from code review Co-authored-by: Julien Gacon --- docs/guides/measure-qubits.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/measure-qubits.mdx b/docs/guides/measure-qubits.mdx index 4821a44e8c2..c542db816da 100644 --- a/docs/guides/measure-qubits.mdx +++ b/docs/guides/measure-qubits.mdx @@ -9,8 +9,8 @@ To get information about a qubit's state, you can _measure_ it onto a [classical $$ |q\rangle \xrightarrow{measure}\begin{cases} - |0\rangle (\text{outcome}+1), \text{with probability } p_0=|\langle q|0\rangle|^{2}\text{,} \\ - |1\rangle (\text{outcome}-1), \text{with probability } p_1=|\langle q|1\rangle|^{2}\text{.} + 0 (\text{outcome}+1), \text{with probability } p_0=|\langle q|0\rangle|^{2}\text{,} \\ + 1 (\text{outcome}-1), \text{with probability } p_1=|\langle q|1\rangle|^{2}\text{.} \end{cases} $$ @@ -18,7 +18,7 @@ $$ There are several ways to apply measurement to a circuit: -### `QuantumCircuit.measure` method +### `measure` method Use the [`measure`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure) method to measure a [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit#quantumcircuit-class). @@ -74,7 +74,7 @@ from qiskit import QuantumCircuit qc = QuantumCircuit(3, 1) qc.x([0, 2]) -qc.measure_active() # Measure qubits that are not idle. +qc.measure_active() # Measure qubits that are not idle, i.e., qubits 0 and 2. ``` From f7ae32fc0f34c833a29d9773849b4777f6dee6ea Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 3 Oct 2024 09:19:33 -0500 Subject: [PATCH 10/11] Edits --- docs/guides/measure-qubits.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/guides/measure-qubits.mdx b/docs/guides/measure-qubits.mdx index c542db816da..776e25786ca 100644 --- a/docs/guides/measure-qubits.mdx +++ b/docs/guides/measure-qubits.mdx @@ -5,7 +5,7 @@ description: Learn how to measure qubits, including constraints on where measure # Measure qubits -To get information about a qubit's state, you can _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). In Qiskit, measurements are performed in the computational basis, that is, the single-qubit Pauli-$Z$ basis. A measurement will thus yield 0 or 1, depending on the overlap with the Pauli-$Z$ eigenstates $|0\rangle$ and $|1\rangle$: +To get information about a qubit's state, you can _measure_ it onto a [classical bit](/api/qiskit/circuit#qiskit.circuit.Clbit). In Qiskit, measurements are performed in the computational basis, that is, the single-qubit Pauli-$Z$ basis. Therefore, a measurement yields 0 or 1, depending on the overlap with the Pauli-$Z$ eigenstates $|0\rangle$ and $|1\rangle$: $$ |q\rangle \xrightarrow{measure}\begin{cases} @@ -16,7 +16,7 @@ $$ ## Apply a measurement to a circuit -There are several ways to apply measurement to a circuit: +There are several ways to apply measurements to a circuit: ### `measure` method @@ -80,8 +80,7 @@ qc.measure_active() # Measure qubits that are not idle, i.e., qubits 0 and 2. -* Circuits that contain operations _after_ a measurement are called dynamic circuits. Note, that not all backends or simulators might support these. -* Each qubit can be measured only once, except when using dynamic circuits. +* Circuits that contain operations _after_ a measurement are called dynamic circuits. Not all QPUs or simulators support these. * There must be at least one classical register in order to use measurements. * The Sampler primitive requires circuit measurements. You can add circuit measurements with the Estimator primitive, but they are ignored. From 53569fe6a04b20e1a3db91379f7d522d30008a0e Mon Sep 17 00:00:00 2001 From: Rebecca Dimock Date: Thu, 3 Oct 2024 09:43:23 -0500 Subject: [PATCH 11/11] Add class --- docs/guides/measure-qubits.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/measure-qubits.mdx b/docs/guides/measure-qubits.mdx index 776e25786ca..9679d942478 100644 --- a/docs/guides/measure-qubits.mdx +++ b/docs/guides/measure-qubits.mdx @@ -18,7 +18,7 @@ $$ There are several ways to apply measurements to a circuit: -### `measure` method +### `QuantumCircuit.measure` method Use the [`measure`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure) method to measure a [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit#quantumcircuit-class). @@ -53,7 +53,7 @@ from qiskit.circuit import Measure qc.append(Measure(), [0], [0]) # measure qubit 0 into clbit 0 ``` -### `measure_all` method +### `QuantumCircuit.measure_all` method To measure all qubits into the corresponding classical bits, use the [`measure_all`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_all) method. By default, this method adds new classical bits in a `ClassicalRegister` to store these measurements. @@ -65,7 +65,7 @@ qc.x([0, 2]) qc.measure_all() # Measure all qubits. ``` -### `measure_active` method +### `QuantumCircuit.measure_active` method To measure all qubits that are not idle, use the [`measure_active`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure_active) method. This method creates a new `ClassicalRegister` with a size equal to the number of non-idle qubits being measured.