Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions tests/TESTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`) |
142 changes: 142 additions & 0 deletions tests/test_pixel_kernel_timing.py
Original file line number Diff line number Diff line change
@@ -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)
35 changes: 25 additions & 10 deletions tools/kernels.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -786,15 +793,29 @@ 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

# 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
Expand Down Expand Up @@ -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,
Expand Down
Loading