Document when TransformerDFT beats TransformerNUFFT

[Jammy2211]

Summary

The transformer-choice block in scripts/interferometer/start_here.py told readers TransformerNUFFT was "Recommended for any dataset size". Measurement says otherwise below a crossover, so this replaces the claim with the actual rule.

Companion to PyAutoLabs/PyAutoArray#479, which adds the same guidance library-side.

What the guidance now says

The DFT setup costs O(N_vis × N_pix) against the NUFFT's O((N_vis + N_pix) log N) plus a fixed ~2 s overhead — so the product decides which is faster, not the visibility count. Measured on CPU, the crossover sits near N_vis × N_pix ≈ 1e7: the DFT runs at 0.2–0.7× the NUFFT time below it, and the NUFFT is 1.2–1.9× faster above.

At a typical 64×64 mask that's ~5,000 visibilities — but on a 32×32 mask the DFT still wins at 4,000. A visibility-count-only rule would be wrong on half the grids, which is why the prose leads with the product.

Past ~1e8 it stops being a speed question: the DFT's allocation grows with the same product and reaches ~109 GB at a million visibilities, where the NUFFT allocates nothing measurable beyond its working buffers.

Two other things the old wording left out

• Both transformers work with apply_sparse_operator, agreeing to ~3e-13. The old text implied the DFT was the one for that workflow.
• The existing 10,000-visibility DatasetException is now mentioned, with its raise_error_dft_visibilities_limit=False opt-out. A reader who hit that error previously had nothing in the tutorial pointing at it or explaining why it exists.

Scripts Changed

• scripts/interferometer/start_here.py

notebooks/ and markdown/ carry the same prose and are regenerated from scripts/ at release time; the equivalent edits are applied here directly so they are not stale in the interim. Notebook JSON was edited in place rather than round-tripped, so the diff stays surgical.

Test Plan

• Prose changes only — no executable code paths touched
• All 355 notebooks still parse as valid JSON
• No "Recommended for any dataset size" claim remains anywhere in the repo

---

Generated by Claude Code