Skip to content

Improve endcap sampling fraction calculation tutorial #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jacofan wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Improve endcap sampling fraction calculation tutorial #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7fa559b
Use K4GEO environment variable
Feb 20, 2026
26d02fa
Update README
Feb 20, 2026
689954a
Modify empirical determination README
Mar 5, 2026
534a0a4
Fix typo
Mar 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 62 additions & 30 deletions sampling_fractions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,81 @@
# Recipes to update sampling fractions
# Recipes to update Endcap sampling fractions

## Barrel

## Endcap

There are two different approaches available for the endcap, one based on a direct assessment of the sampling fraction of each cell, and one based on an empirical determination of the calibration constant for each cell.

### Direct assessment of sampling fractions
For the direct assessment, one follows a procedure similar to that used for the barrel. First, run a set of single particles using the *calib* version of the detector xml file, where the absorbers and readout PCBs are set to sensitive. You only need to run the simulation step, not reconstruction. Then run:

k4run fcc_ee_samplingFraction_turbineECalEndcap_siminput.py

with the following lines edited to match your configuration:

For the direct assessment, one follows a procedure similar to that used for the barrel. First, run a set of single particles using the *calib* version of the detector xml file, where the absorbers and readout PCBs are set to sensitive. To do so, after having cloned k4geo and k4RecCalorimeter, modify the ALLEGRO main xml file in k4geo
```
- <include ref="ECalEndcaps_Turbine_o1_v03.xml"/>
+ <include ref="ECalEndcaps_Turbine_o1_v03_calibration.xml"/>
```
Then update the environment variable `$K4GEO` so that it points to your local folder (no need to compile k4geo)
```
export K4GEO=path/to/k4geo/
```
You only need to run the simulation step, not reconstruction. For instance
```
ddsim --enableGun --gun.distribution uniform --gun.energy "40*GeV" --gun.particle e- --gun.thetaMin "5*degree" --gun.thetaMax "40*degree" --numberOfEvents 10000 --outputFile ALLEGRO_calibration_sim_40GeV_10000ev_electrons.root --compactFile $K4GEO/FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/ALLEGRO_o1_v03.xml
```
Then run
```
k4run fcc_ee_samplingFraction_turbineECalEndcap_siminput.py`
```
With the following lines edited to match your configuration:
```
\# Electron momentum in GeV
momentum = 40

evtsvc.input = "root/allegro_v03_evts_10000_*sim.root"

This will produce a file histSF_fccee_turbineECalEndcap.root.

