Enable calorimeter hit merging by functions

[ruse-traveler]

Briefly, what does this PR introduce?

This PR extends the functionality of the CalorimeterHitsMerger algorithm. Previously, reconstructed hits could only be merged across a given field of the readout of a calorimeter. This presents a challenge for calorimeters such as the Barrel HCal where

1. our readout has no segmentation beyond just eta & phi, and
2. it could be useful to study the response of the detector as a function of how many readout channels we gang together after reconstruction.

This PR addresses this point by utilizing the EvaluatorSvc in a manner similar to the adjacencyMatrix, peakNeighbourhoodMatrix of the CalorimeterIslandClustering and the sampFrac of CalorimeterHitReco. Now the user has the ability to specify an (almost) arbitrarily complex transformation for a specific field of the readout via the fieldTransformations parameter, which defines both the field to transform and the function to map the indices of that field onto the desired reference indices.

For example:

app->Add(new JOmniFactoryGeneratorT<CalorimeterHitsMerger_factory>(
  "HcalBarrelMergedHits", {"HcalBarrelRecHits"}, {"HcalBarrelMergedHits"},
  {
    .readout = "HcalBarrelHits",
    .fieldTransformations = {"phi:phi-(5*((phi/5)-floor(phi/5)))"}
  },
  app   // TODO: Remove me once fixed
));

Here, the HcalBarrelMergedHits collection will merge 5 hits (i.e. scintillator tiles for the BHCal) adjacent in phi into a one with the position and cellID of the 1st of the 5, and no hits will be merged along eta.

The previous behavior of the algorithm can be recovered by simply specifying the index to be mapped onto. For example:

app->Add(new JOmniFactoryGeneratorT<CalorimeterHitsMerger_factory>(
  "HcalEndcapNMergedHits", {"HcalEndcapNRecHits"}, {"HcalEndcapNMergedHits"},
  {
    .readout = "HcalEndcapNHits",
    .fieldTransformations = {"layer:4", "slice:0"}
  },
  app   // TODO: Remove me once fixed
));

An example script of to change a transformation (and how to update the adjacency matrix accordingly) from the command-line is provided in the snippets repo here.

What kind of change does this PR introduce?

• Bug fix (issue #__)
• New feature (issue Generalize calorimeter hit merging #1669 )
• Documentation update
• Other: __

Please check if this PR fulfills the following:

• Tests for the changes have been added
• Documentation has been added / updated
• Changes have been communicated to collaborators

Does this PR introduce breaking changes? What changes might users need to make to their code?

No.

Does this PR change default behavior?

No.

[ruse-traveler]

I think this is ready to go. I'll post some plots here showing the test case in the BHCal at work shortly...

[ruse-traveler]

Here are some (eta, phi) maps of the tiles before and after merging. I tried out two cases for merging (using the example map from the PR description): once with the no. of tiles to merge set to 1 (so in other words, don't merge the tiles, and once with the no. set to 5 (merge into an sPHENIX-style tower).

Broadly, things look like I would expect them to. Except for the giant hole in the hit map...

[ruse-traveler]

Then another odd feature I noticed is that even when the no. to merge is 1, there are still slight changes in the eta, phi distributions of the tiles even though it should just be copying one collection onto another...

[github-actions]

Capybara summary for PR 1668

• rec_dis_10x100_minQ2=0_craterlake
• rec_dis_10x100_minQ2=1000_craterlake_tracking_only
• rec_dis_18x275_minQ2=0_craterlake_18x275
• rec_dis_18x275_minQ2=1000_craterlake_18x275
• rec_dis_5x41_minQ2=0_craterlake_5x41
• rec_e_1GeV_20GeV_craterlake
• rec_pi_1GeV_20GeV_craterlake
  ^{_{Last updated 2025-01-08T17:55-05:00 ebc3547}}

[veprbl]

Did this break HcalEndcapPInsertMergedHits?

https://eicrecon.epic-eic.org/pr/1668/capybara/rec_dis_5x41_minQ2=0_craterlake_5x41/index.html#HcalEndcapPInsertMergedHits

[ruse-traveler]

Did this break HcalEndcapPInsertMergedHits?

https://eicrecon.epic-eic.org/pr/1668/capybara/rec_dis_5x41_minQ2=0_craterlake_5x41/index.html#HcalEndcapPInsertMergedHits

Uh oh, looks like it 😩
Let me take a closer look...

[ruse-traveler]

Did this break HcalEndcapPInsertMergedHits?

https://eicrecon.epic-eic.org/pr/1668/capybara/rec_dis_5x41_minQ2=0_craterlake_5x41/index.html#HcalEndcapPInsertMergedHits

Looks like it was a typo (second field should've been "slices" not "layers") 😵

[veprbl]

Diff LGTM