AngCorr

Start the Software and Plot a Matrix#

Program optional parameters#

The AngCorr executable can be launched directly from the terminal with a set of optional parameters, which allow the user to load a file, define analysis modes, set gates and backgrounds, and trigger projections.

Command-line syntax#

AngCorr [options]

Available options#

Option	Arguments	Description
`-f`	`<filename>`	Input ROOT file to load (produced by `PlotResults`)
`-m`	`<mode>`	Mode string passed to `PlotAllAngle(mode)` (e.g., `"111"`)
`-g`	`<E1 W1 E2 W2>`	Define a 2D energy gate with centers `E1/E2` and half-widths `W1/W2`
`-b`	`<B1 B2>`	Define a standard background window centered on `B1` (X) and `B2` (Y)
`-ab`	`<AB1 AB2>`	Define an advanced background window centered on `AB1` (X) and `AB2` (Y)
`-p`	(no argument)	Activate projection mode (calls `Project()` automatically)
`-h`	(no argument)	Display the help message and exit

Examples#

Plot all matrices in mode 111 for a given file:

AngCorr -f FIPPS_Clov_Run_072377.root -m "111"

Apply a gate and project spectra:

AngCorr -f FIPPS_Clov_Run_072377.root -m "111" -g 344 3 779 3 -p

Apply a gate with standard background and project:

AngCorr -f FIPPS_Clov_Run_072377.root -m "111" -g 344 3 779 3 -b 320 755 -p

Apply a gate with standard and advanced backgrounds and project:

AngCorr -f FIPPS_Clov_Run_072377.root -m "111" -g 344 3 779 3 -b 320 755 -ab 500 700 -p

Starting from the ROOT interpreter#

The AngCorr software reads the gamma-gamma (GG) matrices generated by the PlotResults software.

To start the software, use the following command:

AngCorr

Then, use the function LoadFile("FileName") to load the input ROOT file:

AngCorr [0] LoadFile("PlotResults/FIPPS_Clov_Runs_072377_to_072388.root")
Q values read from: qvalues.txt
Detector                Q2          ±Q2          Q4          ±Q4
------------------------------------------------------------------
FIPPS-FIPPS       0.633421      0.090476    0.504049      0.061239
FIPPS-IFIN        0.737123      0.149882    0.596978      0.094361
IFIN-IFIN         0.780366      0.244585    0.709818      0.161986
 -- INFO    : FIPPS-FIPPS Angles: 4
 -- INFO    : Available angles:    45   90  135  180
 -- INFO    : FIPPS-FIPPS Normalisation Angles: 4
 -- INFO    : Available angles:    45   90  135  180
 -- INFO    : FIPPS-IFIN Angles: 5
 -- INFO    : Available angles:    45   60   90  120  135
 -- INFO    : FIPPS-IFIN Normalisation Angles: 5
 -- INFO    : Available angles:    45   60   90  120  135
 -- INFO    : IFIN-IFIN Angles: 4
 -- INFO    : Available angles:    60   90  120  180
 -- INFO    : IFIN-IFIN Normalisation Angles: 4
 -- INFO    : Available angles:    60   90  120  180

The Q-values will be read from the file qvalues.txt, which must be located in the current directory. If the file is not found, a default one will be created automatically.

The program prints the Q-values that will be used, along with the different matrices found in the input file, sorted by mode (FIPPS-FIPPS, FIPPS-IFIN, IFIN-IFIN) and by type (standard or normalization).

⚠️ It is also possible to plot angular correlations in symmetric mode (angles between 0° and 90°). In that case, load the file as follows:

AngCorr [0] LoadFile("FIPPS_Clov_Runs_075437_to_075449.root", "NoCond", true)

Plotting the GG Matrix#

Before applying any energy gate, you should first plot the GG matrix. This can be done using one of the following functions:

void PlotAllAngle(TString Mode = "111", bool Norm = false);
void PlotAngle(Int_t Angle, TString Mode = "111", bool Norm = false);

PlotAllAngle plots all matrices, regardless of angle, for a given mode.
PlotAngle plots only the matrix for the specified angle and mode.

⚠️ Make sure the requested angle is available for the selected mode.

Mode Definition#

The Mode is defined using a 3-digit string (0 or 1) corresponding to:

FIPPS-FIPPS
FIPPS-IFIN
IFIN-IFIN

Some examples:

Mode = "111": Process all detector combinations.
Mode = "100": Process only FIPPS-FIPPS combinations.
Mode = "101": Process FIPPS-FIPPS and IFIN-IFIN combinations.

Once the function is called, a canvas will be displayed with the requested matrix in the top-left corner:

PlotAllAngle("111")

Matrix Example

