SSB aberration units (nm) and the thick-sample (tilt + thickness) model - 2026-09-24

SSB aberration units (nm) and the thick-sample (tilt + thickness) model - 2026-09-24#

1. C10 / C12 were Angstrom under an nm label#

Question. The API, docs and ShowPtycho label SSB C10 / C12 in nm. Are they?

Setup. abTEM 4D-STEM of a thin crystal (one BaTiO3 unit cell, 4 A, so thickness cannot move the apparent focus), 300 kV, 30 mrad, 64 x 64 scan at 0.25 A, probe defocus set explicitly (abTEM C10 = -defocus). SSB.find_aberrations(trials=200, refinement="nelder-mead"). Script: study folder c10_unit_test.py (same setup as tests/hardware/cuda/test_ssb_units.py).

abTEM defocus

true C10

fit before

fit after

+100 A

-10.0 nm

-100.26 “nm”

-10.03 nm

-150 A

+15.0 nm

+150.25 “nm”

+15.03 nm

Cause. Every backend evaluates chi = (pi / lambda[A]) alpha^2 (C10 + C12 cos 2(phi - phi12)) (CUDA engine._factor, MPS engine.py factor, WebGPU makeParams f[12], Swift MetalSSBKernels) with no conversion, so the numbers are Angstrom. The 14-coefficient magnitudes follow the same convention. Sign convention matches abTEM.

Fix. The public SSB session (ssb/workflow.py) converts at its boundary: nm in -> x10 to the engine; results, trial histories and fit_sample outputs /10 back to nm (_ENGINE_PER_NM, ABERRATION_UNIT = "nm"). Kernels, backend-level parity tests and fixtures keep Angstrom unchanged. _persistence.SCHEMA = 2 (schema-1 saved results are not reused). Live fit records written by _write_series_fit_metadata carry "aberration_unit": "nm"; records without it are read /10. ShowPtycho (quantem.widget) and quantem.live normalise the same way; the browser WebGPU engine is called through an nm->A helper in ShowPtycho. Not fixed: the native Swift app (c10Nanometers is Angstrom); quantem.live reads its artifacts /10.

Consequence found. The quantem.live dashboard multiplied SSB “nm” by 10 to seed ptychography defocus (LaunchPtychoDialog.tsx:66, PtychoLauncherDialog.tsx:262, trial_launch.py:109), so SSB-seeded launches used 10x the defocus. With true nm the x10 is correct.

Test: tests/hardware/cuda/test_ssb_units.py.

2. Thick-sample SSB: sample tilt and thickness#

Model. Slice at depth z (from mid-depth) sees defocus C10 + z and sits shifted by z theta. Averaging each SSB term over the depth gives real weights: gamma = w1 t1 - w2 t2, t1 = P(q-k) conj P(k), t2 = conj P(q+k) P(k), w = sinc(rate t / 2), rate1 = -factor(alpha_m^2 - alpha_k^2) - 2 pi q.theta, rate2 = +factor(alpha_p^2 - alpha_k^2) - 2 pi q.theta. Thickness 0 -> weights 1 -> standard SSB exactly.

Objective. The phase-variance loss used by fit does not see tilt (sim tilted (3,-4) -> (5.5, 0.4); untilted -> (-2.7, -4.3)): it applies a phase-only correction. The least-squares fit of G = Psi gamma, sum over q in 0.2-0.9 /A of |sum_k G conj(gamma)|^2 / sum_k |gamma|^2 (SSBEngine.thick_fit), does. Search: multivariate TPE over C10, C12, phi12, tilt, thickness jointly (C10 must move to the mid-depth focus; tilt-only from the standard optimum stops at (8.6, -6.3)), then Nelder-Mead.

data

truth

CUDA

MPS (Apple M5)

sim BaTiO3 15.2 nm tilted

(3, -4) mrad

(3.0, -4.1)

(3.12, -4.19)

sim untilted control

(0, 0)

(-0.3, -0.1)

(0.002, 0.000)

logic device (Si), clean-crystal corner, 128 x 128

ptycho (-11.6, +2.8) object frame (256 crop)

(-10.3, +4.7) scan = (-10.9, +3.1) object frame: 2.4 deg, 5 %

-

BaTiO3/SrTiO3 film ~15 nm, 128 crop

ptycho ~5 mrad

no stable optimum (grid edge)

-

Thickness is a model depth spread, not a measurement (15.2 nm sim -> 10-13 nm).

Frame. SSB tilt is in the scan frame; quantem.thick’s object frame is the scan rotated by the same rotation_deg (p_obj = M p_scan, no sign change, transpose only if the reconstruction transposed). Details: study notes (frame check).

