add measurement information (#1988)

Closes #1925

---------

Co-authored-by: Julien Gacon <[email protected]>
Co-authored-by: ABBY CROSS <[email protected]>

docs/guides/_toc.json

@@ -137,6 +137,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"

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)

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 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}
+      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}
+$$
+
+## Apply a measurement to a circuit
+
+There are several ways to apply measurements to a circuit:
+
+### `QuantumCircuit.measure` method
+
+Use the [`measure`](/api/qiskit/qiskit.circuit.QuantumCircuit#measure) method to measure a [`QuantumCircuit`](/api/qiskit/qiskit.circuit.QuantumCircuit#quantumcircuit-class).
+
+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` 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
+```
+
+### `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.
+
+```python
+from qiskit import QuantumCircuit
+
+qc = QuantumCircuit(3, 1)
+qc.x([0, 2])
+qc.measure_all() # Measure all qubits.
+```
+
+### `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.
+
+```python
+from qiskit import QuantumCircuit
+
+qc = QuantumCircuit(3, 1)
+qc.x([0, 2])
+qc.measure_active() # Measure qubits that are not idle, i.e., qubits 0 and 2.
+```
+
+
+<Admonition type="attention" title="Important notes">
+
+* 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.
+
+</Admonition>
+
+## Next steps
+
+<Admonition type="tip" title="Recommendations">
+- [`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
+</Admonition>

qiskit_bot.yaml

@@ -73,6 +73,8 @@ notifications:
     - "`@lerongil`"
     - "@jyu00"
     - "@beckykd"
+  "docs/guides/measure-qubits":
+    - "@beckykd"
   "docs/guides/get-qpu-information":
     - "@frankharkins"
     - "@abbycross"

scripts/js/commands/checkPatternsIndex.ts

@@ -36,6 +36,7 @@ const ALLOWLIST_MISSING_FROM_TOC: Set<string> = new Set([
   "/guides/post-process-results",
   "/guides/q-ctrl-optimization-solver",
   "/guides/qunasys-quri-chemistry",
+  "/guides/circuit-library",
 ]);
 
 const INDEX_PAGES = [