ShowPtycho: offline HTML + folder export (kernel-less share, WebGPU play)

[bobleesj]

Why

Collaborators (and future-you) should open a finished ShowPtycho session without re-running a notebook or attaching a Python/CUDA kernel: scrub phase/FFT, try locked calibrations, optionally tweak defocus if the math runs in-browser.

Same product shape as:

• Show3D export_sidecar(out_dir) → index.html + data + manifest (Range-fetch friendly)
• Show4DSTEM offline WebGPU HTML (export_html / quantem show4dstem --html)

Today ShowPtycho is live-kernel only (anywidget + Python GPU for drag/commit). No export_html / export_sidecar.

Ask

Add export + sidecar for ShowPtycho so anyone can:

1. In a notebook: finish optimize / explore / star calibrations
2. w.export_html(...) and/or w.export_sidecar(out_dir)
3. Ship a folder (or single HTML when small enough)
4. Open in Chrome over HTTP and play — no Python

Suggested phases

Phase A — display-first offline (ship first)

• Bake what the user already computed: phase, amplitude, FFT products, probe, locked PtychoCalibration / stars, time index if 5D
• Thin index.html + on-disk arrays (prefer folder export for multi-frame / full-res; single-file only when safe size)
• Scrub frames, flip starred aberrations as precomputed views (or switch among baked product stacks)
• Match house patterns: manifest.json, Range-capable serve docs, no silent binning

Phase B — WebGPU live math (the “oh my goodness” path)

• Port the interactive path that currently hits the Python kernel (BF-subsampled phase/FFT while dragging C10/C12/…, full recon on commit) to browser WebGPU / WGSL
• Offline HTML can then re-run free-SSB-style abberation scrub without CUDA host
• Fall back gracefully if WebGPU adapter missing

Phase C — 5D / series (later, related)

• Time series + shared vs per-frame defocus products
• Ties to joint-probe / defocus-drift science work; do not block Phase A

Package boundary (do not put WGSL in quantem.gpu)

Piece	Package
Offline export API, HTML shell, JS UI, scrub	quantem.widget
WGSL / browser WebGPU compute for offline recompute	quantem.widget (same as Show4DSTEM offline WebGPU)
Python CUDA/CuPy/torch SSB + cal for live notebooks	quantem.gpu (called by live kernel / ShowPtycho online)

quantem.gpu is Python multi-backend compute. WGSL runs in Dawn/Chrome, not in the Python process. quantem.gpu already documents backendless WebGPU paths as living elsewhere (export_html style). Keep that split: math source of truth in gpu for Python; browser port of interactive subset in widget.

Acceptance

• ShowPtycho.export_html and/or export_sidecar documented next to Show3D/Show4DSTEM
• Kernel-less Chrome open shows real phase/FFT (not blank); scrub works
• Multi-GB path uses folder + Range fetch (not multi-GB single ArrayBuffer)
• No silent display_bin / downsample unless user opts in and it is announced
• Phase B optional: WebGPU adapter confirmed real hardware before claiming live drag offline

Refs

• Show3D sidecar skill/docs: export_sidecar, offline_stack.u8, Range server
• Show4DSTEM offline WebGPU HTML
• Second-brain: ShowPtycho offline + 5D defocus notebook play

[bobleesj]

Design notes (Bob, 2026-07-14) — kernel strategy + scale

Main goal: people can load and play offline (no Python kernel). Revolutionary path = browser WebGPU SSB/aberration scrub, not a full 40-frame production reconstructor.

Do not load the full experiment

• Avoid shipping / uploading entire 40-extent 5D cubes into the browser.
• Play path targets ROI / teaching sizes: start 128×128 scan, then 256×256.
• Detector side: prefer BF-disk / subsampled pixels for drag (same idea as live ShowPtycho BF-pixel path); full detector only if it still fits and stays interactive.
• Time: scrub one frame at a time (or a tiny T window), not all 40 frames resident in VRAM unless the cube is already small.

Kernel strategy (WGSL, lives in widget)

Prefer two paths, not one mega-kernel:

1. Preview (drag) — lightweight WGSL: subsampled BF pixels → phase/FFT at interactive FPS while moving C10 / defocus / etc.
2. Commit (mouseup / Apply) — fuller SSB pass on the loaded ROI; still 128²/256², not full-FOV 512²×192² unless user opts in later.

Stages can start as separate clear WGSL compute passes (mask → FFT → sideband → iFFT → products) for parity/debug with Python/MPS; fuse only after numbers match and FPS needs it.

Parity target: same math family as quantem.gpu / MPS SSB preview+fit — browser is a third runtime, not a second algorithm. Python stays source of truth for validation; WGSL must pass lattice/products checks on the same small ROI fixtures.

Export package shape (Phase A → B)

• Phase A: bake products for the play ROI into HTML/sidecar so anyone can scrub immediately.
• Phase B: include enough raw/ROI 4D (or BF-indexed) data for WebGPU recompute on that ROI only.
• Optional later: multi-frame series as per-frame on demand (Range-fetch one T) rather than one giant stack.

Non-goals (for v1)

• Full 40×512×512×192×192 in-browser
• Replacing Mac MPS Python path (that stays for real notebooks / large data)
• Silent binning to “make it fit” without labeling the export

MPS remains the serious local-Python path; WebGPU offline is the share + play surface that does not need a kernel.

[bobleesj]

Samsung 128×128 BF-r30 WebGPU parity fixture is generated and verified in real Chrome on mjgoat.

I am redacting private/local raw-data paths and filenames from the public issue. The fixture is available locally on mjgoat in the agreed report directory.

Reference/data details:

• Data: fixed local Samsung 128×128 crop fixture
• BF radius: 30 px; selected 2829 BF pixels
• Exported browser input: BF-indexed G(k) only, shape (2829, 128, 128), complex64
• Locked cal: C10=50.0 nm, C12=22.0 nm, phi12=1.3264502315156905 rad, rotation 73.363725327771 deg
• Python reference: CUDA SSBEngine.reconstruct_with_loss
• Browser path: WGSL gamma/CTF on G(k) → 128×128 inverse FFT rows/cols → mean BF phase/variance → WGSL phase FFT display
• Chrome adapter: nvidia blackwell; softwareAdapter=false

Parity:

Check	max abs err	mean abs err	max rel err	mean rel err	Status
phase	1.4156103e-7	2.2424567e-8	8.0417147e-3	6.0928105e-6	pass
FFT log-mag	4.7087669e-6	4.6474449e-7	4.4862153e-4	1.8113767e-6	pass
loss	2.3703251e-8 abs diff	n/a	n/a	n/a	pass

Timing from the verified run:

• Cold page reload to parity complete, including local sidecar fetch/upload: 1.42 s
• Chrome WebGPU SSB compute after data upload: 0.128 s
• Chrome WebGPU display FFT: 2.90 ms
• Warm slider recompute: about 3.4–5.7 ms SSB + 2.4–6.3 ms FFT, with ~165–171 ms UI debounce wall time

Note: the fixture intentionally does not include raw 4D DPs or full-detector G(k).