Docstring in qml.measure now has MCM statistics example. (#5441)

**Context:** Internal conversation with Juan Miguel. **Description of the Change:** Adds an example to the `qml.measure` docstring. **Benefits:** The feature is more visible. **Possible Drawbacks:** **Related GitHub Issues:** --------- Co-authored-by: Thomas R. Bromley <[email protected]> Co-authored-by: Astral Cai <[email protected]>
PennyLaneAI · Apr 2, 2024 · 04be317 · 04be317
1 parent 1a2895d
commit 04be317
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 0 deletions.
diff --git a/doc/introduction/measurements.rst b/doc/introduction/measurements.rst
@@ -423,6 +423,8 @@ documentation.
     Currently, postselection support is only available on :class:`~.pennylane.devices.DefaultQubit`. Using
     postselection on other devices will raise an error.
 
+.. _mid_circuit_measurements_statistics:
+
 Mid-circuit measurement statistics
 **********************************
 

diff --git a/doc/releases/changelog-dev.md b/doc/releases/changelog-dev.md
@@ -289,6 +289,9 @@
 * A link to the demos for using `qml.SpecialUnitary` and `qml.QNGOptimizer` has been added to their respective docstrings.
   [(#5376)](https://github.com/PennyLaneAI/pennylane/pull/5376)
 
+* A code example in the `qml.measure` docstring has been added that showcases returning mid-circuit measurement statistics from QNodes.
+  [(#5441)](https://github.com/PennyLaneAI/pennylane/pull/5441)
+
 <h3>Bug fixes 🐛</h3>
 
 * Using `@` with legacy Hamiltonian instances now properly de-queues the previously existing operations.

diff --git a/pennylane/measurements/mid_measure.py b/pennylane/measurements/mid_measure.py
@@ -82,6 +82,27 @@ def func():
         Python ``not``, ``and``, ``or``, do not work since these do not have dunder methods.
         Instead use ``~``, ``&``, ``|``.
 
+    Mid-circuit measurement results can be processed with the usual measurement functions such as
+    :func:`~.expval`. For QNodes with finite shots, :func:`~.sample` applied to a mid-circuit measurement
+    result will return a binary sequence of samples.
+    See :ref:`here <mid_circuit_measurements_statistics>` for more details.
+
+    .. code-block:: python3
+
+        dev = qml.device("default.qubit")
+
+        @qml.qnode(dev)
+        def circuit(x, y):
+            qml.RX(x, wires=0)
+            qml.RY(y, wires=1)
+            m0 = qml.measure(1)
+            return (
+                qml.expval(m0), qml.var(m0), qml.probs(op=m0), qml.counts(op=m0), qml.sample(m0)
+            )
+
+    >>> circuit(1.0, 2.0, shots=10000)
+    (0.702, 0.20919600000000002, array([0.298, 0.702]), {0: 298, 1: 702}, array([0, 1, 1, ..., 1, 1, 1]))
+
     Args:
         wires (Wires): The wire of the qubit the measurement process applies to.
         reset (Optional[bool]): Whether to reset the wire to the :math:`|0 \rangle`