This repository contains the basic scripts and workflows used to generate, diagnose, and evaluate the impact of beam-induced backgrounds on a given detector.
Guinea-Pig is a Monte Carlo simulation program used to model beam–beam interactions in high-energy electron–positron colliders. It simulates the electromagnetic interactions that occur when two intense bunches collide, including beamstrahlung, coherent and incoherent pair production, and the resulting disruption of the beams. Guinea-Pig is a single-core, CPU-based application, which makes it relatively slow for large-scale simulations. Nevertheless, it is widely used and well validated, and its output provides realistic beam-induced background particles that are commonly used as input to detector simulations to study their impact on detector performance and occupancies.
TODO
IPC + luminosity tools
TODO
/ceph/submit/data/group/fcc/ee/beam_backgrounds/guineapig/FCCee_Z_CDR_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/guineapig/FCCee_Z_GHC_V23_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/guineapig/FCCee_Z_4IP_GHC_V24p4_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/guineapig/FCCee_Z_GHC_V25p1_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/guineapig/FCCee_Z_GHC_V25p3_4_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/guineapig/FCCee_Z_LCC_V105_FCCee_Z256_2T_grids8
WarpX is a high-performance particle-in-cell (PIC) simulation framework designed to model beam dynamics and electromagnetic fields in accelerator and plasma-based systems. In the context of beam-induced background studies, WarpX can simulate the time-dependent electromagnetic fields of colliding bunches and self-consistently track charged particles through these fields. Unlike Guinea-Pig, WarpX is designed for massively parallel execution, supporting multi-core CPUs and GPU acceleration, which makes it significantly faster and more scalable for large simulations. The detailed phase-space information produced by WarpX can then be used as input to detector simulations to assess the impact of beam-induced backgrounds.
TODO
Both Guinea-Pig and WarpX generate incoherent pair creation (IPC) particles that propagate toward the detector. A significant fraction of these particles reach the innermost detector components, in particular the vertex detector, which is located very close to the beam pipe (radius ~ 10 mm).
To model the detector response to these particles, we use Geant4, which provides a detailed simulation of the full detector geometry and materials. Geant4 takes the generated particles as input and simulates their interactions with the detector elements. The output of this simulation is a collection of so-called simHits, corresponding to energy deposits produced by the primary particles as they traverse sensitive detector volumes. These energy deposits represent the first step toward a measurable detector signal.
In this example, we focus on the CLD vertex detector, which consists of three cylindrical barrel layers located at radii of approximately 13, 35, and 57 mm. The IPC particles intersect these layers and produce simHits, which we will analyze in the following sections.
For each Guinea-Pig or WarpX file produced—corresponding to a single bunch crossing—we generate the detector response using Geant4. Since a large number of input files must be processed, we use HTCondor to submit the jobs in parallel. Each input file is handled by a separate job, which produces a ROOT output file containing the full simulated detector response.
TODO
Each ROOT file corresponds to a single bunch crossing and typically contains O(1000) IPC particles. In total, about 10 000 bunch crossings were simulated. We analyse the full dataset by processing all ROOT files simultaneously using ROOT RDataFrame, which provides a convenient and efficient interface for columnar data analysis.
The script below loops over all input ROOT files and extracts basic properties of the beam-induced background particles, as well as information on their interactions with the innermost layer of the vertex detector.
source /cvmfs/sw.hsf.org/key4hep/setup.sh -r 2025-05-29 # to be done once per session
python analysis/analysis_CLD.py
In the input configuration, you specify the directory containing the ROOT files produced in the previous step. The analysis then writes its results to an output ROOT file, which contains all histograms defined in analysis_CLD.py.
The histograms can be plotted using the following script:
python analysis/plots.py
For a given input ROOT file, the script produces a series of plots, including:
- The multiplicity and kinematic properties of the IPC particles (momentum, angles, energy, etc.).
- The multiplicity of simHits in the different vertex-detector layers.
- Spatial hit distributions on the innermost vertex layer.
- Energy deposition and dE/dx.
The same plotting script also provides functionality to compare two or more configurations within a single plot, enabling direct performance comparisons.
/ceph/submit/data/group/fcc/ee/beam_backgrounds/ddsim/CLD_o2_v07/FCCee_Z_CDR_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/ddsim/CLD_o2_v07/FCCee_Z_GHC_V23_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/ddsim/CLD_o2_v07/FCCee_Z_4IP_GHC_V24p4_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/ddsim/CLD_o2_v07/FCCee_Z_GHC_V25p1_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/ddsim/CLD_o2_v07/FCCee_Z_GHC_V25p3_4_FCCee_Z256_2T_grids8
/ceph/submit/data/group/fcc/ee/beam_backgrounds/ddsim/CLD_o2_v07/FCCee_Z_LCC_V105_FCCee_Z256_2T_grids8