<DO NOT MERGE> 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,13 @@
     "    \\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` (**link to API**) instruction was introduced. As the name suggests, it is a new measurement instruction that is optimized for mid-circuit on IBM QPUs.\n",
+    "\n",
     "## Apply a measurement to a circuit\n",
     "\n",
     "There are several ways to apply measurements to a circuit:\n",
@@ -191,6 +198,38 @@
     "qc.measure_active()  # Measure qubits that are not idle, i.e., qubits 0 and 2."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "b1c5f875-6dfb-48e9-83f4-b25ba516af83",
+   "metadata": {},
+   "source": [
+    "### `MidCircuitMeasure` method\n",
+    "\n",
+    "\n",
+    "\n",
+    "Use `MidCircuitMeasure` (**NEED LINK**) to apply a mid-circuit measurement.  While you can use `QuantumCircuit.measure` for a mid-circuit measurement, `MidCircuitMeasure` is designed specifically for mid-circuit measurements, and is therefore 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.append(MidCircuitMeasure(\"measure_3\"), [0], [1])\n",
+    "circ.measure([0], [0])\n",
+    "circ.measure_all()\n",
+    "print(circ.draw())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "242ffc90-8db9-4e09-98d8-adb74b57afac",
@@ -202,8 +241,14 @@
     "* 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",