Update transpilation optimizations with SABRE tutorial to new template

[henryzou50]

Summary

Revised transpilation-optimizations-with-sabre.ipynb to follow the Tutorial_Template structure, splitting the tutorial into a small-scale simulator walkthrough and a large-scale hardware comparison of SABRE routing heuristics.

Key changes from the old notebook:

• Removed Qiskit Serverless dependency: The old notebook relied on qiskit_serverless and qiskit-ibm-catalog for Part II. The revised version runs everything locally using standard Qiskit transpiler APIs
• Split into simulator + hardware sections: Replaced the old Part I (110-qubit SABRE parameter tuning) and Part II (serverless heuristic comparison) with a small-scale simulator example (15 qubits, Qiskit Aer) and a large-scale hardware example comparing routing heuristics on real hardware
• Added noisy simulator validation: The small-scale section uses qiskit_aer with a real backend noise model to measure execution fidelity across three SabreLayout configurations, demonstrating how parameter tuning affects actual expectation values
• Added SABRE heuristic comparison: The large-scale section compares basic, decay, and lookahead routing heuristics on real hardware, replacing the old serverless-based approach
• Improved visualizations: Bar charts with percentage-improvement annotations, grouped comparisons, and cleaner layout replacing the old 3x1 stacked subplots
• Streamlined code: Consolidated separate transpile/measure/print cells into loop-based patterns, reducing code duplication
• Updated dependencies: Bumped to Qiskit SDK v2.0+, added Qiskit Aer dependency, switched backend from ibm_boston to least_busy()
• Template compliance: Added learning outcomes, prerequisites, structured background, and next steps sections following the standard tutorial template

Tutorial structure:

• Small-scale simulator example (15 qubits): Configure SabreLayout parameters (layout_trials, swap_trials, max_iterations), transpile a star-topology GHZ circuit, and validate fidelity improvements with an Aer noise model
• Large-scale hardware example: Compare SABRE routing heuristics (basic, decay, lookahead) at scale on real hardware with execution and analysis

[qiskit-bot]

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

• @henryzou50
• @nathanearnestnoble

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[kaelynj]

This looks good to me so far! Just a handful of style/grammar changes to make.

[mtreinish]

It might make sense to split the pass manager construction and mutation into a multiple cells. Then you can visualize the pass manager and show where the indexing and modifications come from. Using the PassManager api for modification of existing pass manager is kind of opaque at the best of times and I think visualizing the details helps explain why this works.

[henryzou50]

Done!

Step 2 is now split into separate "inspect → modify → run" cells: pm_1.layout.draw() shows the default layout stage so the [2] index and the ConditionalController wrapping SabreLayout are visible, and a follow-up pm_3.layout.draw() after the replacement makes the structural change explicit.

The replacement also re-wraps the new SabreLayout in the same ConditionalController + BarrierBeforeFinalMeasurements as the preset, so the only behavioral difference from the default is the SABRE configuration itself. For the most part, this re-warp wouldn't matter, but I added it here for consistency.

[mtreinish]

I'm not sure I buy this as a conclusion for a recommendation. The notebook already demonstrates how you can efficiently try more seeds by increasing the trial count locally in the pass. I can't imagine a scenario where trying to distribute that work across multiple remote nodes provides any speed benefit besides insanely large numbers of trials/seeds or intractably large circuits (like billions of gates). The overhead of resource deployment and communication will far outweigh the runtime of increasing the number of trials in your local thread pool. If you want to try even more seed values you should just increase the trial number further.

[henryzou50]

Agreed, and good points. I adjusted the key takeaways section to now recommend bumping swap_trials / layout_trials locally instead, and notes that SABRE already parallelizes trials across local threads so distribution overhead would dominate any speedup at this work-per-trial.

[mtreinish]

I know it's in the introduction but do you want to link to the lightsabre and sabre papers here too?

[henryzou50]

Added!

[mtreinish]

If we're showing a star topology GHZ circuit it feels like we should also show star prerouting: https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.transpiler.passes.StarPreRouting

Like sabre struggles to find this, but there is a known optimal routing available. So while it's important to show how to experiment with sabre to improve layout, it's also equally important to show that there is sometimes a path to apply specific non-general optimization techniques if you know it improves quality. In the case of star prerouting that the entire circuit is a single star and the backend has a linear path large enough for the optimal routing.

