Voxelization

class larndsim.far_field.voxelization.VoxelDict

Bases: TypedDict

x: cupy.typing.NDArray.cupy.float32 | None

y: cupy.typing.NDArray.cupy.float32 | None

z: cupy.typing.NDArray.cupy.float32 | None

q: cupy.typing.NDArray.cupy.float32 | None

larndsim.far_field.voxelization.voxel_id_to_coordinates(voxel_indices, grid_shape, voxel_size, bounds)

Convert flattened voxel indices to physical (x, y, z) center coordinates.

Parameters:

• voxel_indices (cupy.typing.NDArray.cupy.int32) – 1D array of flattened voxel indices

• grid_shape (tuple[int, int, int]) – (nx, ny, nz) tuple

• voxel_size (tuple[float, float, float]) – (dx, dy, dz) tuple in cm

• bounds (tuple[tuple[float, float], tuple[float, float], tuple[float, float]]) – ((x_min, x_max), (y_min, y_max), (z_min, z_max)) in cm

Returns:

NumPy arrays of voxel center coordinates in cm

Return type:

(x_centers, y_centers, z_centers)

larndsim.far_field.voxelization.gpu_voxelize(tracks, tpc_borders=None, voxel_size=None, z_padding=0.0)

Voxelize track segments on GPU.

Parameters:

• tracks (cupy.typing.NDArray) – structured track array (fields: x_start, y_start, z_start, x_end, y_end, z_end, n_electrons, pixel_plane, …)

• tpc_borders (numpy.typing.NDArray | None) – TPC borders override (optional; defaults to detector.TPC_BORDERS)

• voxel_size (float | None) – Voxel size override (optional; defaults to using voxel size from ff_induction)

• z_padding (float) – Extra padding on the range of drift coordinates to cover

Returns:

(voxel_indices, voxel_charges, grid_shape, voxel_size, bounds) where voxel_indices & voxel_charges are 1D CuPy arrays for non-zero voxels.

Return type:

tuple[cupy.typing.NDArray.cupy.int32, cupy.typing.NDArray.cupy.float32, tuple[float, float, float], float, tuple[tuple[float, float], tuple[float, float], tuple[float, float]]]

larndsim.far_field.voxelization.voxelize_segments_kernel(tracks, voxel_charges, voxel_size, bounds, grid_shape)

CUDA kernel for fast voxelization of track segments.

Parallelizes the voxelization process across segments.

Parameters:

• tracks (cupy.typing.NDArray) – structured track array (fields: x_start, y_start, z_start, x_end, y_end, z_end, n_electrons, pixel_plane, …)

• voxel_charges (cupy.typing.NDArray.cupy.float32) – (n_voxels,) output array for voxel charges (flattened 3D grid)

• voxel_size (cupy.typing.NDArray.cupy.float32) – (dx, dy, dt) voxel dimensions

• bounds (cupy.ndarray.(tuple[int, int], cupy.float32)) – ((x_min, x_max), (y_min, y_max), (z_min, z_max))

• grid_shape (cupy.typing.NDArray.cupy.int32) – (nx, ny, nt) grid dimensions

larndsim.far_field.voxelization.get_voxel_cache(tracks)

Get cache of voxels for each TPC.

Parameters:

tracks (cupy.typing.NDArray) – structured track array (fields: x_start, y_start, z_start, x_end, y_end, z_end, n_electrons, pixel_plane, …)

Returns:

Dict from TPC index to a VoxelDict

Return type:

dict[int, VoxelDict]