Update the spacetime codes tutorial to use qiskit-paulice by henryzou50 · Pull Request #5312 · Qiskit/documentation

henryzou50 · 2026-06-29T17:34:55Z

Summary

Reworks the Low-overhead error detection with spacetime codes tutorial around the qiskit-paulice package. The previous version built a single coherent Pauli check by hand and prepared a GHZ state; the new version uses the package to automatically find and insert spacetime Pauli checks into Clifford circuits, then boosts the fidelity of the sampled distribution by postselecting on the check syndromes. The tutorial title, URL, and nav entry are unchanged, so no redirects are needed.

Content

Conforms to the tutorial template: Learning outcomes, Prerequisites, Background,
Requirements, Setup, small-scale simulator example (Steps 1–4), large-scale
hardware example, Next steps, References.
Backend-agnostic: a find_check_layout helper searches the coupling map of any
backend for a low-error qubit path with many available ancillas, and Step 2
selects a device with service.least_busy(). No hardcoded layouts.
Updated to reflect the workflow in the qiskit-paulice tutorial here (https://github.com/Qiskit/qiskit-paulice/blob/main/docs/guides/low_overhead_error_detection_using_spacetime_codes.ipynb) with a hardware run

Supporting changes

_toc.json / index.mdx: entry marked isNew
qiskit_bot.yaml: added @henryzou50 as an owner
scripts/config/notebook-testing.toml: kept in the do-not-run list
Extracted output images regenerated

Add a new Error detection tutorial that uses the qiskit-paulice package to automatically find and insert spacetime Pauli checks into Clifford circuits, then boosts sampled-distribution fidelity by postselecting on check syndromes. It conforms to the tutorial template (Learning outcomes, Prerequisites, Background, Requirements, Setup, small-scale simulator example with Steps 1-4, large-scale hardware example, Next steps, References) and is framed as an extension of the existing ghz-spacetime-codes tutorial, with bidirectional cross-links between the two. Changes: - docs/tutorials/automated-spacetime-pauli-checks.ipynb: new tutorial - docs/tutorials/_toc.json, docs/tutorials/index.mdx: register under "Error detection" (marked isNew) - qiskit_bot.yaml: add owner - scripts/config/notebook-testing.toml: exclude from notebook test runs - docs/tutorials/ghz-spacetime-codes.ipynb: add forward cross-link in Next steps - public/docs/images/tutorials/automated-spacetime-pauli-checks/: extracted plot outputs Note: this run was executed on ibm_marrakesh (Heron r2) and the postselection results are weaker than expected. The qubit layout is hand-picked for ibm_boston (Heron r3) connectivity, so the tutorial needs to be rerun on ibm_boston (or another suitable backend) to investigate the poor results and finalize the outputs, commentary, and usage estimate.

qiskit-bot · 2026-06-29T17:35:00Z

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

@MeltemTolunay
@nathanearnestnoble

review-notebook-app · 2026-06-29T17:35:01Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

henryzou50 · 2026-06-29T20:15:07Z

Note to self, will update this to replace old tutorial instead of adding a new one.

@henryzou50

Rework the "Low-overhead error detection with spacetime codes" tutorial (docs/tutorials/ghz-spacetime-codes.ipynb) in place rather than adding a separate notebook. The tutorial now uses the qiskit-paulice package to automatically find and insert spacetime Pauli checks into Clifford circuits and boosts sampled-distribution fidelity by postselecting on check syndromes, replacing the previous hand-built-check / GHZ-preparation content. The title and URL (/docs/tutorials/ghz-spacetime-codes) are unchanged. - docs/tutorials/ghz-spacetime-codes.ipynb: new qiskit-paulice content, conforming to the tutorial template (Learning outcomes, Prerequisites, Background, Requirements, Setup, small-scale simulator example with Steps 1-4, large-scale hardware example, Next steps, References) - docs/tutorials/automated-spacetime-pauli-checks.ipynb: removed (the short-lived separate notebook); its extracted images moved to the ghz-spacetime-codes image folder - public/docs/images/tutorials/error-detection: removed (old GHZ outputs) - docs/tutorials/_toc.json, docs/tutorials/index.mdx: drop the extra entry; mark the refreshed tutorial isNew - qiskit_bot.yaml: add @henryzou50 as an owner of ghz-spacetime-codes - scripts/config/notebook-testing.toml: drop the extra exclusion entry The committed outputs are from a run on ibm_marrakesh, where the hardcoded ibm_boston layout maps onto bad edges and produces an unrealistic noise model (~19% gate noise). This breaks the demonstration: postselection does not improve fidelity and the postselection rate collapses to under 1%. Rerun on ibm_boston (or another Heron r3 backend) to restore a sane noise model and regenerate the outputs, then reconcile the prose (currently "Heron r3 QPU ibm_boston") and the usage estimate with the backend actually used.

beckykd

Nice work!

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>

henryzou50 · 2026-07-01T21:14:01Z

Thanks @beckykd for the review and suggestions! One note before this is fully ready, I am still currently waiting on the job results for ibm_boston, which should improve the results significantly.

Replace the hardcoded ibm_boston qubit layout with a new find_check_layout helper in the Setup section. The helper searches the backend coupling map with random self-avoiding walks, excludes qubits and two-qubit gates whose reported errors exceed configurable thresholds, and keeps the path that offers the most target/ancilla check pairs (ties broken by lower average gate error). Step 2 now selects a device with service.least_busy() and derives the layout from it, so the tutorial runs on any IBM Quantum QPU; the previous fixed layout mapped onto bad edges on non-Boston devices and produced an unusable noise model (~19% gate noise on ibm_marrakesh). Refresh all committed outputs from a successful run on ibm_kingston: - Simulator: fidelity 0.709 -> 0.953 postselected (postselection rate 0.71) - Hardware: fidelity 0.240 -> 0.848 postselected (postselection rate 0.098) Align the commentary with the measured results: - Correct the gamma discussion (the curves fall toward 1.0 but have not converged at seven checks) - Note that the postselection rate approaches the noisy-state fidelity when the checks detect nearly all erroneous samples - Add a short interpretation of the hardware results and the tradeoffs between postselection rate, depth, and number of checks - Reword Step 2 and the transpilation text to be backend-agnostic Finalize the usage estimate (1 minute on a Heron processor, ibm_kingston or equivalent), matching the wording of recently added tutorials.

henryzou50 · 2026-07-06T15:14:24Z

Finished with the new results and ready for review! Since the earlier approval, the scope settled on reworking the existing tutorial in place (title/URL unchanged), the layout selection is now backend-agnostic via a find_check_layout helper, and all outputs are from a fresh end-to-end run on ibm_kingston (sim: 0.709 → 0.953 postselected;
hardware: 0.240 → 0.848). @beckykd flagging since there a quite a bit of changes since your last review

henryzou50 · 2026-07-06T20:17:02Z

Note to self, change tutorial name

caleb-johnson · 2026-07-13T16:13:55Z

Looking great! A couple of things:

The images aren't rendering for me in the github GUI (here), will these work once the tutorial is merged into the platform?
We link to the github repo at the bottom of the tutorial, you might want to link to the Paulice docs on the Platform. You could add this in addition to the link to the repo or replace it -- whatever you think is best

henryzou50 · 2026-07-13T17:21:33Z

Thanks for the review @caleb-johnson! I applied your suggestion of linking to the Paulics docs on the platform in the next steps as well.

caleb-johnson

Looks really nice!

caleb-johnson · 2026-07-13T17:37:29Z

One other quick note:

I notice the slug on the tutorial is ghz-spacetime-codes, but this tutorial doesnt show anything about a GHZ state.

Maybe this is intentional so the link to the old tutorial brings people here now, rather than breaking? Anyway, just wanted to mention it

henryzou50 · 2026-07-13T17:40:36Z

One other quick note:

I notice the slug on the tutorial is ghz-spacetime-codes, but this tutorial doesnt show anything about a GHZ state.

Maybe this is intentional so the link to the old tutorial brings people here now, rather than breaking? Anyway, just wanted to mention it

Yes, I left the slug as ghz-spactime-codes for now so that we don't have to update the other links. But if we do prefer updating that slug, I can do that as well.

Rework the large-scale hardware section to run a 20-qubit payload on ibm_boston: - Build a dedicated 20-qubit layout with its own target/ancilla pairs, noise model, and pass manager rather than reusing the simulator setup, searching harder (num_trials=500) with tighter error thresholds to avoid a single bad coupler or readout qubit dragging down every stabilizer. - Draw stabilizers by composing a random subset of group generators, since enumerating all 2^n stabilizers is infeasible at this size. - Concentrate the shot budget on fewer stabilizers (10 stabilizers, 40,000 shots) to leave enough postselected samples at the low postselection rate this payload produces. - Merge the separate retrieve cell into the submit cell and refresh all narrative, outputs, and extracted images. - Bump usage estimate from 1 to 4 minutes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Applied Caleb's suggestion to learn the noise model on the QPU instead of inferring a uniform depolarizing channel from calibration data: - Add a NoiseLearner job that characterizes the 20-qubit layout's entangling layers, and a learned_noise_model helper that converts the learner's PauliLindbladError output (physical, per-layer qubit indices) into the layout-relative PauliLindbladMaps that NoiseModel.from_pauli_lindblad_maps expects. Readout noise still comes from calibration data, since the learner characterizes gate layers only. - Keep the steps 1-4 framing, folding layout search, noise learning, and check-finding into step 2, and note that the cell now submits two jobs (tags TUT_ASPC_LEARN and TUT_ASPC). - Refresh hardware results: noisy 0.37 vs postselected 0.69 at a 28.5% postselection rate (~11.4k kept shots per circuit), up from 6.4% (~2.6k) with the uniform model. Add a per-stabilizer results table (noisy, postselected, PS rate, kept shots) and move the plot legend outside the axes so it cannot hide data points. - Add a comment noting that swapping back to NoiseModel.from_backend is a one-line change for readers who want to compare, clarify the stabilizer-subsampling sentence (Caleb's wording), and pin the backend to ibm_boston in the simulator section. - Refresh simulator outputs from the rerun and update the cspell dictionary/ignore list for new terms.

henryzou50 · 2026-07-20T18:59:18Z

@abbycross Thanks for the review, I just applied your suggestions!

abbycross

Thanks!

- Rephrase the learned-noise prose: checks are scored against "noise more similar to that affecting the QPU", and learning the noise requires QPU sampling that belongs in the overall sampling budget. - "On hardware at this size" -> "For circuits of this size", and "much higher expectation value" -> "much better expectation value". - Add the dashed mean lines to the per-stabilizer plot legends as "noisy/postselected fidelity" and relabel the points as "noisy/postselected EVs", in both the simulator and hardware plots. - Restore least_busy backend selection and refresh the simulator outputs and images, which also picks up the new legend labels. - Regenerate the hardware plot image from the saved run's per-stabilizer values (no new QPU job; results unchanged) and drop an environment-specific QPY version warning from the saved output. Keep NoiseLearner and Sampler as-is: Sampler is already SamplerV2 via the aliased import, and NoiseLearnerV3 pairs with the Executor stack rather than the V2 primitives this tutorial uses. Slug rename to spacetime-codes will follow in a separate commit.

Move the notebook and its image directory, and update every reference: image paths in the notebook outputs, the link in the post-selection guide, the tutorials toc and index, the qiskit-bot ownership config, and the notebook-testing config. Note for review: the old URL is already live on production, so this rename needs a platform-side redirect (or acceptance of the broken URL). Same situation as the fractional-gates tutorial rename that was reverted in #5343 - flagging for the docs team to decide.

