# Virtual-Image Kernel Checklist

Target: BF/DF/ADF, CoM/DPC, and arbitrary detector ROI dragging should use a
custom GPU kernel on every production backend. Do not use detector binning,
scan cropping, or CPU fallback as evidence for this checklist unless the row
says so.

## Why This Matters

The future large browse target is `1024x1024x192x192 uint8`, which is 36.0 GiB
resident. Old CuPy/Torch gather paths allocate large transient selected-pixel
slabs during every drag. A BF disk at radius 30 reads about 2,828 detector
pixels per scan position; a dense DF mask can touch most of the 36,864 detector
pixels. That is why the standard must be one custom kernel per product over
resident data, plus a dense-mask strategy such as `total - complement`.

## Expected kernel paths

The CUDA `1024x1024x192x192 uint8` target uses:

| Product | Expected path |
|---|---|
| BF | `cuda_rawkernel_selected` |
| ADF | `cuda_rawkernel_selected` |
| DF | `cuda_rawkernel_total_minus_complement` |
| CoM/DPC | `cuda_rawkernel_com` |

The MPS `1024x1024x192x192 uint8` target uses the same formulation:

| Product | Expected path |
|---|---|
| BF | `mps_metal_selected` |
| ADF | `mps_metal_selected` |
| DF | `mps_metal_total_minus_complement` |
| CoM/DPC | `mps_metal_com` |

The Show4DSTEM WebGPU browser runtime is widget-bundled, but the reusable
source now belongs beside its scientific domain. The parity/performance standard is
the same:

| Product | Expected path |
|---|---|
| BF | `webgpu_wgsl_masked_sum_buffer` |
| ADF | `webgpu_wgsl_masked_sum_buffer` |
| DF | `webgpu_wgsl_masked_sum_buffer` plus dense-mask cache if needed |
| CoM/DPC | `webgpu_wgsl_masked_dpc_buffer` / `webgpu_wgsl_masked_com_buffer` |
| iDPC | `webgpu_wgsl_masked_idpc_buffer` with paired DPC buffers and dual-real FFT |

## Backend Checklist

| Backend path | Current status | Required tests | Performance gate |
|---|---|---|---|
| Show4DSTEM Python CUDA, resident CuPy | Implemented in `CudaKernelCompute`; widget must preserve the CuPy source for compute while keeping Torch for existing display code. Uses warp-shuffle selected reducers, a custom total-count reducer, fused dense `total - complement`, a fused CoM/DPC reducer, a cached full-detector CoM field, and a small per-viewer detector-index cache. | Exact parity vs old CuPy selected-pixel sum for BF/ADF/DF and old CuPy CoM for DPC; widget smoke must report `CudaKernelCompute`; compare-grid path must use the CUDA backend. | 512x512x192x192 uint16 no-bin BF/ADF/DF/DPC faster than old widget path; 1024x1024x192x192 uint8 shape probe must pass before real-data allocation tests. |
| Public `quantem.gpu.detector` CUDA helpers | Implemented through `CudaKernelCompute.masked_sum` for CuPy arrays; encoded acquisitions use `StreamedSeriesCompute` in `detector/cuda/streamed_series.py`. | Exact parity for `masked_sum`, `virtual`, BF/ADF/DF helper outputs. | Same or faster than old CuPy gather path, with lower transient memory. |
| Show4DSTEM MPS chunk-backed data | Implemented for uint8/uint16 through `MetalVirtualImage`; dense DF uses cached `total - complement`; CoM/DPC uses raw Metal `com_u8`/`com_u16`; no Torch-MPS giant tensor for full no-bin browse loads. | Mac runtime parity vs NumPy/reference on BF/ADF/DF and CoM/DPC; widget smoke must report `MetalRawBackend`; no silent CPU fallback. | 512 no-bin interaction should use the Metal path or fast sidecar; 1024 uint8 requires an explicit memory policy before real allocation. |
| Show4DSTEM WebGPU browser | Implemented in canonical domain-owned WebGPU sources. BF/DF/ADF uses `maskedSumBuffer`; DPC row/col uses WGSL CoM, global mean reduction, one-ULP mean-side correction, and centered component output through `maskedDpcBuffer`; iDPC uses paired DPC buffers plus a dual-real FFT. Readback wrappers remain for widget model compatibility and parity tests. | Source contract test plus headed Chrome test with a real adapter, not SwiftShader; BF/ADF/DF, CoM, DPC, and iDPC parity against NumPy/Python reference. | Drag path should keep VI, DPC, and iDPC GPU-resident where the display pipeline can accept GPU buffers; widget model-byte shims remain for current anywidget compatibility. |
| Multi-tilt/series compare grid | CUDA path tested for seven 512 panels at detector bin 2; full no-bin panels are one-at-a-time unless sharded. | Compare-grid BF/ADF/DF parity and timing for 7 panels; verify per-panel backend path. | Refresh all visible panels without falling back to per-panel Torch gather. |

