Ajc/updates to docs for migration#818
Open
abbycross wants to merge 10 commits into
Open
Conversation
abbycross
commented
Jun 11, 2026
| In this package, the number of samples taken from the distribution is generally controlled by a ``num_samples`` argument, and each sample has an associated weight that is used during expectation value reconstruction. Each weight with absolute value above a threshold of 1 / ``num_samples`` will be evaluated exactly. The remaining low-probability elements — those in the tail of the distribution — will then be sampled, resulting in at most ``num_samples`` unique weights. Setting ``num_samples`` to infinity indicates that all weights should be generated rigorously, rather than by sampling from the distribution. | ||
|
|
||
| Much of the circuit cutting literature describes a process where we sample from the distribution, take a single shot, then sample from the distribution again and repeat; however, this is not feasible in practice, so we instead perform all sampling upfront. For now, because of limitations in version 1 of the Qiskit primitives, we take a fixed number of shots for each considered subexperiment and send the subexperiments to the backend(s) in batches. During reconstruction, each subexperiment contributes to the final result with proportion equal to its weight. One must ensure the number of shots taken is sufficient for the heaviest weighted subexperiment. In the future, we plan to support passing an individual ``shots`` count with each subexperiment to Qiskit Runtime, so that each subexperiment will be run with a number of shots proportional to that subexperiment's weight in the final result (see issue `#532 <https://github.com/Qiskit/qiskit-addon-cutting/issues/532>`__). This per-experiment shots count is a new feature enabled by version 2 of the Qiskit primitives. | ||
| Much of the circuit cutting literature describes a process where we sample from the distribution and take a single shot, then sample from the distribution again and repeat; however, this is not feasible in practice, so we instead perform all sampling upfront. For now, because of limitations in version 1 of the Qiskit primitives, we take a fixed number of shots for each considered subexperiment and send the subexperiments to the backend(s) in batches. During reconstruction, each subexperiment contributes to the final result with proportion equal to its weight. We must ensure the number of shots taken is sufficient for the heaviest weighted subexperiment. In the future, we plan to support passing an individual ``shots`` count with each subexperiment to Qiskit Runtime, so that each subexperiment will be run with a number of shots proportional to that subexperiment's weight in the final result (see issue `#532 <https://github.com/Qiskit/qiskit-addon-cutting/issues/532>`__). This per-experiment shots count is a new feature enabled by version 2 of the Qiskit primitives. |
Author
There was a problem hiding this comment.
Does this require any updating in:re primitives, or is this all still true?
Member
There was a problem hiding this comment.
The primitives now support this, but this addon still isn't able to leverage that feature -- that's what the issue is about. So I think the wording should be updated to reflect that the primitives v2 have the necessary feature, and there is an open issue to allow the addon to leverage this. I suggest removing the phrase "In the future, we plan to support" because it is not clear that anyone has plans at this point to fix this issue.
By the way, I expect that the —s will not render properly in Sphinx/restructedtext. Would you be open to using either three contiguous hyphens (---) or a unicode mdash?
Author
There was a problem hiding this comment.
I think unicode will work but I'm not sure how translation will deal with the three hyphens (which is why I have been using — in the first place). Will we still be running sphinx once the docs have migrated?
Member
There was a problem hiding this comment.
@eharvey328 can clarify -- but my understanding is that the documentation pipeline will run Sphinx and use its output as input to a later stage of the build. Assuming this is correct, then --- will be converted to the mdash unicode character when Sphinx runs.
Author
There was a problem hiding this comment.
Ah I see! That would indeed make things easier. @eharvey328 would -- also get converted to emdash in unicode?
Member
There was a problem hiding this comment.
I believe that Sphinx will convert -- to an ndash instead.
abbycross
commented
Jun 12, 2026
Author
garrison
reviewed
Jun 24, 2026
| There are two types of cuts: gate cuts and wire cuts. Gate cuts, also known as "space-like" cuts, exist when the cut goes through a gate operating on two (or more) qubits. Wire cuts, also known as "time-like" cuts, are direct cuts through a qubit wire; essentially, they are single-qubit identity gates that have been cut into two pieces. In this package, a wire cut is represented by introducing a new qubit into the circuit and moving remaining operations after the cut identity gate to the new qubit; see :ref:`wire cutting as move`. | ||
|
|
||
| There are `three settings <https://research.ibm.com/blog/circuit-knitting-with-classical-communication>`__ to consider for circuit cutting. The first is where only local operations (LO) [i.e., local *quantum* operations] are available. The other settings introduce classical communication between the circuit executions, which is known in the quantum information literature as LOCC, for `local operations and classical communication <https://en.wikipedia.org/wiki/LOCC>`__. The LOCC can be either near-time, one-directional communication between the circuit executions (the second setting), or real-time, bi-directional communication (the third setting). | ||
| There are `three settings <https://www.ibm.com/quantum/blog/circuit-knitting-with-classical-communication>`__ to consider for circuit cutting. The first is where only local operations (LO) — as in, local *quantum* operations — are available. The other settings introduce classical communication between the circuit executions, which is known in the quantum information literature as LOCC, for `local operations and classical communication <https://en.wikipedia.org/wiki/LOCC>`__. The LOCC can be either near-time, one-directional communication between the circuit executions (the second setting), or real-time, bi-directional communication (the third setting). |
Member
There was a problem hiding this comment.
will render by Sphinx as an mdash instead of literally as the text —
Suggested change
| There are `three settings <https://www.ibm.com/quantum/blog/circuit-knitting-with-classical-communication>`__ to consider for circuit cutting. The first is where only local operations (LO) — as in, local *quantum* operations — are available. The other settings introduce classical communication between the circuit executions, which is known in the quantum information literature as LOCC, for `local operations and classical communication <https://en.wikipedia.org/wiki/LOCC>`__. The LOCC can be either near-time, one-directional communication between the circuit executions (the second setting), or real-time, bi-directional communication (the third setting). | |
| There are `three settings <https://www.ibm.com/quantum/blog/circuit-knitting-with-classical-communication>`__ to consider for circuit cutting. The first is where only local operations (LO) --- as in, local *quantum* operations --- are available. The other settings introduce classical communication between the circuit executions, which is known in the quantum information literature as LOCC, for `local operations and classical communication <https://en.wikipedia.org/wiki/LOCC>`__. The LOCC can be either near-time, one-directional communication between the circuit executions (the second setting), or real-time, bi-directional communication (the third setting). |
| Sample weights in the Qiskit addon for circuit cutting | ||
| ------------------------------------------------------ | ||
| In this package, the number of samples taken from the distribution is generally controlled by a ``num_samples`` argument, and each sample has an associated weight which is used during expectation value reconstruction. Each weight with absolute value above a threshold of 1 / ``num_samples`` will be evaluated exactly. The remaining low-probability elements -- those in the tail of the distribution -- will then be sampled, resulting in at most ``num_samples`` unique weights. Setting ``num_samples`` to infinity indicates that all weights should be generated rigorously, rather than by sampling from the distribution. | ||
| In this package, the number of samples taken from the distribution is generally controlled by a ``num_samples`` argument, and each sample has an associated weight that is used during expectation value reconstruction. Each weight with absolute value above a threshold of 1 / ``num_samples`` will be evaluated exactly. The remaining low-probability elements — those in the tail of the distribution — will then be sampled, resulting in at most ``num_samples`` unique weights. Setting ``num_samples`` to infinity indicates that all weights should be generated rigorously, rather than by sampling from the distribution. |
Member
There was a problem hiding this comment.
Suggested change
| In this package, the number of samples taken from the distribution is generally controlled by a ``num_samples`` argument, and each sample has an associated weight that is used during expectation value reconstruction. Each weight with absolute value above a threshold of 1 / ``num_samples`` will be evaluated exactly. The remaining low-probability elements — those in the tail of the distribution — will then be sampled, resulting in at most ``num_samples`` unique weights. Setting ``num_samples`` to infinity indicates that all weights should be generated rigorously, rather than by sampling from the distribution. | |
| In this package, the number of samples taken from the distribution is generally controlled by a ``num_samples`` argument, and each sample has an associated weight that is used during expectation value reconstruction. Each weight with absolute value above a threshold of 1 / ``num_samples`` will be evaluated exactly. The remaining low-probability elements --- those in the tail of the distribution --- will then be sampled, resulting in at most ``num_samples`` unique weights. Setting ``num_samples`` to infinity indicates that all weights should be generated rigorously, rather than by sampling from the distribution. |
abbycross
commented
Jun 24, 2026
Co-authored-by: Jim Garrison <jim@garrison.cc>
garrison
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preparing addon docs for migration to IBM Quantum Platform