henryzou50 · 2026-07-27T16:26:47Z

Hi @abbycross, thanks for the review! When you have a moment, could you take another look? The updates since your pass are small:

Applied Caleb's review feedback: a few wording tweaks in the hardware section and clearer plot legends (dashed mean lines labeled as fidelities, points as EVs).

The one major thing to check is the last commit: we renamed the slug from ghz-spacetime-codes to spacetime-codes (file, image directory, and all internal references are updated and CI checks pass). Since the old URL is already live on production, this has the same redirect/SEO question as the fractional-gates rename that ended up being reverted in #5343, it's isolated in its own commit (ac96a79) so it's easy to drop if that's the call here too. Would appreciate your take on whether the rename can go ahead

henryzou50 self-assigned this Jun 29, 2026

henryzou50 requested a review from a team June 29, 2026 17:34

henryzou50 added the tutorial 📒 label Jun 29, 2026

github-project-automation Bot added this to Docs Planning Jun 29, 2026

github-actions Bot had a problem deploying to pr_preview June 29, 2026 17:35 Failure

github-actions Bot deployed to pr_preview June 29, 2026 18:06 View deployment

github-actions Bot deployed to pr_preview June 30, 2026 00:14 View deployment

beckykd previously approved these changes Jul 1, 2026

View reviewed changes

Update docs/tutorials/ghz-spacetime-codes.ipynb

0aafea3

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>

henryzou50 dismissed beckykd’s stale review via 0aafea3 July 1, 2026 21:11

henryzou50 and others added 2 commits July 1, 2026 17:11

Update docs/tutorials/ghz-spacetime-codes.ipynb

9d8f420

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>

Update docs/tutorials/ghz-spacetime-codes.ipynb

5398a92

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>

github-actions Bot temporarily deployed to pr_preview July 1, 2026 21:12 Destroyed

henryzou50 and others added 2 commits July 1, 2026 17:12

Update docs/tutorials/ghz-spacetime-codes.ipynb

92c4931

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>

Update docs/tutorials/ghz-spacetime-codes.ipynb

496dd24

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>

github-actions Bot deployed to pr_preview July 1, 2026 21:13 View deployment

github-actions Bot deployed to pr_preview July 5, 2026 19:31 View deployment

henryzou50 changed the title ~~Add "Automated spacetime Pauli checks with qiskit-paulice" tutorial~~ Update the spacetime codes tutorial to use qiskit-paulice Jul 6, 2026

Link to Paulice docs on the Platform in Next steps

8d92b85

github-actions Bot deployed to pr_preview July 13, 2026 17:21 View deployment

henryzou50 requested review from kaelynj and nathanearnestnoble July 13, 2026 17:25

caleb-johnson approved these changes Jul 13, 2026

View reviewed changes

github-actions Bot deployed to pr_preview July 20, 2026 14:54 View deployment