Skip to content

Update AI transpiler introduction tutorial to new template#4968

Open
henryzou50 wants to merge 18 commits into
Qiskit:mainfrom
henryzou50:update-QATSI
Open

Update AI transpiler introduction tutorial to new template#4968
henryzou50 wants to merge 18 commits into
Qiskit:mainfrom
henryzou50:update-QATSI

Conversation

@henryzou50
Copy link
Copy Markdown
Collaborator

Summary

Revised ai-transpiler-introduction.ipynb to follow the Tutorial_Template structure, simplifying the tutorial to focus on comparing the default transpiler (SABRE) vs the AI transpiler using random circuits.

Key changes from the old notebook:

  • Simplified circuit selection: Uses only random circuits with 2-qubit gates (instead of efficient_su2, QFT, BV, Clifford, and permutation circuits)
  • Added execution and fidelity testing: The old notebook skipped Steps 3-4 entirely ("no experiments will be executed"). The revised version uses mirror circuits to measure fidelity on both an Aer simulator (with a depolarizing noise model) and real hardware
  • Removed Part II benchmarking and Part III permutation synthesis: Consolidated into a focused Default vs AI comparison
  • Added quantitative analysis: Summary tables with mean/stdev for 2Q depth, gate count, and transpilation time, plus percentage improvement plots
  • Added commentary: Markdown cells discussing the depth vs gate count trade-off (AI optimizes depth, SABRE minimizes gate count), transpilation time scaling, and mirror circuit fidelity limitations at large scale
  • Template compliance: Follows the 4-step Qiskit patterns structure (Map, Optimize, Execute, Post-process) for both small-scale simulator and large-scale hardware examples

Tutorial structure:

  • Small-scale simulator example (6-25 qubits, depth 4): Full 4-step walkthrough with Aer simulator fidelity test on the 10-qubit case
  • Large-scale hardware example (26-50 qubits, depth 8): Compressed workflow with real hardware submission on the 26-qubit case

Revised ai-transpiler-introduction.ipynb following the Tutorial_Template
structure.

- Compare default (SABRE) vs AI transpiler using random circuits with
  only 2-qubit gates across small-scale (6-25 qubits) and large-scale
  (26-50 qubits) examples
- Use mirror circuits to evaluate transpilation fidelity on both Aer
  simulator (with depolarizing noise model) and real hardware
- Add summary tables with mean/stdev and percentage improvement metrics
- Add percentage improvement plots comparing AI vs default transpiler
- Include commentary on depth vs gate count trade-offs between the two
  strategies
@henryzou50 henryzou50 requested a review from a team April 10, 2026 09:20
@qiskit-bot
Copy link
Copy Markdown
Contributor

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

  • @henryzou50
  • @nathanearnestnoble

@review-notebook-app
Copy link
Copy Markdown

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@henryzou50 henryzou50 changed the title Revise AI transpiler introduction tutorial Update AI transpiler introduction tutorial to new template Apr 10, 2026
Copy link
Copy Markdown
Collaborator

@nathanearnestnoble nathanearnestnoble left a comment

Choose a reason for hiding this comment

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

The large scale section states "step 1-4 compress into single code block" but is in multiple blocks. Would suggest removing "compress into single code block"

@github-project-automation github-project-automation Bot moved this to In Review in Docs Planning Apr 13, 2026
@henryzou50
Copy link
Copy Markdown
Collaborator Author

The large scale section states "step 1-4 compress into single code block" but is in multiple blocks. Would suggest removing "compress into single code block"

Thanks @nathanearnestnoble , I just pushed a change for that and added the reasoning for why we don't compress the large scale example into a single code block for this tutorial.

@henryzou50 henryzou50 requested a review from kaelynj May 18, 2026 18:43
Copy link
Copy Markdown
Collaborator

@kaelynj kaelynj left a comment

Choose a reason for hiding this comment

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

Looking pretty good so far! Left some comments to address

Also a side note: @henryzou50 you should have write access to the repo now since you're a regular contributor so you shouldn't need to open PRs through a fork.

Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb Outdated
Comment thread docs/tutorials/ai-transpiler-introduction.ipynb
henryzou50 and others added 9 commits June 4, 2026 15:12
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
Co-authored-by: Kaelyn Ferris <43348706+kaelynj@users.noreply.github.com>
From Kaelynj's review:
- Replace the pandas DataFrame summary with a plain printed table, since
  the DataFrame did not render correctly on the docs web page
- Remove the per-circuit print output from the transpilation loops; only
  the mean/std summary table is needed
- Plot 1 - P(|0...0>) instead of the raw survival probability so the
  mirror-circuit fidelity results are legible (the raw bars were flat
  near zero on hardware)
- Restore the AI-synthesis coupling-map limitation note in the analysis
- Drop "service" from the H1 heading so it matches the frontmatter title
- Apply wording suggestions in the fidelity analysis

Additional changes:
- Refactor summary/plot helpers to work off the list of result dicts and
  remove the pandas dependency entirely
- Reconcile commentary with the re-run results: circuit depth (4, not 5),
  depth/gate-count percentages, the 10-qubit fidelity discussion, and the
  large-scale noise-floor wording
- Fix the stale "reduced coupling map" description in Step 2 to reflect
  the actual transpile-to-full-backend + remap_to_contiguous approach
- Convert absolute quantum.cloud.ibm.com doc links to relative paths for
  consistency with other recently updated tutorials
- Fix the broken generate_preset_pass_manager reference link and typo in
  the Background section
@henryzou50
Copy link
Copy Markdown
Collaborator Author

Thanks so much for the review, @kaelynj I've applied your suggestions:

  • Swapped the pandas DataFrames for plain printed tables (they weren't rendering correctly on the web page)
  • Removed the per-circuit loop output so only the mean/std summary table shows
  • The mirror-circuit fidelity plots now show 1 - P(|0...0>) instead of the raw probability, so the results read much more clearly
  • Restored the AI-synthesis coupling-map limitation note in the analysis
  • Dropped "service" from the heading/prose to match the updated title

While I was in there, I also made a few related changes:

  • Removed the pandas dependency entirely (the summary/plot helpers now work directly off the results list)
  • Re-ran the notebook and reconciled the commentary with the new numbers (circuit depth, the depth/gate-count percentages, the 10-qubit fidelity discussion, and the large-scale noise-floor wording)
  • Fixed a stale "reduced coupling map" description in Step 2 that no longer matched the code
  • Converted the absolute doc links to relative paths for consistency with the other recently updated tutorials, and fixed a broken generate_preset_pass_manager link in the Background section

Let me know if you'd like any further changes!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: In Review

Development

Successfully merging this pull request may close these issues.

4 participants