AngCorrGenerator
AngCorrGenerator#
Overview#
The AngCorrGenerator program is used to generate gamma-gamma (GxG) matrices for angular correlation analysis from ROOT trees produced by the EventBuilder or similar software.
On the contrary to the PlotResults code, AngCorrGenerator is thinked to be very general to any type of experimental setup. It can therefore not treat the specific cases using multiple detectors like it is done with PlotResults
It uses a multi-threaded producer-consumer model to efficiently process large datasets, performing:
- Filling of gamma-gamma matrices for each relative angle
- Event mixing to produce background/normalization matrices
- Support for detector geometry merging and custom angular definitions
- Parallel processing with configurable producers and consumers
The output is a ROOT file containing a set of 2D histograms per angle:
GxG_Theta_<angle>→ standard gamma-gamma matrixGxG_Theta_<angle>_Norm→ event-mixed normalization matrix
Configuration File: AngCorrGenerator.conf#
The configuration file defines input patterns, detector geometry, branches, and processing parameters.
Example configuration#
#########################
### Input ROOT files ###
#########################
TreeName FIPPS_Tree
InputFiles ./Builder/*.root # wildcards can be used as read by TChain::Add()
Entries 0 # 0 means process all events
##############################
### Angular correlation ###
##############################
DefineAngle 45 42 # to redefine the angle 45 as 42
RemoveAngle 180 # to remove angle 180 from the analysis
RemoveDet 5 12 65 # remove detector ids 5, 12 and 65
RemoveDet 10-15 # remove detectors from 10 to 15
MergeDetectors 0 1 2 3 0 # Detector ids 0,1,2,3 will be treated as a single detector with id 0
BunchSize 1000 # Number of events in a bunch in the normalisation treatment (default 1000)
NMixingPerBunch 100 # Number of event per bunch to be mixed (default 100)
GxGBinning 2000 0 4000 # Binning of the matrices
#########################
### Branch definition ###
#########################
BranchNames mult E detid subid # subid is optional, to be used with NSubDets
PositionsBranches x y z # Either use position branches,
PositionsFile positions.txt # Either use a position look up table: ID -> X, Y, Z
NSubDets 4
Verbose
#########################
### Thread settings ###
#########################
NThreads 8
Main parameters#
| Keyword | Description |
|---|---|
TreeName |
Name of the input TTree |
InputFiles |
Pattern(s) of ROOT files to process |
Entries |
Number of entries to treat (0 = all) |
DefineAngle A B |
Redefine an angle A° → B° |
RemoveAngle A |
Ignore events with angle A° |
RemoveDet D |
Ignore detector D, list or range N1-N2 |
MergeDetectors D1 D2 .. N |
Merge detectors D1, D2 into ID N |
BunchSize |
Number of events per processing batch |
NMixingPerBunch |
Number of events to use for event mixing per batch |
GxGBinning |
Binning for the 2D gamma-gamma histograms: NBins Xmin Xmax |
BranchNames |
Names of mult, energy, detid, [detsubid] branches |
PositionsBranches |
Branch names for X, Y, Z positions |
PositionsFile |
Optional file with detector positions |
NSubDets |
Number of sub-detectors per main detector |
Verbose |
Print extra information (detector angles, combinations) |
NThreads |
Number of threads (total producers + consumers) |
Program Optional Parameters#
When executed from the terminal, AngCorrGenerator accepts the following options:
| Option | Arguments | Description |
|---|---|---|
-c |
<conf_file> |
Configuration file (default: AngCorrGenerator.conf) |
-e |
<entries> |
Number of events to process (default: from configuration) |
-o |
<output_file> |
Output ROOT file name |
-thr |
<n_threads> |
Force the number of threads to use (overrides config file) |
-prod |
<n_producers> |
Force the number of producer threads (default: computed automatically) |
-v |
(no argument) | Verbose mdoe |
-h |
(no argument) | Display the help message and exit |
RemoveDet with ranges#
RemoveDet now accepts ranges of detector IDs:
- A single integer removes a single detector
- A range
N1-N2removes all detectors from N1 to N2 inclusive - Multiple values/ranges can be space-separated on the same line
Output#
The program generates a ROOT file containing:
GxG_Theta_<angle>→ Gamma-gamma histogram for a given angleGxG_Theta_<angle>_Norm→ Event-mixed normalization histogram
A summary of processing time and effective event rate is printed in the terminal:
Multithreading Model#
The program uses a producer-consumer model with:
- Producers → Read ROOT files, group events in batches (bunches)
- Consumers → Fill gamma-gamma histograms and normalization histograms
A monitoring thread prints CPU usage and queue size in real-time:
Best Practices#
- Use a reasonable
BunchSize(e.g., 1000) to balance memory and speed. - Set
NMixingPerBunchaccording to the expected background statistics. - Avoid too many producers if you have few input files: consumers must stay busy.
- Check output histograms in ROOT to validate angles and binning.
Usage Examples#
Using FIPPS data#
Using the Ge branch (no addback)#
To obtain the Germanium detector global ID, we need to combine the Clover Id and the Ge sub-ID (0->4). The configuration needs to be defined as:
TreeName FIPPS_Tree
InputFiles Builder/07*.root
NThreads 14
BunchSize 1000
NMixingPerBunch 100
BranchNames Ge_Mult Ge_E Ge_ClovId Ge_Id
NSubDets 4
PositionsBranches Ge_X Ge_Y Ge_Z
The output of the program during the processing should be similar to:
**************************************
* Reading AngCorrGenerator conf File *
**************************************
Conf File: AngCorrGenerator.conf
-- INFO : Input files pattern : Builder/07*.root
-- INFO : Number of ROOT files : 12
-- INFO : Numner of threads used : 14 → Producers : 3, Consumers : 11
-- INFO : Events to treat : 592960854
-- INFO : Bunch size : 1000
-- INFO : N Mixed events per bunch: 100
-- INFO : Gamma-Gamma binning : 2000 [0,2000]
Total 183908218 evts |===>................| 19.00% [ 8.38e+05 evts/s, time left: 0h02min52s ]
Total 204896510 evts |===>................| 18.00% [ 8.51e+05 evts/s, time left: 0h03min11s ]
Total 204156126 evts |===>................| 17.00% [ 8.44e+05 evts/s, time left: 0h03min18s ]
[Prod busy: 76.4 % | Cons busy: 97.0 %] -> queue size = 22
Using AngCorr, we obtain the following curve (Qvalues to 1):
We can then limit the analysis to FIPPS detectors by removing IDs from IFIN:
TreeName FIPPS_Tree
InputFiles Builder/07*.root
NThreads 14
BunchSize 1000
NMixingPerBunch 100
BranchNames Ge_Mult Ge_E Ge_ClovId Ge_Id
NSubDets 4
PositionsBranches Ge_X Ge_Y Ge_Z
RemoveDet 32-63
Using positions from the LUT#
TreeName FIPPS_Tree
InputFiles Builder/07*.root
NThreads 14
BunchSize 1000
NMixingPerBunch 100
BranchNames Ge_Mult Ge_E Ge_ClovId Ge_Id
NSubDets 4
PositionsFile detector_positions.txt
RemoveDet 32-63
Merging detector ids per clover#
This configuration is merging multiple ids in once. It needs to be used with the PositionsFile to be able to recalculate the mean angles of the "new detectors".
This is a "kind of add-back", without summing the energies. Used to increase the statistics by reducing the number of available angles.
TreeName FIPPS_Tree
InputFiles Builder/07*.root
NThreads 14
BunchSize 1000
NMixingPerBunch 100
BranchNames Ge_Mult Ge_E Ge_ClovId Ge_Id
NSubDets 4
PositionsFile detector_positions.txt
MergeDetectors 0 1 2 3 0
MergeDetectors 4 5 6 7 1
MergeDetectors 8 9 10 11 2
MergeDetectors 12 13 14 15 3
MergeDetectors 16 17 18 19 4
MergeDetectors 20 21 22 23 5
MergeDetectors 24 25 26 27 6
MergeDetectors 28 29 30 31 7
MergeDetectors 32 33 34 35 8
MergeDetectors 36 37 38 39 9
MergeDetectors 40 41 42 43 10
MergeDetectors 44 45 46 47 11
MergeDetectors 48 49 50 51 12
MergeDetectors 52 53 54 55 13
MergeDetectors 56 57 58 59 14
MergeDetectors 60 61 62 63 15
