feat(spectroscopy): Wave 2 — composition → auto-populated model

[CSSFrancis]

Closes #62. Part of tracker #48.

Stacked on #82 (needs ModelSpec + the engine) — base retargets to main once that lands.

Elements in, model out

Type which elements are present, get a populated model. exspy owns the spectroscopy — edge and line energies, GOS edge shapes, family relationships — because reimplementing it would mean diverging from the numbers the community publishes. This module owns the plumbing:

• one call for EELS and EDS alike returning a ModelSpec, so the result feeds the batched engine, the wizard and the renderer through one type;
• pruning to the measured range;
• an honest report of whether the batched engine can fit the result.

The asymmetry worth knowing

	components	batched engine
EDS	Polynomial + Gaussian	✅ fully supported — gets the GPU path now
EELS	EELSCLEdge (GOS table)	❌ no batched port yet (#63) → falls back to hyperspy

The fallback is correct, just slower. It's reported in the returned info rather than left as a surprise.

Why pruning isn't housekeeping

exspy will happily add a Cu-L line at 0.93 keV to a spectrum whose useful range starts at 2 keV. A component with no data under it is not harmless: its amplitude is unconstrained, so the optimiser trades it against everything else and degrades the parameters that are measurable.

Two exspy behaviours that don't do what their names suggest

1. add_lines appends — restricting needs set_lines.
2. Even then, the EDS model expands each element into its whole family (selecting Fe_Ka still builds Fe_Kb, Fe_La, Fe_Ln, …) regardless of metadata.Sample.xray_lines. So honouring only_lines means filtering the built spec by name.

A real bug this shook out

Polynomial and Offset shaped their output with expand_as/expand, which forces the parameter block's P down to the axis's leading 1 and raises for any batch bigger than one spectrum. Found by fitting a real EDS model, whose background is a Polynomial — not by the component tests, because every one of them used a single spectrum, where expand_as happens to work.

That's the actual defect: a batched component library whose tests never batched. Closed with TestEveryComponentBatches, which runs every component at P=4 and asserts value shape, gradient shape, and that row 1 reflects its own parameters — a broadcasting slip returning row 0 for everything would still have the right shape.

The fix commit is included here since this is the first PR that exercises it; it's a fix to #82's code.

Notes

• The source signal is never mutated — a user may be exploring several compositions.
• The whole test module importorskips exspy, so the no-extras CI job skips cleanly rather than erroring. That's the point of the extra.

15 composition tests + the batching suite; 147 green on this branch. Still open in Wave 2: #61, #63, #64, #65, #66, #67.

[CSSFrancis]

Three bugs found by round-tripping a real composition model

I went to start #63 (tabulated EELS edges) and couldn't — ModelSpec.to_model could not rebuild an EELS or EDS model at all. Worth flagging separately because two of the three fail silently.

to_model rebuilt every component bare, which breaks for anything taking constructor arguments:

1. EELSCLEdge raises — element_subshell is required. No EELS model could go spec → hyperspy.
2. Polynomial is worse, because it does not raise. Rebuilt bare it comes back at its default order, so exspy's order-6 EDS background silently lost a3..a6 — to_model skipped the parameters that no longer existed and returned a different model that still fits and still looks plausible.
3. Fixing those surfaced a third: EELSCLEdge.fine_structure_coeff is a vector with 8 elements, and ParameterSpec stored a single float, so hyperspy rejected the assignment on length.

Why the existing tests missed it

The round-trip tests only ever went model → spec, never spec → model with a component of this kind. A round-trip test that only goes one way isn't one.

Fixes

• ComponentSpec.init_args, captured by from_model via a small _INIT_ARGS table. An unrebuildable component now gets an error naming the table to add to, rather than a TypeError from deep inside hyperspy.
• Vector parameters round-trip faithfully (value becomes a list) but are excluded from the packed vector via ComponentSpec.scalar_parameters — the solver puts one scalar per column, and no component with such a parameter is fittable by the batched engine anyway (components.supports already says no). components.py uses the same scalar view so the two can't drift.

198 tests green on this branch.

#63 itself is not done — this was the blocker in front of it, not the work. Next up.

[CSSFrancis]

#63 done — EELS now gets the GPU path

An EELS core-loss edge is not a formula: EELSCLEdge looks its shape up in a GOS table, which is why it had no batched port and why EELS fell back to hyperspy's one-pixel-at-a-time fitting while EDS (gaussians) got the GPU.

The way out is noticing what is actually being fitted. Across a spectrum image the edge shape is the same everywhere — atomic physics, fixed by element and microscope. What varies pixel to pixel is how much of the element there is and exactly where its edge starts. So the edge is sampled once on the signal axis and replaced by a tabulated component fitting intensity (linear) and onset_shift, batched like everything else.

model_for_composition(...)  ->  engine_supported: False
tabulate_model(...)         ->  engine_supported: True

The approximation, stated rather than buried

Fine structure and effective angle are frozen at the values the table was sampled with. They're what make an edge a lookup in the first place, and refitting them would mean re-sampling the table every iteration — the per-item Python work the batched engine exists to avoid.

tabulate_model() returns what it froze. Right trade for quantification; wrong one for fine-structure analysis — which is why it's an explicit call and not automatic.

Two deliberate choices

• Outside the table the value holds at the end sample rather than extrapolating. Extrapolating a GOS tail would invent signal where the measurement has none.
• The onset-shift derivative is a central difference over one channel, not the exact piecewise-linear slope. The exact one is a step function that jumps at every segment boundary, so LM chatters as the shift crosses a channel. It differs from autodiff by ~1.5% of the gradient's own scale, only within a channel of a kink — and the test states that as the property rather than asserting an equality which isn't true.

Verified

• the table reproduces hyperspy's edge to 1e-9
• a fit recovers a known intensity, and a known 12 eV onset shift
• on the synthetic SI the fitted O_K intensity tracks the concentration map the data was built from

218 tests green. I also rebased this branch onto the current #82 tip so the stack doesn't hand you a components.py conflict at merge time — 2-D support and the tabulated component now coexist and are tested together.