Sample the field and the pupil the same way, from one grid

[roytsmart]

linearize documents pupil as cell vertices, then defaults to two grids which are neither vertices nor each other: area_effective invents its own, while the distortion and vignetting fits take grid_input.pupil, which holds the points rays are traced at.

So the default is not expressible through the parameter. Passing the grid the docstring names gives a different model:

linearize(pupil=None)  vs  linearize(pupil=grid_input.pupil):
  distortion coefficients differ by   0.02%
  vignetting coefficients differ by 162.69%
  effective area differs by           1.57%

Nothing errors. A reader who takes "the vertices of the pupil grid" at face value, and passes grid_input.pupil to be explicit, silently gets a vignetting model 163% away from the default.

One rule for both axes

field and pupil are cell vertices. area_effective samples a point drawn uniformly inside every cell; the fits trace at the cell centers. Both models describe the same grid, so passing the defaults back reproduces leaving them out:

linearize()  vs  linearize(field=<default>, pupil=<default>):
  distortion  0.00e+00   (bit-identical: True)
  vignetting  0.00e+00   (bit-identical: True)
  area        0.73%      <- jitter; two default runs differ by 1.96%

Stratifying the field is what the vertices buy

The field average used to wander with the sampling instead of converging. It now does both monotonically, against a 40×40 reference:

   cells |    bias |   noise
 11x11   |  0.67% |  1.93%
 15x15   |  0.54% |  0.73%
 21x21   |  0.27% |  0.46%
 25x25   |  0.23% |  0.41%
 31x31   |  0.11% |  0.27%

Before, on a deterministic field grid, the bias ran 0.38%, 0.95%, 0.59%, 0.78%, 0.61% with no trend — refining it was a coin flip rather than an improvement.

What it costs

Measured on the ESIS as-built model, against today:

  distorted position moves by 0.013 pix   (resolution element is 2.81 pix)
  illumination moves by       1.37%
  effective area moves by     1.77%

All well inside the 5.8% photon noise implied by the SNR 17.3 requirement, and the position shift is 1/200 of a resolution element.

Tests

test_area_effective_ignores_field_outside_the_field_of_view is rewritten for the vertex convention, extending the grid by dark cells rather than dark points. Sized deliberately: at 10 cells per axis its noise is 1.4% against the 49% error it guards against, and it is verified to fail with the field mask removed.

Full suite: 18314 passed, 304 skipped, 17 xfailed. _sequential.py at 100% line coverage. esis passes downstream unchanged (260 tests).

Relationship to #187

This is deliberately not #187. grid_input keeps its current meaning — the points rays are traced at — and nothing outside linearize and area_effective changes, so no downstream migration and no major version bump. It settles the convention only where the two interpretations were already colliding.

🤖 Generated with Claude Code

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #219   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          121       121           
  Lines         7462      7491   +29     
=========================================
+ Hits          7462      7491   +29     

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.

[roytsmart]

I'm pretty sure we need to use axis_field and axis_tuple here

[roytsmart]

You're right. Fixed in 8fe39e6.

tuple(na.shape(field)) is every axis the grid has, when only the two field axes should go from vertices to centers. Any other axis the grid carries gets averaged into itself. On a four-channel system whose field varies per channel:

  cell_centers(axis=tuple(na.shape(field))) -> {'_field_x': 11, 'channel': 3, '_field_y': 11}
  cell_centers(axis=axis_field)             -> {'_field_x': 11, 'channel': 4, '_field_y': 11}

Four channels become three, each an average of its neighbours, and nothing raises.

Now named through the same _normalize_axis_wavelength / _normalize_axis_field / _normalize_axis_pupil helpers the fits already use, which subtract shape and the wavelength axis and so pick out exactly the two intended.

Worth noting this predates the rest of the PR: pupil_centers was written this way before I touched it, and I copied the pattern across to field_centers. It never showed because nothing in the suite passes a grid with an axis beyond the two being centered.

test_linearize_keeps_axes_it_is_not_centering closes that: it passes a field which drifts with wavelength and asserts the wavelength axis survives at full length. Verified to fail with the old handling restored.

Full suite: 18315 passed, _sequential.py at 100%.