Add shadow tomography tutorial

[Irma Avdic (iavdic)]

Summary

Shadow tomography is a powerful framework for estimating properties of quantum states with significantly fewer measurements than full state tomography. This tutorial introduces the classical shadows protocol through the preparation and characterization of a GHZ state, demonstrating how randomized measurements can be used to efficiently predict many observables from single-measurement data. The tutorial incorporates error-detected 100-qubit GHZ state preparation highlighting how classical shadows can be applied to systems that would be impractical to characterize using conventional tomography. The tutorial covers state preparation, shadow data acquisition, classical post-processing, and observable estimation.

Files

The PR adds the following files:

• the notebook docs/tutorials/shadow-tomography/shadow-tomography-ghz.ipynb

[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! 🙌

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[CLAassistant]

All committers have signed the CLA.

[Rebecca Dimock (beckykd)]

This is so interesting! I keep getting distracted with other work though, so I'm only partway done. I'll finish my review tomorrow.

[Rebecca Dimock (beckykd)]

This is so interesting! I keep getting distracted with other work though, so I'm only partway done. I'll finish my review tomorrow.

[Rebecca Dimock (beckykd)]

Excellent work! Thank you!

[Rebecca Dimock (beckykd)]

Forgot about the rename :)

[Irma Avdic (iavdic)]

Thank you very much for the feedback and suggestions, Rebecca Dimock (@beckykd)!!

[Henry Zou (henryzou50)]

Really nice tutorial and great job Irma Avdic (@iavdic)! It runs cleanly and the content here is great I added the missing registration (_toc.json, index.mdx, notebook-testing.toml, qiskit_bot.yaml), fixed the notebook metadata/formatting, and added a cspell:ignore entry, so CI should now pass.

Here is a checklist of fixes before merge:

1. Links

• Next steps cell -- replace the three literal https://quantum.cloud.ibm.com/... placeholders:
  • "General formulation of quantum information" -> /learning/courses/general-formulation-of-quantum-information
  • "Low overhead error detection using spacetime codes tutorial" -> /docs/tutorials/ghz-spacetime-codes
  • "Qiskit Paulice addon API documentation" -> /docs/api/qiskit-addon-paulice
• Convert the ~9 absolute https://quantum.cloud.ibm.com/... links (Learning outcomes, Prerequisites, hardware intro) to relative paths (/docs/..., /learning/...), as this is the convention in all recent tutorials.

2. Requirements cell

