add the chemistry active space notebook course by HABER7789 · Pull Request #3568 · microsoft/qdk

Dhairya Patel (HABER7789) · 2026-08-11T20:28:18Z

Chemistry Course

Ports the ground-state QPE tutorial from Sphinx rst into a notebook course, placed beside circuit-diagrams-new in the learning test workspace. chemistry-course-tools has the converter script, plus the verifier used to validate them.

This branch targets the branch behind #3526 and GitHub will retarget to main once it merges.

Note: This is content only; no extension code.

…ER7789/chemistry-course

…ER7789/chemistry-course # Conflicts: # .gitignore

- Course now lives in resources/qdk-learning/courses/chemistry-qpe - Authoring tools in resources/qdk-learning/utils/chemistry-qpe, kept out of the package by .vscodeignore - Dropped the course id, the folder name is the id now - requirements.txt uses >= so a minor release does not break the course - Stopped calling the course a port in the manifest and README

Bill Ticehurst (billti) · 2026-08-18T00:22:31Z

+    {
+      "id": "overview",
+      "title": "Tutorial Overview",
+      "dir": "overview"


Minor nit: But perhaps the overview directory should be 00- prefixed, and the actual content should start from 01-, that way the folders are listed in the correct order. (Not too important before getting this in though)

That would be tidier, but shouldn't affect display order, only folder older.

Yes, the course.json file controls the display order so I’ll rename them to 00-overview and the content from 01 to 06 and update the manifest and converter references.

Bill Ticehurst (billti) · 2026-08-18T00:23:23Z

@@ -0,0 +1,2 @@
+qdk-chemistry[jupyter]>=2.1.0
+ipykernel>=6.0


Do you need both this file and the importChecks in course.json? I see course.json also lists PySCF, which isn't here.

This file is for constructing a venv. The import checks are for confirming that the current env (which may or may not be the course venv) has certain key imports available.

Bill Ticehurst (billti) · 2026-08-18T00:30:26Z

+            "from the QDK course folder."
+        )
+
+    course = json.loads(course_json_path.read_text())


You nearly always want to pass the encoding="utf-8" parameter to read_text, else I believe it defaults to Windows-1252 on Windows, which can lead to... surprises.

In fairness, this was almost certainly inherited - probably from a vibe-coded prototype.

Alright. I'll add the encoding utf-8.

…ourse

Andrew Casey (amcasey) · 2026-08-18T01:51:04Z

 .idea/
 *.so
 samples/scratch/
+# A stray workspace created by running the extension at the repo root.


How did you manage to do that? All of the launch.json targets point at samples, don't they?

This came from when I was locally testing, you are correct about the current launch.json I'll remove it.

Andrew Casey (amcasey) · 2026-08-18T01:51:20Z

 samples/qdk-learning/
 samples/qdk-learning.json
