Backends

The canonical source-tree and cross-language test organization is documented in Backend layout and parity contract. Backend implementations remain private behind one domain-level scientific API; folder moves require the machine-readable parity gates in tests/parity/backend_matrix.json.

quantem.gpu supports three backend names:

Backend	Purpose	Notes
cuda	NVIDIA GPU IO, decompression, reductions, and SSB reference paths	Uses CuPy/CUDA kernels where available.
mps	Apple Silicon Metal/MLX paths	Used for ANS-encoded loading, BF/DF/DPC images, and SSB fit/reconstruction/preview paths.
cpu	Test/reference implementation	Available only when explicitly requested by a test or reference comparison.

Check the selected backend:

import quantem.gpu as qgpu

backend = qgpu.device.detect()
print(backend)

Request a backend explicitly when you need honest failure:

qgpu.device.resolve("cuda")  # raises if CUDA is unavailable
qgpu.device.resolve("mps")   # raises if MPS is unavailable

Use backend="auto" for normal scripts and backend="cuda" or backend="mps" in parity/performance tests.

WebGPU is a browser runtime, not a Python device backend. Reusable browser compute sources live beside their scientific domains and are packaged for browser clients. SSB-specific WebGPU implementation files live under ssb/webgpu. Browser performance claims must log a real adapter; SwiftShader or another software adapter is only a smoke test.

CUDA service placement can select several devices for independent resident datasets. Their VRAM is not combined to make one dataset fit. WebGPU does not expose CUDA-style multi-GPU placement; the browser selects one adapter for a page.

Backend coverage

CUDA and MPS are the native production backends. CPU is test/reference only and is never selected as a silent scientific fallback.

Status terms: Done means implemented with real-data parity and performance evidence; Partial means source exists but the full signoff matrix is not complete; Gap means the backend does not implement that capability yet.

Capability	CUDA	MPS	WebGPU	CPU	Notes
Device report and explicit selection	Done	Done	NA	Done	WebGPU adapter selection is browser-side.
HDF5 metadata, readiness, discovery	Done	Done	Done	Done	Keep one shared API for all clients.
Full HDF5 bitshuffle/LZ4 load/decompress	Done	Done	Done	Reference	CUDA and MPS load complete acquisitions into ANS-encoded residents that keep native counts. CUDA and WebGPU retain native uint8/uint16 source paths. Python MPS has signed-off native uint16/uint32 source decode; native-uint8 bitshuffle-source decode remains unqualified. WebGPU strict full-stack no-bin 1024x1024x192x192 browse is rejected as a memory-policy path; use product-first, crop, or explicit bin.
Scan-region selection	Done	Done	Done	Reference	CUDA and MPS load the complete acquisition and return a rectangle with read(scan_region=..., detector_region=...) from the encoded resident; io.load(..., dtype="scaled_uint16", scan_region=...) bounds precision storage. WebGPU uses frame-window slicing before upload/decode.
Exact detector bin	Done	NA	Done	Reference	io.load keeps the native detector. CUDA detector and scan bins are exact integer views of one encoded resident in the browse service (quantem.gpu.remote.plan.BrowsePlan); Python MPS has no requested detector bin. WebGPU has explicit count-preserving detBin source support; full 512x512x192x192 detBin=2/4/8 headed parity is exact on a real NVIDIA WebGPU adapter, including native non-low8 uint16 detBin=2.
BF/DF/ADF resident kernels	Done	Done	Done	Reference	CUDA RawKernel, MPS Metal, and WebGPU WGSL selected reducers are implemented for uint8/uint16/uint32 resident data.
Dense DF/ADF strategy	Done	Done	Done	Reference	Dense masks use cached total - complement where cheaper.
CoM/DPC resident kernels	Done	Partial	Done	Reference	Detector-bin-4 CUDA/MPS CoM passes the frozen gate. The public MPS native-detector interaction sidecar is detector-bin-2 and is not full-resolution parity. WebGPU row/col DPC has full no-bin headed signoff on real hardware.
Cached detector/DPC products	Done	Done	Product-first Done / cache-read Done	Cache-read Done	CUDA and MPS build the product cache from one encoded load, including exact uint64 total/ABF/ADF maps; a cache written without those fields reports them as unavailable. WebGPU owns browser selected-block product caches and can read prepared cache products.
iDPC	Done	Partial	Done	Reference	Current CUDA/MPS detector-bin-4 iDPC exceeds the frozen 1e-5 cross-backend gate; native-detector MPS sidecar iDPC is also blocked. WebGPU fixed-rotation iDPC uses paired DPC buffers and a dual-real FFT with an explicit float32 tolerance.
Ptychographic SSB preview	Done	Done	Partial	Reference	Python MPS and the separate native MetalSSBKernels product have parity-qualified implementations; WebGPU source lives under ssb/webgpu, but its full browser matrix is not complete.
Ptychographic SSB fit/reconstruction	Done	Done	Partial	Not target	Python MPS supports its current parity shapes. Native Swift/Metal supports exact 512×512 reconstruction, phase-variance loss, and deterministic 200-trial TPE plus Nelder–Mead fitting; other native scan sizes remain gaps.
Native Browser FFT (MetalImageFFT.logMagnitude)	NA	Done	NA	Reference	Native Swift/Metal product for already-transferred 2D BF/ADF/custom images. 512×512 must stay inside 120 Hz when warm. Not a Python MPS path.
GIF/MP4 movie rendering	Done	Done	NA	Fallback	CUDA/NVENC and Metal/VideoToolbox paths live here; presentation controls remain client-owned.
Browser source ownership	Done	Done	Done	NA	Reusable TypeScript/WGSL source lives beside each scientific domain.

The rule for new heavy work is: implement the compute or IO path in quantem.gpu, then let clients call the shared contract.

Benchmark ownership

This page owns capability and source-boundary status only. Numerical results are not copied here:

• Implementation overview is the current human-facing speed, memory, feature, and parity dashboard.

• Verified benchmark results is the authoritative provenance ledger.

• Optimization ledger preserves accepted and rejected experiments.

Keeping the backend map timing-free prevents a prepared-index reopen, resident kernel, historical campaign, or application first product from drifting into a misleading source-load comparison.

Adding a backend kernel

For agents and maintainers, a new optimized path is not complete until the source, tests, documentation, and measured evidence land together.

Kernel family	CUDA source	MPS source	WebGPU source	Required gate
HDF5 bitshuffle/LZ4 decode	quantem.gpu.io.hdf5.cuda	quantem.gpu.io.hdf5.mps	io/hdf5/webgpu	Corrected-frame checksum parity and load-stage timing.
BF/DF/ADF masked sums	quantem.gpu.detector.cuda / detector	quantem.gpu.resident.mps	detector/webgpu / local-h5.ts	Exact integer product parity and first/warm interaction timing.
CoM/DPC	quantem.gpu.detector.cuda	quantem.gpu.resident.mps	dpc/webgpu	Row/col CoM and centered DPC parity within 1e-5.
Display colormap/histogram/log/FFT	None; CPU reference quantem.gpu.display.cpu	MetalDisplayKernels	quantem.gpu.display.webgpu	Exact uint8 RGBA and 256-bin counts for linear/signed-log float32 fixtures; FFT agreement within the stated float precision.
SSB object, phase, loss	quantem.gpu.ssb.cuda	quantem.gpu.ssb.mps; native MetalSSBKernels	ssb/webgpu	Same complete BF disk, aberrations, float32/complex64 parity, and interactive redraw timing.
Movie rendering	quantem.gpu.movie.cuda	quantem.gpu.movie.mps	NA	Frame parity and encoded movie smoke tests.