Add tutorial: Compilation methods for Hamiltonian simulation circuits #3553

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Open

henryzou50 wants to merge 8 commits into Qiskit:main from henryzou50:ham-sim-compilation

henryzou50 commented Jul 16, 2025

Add tutorial: Compilation methods for Hamiltonian simulation circuits

This PR adds a new tutorial to the Qiskit documentation titled "Compilation methods for Hamiltonian simulation circuits" and addresses issue #3552

The notebook provides a comparative overview of three compilation methods in Qiskit for Hamiltonian simulation workloads:

SABRE transpiler: Efficient routing and layout optimization.
AI Transpiler: Intelligent, automated transpilation and synthesis for Pauli networks.
Rustiq plugin: Precise and low-depth synthesis for PauliEvolutionGate operations used in Trotterized dynamics.

What the tutorial covers

Compilation strategies for circuits relevant to quantum simulation.
Depth and gate count comparisons across methods.
Circuit examples created from Qiskit’s Patterns module.

Files added

docs/tutorials/100_representative.json
docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

Note: The location of 100_representative.json will likely need to be changed, as week as the notebook's reference of it. This json file is used as the file that contains the benchmarking circuits for Hamlib. What is the best location / most appropriate for this file?

Before finalizing this tutorial

Add a survey link to the end of the notebook (support appreciated).
Update notebook metadata and JSON headers to follow Qiskit documentation conventions (support appreciated).

henryzou50 added 2 commits

July 16, 2025 11:30


          Add tutorial notebook and JSON resource for Hamiltonian simulation co…

517b2b0

…mpilation methods

This commit adds the initial version of the tutorial notebook on compilation methods
for Hamiltonian simulation circuits, along with the accompanying `100_representative.json`
file used for circuit examples.

Still to finalize:
- Placement of the notebook and resource file in the tutorials directory structure
- Internal documentation links and cross-references
- Survey link at the end of the notebook


          Revised the toc, index, and qiskit_bot, and remove survey link and tr…

cafec89

…ademark symbol

Added the corresponding adjustments for creating a new tutorial.

Note that we still need to adjust the json and metadata of the tutorial, which would be done in the PR.

review-notebook-app bot commented Jul 16, 2025

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

CLAassistant commented Jul 16, 2025 •

edited

Loading

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ abbycross
❌ henryzou50
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

Contributor

qiskit-bot commented Jul 16, 2025

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

kaelynj requested review from beckykd and abbycross

July 17, 2025 14:39

miamico requested a review from christopherporter1

July 17, 2025 17:33


          Add metadata

1c75b15

Collaborator

abbycross commented Jul 21, 2025 •

edited

Loading

Can we link to the SABRE deep-dive tutorial mentioned in the Compilation methods overview section? Or if it isn't published yet, we can add a note to that effect. EDIT: Use https://quantum.cloud.ibm.com/docs/tutorials/transpilation-optimizations-with-sabre

abbycross added 5 commits

July 21, 2025 15:06


          spelling and copyedit first few sections

b7d7f72


          next chunk, and fix broken link in index

75233c8


          final chunk

c8cd84a


          Update notebook-testing.toml

030458c


          run ./fix

5486aa5

christopherporter1 reviewed

View reviewed changes

Collaborator

christopherporter1 left a comment

Great tutorial. I learned a lot. Thank you. My comments are relatively minor.

docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

