feat: 0.3.0 Wave 0 + Wave 1 — synthetic data, requires_package gate, batched GPU fitting

[CSSFrancis]

First code for the 0.3.0 tracker. Three reviewable commits.

Closes #51, #52, #53. Framework half of #49. Unblocks Waves 2-4 with data.

139 new tests, all green. Full suite: 1760 passed, 2 skipped, 1 xfailed — no regressions.

---

1. Synthetic EELS / EDS / EBSD data (spyde/data/)

Waves 1-4 need something loadable per modality before the real datasets land (#80) — and known ground truth beats a golden file, which quietly encodes yesterday's bug.

• eels_si — power law + C/N/O K edges at real onsets
• eds_si — Fe/Ni/Cu K families at real energies, Fe-Kβ/Ni-Kα overlapping on purpose so family-aware fitting ([2.2] Composition → auto-populated components #62) is exercised, not assumed
• ebsd_patterns — real gnomonic Kikuchi geometry, two-grain orientation field, exact Euler angles stamped on the signal so [3.3] GPU dictionary indexing — the reason this wave exists #71 can be checked against truth

Every spatial map differs from its transpose and both mirrors, so a flipped axis fails a test.

2. requires_package gate + domain extras (Wave 0)

Hides an action until its extra is importable, mirroring requires_vectors. find_spec, so it never imports the package. Applied in both filter paths — adding a gate to only one renders a button that never dispatches, and a test asserts both have it.

Extras eels / ebsd / atoms / all, plus a CI job on spyde[all] so gated code actually runs.

Reversed on measurement: numexpr is NOT being added. HyperSpy warns it is missing and "slower to calculate model", but at spectrum sizes that is backwards:

numexpr	spectra/s
absent	110
1 thread	77
4 threads	75
48 threads	70

Its per-call setup dominates ~1k-element arrays. pyproject.toml now carries a comment, because the warning will keep inviting someone to add it.

3. Batched GPU fitting engine (Wave 1.1-1.3)

In spyde/fitting/ — not spyde/models/, which is already the neural disk detector.

JᵀJ is (P, n, n) because n stays tiny; the only big object is the (P, C, n) Jacobian, so P is chunked. jacfwd not jacrev (one pass per input, n≈10, vs per output, C≈2000).

One implementation, not two — the CPU path is the same code with device="cpu". HyperSpy is the reference, and the acceptance test asserts parameter parity with multifit, because "it converged" proves nothing when you are replacing a reference implementation.

Measured, 1024 spectra × 1024 channels, PowerLaw + 3×Erf (11 free params):

hyperspy multifit	214.80 s	4.8 spectra/s	—
batched cpu	27.02 s	37.9 spectra/s	7.9×
batched cuda	3.97 s	257.8 spectra/s	54.1×

Two numerical traps found by measuring, both documented at the code:

• Column scaling is load-bearing. A PowerLaw fits A ~ 1e6 beside r ~ 3, so cond(JᵀJ) ~ 1e12 and float64 Cholesky loses nearly every digit. Unscaled: 247 iterations for a two-parameter fit, stopping 1.5-3.5% short of multifit. Scaled: 46 iterations to chisq ~1e-34.
• Convergence must be a gradient test. Step-size alone reads "stuck against a wall" as converged; requiring an accepted step never fires at all, since at the optimum nothing improves.

Known limitation

Convergence on hard many-parameter models is seed-limited — hyperspy hits maxfev on the same model. That is exactly what seeded propagation (#54) is for; the speedup above is measured at an equal iteration budget for both.

Not yet done in Wave 1

#54 seeding, #55 wizard, #56 picker, #57 drag-to-fit, #58 component area maps, #59 2D. No UI in this PR, so nothing here needs screenshot verification yet.

[CSSFrancis]

Update: answering "is PyTorch really the right way to fit?"

Profiled it rather than argued it. The answer was yes as a vehicle, no as I was using it:

residual evaluation	3.4 ms
jacfwd Jacobian	51.6 ms — 94% of the solver

Autodiff costs one forward pass per parameter, and these components have closed-form derivatives that mostly reuse the value already computed (df/dA is the shape for every linear amplitude). Components now carry analytic gradients:

	before	after
batched cpu	37.9	105.9 spectra/s (2.8×)
batched cuda	257.8	361.6 spectra/s (1.4×)

The GPU gains less because it is now dispatch-bound, not compute-bound — the remaining lever there is kernel fusion (torch.compile/CUDA graphs), not more math. Torch stays the right vehicle: already a dependency, and CPU + CUDA + MPS means it works on Mac too, which JAX-on-Windows and a hand-written CUDA kernel would not.

Also found: my chunk heuristic was starving the GPU. Capping the Jacobian at 2²² elements chopped a 1024-spectrum batch into pieces of 372 and cost a third of the throughput (178 vs 267 spectra/s). Raised to 2²⁶.

Correctness is unchanged — every analytic gradient is asserted equal to autodiff's, which is the ideal oracle since it's derived mechanically from the value function and can't share a mistake with a hand-written formula.

Also in this push

#54 seeded propagation — coarse strided fit → propagate to nearest neighbour → one batched refine. Only converged coarse fits propagate; a failed one has wandered somewhere unphysical and seeding from it spreads the failure.

Two benchmark corrections, both of which had been quietly measuring the wrong thing:

1. With exspy now installed, create_model() returns an EELSModel that already has a background — so the reference had two PowerLaws while the batched side had one. Both sides must fit the same model or the comparison means nothing.
2. The EELS benchmark model cannot represent a hydrogenic edge, so neither engine converges and it was timing the iteration cap, not convergence. Added a well-posed EDS case (gaussian peaks, which the library expresses exactly) as the default; EELS stays as a deliberately-hard timing-only case, documented as such.

Well-posed case: 57.6% converged, 361 spectra/s, 11.6× multifit.

176 tests green.

Known, not yet addressed

The engine runs every pixel for max_iter even once most have converged, where hyperspy stops per-pixel — so the speedup ratio swings (11.6×–66×) with how hard the problem is. Compacting converged items out of the working set is the obvious next win.