Apply an Energy Gate#

The next step is to apply an energy gate corresponding to the gamma-ray transitions for which the angular correlation is to be measured. This is done using the function SetGate:

void SetGate(Float_t Px, Float_t w_Px, Float_t Py, Float_t w_Py)

The parameters are as follows: - Px: energy on the X axis, - w_Px: width of the X gate, - Py: energy on the Y axis, - w_Py: width of the Y gate.

The background is estimated using the method illustrated below:

Background method

The subtraction method corresponding to Equation 1 will be referred to as Standard background, while the one corresponding to Equation 2 will be called Advanced background.

When the gate is applied using, squares such as those shown in the figure above will be overlaid on the matrix:

AngCorr [1] SetGate(344.5,5,779,5)

Gate display

To adjust the position of the background boxes, use the following functions:

AngCorr [5] SetBackGroundX(320)
AngCorr [6] SetBackGroundY(755)

The width and height of the background windows are the same as those of the gate.
Adjusting these positions is important to avoid contamination by diagonal Compton lines, as shown above:

Adjusted background

Gate projection#

Once the energy gate has been set, the next step is to project the angular correlation spectra. This is done using the function Project:

void Project(bool DoStdBgd = 1, bool DoAdvBgd = 1, bool DoNorm = true, bool NormTo90 = true, bool Print = false, bool PlotNorm = false)

Parameters#

DoStdBgd: apply standard background subtraction (equation 1),
DoAdvBgd: apply advanced background subtraction (equation 2),
DoNorm: use normalized matrices,
NormTo90: normalize the distributions to 1 at 90°,
Print: print the number of counts per angle to the terminal.
PlotNorm: plot the normalisation distribution.

By default, the advanced background is enabled. This function projects the gated matrix onto the angle axis, for both standard and normalization matrices, and for each requested mode.

Once the angular distribution is built for each mode, a minimization process is performed to fit the \(A_i\) parameters using:

\[ W(\theta) = A_0 \times \left[ 1 + A_2 \times P_2(\theta) + A_4 \times P_4(\theta) \right] \]

To account for the angular efficiency of the detection system, the fit is corrected using the \(Q_i\) coefficients:

\[ A_i = a_i \times Q_i \]

This gives the actual fitting formula:

\[ W(\theta) = A_0 \times \left[ 1 + a_2 \times Q_{i2} \times P_2(\theta) + A_4 \times Q_{i4} \times P_4(\theta) \right] \]

Since the goal is to extract \(A_0\), \(A_2\), and \(A_4\) for the entire experimental setup, but the spectra are mode-dependent, a global minimization is performed, combining all modes simultaneously.

The results are displayed on the bottom left canvas, split into two pads: - Top: fit results for each mode, - Bottom: global fit result with the physical \(A_i\) values.

The obtained values for \(A_0\), \(A_2\), and \(A_4\) are then printed in the terminal. The values printed in parenthesis with "∆-" and "∆-" are the low and high uncertainty. The values printed in square brackets are corresponding to the final range.

AngCorr [4] Project()
W(theta) = A0 x ( 1 + A2*Qi2*Pk2 + A4*Qi4*Pk4 ), using:

Result: Chi2/ndf = 0.238155
             ndf = 9
=> A0 =  0.9734305 ( ∆-  0.0018925 , ∆+  0.0019864 ) [ 0.9715380 :  0.9754169]
=> A2 = -0.0792561 ( ∆-  0.0242890 , ∆+  0.0171098 ) [-0.1035450 : -0.0621463]
=> A4 = -0.0039301 ( ∆-  0.0088665 , ∆+  0.0074841 ) [-0.0127966 :  0.0035539]

Fit Result

The colored bands represent the uncertainty bands, calculated from the errors on the \(A_i\) (from the fit) and on the \(Q_i\) (from qvalues.txt).

Printing the Number of Counts#

To display the number of counts used in each projection (bypassing the normalization to 1 at 90°), use:

Project(1, 1, 1, 0, 1)

This outputs information like:

 -- INFO    : Projection without normalization, mode 0
 -- INFO    :  -> Theta = 45, N = 210472, Err = 947.052
 ...

Estimating Uncertainties Using Monte Carlo#

Uncertainties on the \(A_i\) coefficients can also be estimated using a Monte Carlo procedure, which samples the \(Q_i\) values and propagates their uncertainties. Use the function:

void SetMonteCarlo(bool on = true, Int_t N = 10000)

on: activate or deactivate the Monte Carlo mode.
N: number of sampling iterations per estimation.

⚠️ Note: This approach is slower, but provides a more flexible estimate of the error, especially when the standard method may not fully capture uncertainty propagation.

