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.

[abbycross]

Suggested change

	"After completing this tutorial, you can expect to understand:\n",
	"After completing this tutorial, you can expect to understand the following:\n",

[abbycross]

Suggested change

	"- Familiarity with [Qiskit Patterns](/docs/guides/intro-to-patterns), [`SparsePauliOp`](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp), and [Trotter time-evolution](/learning/courses/utility-scale-quantum-computing/quantum-simulation).\n",
	"- Familiarity with [Qiskit patterns](/docs/guides/intro-to-patterns), [`SparsePauliOp`](/docs/api/qiskit/qiskit.quantum_info.SparsePauliOp), and [Trotter time-evolution](/learning/courses/utility-scale-quantum-computing/quantum-simulation).\n",

[abbycross]

I don't understand why the emphasis on is here - does it add something in context?

[abbycross]

Suggested change

"The bottleneck is step 3: exact Trotter circuits for long evolutions become too deep for hardware. Approximate quantum compilation with tensor networks (AQC) addresses this by compressing a block of Trotter steps into a fixed, shallow parameterized ansatz whose state fidelity to the exact evolution is maximized classically with an MPS simulator ([arXiv:2301.08609](https://arxiv.org/abs/2301.08609)). The [AQC Dynamics Function](/docs/guides/function-template-aqc-trotter) packages this whole quantum core (Trotter synthesis, AQC compression, and mitigated execution) behind one call:\n",

"Problems can arise in step 3, when exact Trotter circuits for long evolutions become too deep for hardware. AQC with tensor networks addresses this by compressing a block of Trotter steps into a fixed, shallow parameterized ansatz whose state fidelity to the exact evolution is maximized classically with an MPS simulator ([arXiv:2301.08609](https://arxiv.org/abs/2301.08609)). The [AQC Dynamics Function](/docs/guides/function-template-aqc-trotter) packages this whole quantum core (Trotter synthesis, AQC compression, and mitigated execution) behind one call:\n",

[abbycross]

Suggested change

	"So the experiment-specific work stays here in the notebook: ground-state preparation (PRE) and the $S(q, \\omega)$ post-processing (POST). The two quantum-heavy steps, compression and execution, run inside the function.\n",
	"The experiment-specific work stays here in the notebook: ground-state preparation (PRE) and the $S(q, \\omega)$ post-processing (POST). The two quantum-heavy steps, compression and execution, run inside the function.\n",

[abbycross]

Suggested change

	"- The function deployed to your IBM Quantum® Serverless account. Run the companion function template first: [Deploy and run the AQC + Trotter dynamics function template](/docs/guides/function-template-aqc-trotter). That guide walks through getting the source files and uploading the function to your account. This tutorial only calls the deployed function.\n",
	"- The function deployed to your Qiskit Serverless account. Run the companion function template first: [Deploy and run the AQC + Trotter dynamics function template](/docs/guides/function-template-aqc-trotter). That guide walks through getting the source files and uploading the function to your account. This tutorial only calls the deployed function.\n",

[abbycross]

Suggested change

	"- IBM Quantum credentials saved for `QiskitServerless` (see the function template). Both examples below call the deployed function, so both need them.\n",
	"- IBM Quantum® credentials saved for `QiskitServerless` (see the function template). Both examples below call the deployed function, so both need them.\n",

[abbycross]

This renders a little confusingly in html. Is there another way to lay it out - maybe using a markdown table?

[abbycross]

Suggested change

	"Connect to IBM Quantum Serverless and load the deployed `aqc-dynamics-function`. Both examples below call the same `fn` handle, so the function is loaded once, here."
	"Connect to Qiskit Serverless and load the deployed `aqc-dynamics-function`. Both examples below call the same `fn` handle, so the function is loaded once, here."

[abbycross]

Suggested change

	"We first run the full workflow on a small 10-site chain using the exact `statevector` backend. This validates the PRE → FUNCTION → POST pipeline before spending any QPU time."
	"We first run the full workflow on a small 10-site chain by using the exact `statevector` backend. This validates the PRE → FUNCTION → POST pipeline before spending any QPU time."

[abbycross]

Suggested change

