Introduction

Lorenzetti is a dedicated HEP framework conceptualized to streamline the Research & Development (R&D) of calorimetry signal processing, reconstruction, and triggering algorithms. While modern LHC experiments rely on massive, monolithic software stacks, Lorenzetti provides a lightweight, modular, and stand-alone environment that grants researchers direct access to high-fidelity simulation data. Built upon the robust Geant4 toolkit, Lorenzetti simulates the complete physics of particle showers within complex detector geometries. However, unlike general-purpose simulators, it focuses deeply on the readout chain: transforming raw energy deposits into realistic electronic pulses, digitizing them, and reconstructing the original particle properties.

This framework addresses a critical gap in the community: Access to quality data. Experiment-specific data is often restricted or difficult to generate for outsiders. Lorenzetti democratizes this by establishing a standard reference for:

• Algorithm Development: Fast prototyping of filters (Optimal Filtering, Wiener), clustering algorithms, and jet reconstruction.

• Machine Learning: Generating massive, labelled datasets ideal for training Neural Networks (e.g., for anomaly detection, pileup mitigation, or super-resolution).

• Trigger Studies: Simulating hardware-level constraints to test fast decision-making logic.

Advanced Pileup Simulation via Overlay

One of Lorenzetti’s most defining features is its ability to realistically simulate high-luminosity environments through a sophisticated Overlay Strategy. High Energy Physics experiments often face the challenge of Pileup—multiple proton-proton collisions occurring simultaneously. Lorenzetti accurately models this by overlaying background “Minimum Bias” events onto the signal event of interest.

Crucially, it handles both In-Time Pileup (simultaneous collisions) and Out-of-Time Pileup (signals from previous or subsequent bunch crossings that distort the current measurement). This is achieved by convolving the energy deposits with the detector’s realistic electronic pulse shapes over a configurable time window. This setup provides a perfect playground for developing cutting-edge Pileup Mitigation algorithms (e.g., using timing information or deep learning) to recover clean signals from high-noise backgrounds, mimicking the harsh conditions of the HL-LHC.

Described fully in Computer Physics Communications (2023), Lorenzetti serves as a “virtual testbeam,” enabling the scientific community to validate novel ideas independently of major collaborations.

Citations

Please cite the following paper if you use the software:

Lorenzetti Showers: A general-purpose framework for supporting signal reconstruction and triggering with calorimeters Computer Physics Communications, Volume 286, 2023, 108671. DOI: 10.1016/j.cpc.2023.108671

Directory Structure

Here is an overview of the repository structure:

📂 lorenzetti/
├── 📂 core/             # Core libraries, utilities, and common tools.
├── 📂 events/           # Event data models (EDM) and ROOT I/O handling definitions.
├── 📂 generator/        # Physics event generator interfaces (e.g., Pythia8).
├── 📂 geometry/         # Detector geometry construction and definitions using Geant4.
├── 📂 reconstruction/   # Algorithms for signal processing and object reconstruction.
├── 📂 docs/             # Documentation, guides, and Jupyter notebook tutorials.
├── 📂 examples/         # Scripts and configuration examples for large-scale productions.
├── 📂 ci_tests/         # Continuous Integration checks and validation workflows.
├── 📄 CMakeLists.txt    # Main CMake configuration file.
├── 📄 Makefile          # Shortcut commands for building and testing.

Installation

The recommended way to use Lorenzetti is via pre-built container images (Docker or Singularity), which come with all dependencies pre-installed.

Singularity (Recommended)

singularity pull docker://lorenzetti/lorenzetti:latest
singularity run lorenzetti_latest.sif

Manual Build

For development, you can clone and build the source inside the container:

git clone https://github.com/lorenzetti-ufrj-br/lorenzetti.git && cd lorenzetti
make
source build/lzt_setup.sh

Validation

Lorenzetti is rigorously tested using Github Actions. The validation workflow includes:

1. Event Generation: gen_zee.py, gen_jets.py, gen_minbias.py

2. Simulation: simu_trf.py (Hit generation)

3. Merging: merge_trf.py (Pileup mixing)

4. Digitalization: digit_trf.py (Electronic signal simulation)

5. Reconstruction: reco_trf.py (Object reconstruction)

6. Analysis: ntuple_trf.py (Root Ntuple dumping)

Detector Construction (Version 1)

The standard detector in Lorenzetti aims to mimic the properties of modern high-granularity calorimeters used in LHC experiments (such as ATLAS). It is constructed as a cylindrical 4π detector with two main systems:

Figure 1: Lorenzetti Detector Geometry showing ECAL and HCAL layers (Simplified).

Front View

Lateral View

Electromagnetic Calorimeter (ECAL)

A sampling calorimeter designed to measure electrons and photons with high precision.

• Material: Lead (Pb) absorber plates interleaved with Liquid Argon (LAr) as the active medium.

• Structure: * Pre-Sampler: A thin layer to correct for energy loss upstream. * Layer 1 (Strips): Finely segmented (Δη ≈ 0.003) for π⁰/γ separation. * Layer 2 (Middle): The thickest layer (55 radiation lengths) containing most of the shower energy. * Layer 3 (Back): Estimates energy leakage into the hadronic calorimeter.

Hadronic Calorimeter (HCAL)

Located outside the ECAL, this sampling calorimeter measures jets and missing energy.

• Material: Iron (Fe) absorber plates with Plastic Scintillator tiles.

• Structure: Divided into 3 longitudinal layers with coarser granularity (Δη × Δφ ≈ 0.1 × 0.1).

Detector Layers & Granularity

System	Layer	Name	Material	Granularity (Δη × Δφ)
ECAL (Barrel)	0	Pre-Sampler	LAr / Pb	0.025 × 0.1
	1	Front (Strips)	LAr / Pb	0.003125 × 0.1
	2	Middle	LAr / Pb	0.025 × 0.025
	3	Back	LAr / Pb	0.050 × 0.025
TileCal (Barrel)	1	Front	Scint. / Fe	0.1 × 0.1
	2	Middle	Scint. / Fe	0.1 × 0.1
	3	Back	Scint. / Fe	0.2 × 0.1
EMEC (EndCap)	0	Pre-Sampler	LAr / Pb	0.025 × 0.1
	1	Front	LAr / Pb	varies (0.003-0.006) × 0.1
	2	Middle	LAr / Pb	0.025 × 0.025 / 0.1 × 0.1
	3	Back	LAr / Pb	0.050 × 0.025 / 0.1 × 0.1
HEC (EndCap)	1-3	All Layers	LAr / Cu	0.1 × 0.1 / 0.2 × 0.2

The geometry is highly customizable via Python scripts, allowing users to modify layer depths, material composition, and segmentation without recompiling the C++ core.

Contribution

We welcome everyone to contribute! 🌍 Whether it’s fixing bugs, adding new generators, or improving documentation.

1. Fork the repository.

2. Create your feature branch (git checkout -b feature/AmazingFeature).

3. Commit your changes.

4. Open a Pull Request.

Please ensure your code passes existing tests.

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.