• Make the visualization link relative: /docs/api/qiskit/visualization.
• (Pending Rebecca Dimock (@beckykd)'s confirmation on the inline thread) Keep IBM Quantum Compute v0.28 or later as suggested, or revert to Qiskit Runtime vX.Y or later to match the other tutorials, whichever Becky confirms as the convention for versioned requirements lines.

3. Fidelity claims — Interpret the results cell + hardware-cell prints

• Remove the claim that ½⟨ZᵢZᵢ₊₁⟩ is "a lower bound on the GHZ-state fidelity": the state (|0…0⟩ − |1…1⟩)/√2 has ⟨ZᵢZⱼ⟩ = 1 for every pair (proxy = 0.5, "perfect") but zero fidelity with the GHZ state, no ZZ-only quantity can bound fidelity, because ZZ is blind to phase.
• Remove "anything greater than 0 confirms genuine quantum correlations": the separable mixture ½(|0…0⟩⟨0…0| + |1…1⟩⟨1…1|) gives ⟨ZZ⟩ = 1 with zero entanglement. Suggest presenting the ZZ data as probing the classical-correlation half of the GHZ signature (certifying coherence would need X-basis parity measurements).
• Rename the two Fidelity (proxy) print labels in the hardware cell to match (e.g. "Mean nearest-neighbor ZZ").
• Soften "demonstrates that the spacetime parity checks are catching real hardware errors rather than discarding shots at random" -> "consistent with the checks detecting real errors." The checks postselect on ZZ-type parities, so improvement in ⟨ZZ⟩ is expected by design and doesn't show the kept state is cleaner in the phase sector, where these checks are blind.

4. Variants table -- global Clifford row

• Replace the sample complexity O(2^k log M/ε²) with O(Tr(O²) log M/ε²). Ref [1]'s Clifford bound is ~3 Tr(O²) log M/ε², which for a weight-k Pauli on N qubits grows like 2^N -- exponential in system size, which is exactly why the row's "suitable observables" says low-rank/fidelity. As written, 2^k would make global Clifford strictly better than local Pauli's 3^k, contradicting the paragraph below the table.

5. Citation -- helper-functions markdown cell

• Add the spacetime-codes paper (arXiv:2504.15725) to the References list as [6].
• Change the backward-propagation citation from [4] (Bertoni Shallow Shadows -- wrong paper) to the new [6].

6. Accuracy nits

• Background: "over 10³³ shots" for 50 qubits, where the parameter count is 4⁵⁰ − 1 ≈ 1.3×10³⁰, not 10³³. Either show the arithmetic (~10³⁰ parameters × ~10³ shots each) or soften to "on the order of 10³⁰."
• Hardware intro: "a single-qubit error on either neighbor flips the ancilla" -> "a single bit-flip error on either neighbor flips the ancilla" (phase errors are invisible to a ZZ parity check, and simultaneous flips on both neighbors cancel).

7. Hardware-cell robustness

• degree_two_nodes is built from the wrong layout: after the root-search loop, ghz_qubits holds the layout of the last root tried (even a wrong-size one, the size check runs after the assignment), not best_root. Fix: re-run parallel_ghz(best_root, ghz_size, backend, bad_edges, bad_nodes) before computing degree_two_nodes.
• If no root qualifies, best_root stays −1, every skip trial fails the size check, best_qc stays None, and len(ghz_qubits) raises TypeError before the intended "No GHZ found" exception can fire. Fix: initialize best_root = None / base_depth = float("inf") and raise a clear error right after the root loop.

[Henry Zou (henryzou50)]

Rebecca Dimock (@beckykd) Quick check before Irma finalizes: the July rename (#5419) applies to the cloud service (-> IBM Quantum Compute Service), while the pip package kept the name qiskit-ibm-runtime. Other tutorials and guides still write these as "Qiskit Runtime vX.Y or later".

Should requirements lines use the new name or stay "Qiskit Runtime"? Happy either way, if the former, we should open a follow-up to update the other tutorials for consistency.

[Irma Avdic (iavdic)]

Thank you very much for the feedback, Henry Zou (@henryzou50)! Just made the final fixes. Please let me know if there's anything else I can do!

[Henry Zou (henryzou50)]

Thanks for the update Irma Avdic (@iavdic)! Mostly looks good to me and thanks for the changes!

There is just one remaining issue: the renamed prints kept the old ½ factor.

The two Fidelity (proxy) prints were relabeled "Mean nearest-neighbor ZZ" but still compute 0.5 * np.mean(...), so the output contradicts the lines above it:

Before detection: <ZiZi+1>=  0.5737...
Before detection: Mean nearest-neighbor ZZ= 0.2868...   <- half the value printed above

The fix: delete the last two print statements in the hardware cell (the ones with 0.5 * np.mean(ZZ_hw) and 0.5 * np.mean(ZZ_kept)), as the mean ZZ is already printed just above, and remove the two matching lines from the stored cell output.

After that is fix, it should be good to go!

[Henry Zou (henryzou50)]

Thanks Irma Avdic (@iavdic), this looks good to go now!

Since the remaining fix was minor, I went ahead and applied it for you as I was fixing the lint issues: I removed the two 0.5 * np.mean(...) print statements from the hardware cell (the mean ⟨ZᵢZᵢ₊₁⟩ is already printed just above) along with the two matching lines in the stored cell output. I also fixed two links that went stale after recent changes on main (/docs/tutorials/ghz-spacetime-codes -> /docs/tutorials/spacetime-codes, and the general-measurements course link now points to /introduction), and merged main into the branch.

One logistical note on CI: the Execute notebooks check cannot pass on a PR from a fork. Because this PR registers the notebook in scripts/config/notebook-testing.toml, CI runs the full notebook test suite, which needs repository secrets that fork PRs don't receive. Since you don't have write access to Qiskit/documentation, I'll push this branch to the main repository directly and open a PR from there so CI can run fully, so no action needed on your end.

Thanks again for the great tutorial!

[Irma Avdic (iavdic)]

Thank you very much, Henry Zou (@henryzou50)!!

[Henry Zou (henryzou50)]

Move to #5531 because the original PR is from a fork: