From c00aec761d22206045384e0985a8048eb2a381e1 Mon Sep 17 00:00:00 2001 From: Yashvi-Sharma Date: Mon, 9 Nov 2026 15:53:56 -0800 Subject: [PATCH 1/3] Make Transform2D input normalization an opt-in per-trace setting Transform2D.fit rescaled its inputs to [-1, 1] unconditionally. That changes what .matrix means, so it cannot be the default for a fork that intends to upstream it. It is now off by default and selected per trace via fit_normalize, alongside the existing fit_degree, which is already the established way to vary the fit for one instrument. Measured, the rescaling is a safeguard for poorly scaled inputs rather than a general improvement. On coordinates running 0..2048 it cuts the worst residual by a factor of ~650 (5.8e-11 to 8.9e-14). On the centred focal-plane mm that ScopeSim actually fits, both routes reach machine precision and the unnormalized fit is if anything slightly better, so enabling it does not move an existing trace. Two existing tests were named for normalization but passed with or without it, so they were not testing it. Both now state their mode explicitly, and new tests cover the case where rescaling genuinely matters, the case where it is immaterial, and that the chain-rule factor keeps gradients in input units. Co-Authored-By: Claude Opus 5 --- scopesim/effects/spectral_trace_list_utils.py | 19 ++++-- .../test_SpectralTraceListUtils.py | 68 ++++++++++++++++++- 2 files changed, 78 insertions(+), 9 deletions(-) diff --git a/scopesim/effects/spectral_trace_list_utils.py b/scopesim/effects/spectral_trace_list_utils.py index 09e0af97..43ebba18 100644 --- a/scopesim/effects/spectral_trace_list_utils.py +++ b/scopesim/effects/spectral_trace_list_utils.py @@ -106,6 +106,7 @@ class SpectralTrace: "description": "", "trace_flux_jacobian": "!SIM.spectral.trace_flux_jacobian", "fit_degree": 4, + "fit_normalize": False, } def __init__(self, trace_tbl, cmds=None, **kwargs): @@ -202,12 +203,16 @@ def compute_interpolation_functions(self): self.wave_max = quantify(np.max(lam_arr), u.um).value degree = self.meta["fit_degree"] - self.xy2xi = Transform2D.fit(x_arr, y_arr, xi_arr, degree=degree) - self.xy2lam = Transform2D.fit(x_arr, y_arr, lam_arr, degree=degree) - self.xilam2x = Transform2D.fit(xi_arr, lam_arr, x_arr, degree=degree) - self.xilam2y = Transform2D.fit(xi_arr, lam_arr, y_arr, degree=degree) - self._xiy2x = Transform2D.fit(xi_arr, y_arr, x_arr, degree=degree) - self._xiy2lam = Transform2D.fit(xi_arr, y_arr, lam_arr, degree=degree) + # Rescaling the inputs to [-1, 1] conditions the Vandermonde matrix + # for coordinates far from the origin. It also changes what .matrix + # means, so like fit_degree it is a per-trace setting, default off. + normalize = self.meta["fit_normalize"] + self.xy2xi = Transform2D.fit(x_arr, y_arr, xi_arr, degree=degree, normalize=normalize) + self.xy2lam = Transform2D.fit(x_arr, y_arr, lam_arr, degree=degree, normalize=normalize) + self.xilam2x = Transform2D.fit(xi_arr, lam_arr, x_arr, degree=degree, normalize=normalize) + self.xilam2y = Transform2D.fit(xi_arr, lam_arr, y_arr, degree=degree, normalize=normalize) + self._xiy2x = Transform2D.fit(xi_arr, y_arr, x_arr, degree=degree, normalize=normalize) + self._xiy2lam = Transform2D.fit(xi_arr, y_arr, lam_arr, degree=degree, normalize=normalize) if "slit_dispersion_colname" in self.meta: center = xi_arr == 0 derivative = self.table[self.meta["slit_dispersion_colname"]].quantity.to_value(u.um / u.arcsec) @@ -1158,7 +1163,7 @@ def __call__(self, x, y, grid=False, **kwargs): return result @classmethod - def fit(cls, xin, yin, xout, degree=4, normalize=True): + def fit(cls, xin, yin, xout, degree=4, normalize=False): """Determine polynomial fits.""" xin = np.asarray(xin, dtype=float) yin = np.asarray(yin, dtype=float) diff --git a/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py b/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py index 04be6bee..46181c57 100644 --- a/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py +++ b/scopesim/tests/tests_effects/test_SpectralTraceListUtils.py @@ -259,7 +259,7 @@ def test_fit_preserves_high_dynamic_range_coefficients(self): + 0.2 * x ) - tf2d = Transform2D.fit(x, y, z, degree=4) + tf2d = Transform2D.fit(x, y, z, degree=4, normalize=False) assert tf2d.matrix.dtype == np.float64 assert np.max(np.abs(tf2d(x, y) - z)) < 1e-5 @@ -274,7 +274,7 @@ def test_gradient_with_normalized_fit_uses_input_units(self): y = y_grid.ravel() z = 3 + 2 * x + 5 * y + 7 * x * y + 11 * y**2 - tf2d = Transform2D.fit(x, y, z, degree=2) + tf2d = Transform2D.fit(x, y, z, degree=2, normalize=True) dz_dx, dz_dy = tf2d.gradient() assert dz_dx(x, y) == pytest.approx(2 + 7 * y, rel=1e-10, abs=1e-10) @@ -343,3 +343,67 @@ 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) + + def test_normalization_conditions_poorly_scaled_inputs(self): + # Inputs far from the origin are where rescaling to [-1, 1] pays off. + # ScopeSim's focal-plane mm are centred, so this is a safeguard for + # other coordinate conventions rather than a general improvement. + x_grid, y_grid = np.meshgrid(np.linspace(0, 2048, 40), np.linspace(0, 2048, 40), indexing="ij") + x, y = x_grid.ravel(), y_grid.ravel() + xs, ys = (x - 1024)/2048, (y - 1024)/2048 + z = 1. + .35*(ys + .02*xs + .1*ys**2 + .03*xs*ys + .005*ys**3) + + plain = Transform2D.fit(x, y, z, degree=4, normalize=False) + scaled = Transform2D.fit(x, y, z, degree=4, normalize=True) + + plain_residual = np.max(np.abs(plain(x, y) - z)) + scaled_residual = np.max(np.abs(scaled(x, y) - z)) + assert scaled_residual < plain_residual / 100 + + def test_normalization_is_immaterial_for_centred_focal_plane_mm(self): + # The coordinates ScopeSim actually fits. Both routes reach machine + # precision, so enabling the flag must not move anybody's trace. + x_grid, y_grid = np.meshgrid(np.linspace(-50, 50, 40), np.linspace(-25, 25, 40), indexing="ij") + x, y = x_grid.ravel(), y_grid.ravel() + z = 1. + .35*(y/50 + .02*x/100 + .1*(y/50)**2) + + plain = Transform2D.fit(x, y, z, degree=4, normalize=False) + scaled = Transform2D.fit(x, y, z, degree=4, normalize=True) + + assert np.max(np.abs(plain(x, y) - z)) < 1e-12 + assert np.max(np.abs(scaled(x, y) - z)) < 1e-12 + + +class TestSpectralTraceFitNormalize: + def test_defaults_to_the_upstream_unnormalized_fit(self): + spt = SpectralTrace(_tilted_linear_trace_table()) + assert spt.meta["fit_normalize"] is False + assert spt.xy2lam.pretransform_x is None + + def test_opting_in_rescales_the_fit_inputs(self): + spt = SpectralTrace(_tilted_linear_trace_table(), fit_normalize=True) + assert spt.xy2lam.pretransform_x is not None + assert spt.xy2lam.dpretransform_x != 1.0 + + def test_both_routes_agree_on_this_trace(self): + # Focal-plane mm are centred, so the two fits must describe the same + # trace; enabling the option is not allowed to move anybody's spectrum. + table = _tilted_linear_trace_table() + plain = SpectralTrace(table.copy()) + scaled = SpectralTrace(table.copy(), fit_normalize=True) + + x_mm = np.linspace(1.2, 2.8, 17) + y_mm = np.linspace(-0.08, 0.08, 17) + assert scaled.xy2lam(x_mm, y_mm) == pytest.approx(plain.xy2lam(x_mm, y_mm), abs=1e-9) + assert scaled.xy2xi(x_mm, y_mm) == pytest.approx(plain.xy2xi(x_mm, y_mm), abs=1e-9) + + def test_gradients_are_in_input_units_either_way(self): + # The chain-rule factor is what keeps the normalized gradient in + # per-mm rather than per-rescaled-unit. + table = _tilted_linear_trace_table() + plain = SpectralTrace(table.copy()) + scaled = SpectralTrace(table.copy(), fit_normalize=True) + + x_mm, y_mm = np.linspace(1.2, 2.8, 9), np.linspace(-0.08, 0.08, 9) + for plain_grad, scaled_grad in zip(plain.xy2lam.gradient(), scaled.xy2lam.gradient()): + assert scaled_grad(x_mm, y_mm) == pytest.approx(plain_grad(x_mm, y_mm), abs=1e-7) From 1d9d809a98c52debf80257423f0e40796bfe5706 Mon Sep 17 00:00:00 2001 From: Yashvi-Sharma Date: Mon, 9 Nov 2026 16:31:44 -0800 Subject: [PATCH 2/3] Add PR description for the Transform2D normalization change Co-Authored-By: Claude Opus 5 --- tb-04-transform2d-normalize_changes.md | 111 +++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 tb-04-transform2d-normalize_changes.md diff --git a/tb-04-transform2d-normalize_changes.md b/tb-04-transform2d-normalize_changes.md new file mode 100644 index 00000000..56df2427 --- /dev/null +++ b/tb-04-transform2d-normalize_changes.md @@ -0,0 +1,111 @@ +# tb-04-transform2d-normalize + +Makes `Transform2D` input normalization opt-in instead of unconditional, and +replaces two tests that claimed to cover it but did not. + +## Why + +`Transform2D.fit` rescaled `xin` and `yin` to `[-1, 1]` before fitting, stored +the rescaling as a `pretransform`, and carried `1/scale` into `gradient()` as a +chain-rule factor. Upstream's version is five lines with none of that. + +Enabling it by default is not upstreamable for two reasons: + +1. **It changes the public meaning of `.matrix`.** The coefficients are in + rescaled coordinates, not input coordinates. The existing upstream test + `test_fit_gives_correct_matrix` had to be given `normalize=False` to keep + passing — that edit is the clearest evidence the change is observable. +2. It silently alters the fitted transforms of every instrument in the IRDB. + +So it is now off by default and selected per trace. + +## What the rescaling is actually worth + +Measured, because the original justification did not survive checking. + +| Input coordinates | degree | unnormalized | normalized | +|---|---:|---:|---:| +| focal-plane mm, centred (-50..50, -25..25) | 4 | 1.2e-14 | 1.6e-14 | +| focal-plane mm, centred | 6 | 2.8e-14 | 1.9e-13 | +| pixels, uncentred (0..2048) | 4 | 5.8e-11 | 8.7e-14 | +| pixels, uncentred | 6 | 5.8e-11 | 8.9e-14 | + +(worst absolute residual of the fitted surface) + +The rescaling is a **safeguard for poorly scaled inputs**, worth ~650x when +coordinates run far from the origin, and **immaterial — if anything marginally +worse — on the centred focal-plane mm that ScopeSim actually fits.** Both +routes reach machine precision there, which is also why turning it on does not +move an existing trace. + +This corrects the rationale I started with, which was that `fit_degree: 6` in +`ZShooter_SPEC.yaml` made conditioning important. At degree 6 in centred mm the +unnormalized fit is the better of the two. + +## Where the switch lives, and why it is not a `!SIM` flag + +`fit_normalize` is a plain entry in `SpectralTrace._class_params`, defaulting +to `False`, exactly like the `fit_degree` that sits beside it: + +```python +"trace_flux_jacobian": "!SIM.spectral.trace_flux_jacobian", +"fit_degree": 4, +"fit_normalize": False, +``` + +It is resolved in `compute_interpolation_functions` and passed to the six +`Transform2D.fit` calls. + +A global `!SIM.spectral.*` bang-string was tried first and rejected. The fit +happens during `SpectralTrace.__init__`, and several tests construct trace +lists with `cmds=None` while `scopesim.rc.__currsys__` is patched to a bare +`MagicMock` (`test_OpticalTrain.py`'s `patch_globals`). Any bang-key resolved +at construction time fails there, which is why `trace_flux_jacobian` gets away +with it — it is only read later, inside `_trace_flux_scale`. + +Per-trace is also the right scope on the merits: this is a property of one +fit, not of the simulation. `fit_degree` is the precedent, already overridden +for exactly one instrument in `ZShooter_SPEC.yaml`. + +**Config impact:** ZShooter and X-shooter must set `fit_normalize: true` on +their trace effects to keep today's numbers. See the companion irdb branch. + +## Tests + +Two existing tests were named for normalization but passed with it on *or* off, +so they were not testing it: + +- `test_fit_preserves_high_dynamic_range_coefficients` — now explicitly + `normalize=False`; it is really a float64-dtype and accuracy test. +- `test_gradient_with_normalized_fit_uses_input_units` — now explicitly + `normalize=True`, so the `dpretransform` chain-rule factor is actually + exercised. With `normalize=False` that factor is 1 and the test is vacuous. + +New: + +- `test_normalization_conditions_poorly_scaled_inputs` — the uncentred case, + asserting >100x improvement. +- `test_normalization_is_immaterial_for_centred_focal_plane_mm` — both routes + below 1e-12, documenting that enabling it is safe. +- `TestSpectralTraceFitNormalize` — the parameter defaults off, opting in + populates `pretransform_x`/`dpretransform_x`, both routes agree on the mapped + wavelength and slit coordinates to 1e-9, and gradients agree to 1e-7, i.e. + stay in per-mm units either way. + +## Deliberately not included + +`fit2matrix` builds the coefficient matrix as float64 where upstream used +float32. That is left unconditional and unchanged by this branch: float32 for a +degree-4-or-higher 2D polynomial coefficient matrix is indefensible regardless +of normalization, and it deserves its own one-line PR with residual numbers +rather than being bundled into a behaviour toggle. + +`xilam2xy_fit`, `xy2xilam_fit` and `_xiy2xlam_fit` in the same module are dead +— zero call sites anywhere including tests — but they are upstream code +(oczoske, 2021) and untouched by this fork, so removing them is upstream's +call, not ours. + +## Verification + +`scopesim/tests`: 4 failed, 1382 passed. Same four pre-existing failures as on +`main`. From a804f1e35022f6d676ca31f120d35aead9b8b69a 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-04-transform2d-normalize_changes.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename tb-04-transform2d-normalize_changes.md => rework_summaries/tb-04-transform2d-normalize_changes.md (100%) diff --git a/tb-04-transform2d-normalize_changes.md b/rework_summaries/tb-04-transform2d-normalize_changes.md similarity index 100% rename from tb-04-transform2d-normalize_changes.md rename to rework_summaries/tb-04-transform2d-normalize_changes.md