Skip to content

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.

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

Open
wants to merge 8 commits into
base: main
Choose a base branch
from

Conversation

henryzou50
Copy link

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).

…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
…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.
Copy link

Check out this pull request on  ReviewNB

See visual diffs & provide feedback on Jupyter Notebooks.


Powered by ReviewNB

@CLAassistant
Copy link

CLAassistant commented Jul 16, 2025

CLA assistant check
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.

@qiskit-bot
Copy link
Contributor

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

@kaelynj kaelynj requested review from beckykd and abbycross July 17, 2025 14:39
@abbycross
Copy link
Collaborator

abbycross commented Jul 21, 2025

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

Copy link
Collaborator

@christopherporter1 christopherporter1 left a comment

Choose a reason for hiding this comment

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

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

"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",
Copy link
Collaborator

Choose a reason for hiding this comment

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

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

"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",
Copy link
Collaborator

Choose a reason for hiding this comment

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

Just flagging this warning

"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",
Copy link
Collaborator

Choose a reason for hiding this comment

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

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.

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

Choose a reason for hiding this comment

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

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

Copy link
Collaborator

Choose a reason for hiding this comment

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

Correct! it should be ibm_quantum_platform for the channel

"- **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",
Copy link
Collaborator

Choose a reason for hiding this comment

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

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

"- 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."
Copy link
Collaborator

Choose a reason for hiding this comment

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

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 abbycross moved this to In Progress in Docs Planning Jul 29, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: In Progress
Development

Successfully merging this pull request may close these issues.

5 participants