The last step is to fit the histograms from that root file to extract the sampling fractions:
evtsvc.input = "/root/ALLEGRO_calibration_sim_40GeV_10000ev_electrons.root"
```
This will produce a file `histSF_fccee_turbineECalEndcap.root`.

The last step is to fit the histograms from that root file to extract the sampling fractions. To do so, we need in particular the module `calo_init`, which is in `k4RecCalorimeter/RecFCCeeCalorimeter/scripts/`:
```
export PYTHONPATH=$PYTHONPATH:/your/path/to/k4RecCalorimeter/RecFCCeeCalorimeter/scripts/
python plot_turbineEcalEndcap_samplingFraction.py histSF_fccee_turbineECalEndcap.root 40 --axisMin=-0.01 --axisMax=0.5
```
Some plots are also produced in the folder plots_sampling_fraction

**Notes/caveats**: The extraction of the sampling fractions tends to not be as reliable for the endcap as the barrel. This is because each cluster essentually deposits some energy in all of the calibration layers of the barrel (since the layers are arranged in depth), but that is not the case for the endcap, where layers are arranged in both depth and in the rho coordinate. This means that most layers are empty for any one given cluster, leading to a large low-side tail in the sampling fraction plots that can make the fit unreliable. It is generally the case that using the sampling fractions as calibration constants allows one to reconstruct the correct cluster energy to within 1% for the barrel; for the endcap the variation is closer to 10%. So for precise studies of the endcap performance, the empirical determination of calibration constants described below is preferable.

### Empricial determination of calibration constants

For this procedure, one generates a large set of single-particle events (single photons may be best, as they are not affected by the B field). Typically I have used 100k particles at 40 GeV, uniformly distributed in theta and phi across the theta values relevant to the endcap (5 to 40 degrees). I generally run with the upstream detectors removed so that the performance of the endcap calorimeter can be isolated. Events are reconstructed using sampling fractions of 1 for each cell.

The resulting reconstructed events are then processed by the ROOT macro turbineEcalEndcap_autoCalib_analytic_topo.C, as follows:

### Empirical determination of calibration constants

For this procedure, one generates a large set of single-particle events (single photons may be best, as they are not affected by the B field). After having cloned k4geo and FCC-config, remove/comment the upstream detectors from the main xml (so that the performance of the endcap calorimeter can be isolated)
```
<!-- <include ref="LumiCal.xml"/> -->
<!-- <include ref="VertexComplete_IDEA_o1_v03.xml"/> -->
<!-- <include ref="DriftChamber_o1_v02.xml"/> -->
<!-- <include ref="SiliconWrapper_o1_v03.xml"/> -->
```
Then update the environment variable `$K4GEO` and simulate some events (typically 100k particles at 40 GeV) uniformly distributed in theta and phi across the theta values relevant to the endcap (5 to 40 degrees)
```
export K4GEO=path/to/k4geo/
ddsim --enableGun --gun.distribution uniform --gun.energy "40*GeV" --gun.particle gamma --gun.thetaMin "5*degree" --gun.thetaMax "40*degree" --numberOfEvents 100000 --outputFile ALLEGRO_calibration_sim_40GeV_100000ev_gamma.root --compactFile $K4GEO/FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/ALLEGRO_o1_v03.xml
```
Modify the reconstruction steering file in FCC-config to use sampling fraction of 1 for each cell in the endcap, commenting or deleting the original settings
```
# ecalEndcapSamplingFraction = [0.0897818] * 1+ [0.221318] * 1+ [...] +[1] * 1+ [1] * 1
ecalEndcapSamplingFraction = [1.0] * 98
```
Run the reconstruction, saving cells and hits, e.g.
```
k4run FCC-config/FCCee/FullSim/ALLEGRO/ALLEGRO_o1_v03/run_digi_reco.py --saveCells --saveHits --IOSvc.Input /path/to/ALLEGRO_calibration_sim_40GeV_100000ev_gamma.root --IOSvc.Output ALLEGRO_calibration_reco_40GeV_100000ev_gamma.root
```
The resulting reconstructed events are then processed by the ROOT macro `turbineEcalEndcap_autoCalib_analytic_topo.C`, as follows
```
TChain *t = new TChain("events")
t->Add(<set of reconstructed ntuples>)
.L turbineEcalEndcap_autoCalib_analytic_topo.C+
turbineEcalEndcap autoCalib_analytic_topo a(t)
t->Add("set of reconstructed files")
.L turbineECalEndcap_autoCalib_analytic_topo.C+
turbineECalEndcap_autoCalib_analytic_topo a(t)
a.Calibrate()
```
The result will be a file `turbineEcalEndcap_samplingFractionsAnalytic.txt` that contains the calibration constants is a format that can be directly inserted into the reconstruction steering file.

The result will be a file turbineEcalEndcap_samplingFractionsAnalytic.txt that contains the calibration constants is a format that can be directly inserted into the reconstruction steering file.

**Notes/caveats**: this process is based on the assumption that the true energy of each cluster is 40 GeV. If you generated the particles at the different energy, you will need to edit the following line in turbineEcalEndcap_autoCalib_analytic_topo.C:

\#define Etrue 40.0

**Notes/caveats**: this process is based on the assumption that the true energy of each cluster is 40 GeV. If you generated the particles at the different energy, you will need to edit the following line in `turbineEcalEndcap_autoCalib_analytic_topo.C`:
```
define Etrue 40.0
```
Also, since this procedure operates under the assumption that all of the energy was deposited in the endcap, it does not give appropriate calibrations for the cells at the outer edge of the endcap that are "shadowed" by the barrel. It is much better to use the direct sampling fraction approach for multi-subsystem studies that include that region.


Expand Down
6 changes: 3 additions & 3 deletions sampling_fractions/fcc_ee_samplingFraction_turbineECalEndcap_siminput.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

from Configurables import k4DataSvc, PodioInput
evtsvc = k4DataSvc('EventDataSvc')
evtsvc.input = "root/allegro_v03_evts_10000_*sim.root"
evtsvc.input = "/root/ALLEGRO_calibration_sim_40GeV_10000ev_electrons.root"
podioevent = k4DataSvc("EventDataSvc")

inp = PodioInput('InputReader')
Expand All @@ -30,9 +30,9 @@
geoservice = GeoSvc("GeoSvc",
OutputLevel = INFO)

path_to_detector = os.environ.get("FCCDETECTORS", "")
path_to_detector = os.environ.get("K4GEO", "")
detectors_to_use=[
'./FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/ALLEGRO_o1_v03_calibration.xml',
'FCCee/ALLEGRO/compact/ALLEGRO_o1_v03/ALLEGRO_o1_v03.xml',
#'Detector/DetFCCeeIDEA-LAr/compact/FCCee_DectEmptyMaster.xml',
#'Detector/DetFCCeeIDEA-LAr/compact/FCCee_DectMaster.xml',
#'Detector/DetFCCeeECalInclined/compact/original_FCCee_ECalBarrel_calibration.xml',
Expand Down
Loading