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.

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").

Switch the hardware example from ibm_boston to ibm_fez and refresh all
cell outputs and the results commentary to match the new run (unmitigated
~0.2, full PEC gamma^2 ~4.2e3, PEC+SLC gamma^2 ~5.9e2 at ~10% residual
bias, ~7-fold overhead reduction).

Make the noise-learning depth schedule robust: keep a fixed candidate
schedule [1, 2, 4, 8, 12, 16, 24, 32, 40, 48], drop any candidate that
exceeds the circuit's depth, and always cap the deepest value at
max_layer_pair_depth so we never learn deeper than the circuit being
mitigated. Previously sorted({1, 2, 4, 8, 12, 16, max_layer_pair_depth})
could include hardcoded depths (e.g. 12, 16) beyond the circuit when
max_layer_pair_depth was small.

On counting two-qubit layers: we count InjectNoise-annotated boxes rather
than QuantumCircuit.depth(num_qubits == 2). After boxing, circuit data are
full-width BoxOp instructions, so a num_qubits == 2 filter matches nothing;
the boxing pass tags exactly one InjectNoise annotation per two-qubit layer,
so counting those boxes gives precisely the layer depth NLv3 will learn.
Added an inline comment to this effect.

Measure the two-qubit-layer depth with isa_circuit.depth(num_qubits == 2)
instead of counting InjectNoise-annotated boxes, and drop the now-unused
get_annotation / InjectNoise imports. After boxing, two-qubit gates are hidden
inside full-width BoxOp instructions, so a num_qubits == 2 filter on
boxed_circuit matches nothing and QuantumCircuit.depth does not recurse into
boxes; the pre-boxed ISA circuit gives the true 2q critical-path depth, halved
for layer pairs. Value unchanged for this circuit (depth_2q = 40 -> 20).

Refresh outputs from a new ibm_fez run and update the results commentary to
match (full PEC gamma^2 ~2.4e3, PEC+SLC gamma^2 ~3.7e2, ~6-fold reduction,
SLC settling near 0.9 within the ~10% residual-bias bound).

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Co-authored-by: abbycross <across@us.ibm.com>

Text clarifications (expectation value vs. observable, Step 1
motivation, noise-model structure, SLC parameter explanations,
timeout-by-design note), code cleanup of the circuit helpers,
transpiler-selected qubit layout instead of a hand-picked chain,
and explicit inject_noise_site="after" required by SLC now that
samplomatic's default changed. Notebook re-run on hardware to follow.

Re-executed the full notebook end-to-end on ibm_kingston (previous run
was on ibm_fez) and regenerated all extracted output images.

The new backend is substantially less noisy, so the run-specific
numbers changed: full PEC now carries a sampling overhead of
gamma^2 ~ 1.6e2 (was ~2.4e3), and SLC reduces it a further ~3.4-fold
to ~48 at the 10% residual-bias bound (was ~6-fold to ~3.7e2).

Rewrote the results discussion cell to match: plain PEC now converges
near the upper edge of the 10% bias band (~1.1) instead of drifting to
a biased value, and PEC+SLC settles on the exact value (~1.0) inside
the band at roughly a third of the sampling cost. Added a note that
the learned rates and overheads depend on the backend and calibration
at execution time, since rerunning can shift these values.

Also restored the missing execution count on the backend-selection
cell so the notebook numbering is sequential again.