From f1925557c4818319b85a2fc572b7cbaf1b6b9f85 Mon Sep 17 00:00:00 2001 From: Pierre Granger Date: Thu, 19 Nov 2026 23:07:54 +0100 Subject: [PATCH] fix: pixel kernel sub-tick time shift runs backwards when rebinning interpolate_pixel_response_kernel delays the fine (NPZ-resolution) trace by the sub-bin fraction, then applied jnp.roll(-t_sub_bin), which moves it EARLIER by the whole-bin part of the offset. With rebin_factor > 1 (any tick coarser than the 0.1 us NPZ bin, e.g. the default 0.5 us) the signal time is a sawtooth in the deposit's arrival time: 0.85 us peak-to-peak on the ND-LAr preset. rebin_factor = 1 (0.1 us tick) is unaffected. - Delay by +t_sub_bin with zero fill (no wrap-around of the tail). - Align the rebin groups with the simulation ticks: prepend (1 - time_zero_bin_npz) % rebin_factor zero time bins so that the arrival bin minus one is a multiple of rebin_factor. Without this the arrival lands ((time_zero_bin_npz - 1) % rebin_factor) NPZ bins late (0.4 us for the shipped response at 0.5 us). The placed kernel output now equals the tick average of the response arriving at the true time. kernel_time grows by one tick when padding is needed (69 -> 70 for the shipped response at 0.5 us). tests: test_pixel_kernel_timing.py (exact comparison with the delayed response at rebin 1 and 5, centroid linearity, d/d(arrival) continuity and finite differences across tick and NPZ-bin boundaries). --- tests/TESTS.md | 1 + tests/test_pixel_kernel_timing.py | 142 ++++++++++++++++++++++++++++++ tools/kernels.py | 35 +++++--- 3 files changed, 168 insertions(+), 10 deletions(-) create mode 100644 tests/test_pixel_kernel_timing.py diff --git a/tests/TESTS.md b/tests/TESTS.md index bdd4f21..3feb698 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_timing.py | 7 | Pixel kernel sub-tick timing (`tools/kernels.py`): placed output equals the tick-averaged response at the true arrival time, centroid linearity, d/d(arrival) vs finite differences | | 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_timing.py b/tests/test_pixel_kernel_timing.py new file mode 100644 index 0000000..8300564 --- /dev/null +++ b/tests/test_pixel_kernel_timing.py @@ -0,0 +1,142 @@ +""" +Sub-tick timing of the pixel response kernel. + +The pixel response NPZ is at a finer time resolution (0.1 us) than the +simulation tick, so ``interpolate_pixel_response_kernel`` shifts the trace by +the deposit's sub-tick offset and then rebins it. These tests place the kernel +output on the global time axis exactly as the simulator does +(``global_tick = time_index - time_zero_bin + j``) and check it against the +response delayed to the true arrival time. + +Files under test: tools/kernels.py (load_pixel_response_kernel, +interpolate_pixel_response_kernel) +""" + +import jax +import jax.numpy as jnp +import numpy as np +import pytest + +from tools.kernels import load_pixel_response_kernel, interpolate_pixel_response_kernel + + +NPZ_DT = 0.1 # us, NPZ time bin +N_GLOBAL = 64 # global ticks used to place the kernel output + + +def _write_npz(path, arrival_bin, n_time=48, shape="ramp"): + """Synthetic distance-indexed pixel response, 10 bins per pixel. + + Centre-pixel current over the 20 NPZ bins before arrival (integral 1 + electron per electron), zero after arrival: an asymmetric ramp, or a + smooth Gaussian (sigma 0.3 us) for which the tick-centre centroid of the + rebinned signal has no visible binning error. + """ + resp = np.zeros((15, 15, n_time)) + k = np.arange(arrival_bin - 20, arrival_bin) + if shape == "ramp": + pulse = (k - k[0] + 1.0) ** 2 + else: + pulse = np.exp(-0.5 * ((k - k.mean()) / 3.0) ** 2) + pulse /= pulse.sum() * NPZ_DT + resp[:5, :5, k] = pulse + np.savez(path, response=resp, pixel_bin_size=0.04, time_bin_size=NPZ_DT, + drift_time=arrival_bin * NPZ_DT) + return pulse, k + + +def _place(pk, tick_us, dt): + """Centre-pixel kernel output placed on the global tick axis (simulator rule).""" + time_index = jnp.floor(tick_us / dt).astype(jnp.int32) + t_offset = tick_us / dt - time_index + out = interpolate_pixel_response_kernel( + pk.DKernel, 0.0, 0.0, 0.0, t_offset, pk.pixel_spacing, + 3, 3, pk.rebin_factor)[1, 1] + idx = time_index - pk.time_zero_bin + jnp.arange(out.shape[0]) + return jnp.zeros(N_GLOBAL).at[idx].add(out) + + +def _expected(pulse, k, arrival_bin, tick_us, dt): + """Exact tick average of the piecewise-constant response delayed to arrive at tick_us.""" + edges = np.arange(N_GLOBAL + 1) * dt + out = np.zeros(N_GLOBAL) + for v, kk in zip(pulse, k): + lo = tick_us + (kk - arrival_bin) * NPZ_DT + overlap = np.clip(np.minimum(edges[1:], lo + NPZ_DT) - np.maximum(edges[:-1], lo), 0, None) + out += v * overlap / dt + return out + + +@pytest.mark.parametrize("arrival_bin", [33, 36]) +@pytest.mark.parametrize("rebin", [1, 5]) +def test_kernel_matches_delayed_response(tmp_path, arrival_bin, rebin): + """Placed kernel output equals the tick-averaged response arriving at tick_us. + + Sweeps the arrival over three ticks. arrival_bin 33 and 36 give the two + phases (arrival_bin - 1) % 5 = 2 and 0 of the NPZ time origin. + """ + path = tmp_path / "pixel_response.npz" + pulse, k = _write_npz(path, arrival_bin) + dt = NPZ_DT * rebin + pk = load_pixel_response_kernel(str(path), num_s=4, time_spacing=dt, pixel_pitch_cm=0.4) + for tick_us in 20 * dt + np.linspace(0.0, 3 * dt, 31): + got = np.asarray(_place(pk, float(tick_us), dt)) + want = _expected(pulse, k, arrival_bin, tick_us, dt) + np.testing.assert_allclose(got, want, atol=1e-5 * want.max(), + err_msg=f"tick_us={tick_us:.3f}") + + +def test_centroid_follows_arrival(tmp_path): + """Signal centroid minus arrival time is constant across a tick (0.5 us tick). + + The expected offset is the centroid of the response relative to its + arrival. Tolerance 0.005 us (1 % of a tick). + """ + arrival_bin = 33 + path = tmp_path / "pixel_response.npz" + pulse, k = _write_npz(path, arrival_bin, shape="gauss") + dt = 0.5 + pk = load_pixel_response_kernel(str(path), num_s=4, time_spacing=dt, pixel_pitch_cm=0.4) + c_resp = np.sum(pulse * ((k + 0.5 - arrival_bin) * NPZ_DT)) / pulse.sum() + t_mid = (np.arange(N_GLOBAL) + 0.5) * dt + resid = [] + for tick_us in 10.0 + np.linspace(0.0, 2 * dt, 41): + sig = np.asarray(_place(pk, float(tick_us), dt)) + resid.append(np.sum(sig * t_mid) / sig.sum() - (tick_us + c_resp)) + resid = np.array(resid) + assert np.abs(resid).max() < 0.005, resid + + +class TestTimingGradient: + """d(signal)/d(arrival time) is finite and matches finite differences.""" + + @pytest.fixture + def setup(self, tmp_path): + """Kernel built in float32 as in production; evaluated in float64 so the + finite differences converge (see test_pipeline_forward.py).""" + path = tmp_path / "pixel_response.npz" + _write_npz(path, 33) + dt = 0.5 + pk = load_pixel_response_kernel(str(path), num_s=4, time_spacing=dt, pixel_pitch_cm=0.4) + was_enabled = jax.config.jax_enable_x64 + jax.config.update("jax_enable_x64", True) + w = jnp.asarray(np.random.RandomState(0).normal(size=N_GLOBAL)) + yield (lambda t: jnp.sum(w * _place(pk, jnp.float64(t), dt))), dt + jax.config.update("jax_enable_x64", was_enabled) + + def test_continuous_across_tick_boundary(self, setup): + f, dt = setup + t_b = 21 * dt + for eps in (1e-4, 1e-6): + assert abs(float(f(t_b - eps)) - float(f(t_b + eps))) < 100 * eps + + def test_grad_matches_fd_near_boundaries(self, setup): + f, dt = setup + h = 1e-5 + # either side of a tick boundary and of an NPZ-bin boundary inside a tick + for t in (21 * dt - 3 * h, 21 * dt + 3 * h, 21 * dt + 0.2 - 3 * h, 21 * dt + 0.2 + 3 * h, + 21 * dt + 0.137): + g = float(jax.grad(f)(jnp.float64(t))) + fd = (float(f(t + h)) - float(f(t - h))) / (2 * h) + assert np.isfinite(g) + assert g == pytest.approx(fd, rel=1e-4, abs=1e-6), (t, g, fd) diff --git a/tools/kernels.py b/tools/kernels.py index 4bf69fa..34e388d 100644 --- a/tools/kernels.py +++ b/tools/kernels.py @@ -692,11 +692,18 @@ def interpolate_pixel_response_kernel(DKernel, s_observed, interpolated = t_alpha * v_interp[:-1] + (1 - t_alpha) * v_interp[1:] output_fine = output_fine.at[ipy, ipz, :].set(interpolated) + # The sub-bin interpolation above delays the trace by (t_alpha - 1) NPZ + # bins; delay it by t_sub_bin more whole bins (zero-filled, no wrap) so the + # arrival lands t_offset * rebin_factor NPZ bins into the rebin group that + # holds it (see time_zero_bin in load_pixel_response_kernel). + Ht_sim = Ht_interp // rebin_factor + fine_idx = jnp.arange(Ht_interp) + shifted = jnp.where(fine_idx >= t_sub_bin, + jnp.roll(output_fine, t_sub_bin, axis=-1), 0.0) + # Rebin time axis: average groups of rebin_factor NPZ bins → simulation bins # Kernel stores signal rate (current per unit time). Averaging preserves # the rate when changing bin width — matches pixlar's slice_and_merge. - Ht_sim = Ht_interp // rebin_factor - shifted = jnp.roll(output_fine, -t_sub_bin, axis=-1) truncated = shifted[:, :, :Ht_sim * rebin_factor] output = truncated.reshape(num_py, num_pz, Ht_sim, rebin_factor).mean(axis=-1) @@ -786,8 +793,6 @@ def load_pixel_response_kernel(npz_path, num_s=32, time_spacing=0.5, npz_pixel_bin = float(data['pixel_bin_size']) npz_time_bin = float(data['time_bin_size']) - Hpy, Hpz, Ht = response.shape - # pixel_spacing: NPZ bin / pixel pitch (unitless ratio, like wire_spacing) # bins_per_pixel = 1 / pixel_spacing ≈ pixel_pitch / npz_bin pixel_spacing = npz_pixel_bin / pixel_pitch_cm @@ -795,6 +800,22 @@ def load_pixel_response_kernel(npz_path, num_s=32, time_spacing=0.5, # Rebin factor: how many NPZ time bins per simulation time step rebin_factor = int(round(time_spacing / npz_time_bin)) + # Time zero: the charge arrives at the start of NPZ bin time_zero_bin_npz. + # After the sub-bin time interpolation (-1, same as wire) and the whole-bin + # delay in interpolate_pixel_response_kernel, a deposit with time offset f + # arrives at fine index (time_zero_bin_npz - 1) + f * rebin_factor. + # Prepend zero time bins so that time_zero_bin_npz - 1 is a multiple of + # rebin_factor: the rebin groups then line up with the simulation ticks and + # the arrival falls exactly f into output bin time_zero_bin_out. + t_start_us = float(data['drift_time']) + time_zero_bin_npz = int(round(t_start_us / npz_time_bin)) + t_pad = (1 - time_zero_bin_npz) % rebin_factor + response = jnp.pad(response, ((0, 0), (0, 0), (t_pad, 0))) + time_zero_bin_npz += t_pad + time_zero_bin_out = (time_zero_bin_npz - 1) // rebin_factor + + Hpy, Hpz, Ht = response.shape + s_levels = jnp.linspace(0.0, 1.0, num_s) # Convert max sigmas from detector units to NPZ kernel bin units @@ -823,12 +844,6 @@ def load_pixel_response_kernel(npz_path, num_s=32, time_spacing=0.5, py_zero_bin = num_py_out // 2 pz_zero_bin = num_pz_out // 2 - # Time zero bin: convert from NPZ bins to simulation time steps - t_start_us = float(data['drift_time']) - time_zero_bin_npz = int(round(t_start_us / npz_time_bin)) - # -1 for time interpolation (same as wire), then convert to sim bins - time_zero_bin_out = (time_zero_bin_npz - 1) // rebin_factor - return PixelResponseKernel( DKernel=DKernel, kernel_py=num_py_out,