## Done For This Branch

- CUDA RawKernel selected-pixel reducer for resident CuPy `uint8` and `uint16`.
- CUDA selected reducers use warp shuffle instead of repeated block-wide shared
  reductions.
- CUDA dense DF uses cached integer `total - complement` and fuses complement
  reduction, subtraction, and final float32 output in one kernel.
- CUDA total-count maps use a custom row reducer instead of CuPy's generic
  `sum(axis=1)` path.
- CUDA DPC/CoM uses a fused raw kernel that accumulates total intensity,
  detector-row moment, and detector-column moment in one pass over each
  diffraction pattern. The full-detector CoM field is cached per backend, so
  repeated DPC/iDPC requests do not reread the resident 4D block.
- Shape-only support check covers `1024x1024x192x192 uint8` for CUDA and MPS.
- MPS Metal `uint8` masked-sum, detector-sum, mean-DP, bin-sidecar,
  radial-cache, and CoM kernels are present.
- MPS dense dark-field masks use the cached `total - complement` path, matching
  the CUDA dense-mask strategy.
- WebGPU source ownership is split across the relevant scientific domains, with the
  Show4DSTEM engine and ShowPtycho SSB engine copied as canonical source
  package data. Widget build/export syncs these sources before bundling.
  BF/DF/ADF has a GPU-resident buffer path; DPC row/col now uses a WGSL CoM
  reducer, WGSL mean reducer, one-ULP mean-side correction, and WGSL
  centered-component pass. Browser iDPC uses paired DPC buffers and a dual-real
  FFT before the Poisson integration.
- Local full 512x512x192x192 no-bin WebGPU DPC/iDPC browser signoff on a real
  NVIDIA Blackwell adapter:
  - corrected-frame load parity: passed
  - DPC row/col max abs error: `7.63e-6`
  - iDPC mean abs error: `4.70e-6`; max abs error: `3.05e-5` from float32 FFT order
  - DPC row/DPC col/iDPC display medians: `14.9/13.2/13.2 ms`
  - DPC row/col/iDPC recompute medians: `13.7/19.3/22.7 ms`
  - idle RAF: `60 FPS`
  - local-file timing reruns use `--require-local-profile` so the browser URL
    fallback cannot be recorded as a local-file benchmark
- Local full 512x512x192x192 and true crop-256 WebGPU detector-bin local-H5
  signoff on a real NVIDIA Blackwell adapter:
  - `detBin=2/4/8` corrected-frame checksums: exact against the
    zero-bad-before-bin reference
  - full-load low8 page profiles: `1.199/1.212/1.106 s`
  - crop-256 20-repeat medians: `0.774/0.755/0.733 s`
  - crop-256 p95: `0.798/0.813/0.775 s`
  - native non-low8 `uint16` `detBin=2`: exact at `2.651 s`
- Local true 1024x1024x192x192 WebGPU product-first selected-block BF
  signoff on a real NVIDIA Blackwell adapter:
  - BF radius: `30`
  - selected compressed payload: `6.88 GB`
  - output image: `4.19 MB`
  - 4-run median wall/profile/product: `4.92/4.85/1.56 s`
  - max/mean absolute error: `0/0` against an independent Python reference
  - this is product-first BF evidence, not full-stack no-bin browse/load