Detector orientation matters. On the logic device the standard fit barely separates the axis-swapped detector orientation (fit 37.4 vs 35.7); the tilt model on the wrong orientation gives a ridge and streaked images. Choose orientation with the thick fit (or trust the calibrated rotation).

Performance. CUDA 128 crop (8889 BF): thick preview 29-61 ms, fit_sample 30-55 s (1500 trials). MPS M5: preview ~20 ms after 1 s compile, fit ~65 s.

API. SSB.find_aberrations(tilt=True) (result .tilt_mrad (row, col), .depth_spread_nm, .tilt_fit_gain, .report()), SSB.preview(aberrations, tilt_mrad=(row, col), depth_spread_nm=d), SSB.supports_tilt. CUDA and MPS backends. WebGPU (reconstruct(..., {sample: {tiltRowMrad, tiltColMrad, thickness}}), a separate thick shader so the thin path is bit-identical) drives ShowPtycho exports: logic crop in Mac Chrome (Metal) loss 0.170941 vs CUDA 0.170950, phase correlation 0.99999997; fitting stays in Python. Tests: tests/hardware/cuda/test_ssb_thick_sample.py, tests/hardware/mps/test_ssb_thick_sample_mps.py, tests/webgpu/ssb-thick-sample.ts (+ run_ssb_thick_sample.py, weights vs CUDA: max rel 5e-4, median 1.5e-7).

3. cuFFT import order#

ImportError: libcufft.so.11 in every notebook that imports quantem.widget (torch) before SSB: torch (conda CUDA 13) loads its cuFFT first and cuda.pathfinder then skips CuPy’s CUDA 12 wheel library. quantem.gpu._cuda_libraries.preload() at package import dlopens the nvidia-*-cu12 wheel libraries by path (different sonames, both coexist). Test in test_ssb_thick_sample.py::test_cupy_fft_loads_after_torch_cufft.

4. Speed: standard vs thick-sample, CUDA vs MPS (measured 2026-09-24)#

