Processing

Functions:

batch_to_Exyz(batch)	Transforms the cylindrical coordinate representation (z, alpha, r) in a batch of graphs to Cartesian coordinates (x, y, z), and calculates pseudo-rapidity (eta) and azimuthal angle (phi) for each node in the graph.
pc_to_voxel(batch)	Converts a pytorch geometric batch of point clouds into a torch batch of 3D voxel grids.
shift_multi_hits(batch[, globalidx, ...])	Shifts hits that belong to the same cell, to neighboring, empty cells, if available.
shift_sum_multi_hits(batch[, forbid_dublicates])	Faster combination of shift_sum_multi_hits and shift_sum_multi_hits.
sum_multi_hits(batch[, globalidx, ...])	Sums the energy of duplicate hits in the same cell for each event.
voxel_to_pc(voxel, Einc)	Converts a 3D voxel tensor representation of a particle shower into a hit cloud (pc).

caloutils.processing.batch_to_Exyz(batch: <Mock name='mock.Batch' id='140552768441696'>) → <Mock name='mock.Batch' id='140552768441696'>

Transforms the cylindrical coordinate representation (z, alpha, r) in a batch of graphs to Cartesian coordinates (x, y, z), and calculates pseudo-rapidity (eta) and azimuthal angle (phi) for each node in the graph.

Parameters

batchBatch

The batch of graphs where each node feature vector includes a cylindrical coordinate representation (Energy, z, alpha, r) where z is the long axis of the cylindrical coordinate system, alpha is the azimuthal angle, and r is the radial distance from the z-axis.

Returns

batchBatch

The modified batch object where an additional “xyz” attribute is added which includes the Cartesian coordinates for each node in the graphs. Additionally, “eta” (pseudo-rapidity) and “phi” (azimuthal angle) attributes are calculated and added to the batch object.

Note

Pseudo-rapidity (eta) and azimuthal angle (phi) are commonly used in particle physics to describe the direction of a particle relative to the beam axis (z-axis in this context).

caloutils.processing.pc_to_voxel(batch: <Mock name='mock.Batch' id='140552768441696'>) → <Mock name='mock.Tensor' id='140552768372112'>

Converts a pytorch geometric batch of point clouds into a torch batch of 3D voxel grids.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events.

Returns

torch.Tensor

A tensor of shape (batch_size, num_z, num_alpha, num_r), where each element represents the energy in the corresponding voxel.

caloutils.processing.shift_multi_hits(batch: <Mock name='mock.Batch' id='140552768441696'>, globalidx: <Mock name='mock.Tensor' id='140552768372112'> | None = None, return_globalidx: bool = False)

Shifts hits that belong to the same cell, to neighboring, empty cells, if available. Leaves the highest energy hit in the cell and prioritizes moving the 2nd most energetic (then 3rd most …) hit. The function modifies the batch in place, updating batch.x, batch.batch, and batch.ptr.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events. Batch.x contains the hit energy and 3D coordinates of hits. Batch.batch contains the indices that map which hit belongs to which shower.

forbid_dublicatesbool, optional

If True, asserts that there were no duplicate hits in the original data. Defaults to True.

Returns

batchBatch

The modified Batch object where duplicate hits have been summed.

caloutils.processing.shift_sum_multi_hits(batch, forbid_dublicates=False)

Faster combination of shift_sum_multi_hits and shift_sum_multi_hits. First shifts hits assigned to the same cell to empty neigboring cells, then sums the energy of then hits remaining in the same cell. If forbid_dublicates=False, the function also verifies that there were no duplicate hits in the original data. The function modifies the batch in place, updating batch.x, batch.batch, and batch.ptr.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events. Batch.x contains the hit energy and 3D coordinates of hits. Batch.batch contains the indices that map which hit belongs to which shower.

forbid_dublicatesbool, optional

If True, asserts that there were no duplicate hits in the original data. Defaults to True.

shiftmultihitbool, optional

If True, tries to move hits from overfilled cells to neighboring empty cells. Defaults to True.

Returns

batchBatch

The modified Batch object where duplicate hits have been summed.

caloutils.processing.sum_multi_hits(batch: <Mock name='mock.Batch' id='140552768441696'>, globalidx: <Mock name='mock.Tensor' id='140552768372112'> | None = None, forbid_dublicates: bool = False)

Sums the energy of duplicate hits in the same cell for each event. If fake=False, the function also verifies that there were no duplicate hits in the original data. The function modifies the batch in place, updating batch.x, batch.batch, and batch.ptr.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events. Batch.x contains the hit energy and 3D coordinates of hits. Batch.batch contains the indices that map which hit belongs to which shower.

forbid_dublicatesbool, optional

If True, asserts that there were no duplicate hits in the original data. Defaults to True.

Returns

batchBatch

The modified Batch object where duplicate hits have been summed.

caloutils.processing.voxel_to_pc(voxel: <Mock name='mock.Tensor' id='140552768372112'>, Einc: <Mock name='mock.Tensor' id='140552768372112'>) → <Mock name='mock.Batch' id='140552768441696'>

Converts a 3D voxel tensor representation of a particle shower into a hit cloud (pc). The conversion is done by finding all non-zero elements in the voxel tensor, storing their values and their coordinates in 3D space, and grouping them by shower.

Parameters

voxelTensor

A 4D tensor representing multiple particle showers in pc_to_voxeld format. Dimensions are (num_showers, num_z, num_alpha, num_r).

EincTensor

A 1D tensor representing containing the incoming energy of each shower. Dimensions are (num_showers,).

Returns

batch: Batch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the showers, where: - batch.batch is a 1D tensor where each element is the ID of the shower the corresponding point in the point cloud belongs to. - batch.x is a 3D tensor where each row represents a hit in the point cloud, with the columns being the value of the voxel and its 3D coordinates (r, alpha, z). - batch.y is a 2D tensor where each row represents the incoming energy of the shower and the number of non-zero voxels (hits) in it.

Raises

AssertionError

If there are NaN values in the point cloud tensor x.