Improve noise learning docs (Qiskit#1975)

* more info * ref * Update qiskit_ibm_runtime/options/layer_noise_learning_options.py Co-authored-by: joshuasn <53916441+joshuasn@users.noreply.github.com> * Update qiskit_ibm_runtime/options/layer_noise_learning_options.py Co-authored-by: joshuasn <53916441+joshuasn@users.noreply.github.com> * CR --------- Co-authored-by: joshuasn <53916441+joshuasn@users.noreply.github.com> Co-authored-by: ptristan3 <44805021+ptristan3@users.noreply.github.com> Co-authored-by: Ian Hincks <ian.hincks@ibm.com>
rathishcholarajan · Oct 25, 2024 · 9522760 · 9522760
1 parent 9a81701
commit 9522760
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 13 deletions.
diff --git a/qiskit_ibm_runtime/noise_learner/noise_learner.py b/qiskit_ibm_runtime/noise_learner/noise_learner.py
@@ -121,7 +121,7 @@ class NoiseLearner:
     References:
         1. E. van den Berg, Z. Minev, A. Kandala, K. Temme, *Probabilistic error
            cancellation with sparse Pauli–Lindblad models on noisy quantum processors*,
-           Nature Physics volume 19, pages1116–1121 (2023).
+           Nature Physics volume 19, pages 1116–1121 (2023).
            `arXiv:2201.09866 [quant-ph] <https://arxiv.org/abs/2201.09866>`_
 
     """

diff --git a/qiskit_ibm_runtime/options/layer_noise_learning_options.py b/qiskit_ibm_runtime/options/layer_noise_learning_options.py
@@ -33,6 +33,30 @@ class LayerNoiseLearningOptions:
         These options are only used when the resilience level or options specify a
         technique that requires layer noise learning.
 
+    .. note::
+
+        The total number of unique circuits implemented to learn the noise of a single layer
+        depends solely on :attr:`~layer_pair_depths` and :attr:`~num_randomizations`. For example,
+        if ``layer_pair_depths`` contains six depths and ``num_randomizations`` is set to ``32``,
+        the noise learning stage executes a total of ``6 * 9`` unique circuits per layer, each
+        one with ``32`` randomizations (at :attr:`~shots_per_randomization` each).
+
+        The number ``9`` above is the number of unique circuits that need to be implemented to
+        learn the noise for all the two-qubit subsystem in the given layer by performing local
+        measurements. Indeed, learning the noise for a single one of these subsystems requires
+        measuring all the ``16`` two-qubit Paulis on that subsystem. Taking advantage of
+        commutation relations to measure more than one of these Paulis (for example, ``XI``,
+        ``IX``, and ``XX``) with a single circuit, it is possible to measure all these ``16``
+        Paulis by implementing only ``9`` circuits. Parallelizing these measurement tasks in the
+        optimal way allows then measuring the ``16`` Paulis for all of the layer's two-qubit
+        subsystems with only ``9`` circuits. More details in Ref. [1].
+
+    References:
+        1. E. van den Berg, Z. Minev, A. Kandala, K. Temme, *Probabilistic error
+           cancellation with sparse Pauli–Lindblad models on noisy quantum processors*,
+           Nature Physics volume 19, pages 1116–1121 (2023).
+           `arXiv:2201.09866 [quant-ph] <https://arxiv.org/abs/2201.09866>`_
+
     """
 
     max_layers_to_learn: Union[UnsetType, int, None] = Unset
@@ -53,11 +77,13 @@ class LayerNoiseLearningOptions:
         Default: 128.
     """
     num_randomizations: Union[UnsetType, int] = Unset
-    r"""The number of random circuits to use per learning circuit
-        configuration. A configuration is a measurement basis and depth setting.
-        For example, if your experiment has six depths, and nine required measurement bases,
-        then setting this value to 32 will result in a total of ``32 * 9 * 6`` circuits
-        that need to be executed (at :attr:`~shots_per_randomization` each). 
+    r"""The number of random circuits to use per learning circuit configuration.
+        A configuration is a measurement basis and depth setting. For example, if your experiment
+        has six depths, then setting this value to 32 will result in a total of ``32 * 9 * 6``
+        circuits that need to be executed (where ``9`` is the number of circuits that need to be
+        implemented to measure all the required observables, see the note in the docstring for
+        :class:`~.LayerNoiseLearningOptions` for mode details), at :attr:`~shots_per_randomization`
+        each. 
         
         Default: 32.
     """

diff --git a/qiskit_ibm_runtime/options/noise_learner_options.py b/qiskit_ibm_runtime/options/noise_learner_options.py
@@ -24,7 +24,33 @@
 
 @primitive_dataclass
 class NoiseLearnerOptions(OptionsV2):
-    """Options for :class:`.NoiseLearner`."""
+    """
+    Options for :class:`.NoiseLearner`.
+
+    .. note::
+
+        The total number of unique circuits implemented to learn the noise of a single layer
+        depends solely on :attr:`~layer_pair_depths` and :attr:`~num_randomizations`. For example,
+        if ``layer_pair_depths`` contains six depths and ``num_randomizations`` is set to ``32``,
+        the noise learning stage executes a total of ``6 * 9`` unique circuits per layer, each
+        one with ``32`` randomizations (at :attr:`~shots_per_randomization` each).
+
+        The number ``9`` above is the number of unique circuits that need to be implemented to
+        learn the noise for all the two-qubit subsystem in the given layer by performing local
+        measurements. Indeed, learning the noise for a single one of these subsystems requires
+        measuring all the ``16`` two-qubit Paulis on that subsystem. Taking advantage of
+        commutation relations to measure more than one of these Paulis (for example, ``XI``,
+        ``IX``, and ``XX``) with a single circuit, it is possible to measure all these ``16``
+        Paulis by implementing only ``9`` circuits. Parallelizing these measurement tasks in the
+        optimal way allows then measuring the ``16`` Paulis for all of the layer's two-qubit
+        subsystems with only ``9`` circuits. More details in Ref. [1].
+
+    References:
+        1. E. van den Berg, Z. Minev, A. Kandala, K. Temme, *Probabilistic error
+           cancellation with sparse Pauli–Lindblad models on noisy quantum processors*,
+           Nature Physics volume 19, pages 1116–1121 (2023).
+           `arXiv:2201.09866 [quant-ph] <https://arxiv.org/abs/2201.09866>`_
+    """
 
     max_layers_to_learn: Union[UnsetType, int, None] = Unset
     r"""The max number of unique layers to learn.
@@ -45,19 +71,21 @@ class NoiseLearnerOptions(OptionsV2):
 
     num_randomizations: Union[UnsetType, int] = Unset
     r"""The number of random circuits to use per learning circuit configuration.
-    
+
     A configuration is a measurement basis and depth setting. For example, if your experiment
-    has six depths, and nine required measurement bases, then setting this value to 32 will
-    result in a total of ``32 * 9 * 6`` circuits that need to be executed (at
-    :attr:`~shots_per_randomization` each). Default: 32.
+    has six depths, then setting this value to 32 will result in a total of ``32 * 9 * 6``
+    circuits that need to be executed (where ``9`` is the number of circuits that need to be
+    implemented to measure all the required observables, see the note in the docstring for
+    :class:`~.NoiseLearnerOptions` for mode details), at :attr:`~shots_per_randomization`
+    each.
     """
 
     layer_pair_depths: Union[UnsetType, List[int]] = Unset
     r"""The circuit depths (measured in number of pairs) to use in learning experiments.
     
     Pairs are used as the unit because we exploit the order-2 nature of our entangling gates in
-    the noise learning implementation. A value of ``3`` would correspond to 6 layers of the layer
-    of interest, for example. Default: (0, 1, 2, 4, 16, 32).
+    the noise learning implementation. For example, a value of ``3`` corresponds to 6 repetitions
+    of the layer of interest. Default: (0, 1, 2, 4, 16, 32).
     """
 
     twirling_strategy: Union[UnsetType, TwirlingStrategyType] = Unset