Setup. bench_ssb_tilt.py (study folder): SSB on uint16 counts, 192 x 192 detector, 300 kV, 30 mrad. Preview = median of 30 SSB.preview calls returning the loss (a float, so the device is synchronised); drag = the same through preview_context(num_bf // 4). Fit = SSB.find_aberrations(trials=200, refinement="nelder-mead"); tilt fit = the thick-sample search (then fit_sample: 200-trial standard baseline + 300 joint trials + 3-start Nelder-Mead, all on the least-squares objective). CUDA: RTX PRO 6000 Blackwell, idle GPU. MPS: M5 (128 GB). Same committed source on both. Samples: logic device (Si) and BaTiO3/SrTiO3 film.

scan

sample

backend

preview std / thick (ms)

drag std / thick (ms)

fit std / thick (s)

tilt (mrad, scan frame)

128^2

logic

CUDA

16.4 / 26.2

1.8 / 3.0

1.9 / 3.3

(-10.25, +4.68)

128^2

logic

MPS

8.8 / 11.4

3.0 / 3.4

2.9 / 5.8

(-10.26, +4.68)

128^2

film

CUDA

16.3 / 26.2

4.1 / 7.7

3.5 / 1.2

(-0.66, -5.35)

128^2

film

MPS

9.0 / 11.3

2.7 / 3.2

2.7 / 2.4

(-0.65, -5.34)

256^2

logic

CUDA

16.5 / 97.9

9.0 / 29.4

9.5 / 3.9

(-9.79, +4.80)

256^2

logic

MPS

36.4 / 48.1

9.6 / 12.5

13.3 / 23.4

(-9.79, +4.80)

256^2

film

CUDA

21.1 / 52.4

4.2 / 12.9

5.3 / 2.5

(-0.45, -5.40)

256^2

film

MPS

40.6 / 93.1

23.7 / 32.6

19.5 / 9.0

(-0.45, -5.39)

512^2

logic

CUDA

26.7 / 393.9

44.3 / 113.6

10.8 / 22.3

(-9.14, +4.03)

512^2

logic

MPS

128.1 / 2793

33.0 / 713.9

59.2 / 93.5

(-9.13, +4.04)

512^2

film

CUDA

60.7 / 242.8

44.4 / 118.7

13.8 / 7.4

(-0.09, -5.08)

512^2

film

MPS

173.0 / 2861

47.1 / 704.8

52.3 / 24.0

(-0.10, -5.06)

Conclusions.

  • The fit is not the bottleneck: full-field tilt fit 7-22 s on CUDA, 24-94 s on MPS; CUDA and MPS agree to 0.02 mrad.

  • The thick preview is. CUDA’s reconstruct_thick is a chunked element-wise kernel + cuFFT, outside the fused standard kernels: 1.6x the standard preview at 128^2, 15x at 512^2 (394 ms: the ShowPtycho tilt slider is not interactive at full field).

  • MPS fuses the depth weights into the row-IFFT kernel, but that kernel exists only for 128/256/1024 scans (backends/mps/_thick_sample.py:39, engine.py:1587); 512^2, the common full scan, falls back to the MLX reference graph (2.8 s, 22x standard).

  • CUDA drag (25 % BF) is slower than the full preview at 512^2 (44 vs 27 ms): the drag path does not scale with the subset.

  • Crop-to-full tilt is stable on both samples (logic -10.3/-9.8/-9.1 row; film about 5 mrad along -col).

Fix candidates. CUDA: fold w1/w2 into the fused standard kernel (the MPS approach). MPS: add a 512 row-IFFT specialisation. Both before claiming a real-time full-field tilt slider.

5. Fit strategy, trial count, rotation (full 512 x 512 field, CUDA, 2026-09-24)#

Scripts fit_strategies.py, trials_rotation.py (study folder). All candidates scored on the same least-squares objective; “fit” is relative to the best value found on that acquisition. Seeds 0-2 (strategies), 0-4 (trials).

strategy

logic device

film

time

standard SSB (no tilt)

0.55

0.78

8-9 s

standard fit, then tilt + thickness only

0.91, every seed

0.99, every seed

10-11 s

same, then Nelder-Mead over all six

1.00 (2 of 3 seeds exact)

1.00

11-16 s

joint TPE 200 + Nelder-Mead

1.00

1.00

4-15 s

standard baseline 200 + joint 300 + Nelder-Mead (then default)

1.00

1.00

3-14 s

centre 128 crop search + full-field Nelder-Mead

1.00

0.9993 (row tilt -0.7)

2-6 s

Sequential fitting stalls because C10 must move with the tilt (logic device 15.3 -> 4.0 nm mid-depth defocus).

joint trials

film: seeds at best / tilt spread

logic: seeds at best

50

3 / 5, up to 1 mrad off

5 / 5 (one at 0.9988)

100

5 / 5

4 / 5 (one at 0.9993)

200

5 / 5, +-0.02 mrad

5 / 5

300, 400

5 / 5, same answer

5 / 5

Time does not depend on trials (Nelder-Mead dominates). Decision: fit(tilt=True) = one joint search of trials (default 200, the same budget as the standard fit) + 3-start Nelder-Mead; fit_sample() removed.

Rotation (joint fit at calibrated +- 6 deg): both acquisitions peak at +1 deg (logic fit +0.3 %, film +1.1 %); the tilt moves by < 0.25 mrad; +-4 deg costs 4-10 %. Rotation is well determined but left fixed at the calibration: it is a per-instrument calibration shared by every acquisition, and freeing it trades off against the tilt direction. The consistent +1 deg on two datasets is a lead for the rotation calibration itself.

6. SSB.open keeps the acquisition ANS encoded#

SSB.open asked io.load for representation="dense", which the GPU loader now refuses (“GPU acquisitions must remain ANS encoded”). It now loads encoded (film, 512 x 512 x 192 x 192: 2.2 GB resident, 3.0 s), finds the bright-field disk on the full-detector mean pattern (0.34 s) with the backend’s own rule, decodes only that detector crop (112 x 112, 0.22 s) and pins the disk centre (bf_center, detector pixels) so the crop selects the same pixels. Session memory 9.6 GB instead of decoding the 19 GB cube first. Against direct SSB(...) construction on the fully decoded cube: same 8939 BF pixels, max |phase difference| 6e-8 rad, identical loss (tests/hardware/cuda/test_ssb_open_encoded.py).

Also: at the full BF count, the drag-preview context no longer copies G and a result buffer (2 x BF x scan complex64, 37 GB at 512 x 512); CUDA and MPS reuse the session.

Rejected / open#

  • Rescaling _factor x10 inside the kernels: would change every backend-level fixture and Optuna trajectory; the boundary conversion keeps them.

  • Lattice-SNR score (peak / median background): gamed by noise-free data and by weight normalisation; replaced by the least-squares fit.

  • BaTiO3/SrTiO3 film: tilt not recovered - candidates scan distortion (2.4 %, 1.3 deg), scale mismatch (~3 %), diffuse background.

  • Pre-existing, unrelated: detector/workflow.py:560-565 sums float data with uint64 (float inputs lose their BF disk on MPS); test_cuda_packed_ssb fails on the io representation policy.