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
9 changes: 8 additions & 1 deletion docs/physics/response-kernels.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |
Expand All @@ -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).
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_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`) |
51 changes: 51 additions & 0 deletions tests/test_pixel_kernel_grid.py
Original file line number Diff line number Diff line change
@@ -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)
21 changes: 12 additions & 9 deletions tools/kernels.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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):
Expand Down Expand Up @@ -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
Expand Down