SetMonteCarlo(1, 1e6)
Project()
Monte-Carlo estimation of errors: 415824 /1000000 :41.5823%:

Fit Result

Defining a Transition#

If you already know the nuclear transition you want to analyze—or if you want to explore different transition types and mixing ratios—you can use the function SetTransition:

void SetTransition(int twoI1, int twoI2, int twoI3, double mix1 = 0., double mix2 = 0.);

Parameters#

twoI1, twoI2, twoI3: spins of the three levels involved in the cascade, from top to bottom of the level scheme.
⚠️ Spins must be entered as integers multiplied by 2 to avoid using half-integer types.
Example: for a 4 → 2 → 0 transition, use SetTransition(8, 4, 0).
mix1: mixing ratio of the first transition (optional).
mix2: mixing ratio of the second transition (optional).

Example: \(^{152}\text{Eu}\) Cascade#

In this example, we analyze the cascade 779 → 344 keV from a \(^{152}\)Eu calibration source, which corresponds to a:

\[ 3^- \rightarrow 2^+ \rightarrow 0^+ \]

The 779 keV transition has a known M2/E1 mixing ratio of 0.003. Therefore, we use:

AngCorr [15] SetTransition(6, 4, 0, 0.003, 0.)
Theoretical function: A2=-0.0690824 A4=-0.0000007 Delta1=0.0030000, Delta2=0.0000000

This command will print the theoretical values of the angular correlation coefficients \(A_2\) and \(A_4\) based on the specified level scheme and mixing ratios.

The theoretical angular correlation function will also be displayed on the bottom left of the canvas, overlaid as dashed lines on top of the experimental fit:

Theoretical overlay

Mixing Minimization#

To determine the mixing ratio ∂, two strategies are available: - Minimize the first transition’s mixing ratio while keeping the second one fixed, - Or the reverse: minimize the second mixing while the first is fixed.

This is done using the FitDelta method:

AngCorr [6] FitDelta(1)
 -- INFO    : Fit Mixing:
 -- INFO    : Chi2 min 0 = 0.07433222
 -- INFO    :   -> Mixing estimation based on Chi2min+1 evaluation:
     ∂  =      -0.01 ( ∆-     0.0261 , ∆+     0.0263 ) [   -0.0361 :     0.0163]
 -- INFO    :   -> Mixing estimation based on experimental error bars:
     ∂  =      -0.01 ( ∆-     0.0304 , ∆+     0.0219 ) [   -0.0405 :     0.0119]

 -- INFO    : Chi2 min 1 = 27.60732
 -- INFO    :   -> Mixing estimation based on Chi2min+1 evaluation:
     ∂  =       6.02 ( ∆-      0.862 , ∆+       1.18 ) [      5.16 :        7.2]
 -- WARNING:      Experimental point not on the curve, uncertainties estimated using the Chi2+1 values

This command generates: - On the top right canvas: a plot of the theoretical \(A_4/A_2\) ratio versus different mixing values. The green point represents the theoretical \(A_2\) and \(A_4\) for the specified mixing. - On the bottom right canvas: the \(\chi^2\) difference between experimental and theoretical \(A_i\) values as a function of the mixing.
Detected minima are marked, showing both \(\chi^2\) values and associated mixing ratios. These are also projected on the top canvas using matching color codes.

FitDelta result

In this case, the experimental result is compatible with the theoretical prediction, considering the experimental uncertainty.

Mixing Ratio Uncertainty Evaluation#

The uncertainty on the mixing ratio is evaluated using two complementary approaches:

\( \chi^2_\text{min} \) + 1 method
This approach determines the confidence interval around the best-fit minimum.
The minimum and maximum values of the mixing ratio (∂) are identified where the χ² curve reaches \( \chi^2_\text{min} \) + 1, providing the standard 1‑σ uncertainty range.
Experimental box method
If the experimental uncertainty box (shown in red on the plot) intersects the theoretical curve,
the range of ∂ values corresponding to the horizontal extent of this box is also evaluated.
This gives a more visual estimate of the allowed mixing-ratio interval.

All detected minima are reported in the terminal, including: - the ∂ value at the minimum, - the corresponding χ², - and the uncertainty range determined by the methods above.

Fitting the Second Mixing Ratio#

You can perform the fit on the second transition (instead of the first) by calling:

AngCorr [2] FitDelta(2)
 -- INFO    : Fit Mixing:
 -- INFO    : Chi2 min 0 = 0.4725841
 -- INFO    :   -> Mixing estimation based on Chi2min+1 evaluation:
     ∂  =  -4.63e-13 ( ∆-      0.479 , ∆+      0.479 ) [    -0.479 :      0.479]
 -- INFO    :   -> Mixing estimation based on experimental error bars:
     ∂  =  -4.63e-13 ( ∆-      0.334 , ∆+      0.334 ) [    -0.334 :      0.334]