[henryzou50]

Great suggestion! I added StarPreRouting is now integrated as a fourth comparison point in both the small-scale example and the large-scale example. There's also a short note in Step 1 introducing the pass for context.

[mtreinish]

You can simplify this code slightly by running StarPreRouting as a pre_layout stage that will run right before layout. This then gets the efficiency improvements of not having to round trip between a dag and circuit multiple times and integrates the better routing as part of the single pass manager.

Suggested change

	"prerouter = PassManager([StarPreRouting()])\n",
	"qc_linear = prerouter.run(qc)\n",
	"\n",
	"# Transpile the pre-routed circuit with the default level-3 pass manager\n",
	"pm_star = generate_preset_pass_manager(\n",
	" optimization_level=3, backend=backend, seed_transpiler=seed\n",
	")\n",
	"tqc_star = pm_star.run(qc_linear)\n",
	"prerouter = PassManager([StarPreRouting()])\n",
	"# Transpile the pre-routed circuit with the default level-3 pass manager\n",
	"pm_star = generate_preset_pass_manager(\n",
	" optimization_level=3, backend=backend, seed_transpiler=seed\n",
	")\n",
	"pm_star.pre_layout = prerouter\n",
	"tqc_star = pm_star.run(qc)\n",

[henryzou50]

Thanks Matt! I'm currently working on applying StarPreRouting to both the small-scale and large-scale comparison sections (will be in my next push), and while doing that I noticed qiskit's own test suite for StarPreRouting uses an even shorter pattern that avoids the explicit PassManager wrapper:

pm_star = generate_preset_pass_manager(
    optimization_level=3, backend=backend, seed_transpiler=seed
)
pm_star.init += StarPreRouting()

This is a single line on top of the default preset and also avoids the dag↔circuit round-trip (since it runs as part of the StagedPassManager's normal flow). Do you think this is preferable, or is there a reason to use a pre_layout stage instead, e.g. semantic clarity that StarPreRouting is layout-related rather than init-related, or a difference in how it interacts with the other init passes that I should be aware of?

[henryzou50]

Thanks @kaelynj, @mtreinish, and @abbycross for the careful reviews and helpful feedback! I've worked through all the suggestions and pushed updates. One further point, since the tutorial title changed to "Transpilation optimization with SABRE", should I also adjust the notebook name to "transpilation-optimization-with-sabre.ipynb"?

Most of the changes here address @mtreinish's review.

Summary of changes:

Structure / readability of the small-scale SabreLayout example

• Split the monolithic Step 2 cell into separate "inspect → modify → run" cells, and added pm.layout.draw() visualizations so readers can see exactly where SabreLayout lives in the layout stage and how the structure changes after pm.layout.replace(...) runs.
• Re-wrapped the custom SabreLayout in the same ConditionalController + BarrierBeforeFinalMeasurements that the default preset uses, so the only behavioral difference from the default is the SABRE configuration itself (the preset's gating on VF2's perfect mapping is preserved). Same wrapping applied to the routing stage in the large-scale example.

StarPreRouting integration

• Added a short note in Step 1 introducing StarPreRouting as a structure-aware alternative when the circuit topology is known.
• Integrated StarPreRouting as a fourth comparison point in both the small-scale example (as pm_star) and the large-scale example (alongside basic/decay/lookahead).
• On the 100-qubit hardware run, StarPreRouting substantially outperforms every SABRE heuristic, which makes the "general-purpose vs. structure-aware" point land much more clearly than the SABRE-only comparison did.

Analysis & content

• Removed the recommendation to fan seed trials out via Qiskit Serverless (SABRE already parallelizes trials across local threads).
• Added SABRE and LightSABRE paper references to the Next steps section.
• Revised all analysis commentary cells to match the latest run data.

Other small fixes

• Used relative /docs/... link format consistent with other doc links.
• Cleaned up some minor things like a duplicated <Admonition> opener in Next steps.
• Tightened the small-scale fidelity bar chart layout so value labels no longer collide with the chart title.

Happy to iterate further if anything still looks off, especially around the StarPreRouting placement (init += vs. a dedicated pre_layout stage). Thanks again!

[abbycross]

@henryzou50 I don't suggest changing the file name - it means we'd have to add a redirect.