"In a hand-written workflow these are two separate stages: optimize the circuits for hardware (Step 2) and execute them (Step 3). The function template collapses both into one call. It performs Trotter synthesis, AQC compression, and hardware transpilation, then runs the circuits (here on the exact simulator, later with built-in error mitigation on hardware). The two tuning parameters are `aqc_segments` (the compression plan) and `aqc_options` (the MPS and optimizer settings). Each segment `{\"n_steps\": k, \"ansatz_steps\": m}` compresses `k` consecutive Trotter steps into an ansatz built from an `m`-step Trotter target, and any steps beyond `sum(n_steps)` run as plain Trotter. Early, low-entanglement steps compress well into a shallow (`ansatz_steps=1`) ansatz, so here we compress the first 3 steps into a 1-layer ansatz and the next 2 into a deeper 2-layer ansatz; the remaining 5 of the 10 Trotter steps run as plain Trotter. For `aqc_options` we mirror the original tutorial: MPS bond dimension `max_bond=32`, `cutoff=1e-8`, and an L-BFGS-B optimizer capped at 100 iterations.\n",

"In a hand-written workflow these are two separate stages: optimize the circuits for hardware (Step 2) and execute them (Step 3). The function template collapses both into one call. It performs Trotter synthesis, AQC compression, and hardware transpilation, then runs the circuits (here on the exact simulator, later with built-in error mitigation on hardware). The two tuning parameters are `aqc_segments` (the compression plan) and `aqc_options` (the MPS and optimizer settings). Each segment `{\"n_steps\": k, \"ansatz_steps\": m}` compresses `k` consecutive Trotter steps into an ansatz built from an `m`-step Trotter target, and any steps beyond `sum(n_steps)` run as plain Trotter. Early, low-entanglement steps compress well into a shallow (`ansatz_steps=1`) ansatz, so here we compress the first three steps into a single-layer ansatz and the next two into a deeper two-layer ansatz; the remaining five of the 10 Trotter steps run as plain Trotter. For `aqc_options` we mirror the original tutorial: MPS bond dimension `max_bond=32`, `cutoff=1e-8`, and an L-BFGS-B optimizer capped at 100 iterations.\n",

[abbycross]

Suggested change

"Call the function loaded in Setup. `backend=\"statevector\"` runs the exact reference path: no QPU time, with the circuits running on an exact statevector simulator inside the serverless worker (a saved Serverless account is still needed to call it). The `initial_state` carries the prepared ground state (including the kick); `observables` is omitted so the function measures the default per-site $Z$."

"Call the function loaded in Setup. `backend=\"statevector\"` runs the exact reference path: no QPU time, with the circuits running on an exact statevector simulator inside the serverless worker (a saved Qiskit Serverless account is still needed to call it). The `initial_state` carries the prepared ground state (including the kick); `observables` is omitted so the function measures the default per-site $Z$."

[abbycross]

Suggested change

"The same workflow scales up without changing any of the science code: a 30-site chain, twice the Trotter depth (20 steps), a compression plan that varies the ansatz depth (a deeper ansatz for the later, more-entangled steps), and execution on a real IBM Quantum processor with the function's built-in error mitigation (dynamical decoupling, Pauli twirling, and twirled readout error extinction, or TREX). We walk through the same four steps as the simulator example, reusing the `fn` handle from Setup.\n",

"The same workflow scales up without changing any of the science code: a 30-site chain, twice the Trotter depth (20 steps), a compression plan that varies the ansatz depth (a deeper ansatz for the later, more-entangled steps), and execution on an IBM Quantum processor with the function's built-in error mitigation (dynamical decoupling, Pauli twirling, and twirled readout error extinction (TREX)). We walk through the same four steps as the simulator example, reusing the `fn` handle from Setup.\n",

[abbycross]

Suggested change

	"Build the same KCuF$_3$ Heisenberg `SparsePauliOp` and prepare the ground state, now with a deeper `gs_layers=5` ansatz for the longer chain, then bake in the $\\pi/2$ $Z$ neutron kick at the center site. This is identical to the small-scale mapping, just at $n = 30$.\n",
	"Build the same KCuF$_3$ Heisenberg `SparsePauliOp` and prepare the ground state, now with a deeper `gs_layers=5` ansatz for the longer chain, then bake in the $\\pi/2$ $Z$ neutron kick at the center site. This is identical to the small-scale mapping, but at $n = 30$.\n",

