Add PEC with SLC tutorial#5218
Open
henryzou50 wants to merge 2 commits into
Open
Conversation
Adapt the SLC-PEC tutorial from the QDC Challenges 2025 repo [1] into a documentation tutorial, updated for the released Qiskit Runtime and restructured to follow the standard tutorial template. New files: - docs/tutorials/pec-with-shaded-lightcones.ipynb - public/docs/images/tutorials/pec-with-shaded-lightcones/ (3 background schematics + extracted cell outputs) Registered in docs/tutorials/_toc.json and docs/tutorials/index.mdx under "Error mitigation", excluded from notebook CI in scripts/config/notebook-testing.toml (consistent with other tutorials), and given an owner in qiskit_bot.yaml. Important changes and updates from the original [1]: - API: migrated off the `executor_preview` branch to the released qiskit-ibm-runtime 0.47.0. `Executor`, `QuantumProgram`, and `NoiseLearnerV3` are imported from the top-level package, and noise-learner options are passed as a plain dict instead of `NoiseLearnerV3Options`. (qiskit-addon-slc 0.1.0 is already the latest release, so its pin is kept.) - Credentials: replaced the hardcoded `shared_service` (token + `instance` CRN) and the named `QiskitRuntimeService(name="qdc-2025")` with a plain `QiskitRuntimeService()` that reads saved credentials. - Live execution: removed all saved-job loading (the `shared_service.job(...)` IDs and the `load_cached_*` branches). The noise learner and Executor now run live, and the noise-learning job is tagged `TUT_SLC`. - Noise-learning depth: set the deepest NLv3 `layer_pair_depths` value to half the circuit's two-qubit-layer depth, so the total learned depth matches the depth of the circuit being mitigated (computed programmatically from the boxed circuit). This noticeably improves the learned model for mitigation. - Dropped the cluster-resources demonstration: removed the committed `merged_bounds_cluster.pickle` load. `local_scales` and the execution now use the live laptop-computed `merged_bounds`, and the sampling-overhead plot compares full PEC against PEC+SLC only. Its hardcoded y-limits were removed so it autoscales to the run's values. - Cleanup: removed the `logging.basicConfig` INFO logging (kept the multiprocessing `set_start_method`/`OMP_NUM_THREADS` setup that SLC needs), and stripped INFO-log and local-path stream outputs. - Structure: reformatted to the tutorial template (title/description frontmatter, learning outcomes, prerequisites, adapted background with relative doc links and committed AVIF figures, requirements, setup, next steps). The small-scale simulator section is kept but explains why simulation is skipped (SLC mitigates learned hardware noise). Converted in-page anchor links to plain references. This run was executed on ibm_boston. The PEC+SLC results are not as strong as the original QDC run: full PEC has a very high sampling overhead (gamma^2 ~ 1.8e4), and although PEC+SLC reduces this ~17x and far outperforms plain PEC, it does not fully settle within the 10% bias band in the randomizations shown. The commentary has been updated to reflect this, and the figures will likely be regenerated on a rerun (for example, with more randomizations) before final publication.
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Contributor
|
One or more of the following people are relevant to this code:
|
Rerun the tutorial on hardware and refresh the results commentary to
match the new data:
- Update executed outputs: full PEC sampling cost (gamma^2) 1.8e4 -> 8.7e4,
PEC+SLC sampling cost 1.1e3 -> 4.2e3, plus minor shifts in shots-kept
fractions for noise learning (0.86 -> 0.85) and post-selection (~25.7%
-> ~26.7%).
- Revise the results discussion: SLC now reduces overhead ~20-fold (was
~17-fold), and PEC+SLC settles in the physical region near the exact
value (previously it converged above 1, in the unphysical region).
- Fix a broken sentence in the "Box the circuit" section ("the SLC
workflow the use of" -> "the SLC workflow requires the use of").
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new tutorial, "Probabilistic error cancellation with shaded lightcones." It is an updated version of the SLC-PEC tutorial from the QDC Challenges 2025 repo: https://github.com/qiskit-community/qdc-challenges-2025/blob/main/day3_tutorials/Track_A/slc_pec/qdc_tutorial_slc.ipynb
Probabilistic error cancellation (PEC) produces unbiased expectation values but at a sampling overhead (γ²) that grows exponentially with circuit noise. Shaded lightcones (SLC) bound each noise term's contribution to the observable so the mitigation budget is spent only where it matters, trading a small bounded residual bias for a large reduction in overhead. The tutorial implements the full PEC+SLC workflow on a 20-qubit mirrored Ising circuit (observable ⟨X₆Z₁₃⟩) using
qiskit-addon-slc,samplomatic,NoiseLearnerV3, and theQuantumProgram/Executorclasses in Qiskit Runtime, following the four-step Qiskit pattern, and compares full PEC, PEC+SLC, and the unmitigated baseline.Major changes from the original
executor_previewbranch.Executor,QuantumProgram, andNoiseLearnerV3are imported from the top-levelqiskit_ibm_runtime; noise-learner options are passed as a plain dict (noNoiseLearnerV3Options).qiskit-addon-slc0.1.0 is already the latest release, so its pin is kept.shared_service(token +instanceCRN) and the namedQiskitRuntimeService(name="qdc-2025")with a plainQiskitRuntimeService()that reads saved credentials.shared_service.job(...)IDs and theload_cached_*branches); the noise learner andExecutorexecute live, with the noise-learning job taggedTUT_SLC.layer_pair_depthsvalue is set to half the circuit's two-qubit-layer depth, so the total learned depth matches the depth of the circuit being mitigated (computed programmatically from the boxed circuit). This noticeably improves the learned model.merged_bounds_cluster.pickleload;local_scalesand the execution now use the live, laptop-computedmerged_bounds, and the sampling-overhead plot compares full PEC vs PEC+SLC only (with autoscaling y-limits).logging.basicConfigINFO logging (kept the multiprocessingset_start_method/OMP_NUM_THREADSsetup SLC requires), stripped INFO-log and local-path stream outputs, and converted in-page anchor links to plain references.Files
docs/tutorials/pec-with-shaded-lightcones.ipynb+ images underpublic/docs/images/tutorials/pec-with-shaded-lightcones/(3 background schematics and the extracted cell outputs).docs/tutorials/_toc.jsonanddocs/tutorials/index.mdx(Error mitigation section), added to the notebook-CI exclude list inscripts/config/notebook-testing.toml, and given an owner inqiskit_bot.yaml.Results / testing
Ran on IBM Quantum hardware (
ibm_boston),tox -e lint, the notebook normalizer, spelling, and internal-link checks all pass.