Neutron Scattering Tutorial Function + AQC Function Template

[henryzou50]

Summary

Adds the neutron scattering tutorial (AQC + Trotter dynamics Serverless workflow) and the AQC function template guide. All content authored by @pdd23001, see #5501 for the full original PR description and review discussion.

Why this PR exists

#5501 was opened from a fork, so CI could not deploy a docs preview (the preview workflow needs push access to gh-pages, which fork PRs don't have). I've pushed the same branch (same commits, tip db3d4cd) into this repo so we get a shareable preview link and canreview the rendered pages.

This PR supersedes #5501, which I'll close, and review will continue here. @pdd23001 will finish the remaining work on this PR (hardware example outputs for the template notebook are still pending; see the original description).

[qiskit-bot]

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

• @kevinsung
• @nathanearnestnoble

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[henryzou50]

Thanks @pdd23001, thanks for the changes and this is in great shape. The tutorial<->template contract is fully consistent, the numbers in the commentary all trace to actual outputs, and the physics framing checks out. Overall, looks good, but here are some suggestions I have:

Suggestions

Tutorial (simulate-neutron-scattering-with-a-serverless-workflow.ipynb)

1. "Hamiltonian-agnostic" is inaccurate (cells 3 and 31). The function only accepts 1D nearest-neighbor Pauli Hamiltonians and rejects anything else with a ServerlessError (see the guide's Function reference), so a reader who takes this claim to their own 2D or long-range SparsePauliOp hits a validation error the tutorial said couldn't happen. We can change cell 31 to "the function accepts any 1D nearest-neighbor SparsePauliOp, so a different chain Hamiltonian, initial state, or set of observables runs the same pipeline," and cell 3 to "drives other 1D dynamics experiments."
2. I believe "IBM Quantum Serverless" should be "Qiskit Serverless". Correct me if I am wrong here.
3. Pick one display name for the template for consistency. Currently we have "AQC Dynamics Function" (cell 3), "AQC Dynamics Template" (cell 31; guide cells 2, 13), and "AQC Dynamics Function Template Github" (guide cell 28). "AQC Dynamics Template" is most used.
4. Reconnect admonition vs. placeholder mismatch (cell 24 vs 25). The admonition says the reconnect cell "carries the job id from our own run," but cell 25 has "<your job id>". Either include the real ID or reword to the guide's phrasing ("Paste your saved job ID over the placeholder..."). Also "Paste yours over there" is informal and should be changed; and "job id" -> "job ID" throughout both notebooks.
5. Appendix names the wrong noise mechanism (cell 30). "Longer chains mean deeper circuits, so noise accumulates", but all three appendix runs use the same 20 Trotter steps, and a nearest-neighbor chain's brickwork circuit gets wider with chain length, not deeper (each Trotter layer just holds more parallel gates, with no routing overhead on the heavy-hex line). What grows is the qubit and gate count. We can change to something like : "longer chains mean more qubits and gates per circuit, so errors accumulate, contrast fades, and spurious weight leaks outside the bounds." Also state the gs_layers used for the 10- and 20-site runs, since the text claims "every other input held fixed."
6. "below"/"above" as page locations (house style; both notebooks -- tutorial cells 3, 4, 5, 8, 17, 20, 24, 30; guide cells 4, 13, 14, 15, 19, 24). Prefer "the following"/"preceding" per the style guide. (Mathematical "bounded below/above" in cell 3 is fine.)

Guide (function-template-aqc-trotter.ipynb)

1. Cell 22 undersells what changes at scale: "Only the chain length, the number of Trotter steps, and the backend differ", the compression plan also differs ([{4,1},{2,2}] -> [{3,1},{3,2}]) and the simulator call passes aqc_options={"max_bond": 32} while the hardware call omits it. Add "and the compression plan," or make them identical.
2. Cell 10 (serverless.upload(fn)) has no output. The sibling template guides both show the QiskitFunction(...) execute result for their upload cells.
3. Cell 7 blockquote -> <Admonition type="note">, matching how notes are formatted elsewhere. While there: "[extras] are honored -- ... is what drags quimb / jax in here" -> "The [extras] syntax is honored: qiskit-addon-aqc-tensor[quimb-jax] is what installs quimb and jax.", and the fake-backend bullet is missing its period.
4. Cell 16 output schema shows integer dict keys ("aqc_fidelities": {1: ...}) but real outputs have string keys after the JSON round-trip ({'1': 1.0, ...} in cell 21 and tutorial cells 16/27). We should have them be consistent
5. Cell 5: "This will allow you to locally instantiate..." -> drop the future tense, e.g. "With these credentials you can instantiate the serverless client locally...".
6. Cell 28: "Github" -> "GitHub"
7. Three small guide fixes:
   • Cell 1: delete the empty markdown cell after the title.
   • Cell 15, "Execution backends" table: the Credentials column is inconsistent -- the statevector and fake rows answer which credentials are needed ("Serverless account only"), but the runtime row just says "Yes", which doesn't tell the reader what's needed beyond the Serverless account. Replace "Yes" with the parallel answer, e.g. "Serverless account + an instance with QPU access". (The prose right under the table already explains the simulator rows, so only the runtime cell needs fixing.)
   • Cell 16 code comments: "e.g." -> "for example" per house style (# e.g. ["Z_0", "ZZ_0_1"] -> # for example: ["Z_0", "ZZ_0_1"], and "non-fatal notices, e.g. a cotengrust fallback" -> "non-fatal notices; for example, a cotengrust fallback").

Minor changes

• Tutorial cell 26's status comment (OPTIMIZING_FOR_HARDWARE -> ...) drops the QUEUED -> INITIALIZING -> RUNNING: prefix that guide cell 19 documents; matching the literal strings avoids confusing users comparing their status() output.
• "Segments" vs. "steps" (tutorial cells 19, 30): "3 + 2 = 5" and "6 one-layer plus 4 two-layer segments" count steps, not segments (there are 2 segments). Suggest "AQC-compressed steps".
• "Appendix: How the workflow scales" -> sentence case after the colon; last Requirements bullet (cell 4) is missing its period; "state prep" -> "state preparation" (guide cell 19).

Note one item I've already fixed on the branch: the tutorial was the only notebook in docs/tutorials/ missing the hours/qpuSeconds usage metadata, so I pushed a commit adding "hours": 4, "qpuSeconds": 1080 (from the notebook's own ~4-hour wall-clock and 18-minute QPU estimate), let me know if those values should be tuned.

[pdd23001]

Hey @henryzou50 fork branch is ready for a fast-forward sync:

pdd23001:aqc-trotter-neutron-scattering @ 19b10bb

That's five commits sitting on top of ef040b4, so it should be a plain
fast-forward with nothing to resolve.

Thanks for committing @abbycross guide suggestions through the UI. Please don't do
the tutorial ones that way though — I've already applied all of them in the fork,
so accepting them in the UI now would either come up outdated or land duplicate
edits on cells I've already changed.

I've done all of your suggestions except two, which I think are better left as
they are:

1. gs_layers in the appendix. @vedangi-pathak asked for the appendix stripped back to
   just the figures and a short caption noting the same parameters are used at
   10/20/30 and that users can tune them. The paragraph carrying "every other
   input held fixed" went with that cut — which also removed the incorrect
   "deeper circuits" explanation, so your item 5 is resolved by deletion rather
   than rewording. Adding gs_layers back would reintroduce exactly the detail she
   asked to remove.

2. The empty markdown cell after the title. That's the version-info cell —
   scripts/ci/check-for-version-info-cells.py requires exactly one empty markdown
   cell tagged version-info immediately after the H1 in every
   docs/guides/*.ipynb, so deleting it fails ./check. It looks empty by design.

Both of Abby's discussion threads are closed in these commits too — the italics
on "is" in workflow step 4, and the ASCII diagram converted to a markdown table
in both notebooks.

We can keep your time metadata values.

Only thing left on my side is the usage estimate in the guide but the others like hamiltonian simulation and chemistry did not have it so I am not sure if we need to do that. Please could you confirm once?

[henryzou50]

@pdd23001 Synced and pushed, hanks for the clean handoff. A few notes:

• I fast-forwarded to your fork as requested, and picked up the extra commit you pushed after your comment (19b10bb, the state preparation wording), so the PR branch now matches your fork exactly plus one commit from me (d0be4f2, see below). Per your warning I didn't accept any of the tutorial suggestions through the UI, everything went in as normal commits on top of your work.

• Your two pushbacks, and agreed on both.

1. Version-info cell stays: you're right, scripts/ci/check-for-version-info-cells.py requires exactly that empty tagged cell after the H1 in every guide notebook, and the other template guides have it too. My suggestion to delete it was wrong.
2. The appendix strip-down also resolves my item 5 (the noise-mechanism wording) by deletion, so nothing to add back there.

• Yes, we don't need usage estimate in the guide, we only need it for tutorials, so nothing left on your side.
• After syncing I cross-checked all of Abby's inline comments and my earlier review against the branch tip. Almost everything was already applied in your commits. There were eight remaining tutorial suggestions, which I applied in the latest commit.

I'll resolve Abby's threads now since they're all addressed at this tip. Overall, looks good to me now, and thanks @abbycross for the thorough pass!

[abbycross]

Thanks for these additions!

[henryzou50]

A quick summary of the latest commit (ee95acc), which is a small cleanup pass with two fixes worth noting:

• The new AQC + Trotter guide is now linked from the templates hub page. Before this, the guide existed but nothing on the landing page pointed to it.
• The neutron scattering tutorial no longer fetches the job result twice. One cell was re-calling job.result() even though the result was already stored earlier; it now reuses that variable.
• The rest is minor polish in the template notebook: an added numpy import so the results cell runs on its own, and some formatting and comments.

[pdd23001]

Pushed 99aace7, rebased on top of @henryzou50 's cleanup commit (5f2dd9d) so the
branch stays linear. Clean fast-forward, no conflicts, and all 8 local checks
pass on the combined tree.

The commit documents return_circuits in the guide's Function reference: one
row in the inputs table, and the circuits key in the output dict (noting it
is present only when the flag is set, and that circuits[i] corresponds to
times[i + 1]).

For context, return_circuits is a feature Vedangi and Hamed requested on the
template. It has now been merged into the templates repo in
qiskit-community/qiskit-function-templates#43, so it is live on main, which
is where this guide tells readers to download source_files from. That is why
the Function reference here needs updating too: without it the guide would
describe an input contract that no longer matches the deployed template.