Model the sun's gravitational light deflection (C library)

[arahlin]

Replaces #29, which GitHub marked merged when light-deflection was briefly rebased
below its own base.

Based on faster-sidereal-time (#30). C library and qpoint only.

The sun bends the incoming ray, and qpoint did not account for it. It was the whole of
the 14 mas by which azel2radec differed from astropy, and of the 43 mas coming back:

against astropy	before	after
azel2radec	14.30 mas	0.79 mas
radec2azel	42.56 mas	0.84 mas

test_astropy.py's tolerance drops from 0.1 arcsec to 5 mas, and make_qpoint there
switches the term on beside the IERS rates, astropy applying it too.

How it is wired

rate_defl turns it on and defaults to never, like rate_dut1 and rate_wobble:
~20 mas for about a tenth of azel2bore, so a caller who does not ask gets byte-for-byte
what they got before. Only the sun's position is cached at that rate — the deflection
depends on where the telescope points, so the per-sample part runs every sample, as
aberration does. It sits last in the forward chain and first in the inverse, physics
applying it before aberration.

Aberration and deflection are one function, qp_apply_aaber_defl, replacing
qp_apply_annual_aberration. eraEpv00 costs 7.8 µs a call and serves both — aberration
wants the earth's barycentric velocity, deflection its heliocentric position, and it
returns both. Calling it twice doubled the whole transform with both rates on always
(3202 ms against 1610 for 200k samples). Sharing the pointing vector and summing the two
rotation vectors into one quaternion halved the per-sample cost again, 35.5 → 17.5 ns.

Switched on it costs 1.10x on azel2bore. Switched off the output is bit-identical to the
pre-deflection build over 240k values, including the mean_aber=False and fast_aber=False
paths.

Three implementation choices:

• eraLdsun does the arithmetic, not the textbook 4.07 mas · cot(elongation/2):
  ERFA is already vendored, and its routine takes the sun-to-observer vector directly
  rather than needing the elongation.
• The rotation always takes the small-angle form, unlike aberration's fast_aber
  switch: the deflection never exceeds ~0.1″, so the dropped cubic term is ~2e-20 rad and
  the exact path measured nearly twice the cost. fast_aber=False keeps its own quaternion.
• The inverse is a sign flip. eraLdsun has no closed-form inverse — ERFA iterates in
  eraAticq — but negating is second order, 1e-9 mas.

Also

eraEpv00 was being called with its two outputs aliased to one array, so the heliocentric
position was overwritten by the barycentric one. Harmless while only the velocity was
wanted; deflection needs both.

qp_reset_rates enumerates the rates one at a time and was missing qp_reset_rate_defl,
so reset_rates carried the previous chunk's sun position into the next. TestResetRates
is rewritten to pin the property rather than call it and assert nothing: with a rate set to
'once' the correction freezes at the first sample, so after reset_rates the answer must
match a freshly built QPoint — parametrised over every rate the package reports, so a
rate added later is covered without anyone remembering.

C API: qp_memory_t gains state_defl, state_defl_inv, e_sun and em_sun; the
ctypes mirror tracks them and all 55 field offsets were checked against the compiled struct.

Tests

465 passing, 14 skipped. TestLightDeflection asserts the term is present, that switching
it off reproduces the old 14 mas and 43 mas exactly, and pins size and direction against
erfa.ldsun.

The module's shared TOL_ARCSEC moves with the term rather than being left loose, since
every comparison in the file now has the deflection switched on. make_qpoint lets a
caller override one of the rates it sets, which is how TestLightDeflection gets the same
QPoint with the term off to show what it is worth.

Coverage, from a temporary -O0 --coverage build under gcc: qp_apply_aaber_defl at 95%
of its 41 lines, qpoint.c unmoved at 95%. Worth stating because rate_defl defaults to
never, so a term nobody switched on would read as zero coverage and look identical to one
that does not work.

🤖 Generated with Claude Code