docs(notebooks): add estimator utility scaling demo

[ashsaki]

Summary

This PR creates a variant of the scaling notebook using Qiskit Runtime's EstimatorV2 and its built-in error mitigation capabilities.

Details and comments

The notebook shows how configure EstimatorV2s built-in error mitigation options to run any circuit at scale. It covers following runs and compares the results.

1. no mitigation
2. Dynamical Decoupling (DD)
3. DD + Twirled Readout Error Extinction (TREx)
4. DD + TREx + (Gate) Twirling
5. DD + TREx + Twirling + Zero Noise Extrapolation (ZNE)

[coveralls]

Pull Request Test Coverage Report for Build 8621923842

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 8607756967:	0.0%
Covered Lines:	290
Relevant Lines:	290

---

💛 - Coveralls

[pedrorrivero]

This is looking great, @ashsaki.

I really like the new plots that you are introducing although some of them we maybe want to study further (e.g. why DD worsens the results?)

Just as a suggestion, it would be great if we could still reproduce some of the same plots from the original scaling notebook here for comparison.

[pedrorrivero]

Also, @ashsaki , can you move the notebook outside of the scaling directory? That directory is there to hold all relevant files for the other demo for automated upload to the LP.

We need to think of short, distinct names for the two notebooks 🙂

[pedrorrivero]

Also, @ashsaki , can you move the notebook outside of the scaling directory? That directory is there to hold all relevant files for the other demo for automated upload to the LP.

We need to think of short, distinct names for the two notebooks 🙂

We have decided on the following names:

• scaling-sampler
• scaling-estimator

[pedrorrivero]

I really like the new plots that you are introducing although some of them we maybe want to study further (e.g. why DD worsens the results?)

Results are looking correct now.

Just as a suggestion, it would be great if we could still reproduce some of the same plots from the original scaling notebook here for comparison.

We cannot reproduce the original plots at different noise factors, because the noisy expectation values are only reported through experimental settings (which are discouraged)

[ashsaki]

I really like the new plots that you are introducing although some of them we maybe want to study further (e.g. why DD worsens the results?)

Results are looking correct now.

I did a new run to separate out the weight-1 and weight-2 observable results. In the new results, DD expectation values are almost identical to no-mitigation one. As the example MBL circuit is quite dense, there are little to none idle qubits. It may be a reason behind similar results with DD vs. no-mitigation. Add this as a note in the notebook.

The PR is now up for review @pedrorrivero.

[pedrorrivero]

Thanks @ashsaki , excellent work! 🥳

A few comments to address:

• You can add our names as authors if you want, in the same style as we have for scaling-sampler (maybe avoid emails)
• Notice that in the scaling-sampler notebook we declare the compute-uncompute function directly in the notebook instead of importing it. Please do so here as well, and make sure that there are no other code discrepancies.
• Delete instance = ....
• Delete all commented-out code that is not meant to be uncommented (e.g. different backends)
• We need to clarify that Runtime does everything for us, and that we are only using other tools for illustration purposes (e.g. DD, PT, ZNE).
  • Note at the very beginning of the notebook.
  • Wherever we use some other tool.
  • Point out in Step 3 that the circuits to be submitted are those without any modifications (e.g. no DD, PT, ZNE).
• When explaining TREX, I think it would be better to explain it in terms twirled measurements and calibrations, as it connects with the Runtime options as well as with the previously introduced concept of twirling, and it also teaches about the needed quantum overhead. We can work together on this if you want.
• ISA stands for Instruction Set Architecture (i.e. basis gates and topology). It affects the observables only secondhand through the effects that take place on the circuits themselves (e.g. circuit layout, routing). Therefore, I am not too convinced about the notion of ISA observables.
• Introduce ISA in the transpilation section.
• Indicate the version of Runtime for which you are listing out options.
• In your tip re/ Runtime's Session it might be more useful to mention execution modes in general and link to the relevant docs.
• For this use case Batch mode is better than session.
• We must encourage people to close the Runtime session/batch! The easiest way to do this is by opening it in a context manager: with Session(...) as session:. Alternatively you can call session.close().
  • Close right after submission.
  • Remove "optional" word.
  • Say that the session will close automatically after the iTTL, but that closing manually is encouraged for efficiency and to avoid unnecessary waiting time.
  • Explain that for a better programming experience it is better to use a context manager and point to documentation → maybe we should use it as well, this would place all execution commands in one cell and avoid the risk of users running the notebook exceeding the iTTL.
  • Add hyperlink to docs explaining iTTL, instead of just pasting the URL.
• Remove unnecessary comment for estimator.options.resilience_level = 0
• Question: when you do estimator.options.resilience_level = 1 do you override previously defined (advanced) settings?
• Update: "Each PrimitiveResult object has a list-like structure holding PubResults. Common metadata is also available inside of PrimitiveResult."
• Write the full word "No-mitigation" in the plots
• I think it would be better to show weight-1, weight-2 and average in the same plot. you don't need to specify this in the title, it is already clear in the legend.
• Remove the two M3 references and add TREX.

