Sqdrift tutorial (CPP and Python)

[Shobhit Pandey (Shobhit21287)]

Summary

This tutorial demonstrates the SqDRIFT algorithm for ground state energy estimation, applied to an N2 molecule in an STO-3G basis. SqDRIFT builds on sample-based quantum diagonalization by using a randomized qDRIFT Trotterization to prepare the states that are sampled, then diagonalizing the resulting subspace classically.

The tutorial is presented in two forms. The Python notebook is the rendered page and is written for teaching: it walks through the algorithm step by step with explanation alongside each stage. The accompanying C++ implementation in SqDRIFT_Tutorial_CPP/ shows the same workflow built directly against the Qiskit C/C++ API, for readers who need the lower-level path. The notebook points to the C++ version, and the C++ README and build instructions cover compiling it with CMake through FetchContent, with no bash scripts required.

Files

The PR adds the following files:

• the notebook docs/tutorials/sqdrift/sqdrift.ipynb, which is the
  rendered tutorial page
• the file docs/tutorials/sqdrift/N2_sto_3g, the FCIDump input defining
  the molecular system
• the C++ companion under docs/tutorials/sqdrift/SqDRIFT_Tutorial_CPP/:
  SqDRIFT.cpp, CMakeLists.txt, README.md, BUILD_INSTRUCTIONS.md

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[qiskit-bot]

Thanks for contributing to Qiskit documentation!

Before your PR can be merged, it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient. Thanks! 🙌

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

• @nathanearnestnoble

[CLAassistant]

All committers have signed the CLA.

[Henry Zou (henryzou50)]

Thanks, Shobhit! The Python notebook and C++ companion are taking shape. Before merging, could you address the following?

1. Tutorial placement and discoverability

• Move the notebook to docs/tutorials/sqdrift.ipynb, alongside the other tutorials. Update its paths in _toc.json, index.mdx, qiskit_bot.yaml, and notebook-testing.toml.
• Add a prominent note above “Learning outcomes” linking to the C++ tutorial directory in this repository, where readers can find the README, build instructions, and source. The current plain-text SqDRIFT.cpp reference isn’t enough to navigate there.
  Something like:

<Admonition type="note" title="Looking for the C++ version?">

