From 53bc3bccd38d7c6df34c0c34865d497d5e3f2888 Mon Sep 17 00:00:00 2001 From: Yashvi-Sharma Date: Mon, 9 Nov 2026 16:09:27 -0800 Subject: [PATCH 1/3] Quantify how far the projected trace flux scale is from the cell area The existing test only asserted that the upstream sqrt(gradient) scale is larger than the area Jacobian on one tilted trace. For this trace family the inverse transforms are xi = 10y and lam = x - 10*tilt*y, so the Jacobian is 10 for every tilt while the projected scale picks up sqrt(1 + (10*tilt)^2). The over-count is therefore unbounded in the shear, which is the argument for making trace_flux_jacobian the default upstream, and the two agree exactly only for an unsheared trace. No production code changes; trace_flux_jacobian is already opt-in and already defaults to the upstream formula. Co-Authored-By: Claude Opus 5 --- .../test_SpectralTraceListUtils.py | 40 ++++++++++++++++++- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py b/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py index 04be6bee..74972ab1 100644 --- a/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py +++ b/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py @@ -83,7 +83,8 @@ def test_trace_flux_jacobian_handles_tilted_trace(self): assert jacobian_scale[0, 0] == pytest.approx(1e-3, rel=1e-5) -def _tilted_linear_trace_table(): +def _tilted_linear_trace_table(tilt=0.1): + """x = wave + tilt*xi, y = xi/10, so the slit is sheared in dispersion.""" xi_grid, wave_grid = np.meshgrid( np.linspace(-1, 1, 5), np.linspace(1, 3, 5), @@ -96,7 +97,7 @@ def _tilted_linear_trace_table(): data=[ wave * u.um, xi * u.arcsec, - (wave + 0.1 * xi) * u.mm, + (wave + tilt * xi) * u.mm, (xi / 10) * u.mm, ], names=["wavelength", "s", "x", "y"], @@ -343,3 +344,38 @@ def test_works_with_non_square_image(self): interps = make_image_interpolations(hdul, kx=1, ky=1) imginterp = interps[0](yy, xx, grid=False) assert np.allclose(imginterp, img) + + +class TestTraceFluxJacobianMagnitude: + """How far the upstream sqrt(gradient) scale is from the true cell area.""" + + @pytest.mark.parametrize("tilt", [0., .05, .1, .2, .3]) + def test_projected_scale_overcounts_by_a_known_factor(self, tilt): + # For this trace family the inverse transforms are + # xi = 10y, lam = x - 10*tilt*y + # so the area Jacobian |d(xi,lam)/d(x,y)| is 10 for every tilt, while + # the projected scale picks up sqrt(1 + (10*tilt)**2). The upstream + # formula therefore over-counts flux without bound as the slit shears. + spt = SpectralTrace(_tilted_linear_trace_table(tilt)) + det_header = header_from_list_of_xy([-1, 1], [-1, 1], 0.01, "D") + x_mm, y_mm = np.array([[2.0]]), np.array([[0.0]]) + + spt.meta["trace_flux_jacobian"] = False + projected = spt._trace_flux_scale(x_mm, y_mm, pixsize=.01, pixscale=.1, det_header=det_header)[0, 0] + spt.meta["trace_flux_jacobian"] = True + jacobian = spt._trace_flux_scale(x_mm, y_mm, pixsize=.01, pixscale=.1, det_header=det_header)[0, 0] + + assert jacobian == pytest.approx(1e-3, rel=1e-5) + assert projected/jacobian == pytest.approx(np.sqrt(1 + (10*tilt)**2), rel=1e-5) + + def test_the_two_agree_only_for_an_unsheared_trace(self): + spt = SpectralTrace(_tilted_linear_trace_table(0.)) + det_header = header_from_list_of_xy([-1, 1], [-1, 1], 0.01, "D") + x_mm, y_mm = np.array([[2.0]]), np.array([[0.0]]) + + spt.meta["trace_flux_jacobian"] = False + projected = spt._trace_flux_scale(x_mm, y_mm, pixsize=.01, pixscale=.1, det_header=det_header)[0, 0] + spt.meta["trace_flux_jacobian"] = True + jacobian = spt._trace_flux_scale(x_mm, y_mm, pixsize=.01, pixscale=.1, det_header=det_header)[0, 0] + + assert projected == pytest.approx(jacobian, rel=1e-9) From a8809230d99d6f760df87ea287c6a7f4409456b4 Mon Sep 17 00:00:00 2001 From: Yashvi-Sharma Date: Mon, 9 Nov 2026 16:33:09 -0800 Subject: [PATCH 2/3] Add PR description for the trace flux scale evidence Co-Authored-By: Claude Opus 5 --- tb-06-trace-flux-evidence_changes.md | 96 ++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 tb-06-trace-flux-evidence_changes.md diff --git a/tb-06-trace-flux-evidence_changes.md b/tb-06-trace-flux-evidence_changes.md new file mode 100644 index 00000000..fc56145e --- /dev/null +++ b/tb-06-trace-flux-evidence_changes.md @@ -0,0 +1,96 @@ +# tb-06-trace-flux-evidence + +Tests only. No production code changes. + +## Why there is no code change + +`SpectralTrace._trace_flux_scale` is already structured the way the rest of +this Tier B series is trying to reach: + +```python +use_jacobian = from_currsys(self.meta["trace_flux_jacobian"], self.cmds) + +if not use_jacobian: + dlam_by_dx, dlam_by_dy = self.xy2lam.gradient() + dlam_per_pix = pixsize * np.sqrt(dlam_by_dx(x_mm, y_mm)**2 + dlam_by_dy(x_mm, y_mm)**2) + return pixscale * dlam_per_pix # upstream, byte for byte + +dxi_by_dx, dxi_by_dy = self.xy2xi.gradient() +dlam_by_dx, dlam_by_dy = self.xy2lam.gradient() +jacobian = (dxi_by_dx(x_mm, y_mm)*dlam_by_dy(x_mm, y_mm) + - dxi_by_dy(x_mm, y_mm)*dlam_by_dx(x_mm, y_mm)) +return np.abs(jacobian) * self._detector_pixel_area(det_header) +``` + +`defaults.yaml` already ships `trace_flux_jacobian : False`, so upstream +behaviour is already the default, and both ZShooter and X-shooter already opt +in. The flag is also overridable per instance as a constructor kwarg. + +What was missing was the argument for making it the default upstream. + +## What the existing test proved, and what it did not + +`test_trace_flux_jacobian_handles_tilted_trace` asserted only that the +projected scale is *larger* than the Jacobian on one tilted trace, plus that +the Jacobian equals 1e-3 there. A sign, not a magnitude — and nothing showing +how the error behaves. + +## The analytic result + +For the `_tilted_linear_trace_table` family, with + + x = lam + tilt*xi, y = xi/10 + +the inverse transforms are exactly + + xi = 10y + lam = x - 10*tilt*y + +so the area Jacobian is + + |d(xi,lam)/d(x,y)| = |0*(-10*tilt) - 10*1| = 10 + +**independent of tilt**, while the projected scale picks up + + sqrt((dlam/dx)^2 + (dlam/dy)^2) = sqrt(1 + (10*tilt)^2) + +The ratio is therefore `sqrt(1 + (10*tilt)^2)`, which grows without bound as +the slit shears, and equals 1 only for an unsheared trace: + +| tilt | over-count | +|---:|---:| +| 0.0 | 1.000 | +| 0.05 | 1.118 | +| 0.1 | 1.414 | +| 0.2 | 2.236 | +| 0.3 | 3.162 | + +The upstream formula measures the length of the wavelength gradient and +multiplies by the slit plate scale, which is the area of a *rectangle*. The +true cell is a parallelogram, and the two agree only when it happens to be +rectangular. That is the case for an unsheared trace and for nothing else. + +## Changes + +- `_tilted_linear_trace_table` takes a `tilt` argument, defaulting to `0.1` so + the existing caller is unaffected. +- `test_projected_scale_overcounts_by_a_known_factor`, parametrised over five + tilts, asserting the Jacobian is 1e-3 at every tilt and that the ratio + matches `sqrt(1 + (10*tilt)^2)` to 1e-5. +- `test_the_two_agree_only_for_an_unsheared_trace`. + +## Still outstanding for an upstream proposal + +Before asking AstarVienna to flip the default, this wants before/after numbers +from a real METIS LSS and a MICADO spectroscopy run, not just the analytic +family above. The issue thread on METIS LMS rectification systematics suggests +that is the kind of evidence the maintainers respond to. Not done here. + +`_detector_pixel_area` is covered separately by +`test_detector_jacobian_uses_physical_pixel_area`, including asymmetric pixels +given in metres. + +## Verification + +`scopesim/tests`: 4 failed, 1382 passed. Same four pre-existing failures as on +`main`. From 8dfcb0d455f229b48a5da25449bcc709833fd959 Mon Sep 17 00:00:00 2001 From: Yashvi-Sharma Date: Mon, 9 Nov 2026 16:56:25 -0800 Subject: [PATCH 3/3] Move the PR description into rework_summaries/ Co-Authored-By: Claude Opus 5 --- .../tb-06-trace-flux-evidence_changes.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename tb-06-trace-flux-evidence_changes.md => rework_summaries/tb-06-trace-flux-evidence_changes.md (100%) diff --git a/tb-06-trace-flux-evidence_changes.md b/rework_summaries/tb-06-trace-flux-evidence_changes.md similarity index 100% rename from tb-06-trace-flux-evidence_changes.md rename to rework_summaries/tb-06-trace-flux-evidence_changes.md