Welcome to caloutils!

Metrics and tools for evaluation of generative models for calorimeter showers based on pytorch_geometric.

• Free software: MIT license
• Documentation: https://caloutils.readthedocs.io.
• Github: https://github.com/DeGeSim/caloutils
• PyPi: https://pypi.org/project/caloutils

Summary

caloutils is a Python package built to simplify and streamline the handling, processing, and analysis of 4D point cloud data derived from calorimeter showers in high-energy physics experiments. The package includes a set of sophisticated tools to perform voxelization, energy response calculations, geometric feature extraction, and more. caloutils aims to simplify the complex analysis pipeline for calorimeter shower data, enabling researchers to efficiently extract meaningful insights. As this tool is based on Point Clouds, the provided metrics should apply to any calorimeter.

Description

4D Point Clouds

The 4D point cloud data handled by caloutils consists of three spatial coordinates and a fourth dimension representing the energy deposited at each point in the calorimeter. This multidimensional dataset captures a comprehensive view of particle showers, serving as a valuable resource in experimental physics.

Key Features

caloutils offers a comprehensive suite of functions and methods to analyze these 4D point clouds:

• Voxelization: The package provides functionalities to convert raw, continuous point clouds into a to a voxel representation. This regular structure can simplifie subsequent analysis or machine learning tasks.
• Energy Response Calculation: Calculate the detector response for a calorimeter shower by summing the hit energies and normalizing by the incoming energy of the particle.
• Geometric Feature Extraction: The package offers tools to calculate geometric features such as the first principal component, spherical ratios, and more.
• Data Transformation: caloutils can transform data from cylindrical to Cartesian coordinates, calculate pseudorapidity and azimuthal angle, and efficiently handle batch data operations.

Installation

You can easily install caloutils via pip:

$ pip install caloutils

Usage

First, the used calorimeter geometry needs to be selected:

import caloutils
caloutils.init_calorimeter("cc_ds2")

For now only dataset 2 and 3 of the Calochallenge<https://github.com/CaloChallenge/homepage> are implemented

1. Convert Voxelized Data to Point Cloud

import caloutils
# Convert the point cloud data into a voxel representation.
batch = caloutils.processing.voxel_to_pc(shower, energies)

batch is an instance of a PyTorch Geometric Batch object, storing the point cloud data

2. Data Transformation

Transform the cylindrical coordinates to Cartesian coordinates and add pseudorapidity and azimuthal angle:

batch_transformed = caloutils.batch_to_Exyz(batch)

These examples are meant to be illustrative and provide a quick understanding of the package usage. For a more comprehensive understanding of each function's intricacies, users are recommended to refer to the full function documentation in the package.

3. Calculate High Level Variables

# Calculate the energy response of a batch of showers.
energy_response = caloutils.variables.energy_response(batch)
# Calculate the principal component of a batch of showers.
first_principal_component = caloutils.variables.fpc_from_batch(batch)
# Or, all at once, stored as attributes of the batch:
batch=caloutils.variables.calc_vars(batch)
print(batch.cyratio.mean())

(Moritz Scham had been funded by Helmholtz Association’s Initiative and Networking Fund through Helmholtz AI (grant number: ZT-I-PF-5-3). This research was supported in part through the Maxwell computational resources operated at Deutsches Elektronen-Synchrotron DESY (Hamburg, Germany). The authors acknowledge support from Deutsches Elektronen-Synchrotron DESY (Hamburg, Germany), a member of the Helmholtz Association HGF.)