Update the tutorial on fractional gates

[t-imamichi]

I went through the tutorial with the latest Qiskit 2.4.1, updated some information and re-ran it with a latest device.

cc: @nathanearnestnoble

[qiskit-bot]

One or more of the following people are relevant to this code:

• @nathanearnestnoble
• @t-imamichi

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[abbycross]

Thanks!

[nathanearnestnoble]

@t-imamichi , it would be great if we could update this to conform to the new tutorial template. Will share with you in DM.

[t-imamichi]

Btw, I found an issue Qiskit/qiskit#16462 of the upcoming version 2.5.0 of Qiskit when updating this notebook.

[henryzou50]

Thanks for the updates and overall LGTM. The structure now conforms to the tutorial template and all earlier review items we discussed before are resolved.

Note we do have one issue on RZZ angle validity, as you mentioned, which make out-of-range RZZ angles urvive transpilation. Looks like this tutorial hits the exact trigger conditions: optimization_level = 2 + randomly generated (often negative) RZZ angles + a fractional backend. As mtreinish explained, because IBMBackend's target doesn't set RZZ angle bounds, the optimization loop can resynthesize a 2q block into an out-of-range RZZ after FoldRzzAngle has run, producing a circuit that fails validation on hardware submission. Note the small-scale Aer example won't surface this (the simulator doesn't enforce the angle bound), but the large-scale hardware submission can fail.

Since the bug pre-exists 2.5.0 and the upstream fix (qiskit-ibm-runtime#2441) has no committed timeline, I'd recommend we merge with mtreinish's bridge workaround now and remove it once #2441 lands, rather than block indefinitely.

One note on applying it: since the PR restructured the notebook, the fix needs to go in two places, not just the single cell Matt referenced in the old published version:

• the small-scale pm_f (where backend_f is built), and
• inside benchmark() for the large-scale run, so it only runs on the fractional backend, something like if "rzz" in backend.target.operation_names: pm.post_optimization.append(FoldRzzAngle()).

The benchmark() one is the important one here, since that's the path that actually submits to hardware. I don't believe the advanced-topic pass managers don't need it as they remove RZZ from the target. Also worth double-checking the exact class name, as Matt wrote FoldRzz, but runtime 0.46 exposes FoldRzzAngle.

[t-imamichi]

Thank you for your suggestion, Henry. I will introduce the workaround and update the corresponding codes.

[t-imamichi]

Note 1: appending FoldRzzAngle to pm.post_optimization is not enough due to some FoldRzzAngle restrictions (it emits redundant gates).
See Qiskit/qiskit-ibm-runtime#2256 (comment) for the details.

Note 2: Troubleshooting section moves to Background section with "Warning" tag and introduced the workaround explicitly.

[henryzou50]

Thanks for the updates @t-imamichi, the RZZ angle handling is in good shape now, and the changes look good.

Two small things:

1. In the small-scale "Step 2" optimize cell, pm_f is created with backend=backend_f, but its post_optimization passes use target=backend.target. Since backend is the non-fractional least_busy backend, this should likely be backend_f.target to match the pass manager's backend (the benchmark() function in the large-scale example already uses the correct target). Could you confirm or fix?

2. In the "Large-scale hardware example → Steps 1-4 combined" cell, the four steps are merged into a single block with no internal markers. Could you add inline dividers like # -------------------------Step 1------------------------- (as in Tutorial template) so readers can map the combined code back to Steps 1–4? It makes the large-scale block much easier to follow.

A few minor copyedits while you're in there:

• "Optimize U gates" section: "the total number of gates is reduced compare to" → "compared to", and "provided by qiskit-basis-constructor package" → "provided by the qiskit-basis-constructor package".
• "Workflow approaches": "The workflow for using the fractional gates" → drop "the".
• "Approach 2" intro: "This asks you to assign parameter values…" → "This approach requires you to assign…".
• The learning outcomes/prerequisites use "users" while the body uses "you", worth making the voice consistent.

[abbycross]

I converted the markdown warning to an Admonition component, and I also did some rewording around the first vs. second approach language. I hope I've simplified/clarified it, but please review my change to ensure it aligns with what you're trying to communicate.

[t-imamichi]

Thank you @abbycross for revising my text. Looks great.