This tutorial uses Python. For the C++ implementation, including source code and build instructions, see the [C++ SqDRIFT tutorial](https://github.com/Qiskit/documentation/tree/main/docs/tutorials/sqdrift/SqDRIFT_Tutorial_CPP).

</Admonition>

• Keeping the supporting files under docs/tutorials/sqdrift/ is fine for now. Kaelyn Ferris (@kaelynj), could you advise on the preferred structure for these files? As one of our first non-Python tutorials, this could establish a useful pattern.

2. Make both examples runnable from the instructions

• Python: The notebook reads fcidump_files/N2_sto_3g without explaining how to obtain it. Please add a download cell or explicit download instructions before its first use. Update both reads after moving the notebook.
• C++ diagonalization: The README’s ln -sf ../../../../fcidump_files/N2_sto_3g fcidump.txt points to a nonexistent location. With the current layout, it needs ../../../../../fcidump_files/N2_sto_3g.
• C++ build guide: The complete build example needs cd .. before ./SqDRIFT, because the executable is written to the project root. Please also remove the reference to the missing set_dyld_path.sh and make the Windows support statements consistent between the two guides.
• Add a short description of the FCIDUMP’s source and molecular geometry so readers can identify and reproduce the example.

3. Tighten the scientific explanations

• The explanation of filter_diagonal_terms() says these terms contribute only a global phase. In general, number-operator terms introduce relative phases that can affect later interference. Please explain the assumptions or approximation that justify removing them here.
• In the qDRIFT equations, distinguish the number of Hamiltonian terms from the number of sampled operators. The notebook currently mixes N and n. Also clarify how coefficient signs are retained in the evolved operators. Please update the C++ README’s equations consistently.
• The Python/C++ comparison should mention that the examples also differ in circuit count, evolution times, and diagonal-term filtering—not just postselection versus configuration recovery. Please avoid attributing the energy difference solely to recovery without a controlled comparison.
• Replace the blanket statement that systems beyond 20 qubits require HPC with an explanation that classical cost depends on the selected-subspace size and available resources.

4. Minor items:

• Please remove the empty markdown cell above Learning Outcomes

[Henry Zou (henryzou50)]

Thanks, Shobhit! Most of the earlier feedback is addressed. I have a few remaining requests before approving:

1. Clarify the diagonal-term filtering explanation.
   The notebook still says these terms cannot change the observed bitstrings. They do not directly change occupation probabilities, but their relative phases can affect later interference. Please remove the claim that filtering leaves sampling unchanged. Possible wording:

We remove diagonal terms from the circuit-generation Hamiltonian to focus sampling on excitation terms. This changes the generated evolution and can change the sampling distribution. The classical diagonalization still uses the full Hamiltonian, including its diagonal terms.

Please confirm that this describes the intended approximation and clarify any implications for the convergence guarantees discussed earlier.

2. Update the simulator note to match the refreshed results.
   The note before SQD post-processing says subspace dimensions stay constant across iterations, but the new output shows them increasing, for example, from 5538 to 6080. Please remove that assertion, as noiseless sampling does not guarantee a constant selected-subspace dimension.

3. Remove the stale C++ results paragraph.
   Immediately before “How this differs from the Python SqDRIFT tutorial,” the README still mentions 1,694 surviving shots and 54 strings. The updated results show 1,103 shots and 45 α-determinants. Please update or delete this paragraph, and avoid equating the α-determinant count with the full α/β subspace dimension.

4. Pin the Runtime dependency to a tested commit.
   Runtime PR #27 has now merged, so the CMake comment about waiting for it is outdated. Ideally, switch to a pinned upstream commit containing the fix and verify the build/run. Alternatively, you can pin the fork commit you already tested and track the upstream migration as a follow-up.

[Henry Zou (henryzou50)]

@Shobhit-Pandey1 following up on my earlier question about where the C++ files should live: I synced with Kaelyn Ferris (@kaelynj) and nathanearnestnoble , and we landed on a new shared location for non-Python tutorial files:

docs/tutorials/assets/<tutorial-name>/<lang>/

For this PR, that means:

Current	New
docs/tutorials/sqdrift/SqDRIFT_Tutorial_CPP/	docs/tutorials/assets/sqdrift/cpp/
docs/tutorials/sqdrift/fcidump_files/N2_sto_3g	docs/tutorials/assets/sqdrift/fcidump_files/N2_sto_3g

The assets directory doesn't exist yet, so please create it in this PR. Since the FCIDump is shared by the Python notebook and the C++ version, I'd suggest keeping it at the tutorial level rather than inside cpp/. That also keeps the ../fcidump_files/N2_sto_3g relative path in SqDRIFT.cpp and the README symlink commands working as they are.

Things that will need updating after the move:

• FCIDUMP_URL and FCIDUMP_PATH in the notebook's download cell, plus the two name = "sqdrift/fcidump_files/N2_sto_3g" cells
• The "Looking for the C++ version?" admonition link in the notebook
• The fcidump_files link in the "Input files" section of README.md

The Julia tutorial (#5557) is moving to the same structure, so this keeps the non-Python tutorials consistent. Let me know if anything is unclear!

[Henry Zou (henryzou50)]

LGTM! Thanks, Shobhit! The latest updates address my remaining review comments, and the tutorial looks good from my side. Since this PR comes from a fork, I’ll carry the reviewed commits into a branch in Qiskit/documentation and open a replacement PR so CI can access the required repository secrets. I’ll preserve your authorship, link back to this PR, and ask Abby for a final review.

[Henry Zou (henryzou50)]

Work continuing at #5683