From bec26fb5f05103712775d1d4b3ef8b84650c1fbd Mon Sep 17 00:00:00 2001 From: Patrick Tsang Date: Wed, 11 Nov 2026 13:25:42 -0800 Subject: [PATCH] kernels: use an odd, centred pixel output window load_pixel_response_kernel set the output window to int((Hpy - 1) / bins_per_pix) pixels per axis. For the 45-bin tables at 10 bins per pitch that is 4 pixels, offsets [-2, -1, 0, 1]: the +2 neighbour was never filled, and the response was not mirror-symmetric under a deposit offset u -> -u. Use 2 * (int((Hpy - 1) / bins_per_pix) // 2) + 1 pixels, offsets [-h..h]. The reach on the negative side is unchanged (2 pitches for 45 bins). The furthest lookup, (h + 1/2) pitch, stays inside the table. Callers already index output pixel i as offset i - py_zero_bin, and compute_box_dims derives the box from kernel_py, so no other code changes. Cost: 5x5 instead of 4x4 response entries per deposit (1.56x). Hand-set box_bpy/box_bpz values tuned for the 4-wide kernel (for example, profiler outputs) need +1. Adds tests/test_pixel_kernel_window.py: waveforms at u and -u match under the pixel mirror m -> -m. It fails before this change. --- docs/physics/response-kernels.md | 1 + tests/TESTS.md | 1 + tests/test_pixel_kernel_window.py | 39 +++++++++++++++++++++++++++++++ tools/kernels.py | 9 ++++--- 4 files changed, 47 insertions(+), 3 deletions(-) create mode 100644 tests/test_pixel_kernel_window.py diff --git a/docs/physics/response-kernels.md b/docs/physics/response-kernels.md index 9165850..882db95 100644 --- a/docs/physics/response-kernels.md +++ b/docs/physics/response-kernels.md @@ -114,6 +114,7 @@ design. This drives the whole downstream units convention. | `intensity × kernel →` | **ENC** (electrons) | **ADC** | | Downstream chain | response → electronics → noise → digitize → ADC | response → done (no electronics/noise/digitize) | | Interp routine | `interpolate_diffusion_kernel` | `interpolate_pixel_response_kernel` (+ time rebin) | +| Output window | `num_wires` wires | `2h + 1` pixels per axis, offsets `[-h..h]`, `h` = half the pitches the table covers (5×5 for 45 bins at 10 bins/pitch) | The wire NPZ files carry a misleading `units = 'ADC_per_electron'` / `adc_per_electron` metadata field. **This loader ignores it** and treats the diff --git a/tests/TESTS.md b/tests/TESTS.md index bdd4f21..145d6a1 100644 --- a/tests/TESTS.md +++ b/tests/TESTS.md @@ -178,3 +178,4 @@ The modules above are documented test-by-test; the remaining suites are listed h | test_production_io.py | 14 | Production HDF5 writers/readers (`production/save.py`, `production/load.py`): CSR + delta encoding round-trips | | test_box_track_hits.py | 2 | Box (group-as-bucket) track-hits path | | test_qs_fractions.py | 5 | Per-deposit charge-share fractions (`qs_fractions`) | +| test_pixel_kernel_window.py | 3 | Pixel kernel output window is centred on the deposit pixel: mirror symmetry under u → −u | diff --git a/tests/test_pixel_kernel_window.py b/tests/test_pixel_kernel_window.py new file mode 100644 index 0000000..bced1c7 --- /dev/null +++ b/tests/test_pixel_kernel_window.py @@ -0,0 +1,39 @@ +"""Pixel response output window (tools/kernels.py). + +The output window must be centred on the deposit's pixel: a deposit at +sub-pixel offset u gives on pixel m the same waveform as a deposit at -u +gives on pixel -m. +""" + +import numpy as np +import pytest + +from tools.kernels import (load_pixel_response_kernel, + interpolate_pixel_response_kernel) + +pytestmark = pytest.mark.requires_kernels + +NPZ = "config/pixel_response.npz" +DT = 0.5 # simulation time step, us + + +@pytest.mark.parametrize("u", [0.13, 0.37, 0.49]) +def test_window_is_mirror_symmetric(u): + z = np.load(NPZ) + pitch = 10 * float(z["pixel_bin_size"]) # integer bins per pitch + k = load_pixel_response_kernel( + NPZ, num_s=4, time_spacing=DT, pixel_pitch_cm=pitch, + max_sigma_trans_unitless=0.2, max_sigma_long_unitless=0.0) + + def waveforms(uy): + return np.asarray(interpolate_pixel_response_kernel( + k.DKernel, 1.0, uy, 0.1, 0.0, k.pixel_spacing, + k.kernel_py, k.kernel_pz, k.rebin_factor)) + + pos, neg = waveforms(u), waveforms(-u) + # Output index i is pixel offset i - py_zero_bin; mirror m -> -m. + m = np.arange(k.kernel_py) - k.py_zero_bin + mirror = k.py_zero_bin - m + assert np.all((mirror >= 0) & (mirror < k.kernel_py)), \ + f"window offsets {m.tolist()} are not symmetric about the deposit pixel" + np.testing.assert_allclose(pos, neg[mirror], rtol=0, atol=1e-6) diff --git a/tools/kernels.py b/tools/kernels.py index 4bf69fa..f954044 100644 --- a/tools/kernels.py +++ b/tools/kernels.py @@ -810,10 +810,13 @@ def load_pixel_response_kernel(npz_path, num_s=32, time_spacing=0.5, sigma_trans_bins, sigma_long_bins, response, s_levels) - # Output spatial dimensions (in pixel pitches) + # Output spatial dimensions (in pixel pitches): an odd window centred on + # the deposit's pixel, offsets [-h..h]. h is half the number of pitches + # the table covers, so the furthest lookup, (h + 1/2) pitch, stays inside + # the table (for 45 bins at 10 bins/pitch: h = 2, offsets [-2..2]). bins_per_pix = int(round(pixel_pitch_cm / npz_pixel_bin)) - num_py_out = int((Hpy - 1) / bins_per_pix) - num_pz_out = int((Hpz - 1) / bins_per_pix) + num_py_out = 2 * (int((Hpy - 1) / bins_per_pix) // 2) + 1 + num_pz_out = 2 * (int((Hpz - 1) / bins_per_pix) // 2) + 1 # Output time dimension (in simulation time steps) # After time interpolation: Ht - 1 NPZ bins, then rebin