+# Learner working copies and progress files, wherever a course is opened.
+**/*.workbook.ipynb


These files should be under qdk-learning, so these lines seem unnecessary.

Andrew Casey (amcasey) · 2026-08-18T01:54:51Z

+        coordinate-minimized selected orbitals needed by mapping, state
+        preparation, and visualization.
+    """
+    ################################################################################


How is this file used? If a learner will see it, we might want to clean up some of these delimiters.

Andrew Casey (amcasey) · 2026-08-18T01:58:11Z

+            ("Packages", ", ".join(f"<code>{m}</code> missing" for m in missing), False)
+        )
+        errors.append(
+            "Install missing packages by running the following in a new cell, then re-run this cell:"


Did you test this? I think I tried and didn't get the result I wanted, but chalked it up to my inexperience with Python.

(If we really believe it works, maybe we should include it in the cell, commented out)

Yes, I tested this requirements installation flow in WSL and it works. I agree it would be easier to discover in the notebook, so I’ll include it as a commented optional command in the environment check cell.

Should we mention virtual environments? Otherwise, I think this might install globally.

Andrew Casey (amcasey) · 2026-08-18T02:03:39Z

@@ -0,0 +1,13 @@
+# Ground-State Molecular Energies with QPE


Is this displayed to the user?

It does show up in the file explorer but not in the QDK-Learning tree. I can remove this, since we have the setup instruction in the overview.

Andrew Casey (amcasey) · 2026-08-18T17:12:33Z

+  {
+   "cell_type": "markdown",
+   "id": "sec-self-consistent-wavefunction-optimization",
+   "metadata"


I'm getting a bunch of warnings in the output window

2026-08-18 10:10:24.815 [warning] Learning: ignoring a "solution" cell for exercise "c-e37c60a46531" in unit "describe-molecule": expected a code cell. 2026-08-18 10:10:24.829 [warning] Learning: ignoring a "solution" cell for exercise "c-75c7822257be" in unit "active-space": expected a code cell. 2026-08-18 10:10:24.841 [warning] Learning: ignoring a "solution" cell for exercise "c-ed49001f7051" in unit "map-to-qubits": expected a code cell. 2026-08-18 10:10:24.857 [warning] Learning: ignoring a "solution" cell for exercise "c-6f500714745c" in unit "trial-state": expected a code cell. 2026-08-18 10:10:24.868 [warning] Learning: ignoring a "solution" cell for exercise "c-4cb620545394" in unit "iterative-phase-estimation": expected a code cell. 2026-08-18 10:10:24.868 [warning] Learning: ignoring a "solution" cell for exercise "c-1f5f4640f7af" in unit "iterative-phase-estimation": expected a code cell.

If they're markdown cells, maybe they were intended to be tagged explanation?

(If we think this is a stumbling block for authors, we could conceivably tag both types of cells as solution and partition them internally into solutions and solution explanations.)

I believe these are from the sample exercises that I have created, they have a solution in the author's copy, but the solution code has not been tagged as solution by the converter and the markdown just has the code snippet format in the author's notebook.

Andrew Casey (amcasey) · 2026-08-18T17:17:27Z

+            ("Packages", ", ".join(f"<code>{m}</code> missing" for m in missing), False)
+        )
+        errors.append(
+            "Install missing packages by running the following in a new cell, then re-run this cell:"


Should we mention virtual environments? Otherwise, I think this might install globally.

Andrew Casey (amcasey) · 2026-08-18T17:58:32Z

+     "section:running-the-chapter-3-workflow"
+    ]
+   },
+   "source": "## Running the Chapter 3 workflow\n\nEverything below starts from the active space selected in Chapter 3. This cell reruns that workflow so the rest of the notebook has a selected space to map. It is the slowest cell here."


I don't think we mention chapter numbers elsewhere in the UI - they're certainly not in the tree. From context, I'm guessing it's the preceding chapter?

Yes it is, I will replace them with unit titles

Andrew Casey (amcasey) · 2026-08-18T17:59:18Z

+     "section:the-jordan-wigner-transformation"
+    ]
+   },
+   "source": "## The Jordan--Wigner transformation\n\nThe [Jordan–Wigner transformation ↗](https://en.wikipedia.org/wiki/Jordan%E2%80%93Wigner_transformation) assigns each fermionic mode to one qubit.\nIn this molecular problem, each fermionic mode is one active spin orbital.\nTo keep the two kinds of labels distinct, let $\\ell_p$ denote the qubit assigned to fermionic mode $p$; its numerical qubit index is $p$.\n\n$$\n\\vert 0\\rangle_{\\ell_p} \\longleftrightarrow \\text{mode }p\\text{ unoccupied},\n\\qquad\n\\vert 1\\rangle_{\\ell_p} \\longleftrightarrow \\text{mode }p\\text{ occupied}.\n$$\n\nThe occupation operator becomes\n\n$$\n\\hat{n}_p=\\hat{a}_p^\\dagger\\hat{a}_p=\\frac{I_{\\ell_p}-Z_{\\ell_p}}{2}.\n$$\n\nThe creation and annihilation operators become\n\n$$\n\\hat{a}_p^\\dagger\n= \\frac{1}{2}\\left(\\prod_{j=0}^{p-1}Z_{\\ell_j}\\right)(X_{\\ell_p}-iY_{\\ell_p}),\n\\qquad\n\\hat{a}_p\n= \\frac{1}{2}\\left(\\prod_{j=0}^{p-1}Z_{\\ell_j}\\right)(X_{\\ell_p}+iY_{\\ell_p}).\n$$\n\nThe [Pauli operators ↗](https://en.wikipedia.org/wiki/Pauli_matrices) $X_{\\ell_p}$, $Y_{\\ell_p}$, and $Z_{\\ell_p}$ act on qubit $\\ell_p$.\nThe combinations $(X_{\\ell_p}-iY_{\\ell_p})/2$ and $(X_{\\ell_p}+iY_{\\ell_p})/2$ raise $\\vert 0\\rangle_{\\ell_p}$ to $\\vert 1\\rangle_{\\ell_p}$ and lower $\\vert 1\\rangle_{\\ell_p}$ to $\\vert 0\\rangle_{\\ell_p}$, respectively.\nWithin the product, $j$ indexes the lower fermionic modes and $Z_{\\ell_j}$ acts on the qubit assigned to mode $j$.\nThe product of $Z$ operators records the parity of occupied lower-indexed modes.\nEach occupied lower-indexed mode contributes an eigenvalue of $-1$, so the product is negative when an odd number of those modes is occupied.\nActing on mode $p$ crosses the occupied lower-indexed modes in the chosen fermionic ordering, with each crossing contributing a minus sign.\nThe parity string supplies their combined sign, so the mapped operators satisfy the fermionic anticommutation relations.\n\n<div style=\"text-align:center;\">\n\n![Worked Jordan–Wigner mapping for target active spin orbital p equals 3, also called fermionic mode 3. Modes 0, 1, and 2 map to qubits ell 0, ell 1, and ell 2 and contribute the parity string Z ell 0 times Z ell 1 times Z ell 2. Its eigenvalue is negative when an odd number of those lower modes is occupied. Target qubit ell 3 carries the X minus iY creation action or X plus iY annihilation action. Multiplying target action by parity string preserves the fermionic ordering sign.](attachment:tutorial_qpe_jordan_wigner_parity.png)\n\n*A fermionic mode is one active spin orbital. For target spin orbital $p=3$, the qubits assigned to preceding spin orbitals supply the parity string $Z_{\\ell_0}Z_{\\ell_1}Z_{\\ell_2}$, while qubit $\\ell_3$ changes the target occupation. The same pattern extends to any target $p$.*\n\n</div>\n\nBecause the parity strings depend on mode ordering, the ordering must be specified: QDK/Chemistry places all active $\\alpha$ modes before all active $\\beta$ modes, a convention called *blocked ordering*.\n\n<div style=\"border-left:4px solid #8c4a00;background:#8c4a001a;border-radius:4px;margin:1em 0;\"><details><summary style=\"background:#8c4a00;color:#ffffff;padding:0.35em 0.8em;cursor:pointer;font-weight:600;\">&#10067;&nbsp;Why does Jordan–Wigner need a string of Pauli Z operators?</summary>\n\n<div style=\"padding:0.1em 1em;\">\n\nThe $Z$ string records the parity of lower-indexed fermionic modes.\nIts sign ensures that encoded creation and annihilation operators anticommute even though operators on different qubits commute.\n\n</div>\n\n</details></div>",


-- was probably hoping to convey that this should be an emdash (which is odd, since it definitely seems like a place you'd put a hyphen/endash).

Andrew Casey (amcasey) · 2026-08-18T18:06:21Z

+     "section:iqpe-circuit-visualization"
+    ]
+   },
+   "source": "## IQPE circuit visualization\n\nThe cells below build the six iteration circuits and render the shortest one. No quantum simulation runs here.\n\n<div style=\"text-align:center;\">\n\n![Overview of the power-one IQPE circuit on thirteen wires. The top wire is the readout ancilla and receives an H gate, an Rz feedback rotation labeled zero, the controlled Pauli-evolution block, a final H gate, and measurement and reset. The remaining twelve wires form the compute register. State-preparation blocks act on the compute wires that require preparation operations, the controlled Pauli-evolution block spans the ancilla and compute register, and reset operations return the compute wires to zero after evolution.](attachment:tutorial_qpe_power_one_circuit_overview.png)\n\n*Overview of the rendered power-one iteration circuit. Dashed outlines mark the nested `MakeIQPECircuit` and `RunIQPE` Q# operations; the solid boxes show their principal composite operations.*\n\n</div>\n\nThe top wire, $\\lvert\\psi_0\\rangle$, is readout ancilla q0.\nIts first H gate creates a superposition, and the `Rz(0.0000)` block applies the phase-feedback rotation.\nThis static preview constructs all six circuits with the builder's initial feedback angle of zero, so the displayed rotation is zero.\nDuring an actual IQPE run, each iteration circuit is rebuilt using the accumulated feedback from earlier measured bits; the power-one iteration can therefore have a nonzero feedback rotation.\n\nThe lower wires, $\\lvert\\psi_1\\rangle$ through $\\lvert\\psi_{12}\\rangle$, are compute-register qubits q1–q12.\nThe `StatePreparation` blocks load the four-determinant trial state on the subsets of compute wires that require preparation operations; blank wires remain part of the compute register.\nThe `RepControlledPauliExp` block is the power-one controlled first-order Trotter evolution.\nThe ancilla controls this block, and the resulting phase kickback places the Hamiltonian eigenphase on the ancilla's relative phase.\nThe final H gate converts that relative phase into measurement probabilities, the measurement produces one shot outcome, and the blue reset operations return the allocated qubits to $\\lvert0\\rangle$.\n\n<div style=\"border-left:4px solid #8c4a00;background:#8c4a001a;border-radius:4px;margin:1em 0;\"><details><summary style=\"background:#8c4a00;color:#ffffff;padding:0.35em 0.8em;cursor:pointer;font-weight:600;\">&#10067;&nbsp;How can you identify the readout ancilla in the rendered circuit?</summary>\n\n<div style=\"padding:0.1em 1em;\">\n\nThe q0 wire receives the H gates and feedback rotation, controls the Hamiltonian evolution, and is measured to obtain the phase bit.\nThe other twelve wires hold the prepared molecular state and form the compute register.\n\n</div>\n\n</details></div>\n\n<div style=\"border-left:4px solid #8c4a00;background:#8c4a001a;border-radius:4px;margin:1em 0;\"><details><summary style=\"background:#8c4a00;color:#ffffff;padding:0.35em 0.8em;cursor:pointer;font-weight:600;\">&#10067;&nbsp;Why do all six iteration circuits have the same width but different lengths?</summary>\n\n<div style=\"padding:0.1em 1em;\">\n\nEvery iteration uses the same twelve-qubit compute register and one readout ancilla, so each circuit has thirteen logical qubits.\nDifferent controlled powers repeat the approximate time-evolution unitary different numbers of times


Where is import json used?

It has not been used, I will remove it. Thanks!

- Renumber the unit folders, starting with overview and regenerated the notebooks - Fix solution/explanation cells and exercise traceback behavior - Add utf-8 and kernel selection guidance for verification - Remove the sample course, duplicate README and unnecessary gitignore rules - Verified notebook terms, cross unit references and also unused imports

Andrew Casey (amcasey)

What editing process did you use that changed the IDs of the cells? We're relying on them to be stable, so that's potentially worrisome.

Dhairya Patel (HABER7789) · 2026-08-19T00:58:20Z

What editing process did you use that changed the IDs of the cells? We're relying on them to be stable, so that's potentially worrisome.

Ohh, thanks for catching this. So I regenerated the notebooks using the converter because I made changed to the code cells. It creates cell IDs from the cell text, so editing a cell changed its ID. Unchanged cells and all exercise IDs stayed the same. Would you like me to fix this before merge, or track it as a follow up?

Mine Starks (minestarks) and others added 30 commits July 15, 2026 13:13

python notebooks in QDK Learning

5523994

Add TODO

13307b8

Cleanup and notes from AI review

cc7cc6e

Move dummy course into test workspace

afbdf9c

Fix tests other than env check

6fcdd63

DO NOT MERGE env check logging

c35cc82

Handle lack of uv

b29f5be

TODOs for qsharp-vscode.learningDoctor

33a5d03

More TODOs

d292482

Handle exception in import check

dd4d157

Transfer TODOs from draft PR

23124b1

First cut at using cell ID rather than cell index

9f3b313

Only offer hints for exercise cells

cb2d162

More TODOs

6ee6530

Tidy diff in agent file

062e6aa

TODOs and tweaks from diff review

aa28d8e

More TODOs

073f94c

First cut at consuming Python Environments API

793bcb8

DO NOT MERGE local launch.json

8740f06

Replace all direct python access with env API calls

e4cdd6a

Detect the absence of a venv

f3982ef

Drop most of CourseEnvironment

824913c

Wire up course.json import checks

57f5874

Use requirements.txt instead of pyproject.toml for easier parsing

9ed8a08

Handle requirements.txt ourselves

ce9797e

Remove requirements.txt parsing

4707736

Don't throw from ensureEnvironment

40bbd28

Tidy up environments.ts

18a5b3c

Drop readme location from course.json

f694920

Drop commands and pyproject.toml from _check_env.py

3ad7b6c

Andrew Casey (amcasey) and others added 4 commits August 13, 2026 18:13

Validate notebook uri

f7f28ec

Added refinements to the notebooks

b72a403

Merge remote-tracking branch 'origin/amcasey/PythonLearning' into HAB…

4532e4c

…ER7789/chemistry-course

Fix chapter references and remove doc-site phrasing

ce4133f

Bill Ticehurst (billti) reviewed Aug 14, 2026

View reviewed changes

Comment thread .../test/suites/learning/test-workspace/qdk-learning/courses/chemistry-active-space/course.json Outdated

Dhairya Patel (HABER7789) and others added 3 commits August 14, 2026 10:25

Mention the PySCF windows installation in the pre-requisites

a0778bd

Move circuits sample course into VS Code resources

4331d36

Rename KatasProvider to KatasCourseProvider

5bee66c

Bill Ticehurst (billti) reviewed Aug 14, 2026

View reviewed changes

Comment thread .../suites/learning/test-workspace/qdk-learning/courses/chemistry-active-space/requirements.txt Outdated

Andrew Casey (amcasey) and others added 5 commits August 14, 2026 12:24

Move course resources into a qdk-learning folder

15b7214

Copy bundled courses into the workspace

823c1e7

Make notebook courses take their IDs from their folder names

024df14

Merge remote-tracking branch 'origin/amcasey/PythonLearning' into HAB…

08d3c5d

…ER7789/chemistry-course # Conflicts: # .gitignore

Bill Ticehurst (billti) reviewed Aug 18, 2026

View reviewed changes

Comment thread source/vscode/.vscodeignore

Bill Ticehurst (billti) reviewed Aug 18, 2026

View reviewed changes

Base automatically changed from amcasey/PythonLearning to main August 18, 2026 00:25

Bill Ticehurst (billti) reviewed Aug 18, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into HABER7789/chemistry-c…

cee5370

…ourse

Andrew Casey (amcasey) marked this pull request as ready for review August 18, 2026 01:50

Andrew Casey (amcasey) requested a review from Ian Davis (idavis) as a code owner August 18, 2026 01:50

Andrew Casey (amcasey) reviewed Aug 18, 2026

View reviewed changes

Dhairya Patel (HABER7789) mentioned this pull request Aug 18, 2026

validate import checks in python course environment setup #3538

Closed

Andrew Casey (amcasey) reviewed Aug 19, 2026

View reviewed changes

Comment thread source/vscode/resources/qdk-learning/courses/chemistry-qpe/00-overview/overview.ipynb

Andrew Casey (amcasey) approved these changes Aug 19, 2026

View reviewed changes

		@@ -0,0 +1,2 @@
		qdk-chemistry[jupyter]>=2.1.0
		ipykernel>=6.0

Uh oh!

Conversation

Dhairya Patel (HABER7789) commented Aug 11, 2026

Chemistry Course

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bill Ticehurst (billti) Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andrew Casey (amcasey) Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Andrew Casey (amcasey) left a comment

Choose a reason for hiding this comment

Uh oh!

Dhairya Patel (HABER7789) commented Aug 19, 2026

Bill Ticehurst (billti) Aug 18, 2026 •

edited

Loading

Andrew Casey (amcasey) Aug 18, 2026 •

edited

Loading