Document mid-circuit measurements

docs/guides/classical-feedforward-and-control-flow.ipynb

@@ -38,7 +38,7 @@
     "The new version of dynamic circuits is now available to all users on all backends. You can now run dynamic circuits at utility scale. See [the announcement](/announcements/product-updates/2025-09-25-new-dynamic-circuits) for more details.\n",
     "</Admonition>\n",
     "\n",
-    "Dynamic circuits are powerful tools with which your can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements.  This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n",
+    "Dynamic circuits are powerful tools with which you can measure qubits in the middle of a quantum circuit execution and then perform classical logic operations within the circuit, based on the outcome of those mid-circuit measurements.  This process is also known as _classical feedforward_. While these are early days of understanding how best to take advantage of dynamic circuits, the quantum research community has already identified a number of use cases, such as the following:\n",
     "\n",
     "* Efficient quantum state preparation, such as [GHZ state,](https://journals.aps.org/prxquantum/abstract/10.1103/PRXQuantum.5.030339) [W-state,](https://arxiv.org/abs/2403.07604) (for more information about W-state, also refer to [\"State preparation by shallow circuits using feed forward\"](https://arxiv.org/abs/2307.14840)) and a broad class of [matrix product states](https://arxiv.org/abs/2404.16083)\n",
     "* [Efficient long-range entanglement](https://journals.aps.org/prxquantum/abstract/10.1103/PRXQuantum.5.030339) between qubits on the same chip by using shallow circuits\n",

docs/guides/measure-qubits.ipynb

@@ -43,6 +43,17 @@
     "    \\end{cases}\n",
     "$$\n",
     "\n",
+    "## Mid-circuit measurements\n",
+    "\n",
+    "Mid-circuit measurements are a key component of dynamic circuits. Prior to `qiskit-ibm-runtime` v0.43.0, `measure` was the only measurement instruction in Qiskit. Mid-circuit measurements, however, have different tuning requirements than _terminal_ measurements (measurements that happen at the end of a circuit). For example, you need to consider the instruction duration when tuning a mid-circuit measurement because longer instructions cause noisier circuits. You don't need to consider instruction duration for terminal measurements because there are no instructions after terminal measurements.\n",
+    "\n",
+    "\n",
+    "In `qiskit-ibm-runtime` v0.43.0, the `MidCircuitMeasure` instruction was introduced. As the name suggests, it is a new measurement instruction that is optimized for mid-circuit on IBM® QPUs.\n",
+    "\n",
+    "<Admonition type=\"note\">\n",
+    "The `MidCircuitMeasure` instruction maps to the `measure_2` instruction reported in the backend's `supported_instructions`. However,  `measure_2` is not supported on all backends. Use `service.backends(filters=lambda b: \"measure_2\" in b.supported_instructions)` to find backends that support it.  New measurements might be added in the future, but this is not guarenteed.\n",
+    "</Admonition>\n",
+    "\n",
     "## Apply a measurement to a circuit\n",
     "\n",
     "There are several ways to apply measurements to a circuit:\n",
@@ -179,7 +190,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "id": "79c8b510-00df-4442-9e8b-e7f7e2006cd7",
    "metadata": {},
    "outputs": [],
@@ -188,7 +199,37 @@
     "\n",
     "qc = QuantumCircuit(3, 1)\n",
     "qc.x([0, 2])\n",
-    "qc.measure_active()  # Measure qubits that are not idle, i.e., qubits 0 and 2."
+    "qc.measure_active()  # Measure qubits that are not idle, that is, qubits 0 and 2."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b1c5f875-6dfb-48e9-83f4-b25ba516af83",
+   "metadata": {},
+   "source": [
+    "### `MidCircuitMeasure` method\n",
+    "\n",
+    "\n",
+    "Use `MidCircuitMeasure` to apply a mid-circuit measurement (requires `qiskit-ibm-runtime` v0.43.0 or later).  While you can use `QuantumCircuit.measure` for a mid-circuit measurement, because of its design, `MidCircuitMeasure` is typically a better choice.  For example, it adds less overhead to your circuit than when using `QuantumCircuit.measure`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "86b25b9d-403c-40bd-b028-e65bb71b4ea4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit import QuantumCircuit\n",
+    "from qiskit_ibm_runtime.circuit import MidCircuitMeasure\n",
+    "from qiskit.circuit import Measure\n",
+    "\n",
+    "circ = QuantumCircuit(2, 2)\n",
+    "circ.x(0)\n",
+    "circ.append(MidCircuitMeasure(), [0], [0])\n",
+    "circ.measure([0], [0])\n",
+    "circ.measure_all()\n",
+    "print(circ.draw())"
    ]
   },
   {
@@ -198,12 +239,17 @@
    "source": [
     "<Admonition type=\"attention\" title=\"Important notes\">\n",
     "\n",
-    "* Circuits that contain operations _after_ a measurement are called dynamic circuits. Not all QPUs support these.\n",
     "* There must be at least one classical register in order to use measurements.\n",
     "* The Sampler primitive requires circuit measurements. You can add circuit measurements with the Estimator primitive, but they are ignored.\n",
     "\n",
-    "</Admonition>\n",
-    "\n",
+    "</Admonition>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f6c0eeae-9850-4761-beac-1a70c31a7bc7",
+   "metadata": {},
+   "source": [
     "## Next steps\n",
     "\n",
     "<Admonition type=\"tip\" title=\"Recommendations\">\n",