Add ParametricInverter, which fits a spectral line profile to every pixel

[roytsmart]

MartInverter solves for the radiance in every voxel of the scene, which is underdetermined: the tutorial configuration has 81,920 unknowns and only 32,768 measurements. ParametricInverter instead solves for a handful of parameters in every spatial pixel, which makes the problem overdetermined (12,288 unknowns for a three-parameter model) and lets the Doppler shift be measured to a small fraction of a velocity bin.

The parameters of neighboring pixels are not independent, since each sensor pixel collects light from many spatial pixels, so the fit is a single optimization over every parameter of every pixel simultaneously. This is done with the Adam optimizer on a GPU.

What's here

• ctis.Regridder assembles the sparse weights of a linear instrument into a single torch CSR matrix, so the forward model is differentiable and the adjoint comes from automatic differentiation. CSR is used instead of scatter-add (index_add_) because it is both ~2.5x faster and, unlike scatter-add, bitwise deterministic on CUDA devices. Determinism matters for the conjugate-gradient solvers planned next.

  Note this adjoint is the exact transpose of the forward model, which backproject is not — backproject applies an extra normalization to conserve flux.

• AbstractLinearInstrument.response exposes the two diagonal factors of the noiseless forward model, so an external differentiable implementation can reproduce image() exactly without reimplementing it. Both IdealInstrument and OptikaInstrument implement it.

• GaussianModel evaluates a Gaussian line profile, integrated analytically across each velocity bin. Bin integration is essential rather than cosmetic: the reconstruction grid is usually comparable to or coarser than the width of the line, so sampling at bin centers would make a sub-bin Doppler shift nearly unobservable.

  The free width parameter is the nonthermal width, with the thermal and instrumental widths held fixed. This makes the lower bound on the observed width exact rather than a penalty, and means the physically interesting quantity is the one which receives an uncertainty, instead of being recovered afterwards from a difference of comparable squares.

Verification

• test_forward_matches_instrument asserts the torch forward model reproduces instrument.image() for both IdealInstrument and OptikaInstrument (agreement to ~2e-7). This is the test that guards the whole approach.
• test__call__recovery builds a scene the model can represent exactly, forward-models it, inverts, and asserts every parameter is recovered with a correlation above 0.95. In practice the fit reaches r = 0.98 (intensity), 0.99 (velocity), 0.99 (width); with Poisson noise, 0.90 / 0.97 / 0.88.
• The Regridder is checked against regridding.regrid_from_weights, for the adjoint identity, for bitwise determinism, and with torch.autograd.gradcheck.

Notes for review

• torch is an optional dependency (pip install ctis[torch]), imported lazily. It is added to the test and doc extras so the new tests actually run in CI.
• response is a new abstract member of AbstractLinearInstrument, so any subclass outside this repo would need to implement it.
• Two things a caller has to get right, both called out in the docstrings: the sensor must be large enough to hold the dispersed scene (voxels that fall off the edge are unconstrained), and the velocity bins should be comparable to the line width.
• No docs page yet — only the jupyter-execute examples in the docstrings.

Next step is to swap Adam for Levenberg-Marquardt, which converges in fewer operator applications and yields per-pixel error bars from JᵀWJ.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B6wnJue6RxMmKBn5sD8gDL

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (d9a30b7) to head (c593898).

Additional details and impacted files

@@            Coverage Diff             @@
##              main       #23    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           23        30     +7     
  Lines          861      1658   +797     
==========================================
+ Hits           861      1658   +797     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.