- Local true 1024x1024x192x192 WebGPU full-stack no-bin browser browse was
  driven with the shape-explicit local-H5 harness and rejected as a memory-policy
  path:
  - no crop, no detector bin, count-audited `uint8` browse decode
  - 105 HDF5 data files plus 105 metadata-only block-index sidecars
  - selected corrected-frame CUDA checksums were prepared for first/middle/last
    frames
  - GPU memory reached about `97.2 GB` of a `97.9 GB` budget
  - browser failed before publishing a load profile/checksum readback with an
    invalid WebGPU buffer after a previous device/buffer error
  - do not mark strict full-stack browser browse as signed off for true 1024;
    use product-first, true scan crop, or explicit detector bin instead
- Local real-data WebGPU browser stress on a 128x128 scan, 96x96 detector,
  uint8 sidecar, real NVIDIA Vulkan adapter:
  - mount/decode to interactive: `1.94 s`
  - BF warm recompute: `2.7-3.7 ms`
  - DPC row warm recompute floor: `6.4-8.7 ms` with browser scheduling outliers
  - DPC col warm recompute floor: `8.3-9.7 ms` with browser scheduling outliers
  - idle RAF: `60.0 FPS`
- Exact focused parity tests for CUDA selected and dense-mask paths.
- Local full 512x512x192x192 real-data benchmark:
  - BF median `4.96 ms -> 1.35 ms`
  - ADF median `16.16 ms -> 3.86 ms`
  - DF median `62.64 ms -> 1.84 ms`
  - max absolute error `0` for every row.
- Local seven-tilt detector-bin2 real-data benchmark:
  - BF median `1.50 ms -> 0.54 ms`
  - ADF median `3.83 ms -> 1.35 ms`
  - DF median `15.88 ms -> 0.53 ms`
  - max absolute error `0` for every row.
- Local seven-tilt Show4DSTEM compare-grid method benchmark after widget
  backend reuse:
  - BF full grid `3.97 ms` (`0.57 ms/panel`)
  - ADF full grid `9.56 ms` (`1.37 ms/panel`)
  - DF full grid `4.00 ms` (`0.57 ms/panel`)
  - max absolute error `0` after the widget's detector-area normalization.
- Local DPC/CoM real-data benchmark:
  - full 512x512x192x192 uint16: `200.42 ms -> 12.39 ms`, max absolute error `0`
  - seven detector-bin2 panels: old summed median `373.14 ms`; uncached CUDA
    summed median `24.06 ms`; first backend-filled grid `24.63 ms`; cached
    repeat path returns the stored CoM arrays without launching a GPU kernel.

## Failed Hypotheses

- Replacing the full-detector CoM loop's per-pixel detector-coordinate division
  with incremental row/column bookkeeping was exact but slower: the seven-panel
  DPC grid regressed from about `27.3 ms` to about `34.5 ms`. Keep the simpler
  division form unless a profiler points elsewhere.

## Next Checklist

- Run Mac MPS `uint8` runtime parity/performance on full no-bin data.
- Run Mac MPS CoM/DPC runtime parity/performance on full no-bin data and record
  the first-click vs cached-repeat timing.
- Add a headed WebGPU test that records the real adapter and verifies BF/ADF/DF
  parity plus `maskedSumBuffer` drag behavior.
- Keep WebGPU CoM/DPC/iDPC headed parity/performance tests in the release gate,
  including the FFT command-batching path that keeps iDPC median redraw under
  the 30 FPS budget.
- Remove any remaining widget-local permanent backend copies after each synced
  domain-owned WebGPU source is covered by build and browser parity tests.
- Treat real WebGPU `1024x1024x192x192` full-stack no-bin browse/load as
  explicitly rejected unless a future browser/device path avoids materializing
  the whole decoded stack. Product-first BF for true 1024 is already signed off.