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