[abbycross]

Suggested change

"The same single call as the simulator example, now with `backend_name` pointing at a real IBM Quantum processor, so the function transpiles and executes there. The compression plan varies the ansatz depth: the first 6 (low-entanglement) Trotter steps compress into a shallow 1-layer ansatz, the next 4 into a deeper 2-layer ansatz, and the remaining 10 of the 20 steps run as plain Trotter. `aqc_options` raises the MPS bond dimension to `max_bond=128` for the longer, more-entangled chain (matching the original), keeping the same L-BFGS-B optimizer capped at 100 iterations. The `estimator_options` turn on the built-in error mitigation: dynamical decoupling (XY4), gate twirling, and TREX measurement mitigation. The function's defaults already match the original tutorial for all of these except the TREX learning budget (`measure_noise_learning`), which is the only genuine difference. The whole block is still written out because a caller-supplied `estimator_options` replaces the function's defaults wholesale instead of merging into them, so omitting a key would fall back to the Qiskit Runtime default rather than the function's."

"The same single call as the simulator example, now with `backend_name` pointing at an IBM Quantum processor, so the function transpiles and executes there. The compression plan varies the ansatz depth: the first six (low-entanglement) Trotter steps compress into a shallow single-layer ansatz, the next four into a deeper two-layer ansatz, and the remaining 10 of the 20 steps run as plain Trotter. `aqc_options` raises the MPS bond dimension to `max_bond=128` for the longer, more-entangled chain (matching the original), keeping the same L-BFGS-B optimizer capped at 100 iterations. The `estimator_options` turn on the built-in error mitigation: dynamical decoupling (XY4), gate twirling, and TREX measurement mitigation. The function's defaults already match the original tutorial for all of these except the TREX learning budget (`measure_noise_learning`). The whole block is still written out because a caller-supplied `estimator_options` replaces the function's defaults wholesale instead of merging into them, so omitting a key would fall back to the IBM Quantum Compute default rather than the function's."

[abbycross]

Suggested change

	"The reconnect cell below carries the job id from our own run. Paste yours over there:\n",
	"The reconnect cell below carries the `job_id` from our own run. Replace it with your own `job_id`:\n",

[abbycross]

Suggested change

	"Identical post-processing to the simulator run: Fourier-transform the Green's function into $S(q, \\omega)$, mirror-symmetrize, and clip negatives. With the longer chain and evolution the two-spinon continuum is far better resolved. It should fill the band between the dashed bounds, brightest near $q = \\pi$."
	"Identical post-processing to the simulator run: Fourier-transform the Green's function into $S(q, \\omega)$, mirror-symmetrize, and clip negatives. With the longer chain and evolution, the two-spinon continuum is far better resolved. It should fill the band between the dashed bounds, brightest near $q = \\pi$."

[abbycross]

Suggested change

"The hardware example above runs a single chain length. The three spectra below come from earlier hardware runs of this same workflow on `ibm_pittsburgh` at 10, 20, and 30 sites, with every other input held fixed: 20 Trotter steps at `dt = 0.6`, the compression plan of 6 one-layer plus 4 two-layer segments, and `max_bond = 128`. These are recorded results, not output from the cells above.\n",

"The hardware example above runs a single chain length. The three spectra below come from earlier hardware runs of this same workflow on `ibm_pittsburgh` at 10, 20, and 30 sites, with every other input held fixed: 20 Trotter steps at `dt = 0.6`, the compression plan of six one-layer plus four two-layer segments, and `max_bond = 128`. These are recorded results, not output from the cells above.\n",

[abbycross]

Suggested change

	"Queue time is not counted in either column. The classical stage climbs steeply, roughly 6 times from 10 to 20 qubits and another 9 times to 30, dominated by the AQC fidelity optimization at `max_bond = 128`. QPU usage grows only about 1.2 times across the same range, because the circuit count and shot budget follow `t_steps` and the twirling settings rather than the qubit count."
	"Queue time is not counted in either column. The classical stage climbs steeply, roughly six times from 10 to 20 qubits and another nine times to 30, dominated by the AQC fidelity optimization at `max_bond = 128`. QPU usage grows only about 1.2 times across the same range, because the circuit count and shot budget follow `t_steps` and the twirling settings rather than the qubit count."