Second delta fit

Examples with Different Detector Modes#

Below are results using various detector combinations:

All modes (Mode = "111"):
FIPPS-FIPPS only (Mode = "100"):
FIPPS-IFIN only (Mode = "010"):
IFIN-IFIN only (Mode = "001"):
FIPPS-FIPPS and FIPPS-IFIN only (Mode = "110"):

2D Mixing Minimization#

It is also possible to minimize the mixing ratios of both transitions simultaneously. To perform this 2D minimization, use the function:

FitDelta2D()

⚠️ This process is significantly more computationally intensive and may take longer.

It produces a 2D \(\chi^2\) landscape like the one shown below:

2D Delta Fit

Fit Q-values#

To determine the Q-values—either for known experimental transitions or from simulations—you can use the function FitQValues:

void FitQValues(bool fitQ2, bool fitQ4, double a2, double a4)

Parameters#

fitQ2: if true, fits the \(Q_2\) coefficients,
fitQ4: if true, fits the \(Q_4\) coefficients,
a2: expected \(A_2\) coefficient of the transition used,
a4: expected \(A_4\) coefficient of the transition used.

You can obtain the \(A_2\) and \(A_4\) values using the SetTransition function (see previous section).

Best Practices#

If the transition used has a very small or zero \(A_2\) or \(A_4\), it does not make sense to fit the corresponding Q-value. In such cases, it's recommended to:

Use two different transitions, each optimized for either \(A_2\) or \(A_4\),
Perform the Q-value fitting in two steps, one for each component.

This ensures better stability and accuracy of the Q-value extraction.

Example: Fitting Q values#

Let’s fit only the \(Q_{2i}\) values for the 779 → 344 keV cascade from \(^{152}\)Eu. This is justified because \(A_4 \sim 0\) for this case:

AngCorr [0] SetTransition(6, 4, 0, 0.003, 0.)
Theoretical function: A2=-0.0690824 A4=-7.346873e-07 Delta1=0.003, Delta2=0
AngCorr [9] FitQValues(1, 0, -0.0690824, -7.34687e-07)
W(theta) = A0 x ( 1 + A2*Qi2*Pk2 + A4*Qi4*Pk4 ), using:
=> A2 = -0.0690824
=> A4 = -7.34687e-07
=> FIPPS-FIPPS Q4 = 1.0000 +- 0.0000
=> FIPPS-IFIN Q4 = 1.0000 +- 0.0000
=> IFIN-IFIN Q4 = 1.0000 +- 0.0000

Result: Chi2/ndf = 0.266272
             ndf = 9
=> A0 = 0.973398   +- 0.00181989
=> FIPPS-FIPPS Q2 = 0.7616 +- 0.0719
=> FIPPS-IFIN Q2 = 0.7670 +- 0.1364
=> IFIN-IFIN Q2 = 0.9220 +- 0.1804
 -- INFO    : Use SetQValues() to load the fitted values in the program

In the terminal output, you first see the fixed \(A_i\) and \(Q_{4i}\) parameters, followed by the fitted \(Q_{2i}\) results.

Applying the Fitted Q-values#

Once you're satisfied with the results, apply them to the analysis using:

AngCorr [4] SetQValues()
Detector                Q2          ±Q2          Q4          ±Q4
------------------------------------------------------------------
FIPPS-FIPPS       0.761552      0.071857    1.000000      0.000000
FIPPS-IFIN        0.767022      0.136443    1.000000      0.000000
IFIN-IFIN         0.921985      0.180362    1.000000      0.000000

This updates the internal Q-values used by the software:

Setting Q-values Manually#

You can also set Q-values manually using:

void SetQ2Q4(double q2, double q4, double eq2, double eq4, int mode)

Where mode corresponds to: - 0: FIPPS-FIPPS, - 1: FIPPS-IFIN, - 2: IFIN-IFIN.

Example: manually setting Q2 and Q4 for IFIN-IFIN:

AngCorr [5] SetQ2Q4(0.95, 0.94, 0.2, 0.2, 2)
Detector                Q2          ±Q2          Q4          ±Q4
------------------------------------------------------------------
FIPPS-FIPPS       0.761552      0.071857    1.000000      0.000000
FIPPS-IFIN        0.767022      0.136443    1.000000      0.000000
IFIN-IFIN         0.950000      0.200000    0.940000      0.200000

Saving and Loading Q-values#

To save current Q-values to qvalues.txt:

SaveQValues()

To reload Q-values from file:

ReadQValues()

To print current Q-values in use:

PrintQValues()