Show4DSTEM: More → Run SSB (auto cal + products in-widget)

[bobleesj]

Why

Today collaborators who want SSB context often leave Show4DSTEM and run live SSB / a notebook pipeline, then come back. That is friction.

Goal: open Show4DSTEM on a 4D (or 5D) dataset → optionally run SSB inside the widget (More menu) with sensible defaults → land SSB phase (and DPC if easy) as inspection products next to BF/ADF. Fun, automatic, one surface.

Related but distinct:

• Show4DSTEM: accept inspection products (DPC_r/DPC_c/SSB phase) as map presets #188 — pass in precomputed products (products=) with no compute (always useful, always light).
• This issue — compute SSB on demand (or auto-background) from Show4DSTEM.

Do not merge the two. Passed-in products stay the zero-cost path; Run SSB is opt-in (or clearly announced auto).

Product design (recommended)

Do not run heavy SSB on every Show4DSTEM open by default

• Full FOV free-SSB / optuna-grade cal can be seconds to minutes and GPU-heavy.
• Silent background SSB on launch would surprise users (GPU steal, notebook hang, wrong cal on bad data).
• Default open stays fast: BF/ADF-style virtual images only (current behavior).

Do: More → Run SSB (opt-in, progressive)

1. More → Run SSB… (or Run ptycho / SSB)
2. Dialog with defaults pre-filled (no expertise required):
   • cal method: Nelder–Mead (or package default optuna-lite)
   • BF radius / center (from detector cal if known)
   • defocus / C10, C12 if exposed
   • ROI option: full FOV vs current scan crop (encourage crop for speed)
3. Progress + cancel
4. On success: register products into the map selector:
   • SSB (phase) — primary
   • optional later: amplitude, DPC r/c if already cheap from same path
5. User can re-run with tweaked params; last result overwrites or versions as SSB (run 2)

Optional later: “Auto SSB in background”

• Toggle under More: Auto-run SSB after load (off by default).
• Only if GPU free / dataset small / user opted in once.
• Always print one line: what ran, how long, how to disable.
• Still must not block first paint of BF/DP.

Architecture

Piece	Where
Show4DSTEM UI (More menu, progress, product tabs)	quantem.widget
SSB / free-SSB math	quantem.gpu (or live bridge only if gpu not cut over yet) — one math copy
ShowPtycho	Rich explore / aberration drag after a good cal — “Open in ShowPtycho” with locked cal later

Rule: Show4DSTEM orchestrates; it does not reimplement SSB kernels.

Defaults (v1 proposal)

• Method: Nelder–Mead (or current package default that is robust on Samsung/Pari-class data)
• Use existing detector center + BF radius when available
• Prefer scan ROI if user has cropped; else full FOV with a soft warning if > threshold size
• Output: phase map at scan shape; expose in product selector with phase colormap
• Device: respect widget GPU policy (e.g. interactive GPU0)

Acceptance

• More → Run SSB opens param dialog with sensible defaults
• Run completes without separate live ssb CLI for a standard 4D master
• SSB phase appears as selectable map product (composes with Show4DSTEM: accept inspection products (DPC_r/DPC_c/SSB phase) as map presets #188)
• First paint of Show4DSTEM still works with auto-SSB off
• Progress + cancel; errors are readable (no bare kernel traceback only)
• Docstring / tutorial one-liner: open → More → Run SSB → scrub phase
• Compute calls quantem.gpu (or documented bridge), not a third SSB copy

Non-goals v1

• Full iterative multislice ptycho in Show4DSTEM (that stays live / ShowPtycho)
• Silent auto-SSB on every open without user opt-in
• Replacing ShowPtycho for aberration scrub

Refs

• GH Show4DSTEM: accept inspection products (DPC_r/DPC_c/SSB phase) as map presets #188 inspection products (pass-in, no compute)
• GH ShowPtycho: offline HTML + folder export (kernel-less share, WebGPU play) #186 ShowPtycho offline / WebGPU (different surface)
• Package split: gpu computes, widget UI, live collaborator share