Docs: clarify shots, default_shots, and twirling shots (#1884)

* clarify shots used

* fix pea typo

qiskit_ibm_runtime/options/twirling_options.py

@@ -27,54 +27,73 @@
 
 @primitive_dataclass
 class TwirlingOptions:
-    """Twirling options. This is only used by V2 primitives.
+    """Twirling options."""
 
-    Args:
-        enable_gates: Whether to apply 2-qubit Clifford gate twirling. Default: False.
+    enable_gates: Union[UnsetType, bool] = Unset
+    r"""Whether to apply 2-qubit Clifford gate twirling.
+      Default: False.
+    """
 
-        enable_measure: Whether to enable twirling of measurements. Twirling will only be applied to
-         those measurement registers not involved within a conditional logic.
-         Default: True for Estimator, false for Sampler.
+    enable_measure: Union[UnsetType, bool] = Unset
+    r"""Whether to enable twirling of measurements.
 
-        num_randomizations: The number of random samples to use when twirling or peforming sampled
-          mitigation. If ``num_randomizations`` is "auto", for every pub executed ``shots`` times:
+    Twirling will only be applied to those measurement registers not involved within a
+    conditional logic. Default: True for Estimator, false for Sampler.
+    """
 
-          * If ``shots_per_randomization`` is also "auto", ``shots_per_randomization`` is set first
-            as described below, then ``num_randomizations`` is set as
-            ``ceil(shots/shots_per_randomization)``, where ``ceil`` is the ceiling function.
-          * Otherwise, the value is set to ``ceil(shots/shots_per_randomization)``.
+    num_randomizations: Union[UnsetType, int, Literal["auto"]] = Unset
+    r"""The number of random samples to use when twirling or peforming sampled mitigation.
 
-          Default: "auto".
+    If ``num_randomizations`` is "auto", for every pub executed ``shots`` times:
 
-        shots_per_randomization: The number of shots to run for each random sample. If "auto", for
-          every pub executed ``shots`` times:
+      * If ``shots_per_randomization`` is also "auto", ``shots_per_randomization`` is set first
+        as described below, then ``num_randomizations`` is set as
+        ``ceil(shots/shots_per_randomization)``, where ``ceil`` is the ceiling function.
+      * Otherwise, the value is set to ``ceil(shots/shots_per_randomization)``.
 
-          * If ``num_randomizations`` is also "auto", the value is set to ``64`` for PEC mitigation
-            or to ``max(64, ceil(shots / 32))`` in all other cases, where ``ceil`` is the ceiling
-            function.
-          * Otherwise, the value is set to ``ceil(shots/num_randomizations)``.
+      Default: "auto".
+
+    .. note::
+      The ``shots`` value specified in a PUB or in the ``run()`` method is considered part of the
+      primitive execution interface and therefore is always obeyed. ``default_shots``, on the other hand,
+      is considered a Qiskit Runtime specific option. Therefore, the product of
+      ``num_randomizations`` and ``shots_per_randomization`` takes precedence over ``default_shots``.
+    """
+
+    shots_per_randomization: Union[UnsetType, int, Literal["auto"]] = Unset
+    r"""The number of shots to run for each random sample.
 
-          Default: "auto".
+    If "auto", for every pub executed ``shots`` times:
 
-        strategy: Specify the strategy of twirling qubits in identified layers of
-            2-qubit twirled gates. Allowed values are
+      * If ``num_randomizations`` is also "auto", the value is set to ``64`` for PEC mitigation
+        or to ``max(64, ceil(shots / 32))`` in all other cases, where ``ceil`` is the ceiling
+        function.
+      * Otherwise, the value is set to ``ceil(shots/num_randomizations)``.
 
-            * If ``"active"`` only the instruction qubits in each individual twirled
-              layer will be twirled.
-            * If ``"active-circuit"`` the union of all instruction qubits in the circuit
-              will be twirled in each twirled layer.
-            * If ``"active-accum"`` the union of instructions qubits in the circuit up to
-              the current twirled layer will be twirled in each individual twirled layer.
-            * If ``"all"`` all qubits in the input circuit will be twirled in each
-              twirled layer.
+      Default: "auto".
 
-            Default: "active-accum".
+    .. note::
+      The ``shots`` value specified in a PUB or in the ``run()`` method is considered part of the
+      primitive execution interface and therefore is always obeyed. ``default_shots``, on the other hand,
+      is considered a Qiskit Runtime specific option. Therefore, the product of
+      ``num_randomizations`` and ``shots_per_randomization`` takes precedence over ``default_shots``.
     """
 
-    enable_gates: Union[UnsetType, bool] = Unset
-    enable_measure: Union[UnsetType, bool] = Unset
-    num_randomizations: Union[UnsetType, int, Literal["auto"]] = Unset
-    shots_per_randomization: Union[UnsetType, int, Literal["auto"]] = Unset
     strategy: Union[UnsetType, TwirlingStrategyType] = Unset
+    r"""Specify the strategy of twirling qubits in identified layers of 2-qubit twirled gates.
+
+    Allowed values are:
+
+      * If ``"active"`` only the instruction qubits in each individual twirled
+        layer will be twirled.
+      * If ``"active-circuit"`` the union of all instruction qubits in the circuit
+        will be twirled in each twirled layer.
+      * If ``"active-accum"`` the union of instructions qubits in the circuit up to
+        the current twirled layer will be twirled in each individual twirled layer.
+      * If ``"all"`` all qubits in the input circuit will be twirled in each
+        twirled layer.
+
+      Default: "active-accum".
+    """
 
     _ge1 = make_constraint_validator("num_randomizations", "shots_per_randomization", ge=1)

qiskit_ibm_runtime/options/zne_options.py

@@ -83,7 +83,7 @@ class ZneOptions:
             * `"gate_folding_back"` uses 2-qubit gate folding to amplify noise. If the noise
               factor requires amplifying only a subset of the gates, then these gates are selected
               from the back of the topologically ordered DAG circuit.
-            * `"pea"` uses a technique called probabalistic error amplification (`PEA
+            * `"pea"` uses a technique called Probabilistic Error Amplification (`PEA
               <https://www.nature.com/articles/s41586-023-06096-3>`_) to amplify
               noise.