From d4be47d8da0af14f283f22c1c58f830826091348 Mon Sep 17 00:00:00 2001 From: Patrick Tsang Date: Wed, 11 Nov 2026 13:25:05 -0800 Subject: [PATCH] kernels: read pixel response bins at (k + 1/2) * bin Pixel response NPZ tables (larnd-sim's, and config/pixel_response.npz) sample the quadrant at bin centres, x_k = (k + 1/2) * bin from the pixel centre. interpolate_pixel_response_kernel read bin k at x = k * bin, so every lookup was half a bin too far out. Charge on pixel edges was lost. With 10 bins per pitch and diffusion off, the total charge collected by all output pixels averaged 0.81 of the pad-sum (0.9 per axis), and fell to 0.016 near a pixel corner. - Read distance d (in bins) at max(d - 1/2, 0). Within half a bin of the centre the mirror neighbour of bin 0 is bin 0, so the clip is exact. - Pad the 3-D diffusion table with mode='symmetric' instead of 'reflect'. 'reflect' assumes a sample at the centre; the bin-centre grid has none. The table format and output shapes are unchanged. Gradients with respect to the sub-pixel offset still match finite differences away from the interpolation kinks. Adds tests/test_pixel_kernel_grid.py: total charge equals the pad-sum within 1e-3 at 20x20 offsets, with and without transverse diffusion. It fails before this change. --- docs/physics/response-kernels.md | 9 +++++- tests/TESTS.md | 1 + tests/test_pixel_kernel_grid.py | 51 ++++++++++++++++++++++++++++++++ tools/kernels.py | 21 +++++++------ 4 files changed, 72 insertions(+), 10 deletions(-) create mode 100644 tests/test_pixel_kernel_grid.py diff --git a/docs/physics/response-kernels.md b/docs/physics/response-kernels.md index 9165850..3b77d71 100644 --- a/docs/physics/response-kernels.md +++ b/docs/physics/response-kernels.md @@ -109,7 +109,7 @@ design. This drives the whole downstream units convention. |---|---|---| | Loader | `load_response_kernels` | `load_pixel_response_kernel` | | Table builder | `generate_dkernel_table` (2-D) | `generate_dkernel_table_3d` (3-D) | -| Base kernel shape | `(H, W)` = (time, wire), two-sided | `(Hpy, Hpz, Ht)`, distance-indexed | +| Base kernel shape | `(H, W)` = (time, wire), two-sided | `(Hpy, Hpz, Ht)`, distance-indexed, bin centres | | Kernel value | **Dimensionless field-impulse fraction** | **ADC per drift-electron** (chip gain baked in) | | `intensity × kernel →` | **ENC** (electrons) | **ADC** | | Downstream chain | response → electronics → noise → digitize → ADC | response → done (no electronics/noise/digitize) | @@ -126,5 +126,12 @@ to the simulation time step (`rebin_factor = time_spacing / npz_time_bin`, averaging groups of fine bins to preserve the current *rate*), and interpolates in `(s, pixel_y, pixel_z, time)`. +The pixel NPZ covers one quadrant of the plane and samples it at bin centres: +bin `k` holds the response at `(k + ½)·bin` from the pixel centre, as in the +larnd-sim tables. The lookup reads a distance `d` (in bins) at `d − ½`, clipped +at 0; within half a bin of the centre the mirror neighbour of bin 0 is bin 0 +itself. For the same reason the 3-D table builder pads the spatial axes with +`mode='symmetric'`, which repeats bin 0 when it mirrors the table about the centre. + For the full unit accounting and threshold semantics, see [units](units.md). For the readout-path differences, see [wire vs pixel](../detector/wire-vs-pixel.md). diff --git a/tests/TESTS.md b/tests/TESTS.md index bdd4f21..d19ab6e 100644 --- a/tests/TESTS.md +++ b/tests/TESTS.md @@ -175,6 +175,7 @@ The modules above are documented test-by-test; the remaining suites are listed h | test_pipeline_forward.py | 15 | Differentiable-path forward + finite-difference gradient checks (`forward`/`forward_segments`) | | test_pipeline_forward_slow.py | 12 | Kernel-dependent differentiable-path integration (marked `slow`) | | test_pixel_post_response_truth.py | 16 | Pixel readout post-response truth (`tools/track_hits.py` pixel path) | +| test_pixel_kernel_grid.py | 2 | Pixel kernel lookup on the bin-centre grid: total charge over output pixels equals the pad-sum at every sub-pixel offset | | 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`) | diff --git a/tests/test_pixel_kernel_grid.py b/tests/test_pixel_kernel_grid.py new file mode 100644 index 0000000..3605f7e --- /dev/null +++ b/tests/test_pixel_kernel_grid.py @@ -0,0 +1,51 @@ +"""Pixel response kernel lookup on the bin-centre grid (tools/kernels.py). + +The pixel NPZ samples the quarter plane at x_k = (k + 1/2) * bin from the +pixel centre. Read correctly, the charge collected by all output pixels +equals the table's pad-sum for every sub-pixel deposit offset. +""" + +import numpy as np +import jax +import jax.numpy as jnp +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 +OFFSETS = (np.arange(20) + 0.5) / 20 - 0.5 # 20 sub-pixel offsets in [-0.5, 0.5) + + +def _kernel(sigma_t): + z = np.load(NPZ) + bins_per_pitch = 10 + pitch = bins_per_pitch * 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=sigma_t, max_sigma_long_unitless=0.0) + # Charge collected by the pad: quarter-plane cells inside the pad, x4, + # divided by the cells per pixel. + half = bins_per_pitch // 2 + pad_q = (4 * z["response"][:half, :half].sum() * float(z["time_bin_size"]) + / bins_per_pitch ** 2) + return k, pad_q + + +@pytest.mark.parametrize("sigma_t", [0.0, 0.2]) # transverse sigma, pixel pitches +def test_total_charge_equals_pad_sum_at_every_offset(sigma_t): + k, pad_q = _kernel(sigma_t) + s = 1.0 if sigma_t else 0.0 + + def total_q(u, v): + out = interpolate_pixel_response_kernel( + k.DKernel, s, u, v, 0.0, k.pixel_spacing, + k.kernel_py, k.kernel_pz, k.rebin_factor) + return out.sum() * DT + + grid = jnp.asarray(OFFSETS, dtype=jnp.float32) + q = np.asarray(jax.jit(jax.vmap(jax.vmap(total_q, (None, 0)), (0, None)))(grid, grid)) + np.testing.assert_allclose(q, pad_q, atol=1e-3) diff --git a/tools/kernels.py b/tools/kernels.py index 4bf69fa..ab68279 100644 --- a/tools/kernels.py +++ b/tools/kernels.py @@ -528,10 +528,11 @@ def apply_diffusion_response(DKernel, s_values, wire_offsets, time_offsets, def generate_dkernel_table_3d(sigma_trans_max, sigma_long_max, base_kernel, s_levels): - """Generate 3D diffusion kernel table via reflect padding + spatial convolution. + """Generate 3D diffusion kernel table via symmetric padding + spatial convolution. - Pixel kernel is distance-indexed (bin 0 = pixel center). Uses reflect - padding on the spatial axes (correct boundary: center sample once) and + Pixel kernel is distance-indexed on a bin-centre grid: bin k holds the + response at (k + 1/2) * bin from the pixel center. Uses symmetric padding + on the spatial axes (the mirror of bin 0 about the center is bin 0) and zero-padded time axis. Separable 3D Gaussian convolution via lax.conv_general_dilated. @@ -558,9 +559,9 @@ def generate_dkernel_table_3d(sigma_trans_max, sigma_long_max, ps = ks_s // 2 pt = ks_t // 2 - # Reflect-pad spatial axes (correct center boundary for distance-indexed), + # Symmetric-pad spatial axes (bin-centre grid: no sample at the center), # zero-pad time axis (signal is zero beyond kernel extent) - padded = jnp.pad(base_kernel, ((ps, 0), (ps, 0), (pt, 0)), mode='reflect') + padded = jnp.pad(base_kernel, ((ps, 0), (ps, 0), (pt, 0)), mode='symmetric') padded = padded.at[..., :pt].set(0.) # zero the time reflection def make_level(s): @@ -655,10 +656,12 @@ def interpolate_pixel_response_kernel(DKernel, s_observed, for ipy in range(num_py): for ipz in range(num_pz): - # Distance from deposit to this output pixel, in kernel bins - # py_offset/pz_offset are sub-pixel offsets [-0.5, 0.5) - dist_py = jnp.abs(py_positions[ipy] - py_offset) * bins_per_pixel - dist_pz = jnp.abs(pz_positions[ipz] - pz_offset) * bins_per_pixel + # Distance from deposit to this output pixel, in kernel bins. + # py_offset/pz_offset are sub-pixel offsets [-0.5, 0.5). + # Bin k is sampled at (k + 1/2) bins; within 1/2 bin of the center + # the mirror neighbour of bin 0 is bin 0, so clipping at 0 is exact. + dist_py = jnp.maximum(jnp.abs(py_positions[ipy] - py_offset) * bins_per_pixel - 0.5, 0.0) + dist_pz = jnp.maximum(jnp.abs(pz_positions[ipz] - pz_offset) * bins_per_pixel - 0.5, 0.0) py_left = jnp.clip(jnp.floor(dist_py).astype(int), 0, Hpy - 2) py_right = py_left + 1