Skip to content

Add some notes about shots and precision #5249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jyu00 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add some notes about shots and precision #5249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dc90d76
add notes
jyu00 Jun 11, 2026
1b22889
Apply suggestions from code review
jyu00 Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/guides/estimator-options.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
"<Admonition type=\"note\">\n",
"These precision parameters are only for specifying _target_ precision, and the results are not guaranteed to reach the specified precision.\n",
"</Admonition>\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",
Expand All @@ -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",
"<Admonition type=\"note\">\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",
"</Admonition>\n",
"\n",
"<Admonition type=\"note\">\n",

@abbycross abbycross Jun 11, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just confirming that you want two admonition boxes in a row - it's fine if intentional

Image

@jyu00 jyu00 Jun 11, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept them separate only because they refer to different things, but I don't feel too strongly either way. Do we usually use 1 box to group these together?

@abbycross abbycross Jun 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If they are related enough, we can list them as bullet points in the same admonition - but I think it's fine to keep these as two admonitions, even one after the other like this, since it adds readability and emphasis, which I think you want here. I just wanted to be sure that was the intent.

"Precision scales inversely with usage. That is, the lower the precision, the more QPU time it takes to run.\n",
"</Admonition>"
]
Expand Down
4 changes: 4 additions & 0 deletions docs/guides/sampler-options.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
"<Admonition type=\"note\">\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",
"</Admonition>\n",
"\n",
"Example:"
]
},
Expand Down
Loading