From dc90d76988717c1ce057793ea58e77e6ca23e30d Mon Sep 17 00:00:00 2001 From: Jessie Yu Date: Thu, 11 Jun 2026 09:10:55 -0400 Subject: [PATCH 1/2] add notes --- docs/guides/estimator-options.ipynb | 8 ++++++++ docs/guides/sampler-options.ipynb | 4 ++++ 2 files changed, 12 insertions(+) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 4f7755869e3..3bd6e37426b 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -250,6 +250,10 @@ "\n", "However, if `precision` is not specified by any PUB or in the run keyword argument (or if they are all `None`), then the precision value from the options is used, most notably `default_precision`.\n", "\n", + "\n", + "These precision parameters are only for specifying _target_ precision, and the results are not guaranteed to reach the specified precision.\n", + "\n", + "\n", "Note that Estimator options contain both `default_shots` and `default_precision`. However, because gate-twirling is enabled by default, the product of `num_randomizations` and `shots_per_randomization` takes precedence over those two options.\n", "\n", "Specifically, for any Estimator PUB:\n", @@ -263,6 +267,10 @@ "For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used.\n", "\n", "\n", + "Although precision specified in the PUB and in `run` have higher precedence, the job would fail if `twirling` is enabled and the product of `num_randomizations` and `shots_per_randomization` is smaller than the shots needed to achieve the precision. In this scenario `EstimatorV2` does not know how to allocate the shots among the specified `num_randomizations`.\n", + "\n", + "\n", + "\n", "Precision scales inversely with usage. That is, the lower the precision, the more QPU time it takes to run.\n", "" ] diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 754a1747b5a..995976a82ca 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -144,6 +144,10 @@ "\n", "Thus, if shots are specified in all possible places, the one with highest precedence (shots specified in the PUB) is used.\n", "\n", + "\n", + "Although shots specified in the PUB and in `run` have higher precedence, the job would fail if `twirling` is enabled and the product of `num_randomizations` and `shots_per_randomization` is smaller than the `shots` value. In this scenario `SamplerV2` does not know how to allocate the shots among the specified `num_randomizations`.\n", + "\n", + "\n", "Example:" ] }, From 1b22889f364e162f52d4fbb355ede58ea6c72575 Mon Sep 17 00:00:00 2001 From: Jessie Yu Date: Thu, 11 Jun 2026 14:58:01 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: abbycross --- docs/guides/estimator-options.ipynb | 2 +- docs/guides/sampler-options.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/estimator-options.ipynb b/docs/guides/estimator-options.ipynb index 3bd6e37426b..999f42c9dc7 100644 --- a/docs/guides/estimator-options.ipynb +++ b/docs/guides/estimator-options.ipynb @@ -267,7 +267,7 @@ "For example, if precision is specified in all four places, the one with highest precedence (precision specified in the PUB) is used.\n", "\n", "\n", - "Although precision specified in the PUB and in `run` have higher precedence, the job would fail if `twirling` is enabled and the product of `num_randomizations` and `shots_per_randomization` is smaller than the shots needed to achieve the precision. In this scenario `EstimatorV2` does not know how to allocate the shots among the specified `num_randomizations`.\n", + "Although precision specified in the PUB and in `run` have higher precedence, the job fails if `twirling` is enabled and the product of `num_randomizations` and `shots_per_randomization` is smaller than the shots needed to achieve the precision. In this scenario, `EstimatorV2` is unable to allocate the shots among the specified `num_randomizations`.\n", "\n", "\n", "\n", diff --git a/docs/guides/sampler-options.ipynb b/docs/guides/sampler-options.ipynb index 995976a82ca..d2e24d83589 100644 --- a/docs/guides/sampler-options.ipynb +++ b/docs/guides/sampler-options.ipynb @@ -145,7 +145,7 @@ "Thus, if shots are specified in all possible places, the one with highest precedence (shots specified in the PUB) is used.\n", "\n", "\n", - "Although shots specified in the PUB and in `run` have higher precedence, the job would fail if `twirling` is enabled and the product of `num_randomizations` and `shots_per_randomization` is smaller than the `shots` value. In this scenario `SamplerV2` does not know how to allocate the shots among the specified `num_randomizations`.\n", + "Although shots specified in the PUB and in `run` have higher precedence, the job fails if `twirling` is enabled and the product of `num_randomizations` and `shots_per_randomization` is smaller than the `shots` value. In this scenario, `SamplerV2` is unable to allocate the shots among the specified `num_randomizations`.\n", "\n", "\n", "Example:"