Also, what is this for? Does it make sense to keep it for users to know about it?

%config InlineBackend.figure_format='retina'

[ashsaki]

• You can add our names as authors if you want, in the same style as we have for scaling-sampler (maybe avoid emails)

Omitted as most other notebooks do not have author names.

• Notice that in the scaling-sampler notebook we declare the compute-uncompute function directly in the notebook instead of importing it. Please do so here as well, and make sure that there are no other code discrepancies.

Done. Let me know if you find other discrepancies.

• Delete instance = ....

Deleted.

• Delete all commented-out code that is not meant to be uncommented (e.g. different backends)

Deleted.

• We need to clarify that Runtime does everything for us, and that we are only using other tools for illustration purposes (e.g. DD, PT, ZNE).

  • Note at the very beginning of the notebook.
    Done.
  • Wherever we use some other tool.
  • Point out in Step 3 that the circuits to be submitted are those without any modifications (e.g. no DD, PT, ZNE).

Done. (too many pointing outs now?)

• When explaining TREX, I think it would be better to explain it in terms twirled measurements and calibrations, as it connects with the Runtime options as well as with the previously introduced concept of twirling, and it also teaches about the needed quantum overhead. We can work together on this if you want.

Need help. Will work together.

• ISA stands for Instruction Set Architecture (i.e. basis gates and topology). It affects the observables only secondhand through the effects that take place on the circuits themselves (e.g. circuit layout, routing). Therefore, I am not too convinced about the notion of ISA observables.

Agree. Changed to physical_observable instead.

• Introduce ISA in the transpilation section.

Done.

• Indicate the version of Runtime for which you are listing out options.

Did not understand completely. We are listing software dependencies at the end of the notebook. Do we need to call qiskit_ibm_runtime.__version__ here as well?

• In your tip re/ Runtime's Session it might be more useful to mention execution modes in general and link to the relevant docs.

Done. Removed the tip banner and replaced it with texts that mentions execution modes Batch and Session and refers to the doc.

• For this use case Batch mode is better than session.

Switched to Batch with a context manager.

• We must encourage people to close the Runtime session/batch! The easiest way to do this is by opening it in a context manager: with Session(...) as session:. Alternatively you can call session.close().

Used context manager which automatically handles the closing.

• Close right after submission.
• Remove "optional" word.
• Say that the session will close automatically after the iTTL, but that closing manually is encouraged for efficiency and to avoid unnecessary waiting time.
• Explain that for a better programming experience it is better to use a context manager and point to documentation → maybe we should use it as well, this would place all execution commands in one cell and avoid the risk of users running the notebook exceeding the iTTL.

Not relevant anymore as switched to Batch with a context manager. Also, Batch does not have a notion of ITTL.

• Add hyperlink to docs explaining iTTL, instead of just pasting the URL.

Not relevant anymore due to switch to Batch with context manager. I prefer not to mention ITTL anymore as it is not relevant.

• Remove unnecessary comment for estimator.options.resilience_level = 0

Removed.

• Question: when you do estimator.options.resilience_level = 1 do you override previously defined (advanced) settings?

Not affirmative. In this notebook, advanced settings are coming later. If needed, we can find the answer separately.

• Update: "Each PrimitiveResult object has a list-like structure holding PubResults. Common metadata is also available inside of PrimitiveResult."

Updated.

• Write the full word "No-mitigation" in the plots

Done.

• I think it would be better to show weight-1, weight-2 and average in the same plot. you don't need to specify this in the title, it is already clear in the legend.

Done. Merged two plots into one.

• Remove the two M3 references and add TREX.

Found one reference to M3 and removed that. Could not find the second reference.

Also, what is this for? Does it make sense to keep it for users to know about it?

%config InlineBackend.figure_format='retina'

This is for high resolution plots. Removed as it is a nicety not a necessity.

[pedrorrivero]

Looking better! Final remarks:

• Let's go together about the notes on external tools in a call and get to the right amount and style
• Use consistent color scheme for color boxes:
  • Note → blue
  • Warning → yellow
  • Tip → green
  • Danger → red
• Use consistent naming and capitalization: Qiskit Runtime
• In the EstimatorV2 section, where you present the options, please say that those are the options as of Runtime version X.Y.Z
• Move TREX reference up, between current references [5] and [6]
• Regarding the text for TREX how about:

Twirled readout error extinction (TREX) is an efficient method for mitigating measurement errors on expectation value problems for Pauli observables. It is based on the notion of twirled measurements, which are accomplished by randomly substituting measurement gates by a sequence of (1) a Pauli-X gate, (2) a measurement, and (3) classical bit flip. Just like in standard gate twirling, this sequence amounts to the same as just a single measurement in the absence of noise; otherwise, it will have the effect of diagonalizing the readout-error transfer matrix, making it trivial to invert. To find such inverse, identity circuits with random measurement twirls need to be executed for calibration, which induces overhead on the quantum hardware.

[pedrorrivero]

Great job @ashsaki! LGTM 🥳