Add PEC with logical noise models tutorial by henryzou50 · Pull Request #5616 · Qiskit/documentation

Henry Zou (henryzou50) · 2026-09-08T18:05:50Z

Summary

Adds a new tutorial, Probabilistic error cancellation with logical noise models, ported from the internal ibm-quantum-learning-enablement repo. The tutorial combines mediator-qubit error detection with PEC on a 49-qubit hexagonal Ising circuit, showing that QED+PEC converges with far fewer shots than PEC alone.

Changes

Add docs/tutorials/probabilistic-error-cancellation-with-logical-noise-models.ipynb and its hero image under public/docs/images/tutorials/.
Extract the 10 embedded plot outputs to extracted-outputs/*.avif via tox -e fix.
Add the tutorial to _toc.json and index.mdx under Error mitigation.
Add a qiskit_bot.yaml ownership entry.
Exclude the notebook from notebook CI in notebook-testing.toml, since it runs on hardware (ibm_boston, ~28 min).

Notes for reviewers

The notebook installs qiskit-noise-learning and qiskit-mitigation from git, as neither is on PyPI yet. The qiskit-mitigation install pins the postselection-rename branch until that module lands on main. Both install lines should be updated once the packages are released.

Port the Ising ED-PEC tutorial notebook and its hex-ising figure, unchanged. ToC, index, image path, and notebook-test config updates will follow in a later commit.

Fix the hero image path, add the tutorial to the ToC, index, and qiskit_bot ownership, exclude it from notebook CI (runs on hardware), and run tox -e fix to normalize the notebook and extract plot outputs.

qiskit-bot · 2026-09-08T18:05:55Z

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

@nathanearnestnoble

review-notebook-app · 2026-09-08T18:05:56Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

abbycross · 2026-09-09T19:57:17Z

+    "![Hexagonal Ising lattice embedded on a heavy-hex qubit layout, with Ising sites on the degree-3 qubits and mediator qubits on the edges between them](/docs/images/tutorials/probabilistic-error-cancellation-with-logical-noise-models/hex-ising.avif)\n",
+    "In this tutorial we will evaluate observables of a ``22``-site Ising model on a ***hexagonal*** lattice using a Heron QPU, which has a ***heavy-hexagonal*** qubit topology. Many demonstrations on Heron QPUs focus on systems defined on heavy-hexagonal lattices to match the system's connectivity; however, hexagonal models tend to be more interesting to study as they appear more commonly in nature and are more difficult to simulate classically due to their denser connectivity. Since the qubit topology of the QPU cannot directly support the connectivity of a hexagonal lattice, we must decide how to efficiently embed the hexagonal model onto the qubit topology. In this example we represent each site in the Ising model with a qubit lying on a vertex of the heavy-hex QPU lattice. We use the qubits on the edges (***mediator qubits***) to facilitate entanglement between the Ising qubits on the vertices. Additionally, the mediator qubits implement entanglement in such a way that they are always expected to return to the ground state $|0\\rangle$. If a mediator qubit measures $|1\\rangle$, it indicates a logical error occurred during circuit execution; postselecting only samples with no detected errors on the mediator qubits yields a smaller distribution of ***logical samples*** which may have a higher fidelity than the raw, noisy distribution. Not only can we detect that an error occurred by measuring a mediator qubit, we can also determine exactly which logical errors that qubit is capable of detecting throughout the circuit. Removing the noise generators the mediator qubits' ***symmetry checks*** are capable of detecting from a noise model leaves a reduced noise model, which can be mitigated using techniques such as probabilistic error cancellation (PEC).\n",
+    "\n",
+    "In this notebook example, we will combine the error detection technique described above with PEC to counteract the quantum noise more effectively than either technique can do alone. We will use ``49`` qubits to embed the ``22``-qubit Ising model and use the extra ``27`` mediator qubits for error detection. We will run PEC on the postselected noise channel to mitigate the noise that evades the symmetry checks. In addition to combining error detection with PEC, we will use techniques such as TREX readout error mitigation and non-Markovian error checks to further combat the effect of quantum noise.\n",


Is it important/significant for the numbers here to be formatted with double ticks? If not, I'd just remove the ticks.

Agreed, these are ordinary quantities, so code formatting isn’t needed. I removed the backticks from numbers throughout the tutorial.

abbycross · 2026-09-09T20:02:59Z

+    "    ax.set_ylabel(\"Expectation value\")\n",
+    "    # Zoom the y-axis onto the data: the ideal, baseline, error-detection, and PEC + error\n",
+    "    # detection curves (with error bars) set the range, so an unconverged PEC arm may run off\n",
+    "    # scale instead of blowing out the axis. The upper margin leaves room for the inset.\n",


"blowing out the axis" - not sure what this means, and will it translate ok?

Oh I meant that large fluctuations in the PEC-only results could expand the y-axis range and make the other curves difficult to distinguish. I rewrote the comment to explain that directly, including that PEC-only values may fall outside the visible range.

…oise-models.ipynb Co-authored-by: abbycross <across@us.ibm.com>

abbycross

Thanks!

Caleb Johnson (caleb-johnson) · 2026-09-10T15:33:11Z

+    "            label=label,\n",
+    "        )\n",
+    "    ax.set_xlim(-400, 24000)\n",
+    "    ax.set_ylim(ideal_avg - 0.18, ideal_avg + 0.18)\n",


setting these two 0.18 to 0.08 makes a nicer convergence chart. I would update these and re-run the notebook for a nicer convergence chart at the end

Caleb Johnson (caleb-johnson) · 2026-09-10T16:35:01Z

+    "            label=label,\n",
+    "        )\n",
+    "    ax.set_xlim(-400, 24000)\n",
+    "    ax.set_ylim(ideal_avg - 0.18, ideal_avg + 0.18)\n",


Suggested change

" ax.set_ylim(ideal_avg - 0.18, ideal_avg + 0.18)\n",

" ax.set_ylim(ideal_avg - 0.08, ideal_avg + 0.08)\n",

Henry Zou (henryzou50) · 2026-09-10T16:45:53Z

Thanks, Caleb! Since the PR has already merged, I’ll include this in a follow-up PR and regenerate the convergence chart. I’ll also coordinate with Abby and Kaelyn to hold publication pending confirmation that xslow is available and working in the default calibration.

…plot (Qiskit#5629) This follow-up to Qiskit#5616 removes the custom `calibration_id` and its outdated explanatory note so the tutorial uses the backend’s default calibration. It also narrows the convergence plot’s y-axis limits from ±0.18 to ±0.08, as Caleb suggested. **Current status** - All eight repository quality checks passed. - The notebook still requires `xslow`; default-calibration execution has not yet been validated. - The plotting code is updated, but the saved convergence chart still uses the previous limits. **Before merging** - [x] Confirm `xslow` is deployed on `ibm_boston`. - [x] Verify `xslow` executes using the default calibration without a custom `calibration_id`. Small hardware test passed per Caleb’s recommendation, a full experiment rerun is not required. - [x] Keep the plotting code consistent with the saved chart. The axis-limit adjustment is deferred until the chart can be regenerated from saved results. - [x] Obtain final review.

Henry Zou (henryzou50) added 2 commits September 8, 2026 13:56

Add PEC with logical noise models tutorial

fdc6f7a

Port the Ising ED-PEC tutorial notebook and its hex-ising figure, unchanged. ToC, index, image path, and notebook-test config updates will follow in a later commit.

Wire up PEC with logical noise models tutorial

2121cec

Fix the hero image path, add the tutorial to the ToC, index, and qiskit_bot ownership, exclude it from notebook CI (runs on hardware), and run tox -e fix to normalize the notebook and extract plot outputs.

Henry Zou (henryzou50) requested a review from abbycross September 8, 2026 18:05

Henry Zou (henryzou50) self-assigned this Sep 8, 2026

Henry Zou (henryzou50) requested a review from a team September 8, 2026 18:05

Henry Zou (henryzou50) added the tutorial 📒 label Sep 8, 2026

github-project-automation Bot added this to Docs Planning Sep 8, 2026

github-actions Bot had a problem deploying to pr_preview September 8, 2026 18:06 Failure

Converted image to avif

1693b78

github-actions Bot had a problem deploying to pr_preview September 8, 2026 18:39 Failure

cspell and typo fixes

9d755b7

github-actions Bot deployed to pr_preview September 8, 2026 18:56 View deployment

Collapse figure helpers cell in rendered tutorial

951e845

github-actions Bot deployed to pr_preview September 9, 2026 18:02 View deployment