+                   "name": "stderr",
+                   "output_type": "stream",
+                   "text": [
+                    "/var/folders/jt/44gl1rhd26v6ykt0frqzl87r0000gn/T/ipykernel_59246/1325294152.py:17: MatplotlibDeprecationWarning: The get_cmap function was deprecated in Matplotlib 3.7 and will be removed in 3.11. Use ``matplotlib.colormaps[name]`` or ``matplotlib.colormaps.get_cmap()`` or ``pyplot.get_cmap()`` instead.\n",

Collaborator

christopherporter1 Jul 25, 2025

Just flagging this warning, which I also get with all my installs updated. I'm not sure what the fixed syntax will be.

docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

+                   "name": "stderr",
+                   "output_type": "stream",
+                   "text": [
+                    "/var/folders/jt/44gl1rhd26v6ykt0frqzl87r0000gn/T/ipykernel_59246/1325294152.py:17: MatplotlibDeprecationWarning: The get_cmap function was deprecated in Matplotlib 3.7 and will be removed in 3.11. Use ``matplotlib.colormaps[name]`` or ``matplotlib.colormaps.get_cmap()`` or ``pyplot.get_cmap()`` instead.\n",

Collaborator

christopherporter1 Jul 25, 2025

Just flagging this warning

docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

+                   "name": "stderr",
+                   "output_type": "stream",
+                   "text": [
+                    "/var/folders/jt/44gl1rhd26v6ykt0frqzl87r0000gn/T/ipykernel_59246/682414580.py:1: UserWarning: Providing `coupling_map` and/or `basis_gates` along with `backend` is not recommended, as this will invalidate the backend's gate durations and error rates.\n",

Collaborator

christopherporter1 Jul 25, 2025

This warning appears several times. I don't understand why we need to pass basis gates to the pass manager. Won't it get that from the backend? I also don't know why we need this for the tutorial, because won't all the pms get the same set of basis gates from the backend? I do understand that the warning is not really important since this stops at transpilation and never runs anything. If you're sure that this step that throws the error is needed, ignore the comment.

docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

+                  }
+                 ],
+                 "source": [
+                  "# QiskitRuntimeService.save_account(channel=\"ibm_quantum\", token=\"<MY_IBM_QUANTUM_TOKEN>\", overwrite=True, set_as_default=True)\n",

Collaborator

christopherporter1 Jul 25, 2025

channel="ibm_quantum" is no longer valid on Cloud, right?

Collaborator

abbycross Jul 25, 2025

Correct! it should be ibm_quantum_platform for the channel

docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

+                  "- **How to leverage the AI transpiler for advanced, automated circuit optimization.**\n",
+                  "- **How to employ the Rustiq plugin for circuits requiring precise synthesis of operations, particularly in Hamiltonian simulation tasks.**\n",
+                  "\n",
+                  "This tutorial uses three example circuits generated with Qiskit’s patterns module to illustrate the performance of each compilation method. By the end of this tutorial, users will be equipped to choose the appropriate compilation strategy based on their specific requirements and constraints.\n",

Collaborator

christopherporter1 Jul 25, 2025

What is "Qiskit's patterns module"? I don't see the word "pattern" appear anywhere.

docs/tutorials/compilation-methods-for-hamiltonian-simulation-circuits.ipynb

+                  "- The pie charts show that AI Pauli performed best for the largest percentage of circuits in terms of both depth and size.\n",
+                  "- Despite this, Rustiq still had the lowest average depth and gate count.\n",
+                  "\n",
+                  "Each Hamiltonian circuit in this experiment differs significantly in structure, and this is reflected in the varying performance of the methods. The best-performing method depends on the circuit being compiled. Although Rustiq performed best on average, the results suggest that no single method dominates across all Hamiltonian circuits. We recommend users test multiple transpilation methods - particularly Rustiq and AI Pauli — to determine which produces the most efficient circuit for their specific use case."

Collaborator

christopherporter1 Jul 25, 2025

This is great. But I feel like I'm missing something. It seems the takeaway of all of this is "Use the AI transpiler" provided that you don't mind waiting for some potentially long transpilation times. But even that seems like it would almost always be the case: you would almost always trade classical overhead for quantum efficiency. Is there nuance that isn't being explicitly called out? Like are there cases where the scaling shown here breaks down, or could the message really be that broad: "Use AI transpiler"?

abbycross added this to Docs Planning

abbycross moved this to In Progress in Docs Planning

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

Labels

None yet