Documentation in progress...

Overview

One of the problems that often has to be solved when analyzing data from electron-positron colliders is obtaining a Born cross section using visible cross section data. There are a number of generally accepted methods for solving this problem. Paper JHEP11(2021)203 (arXiv:2108.07539) presents a new method for obtaining a Born cross section using visible cross section data. This method is based on the approximate reduction of the integral equation connecting visible and Born cross sections to a system of linear equations. Since the integral equation is an integral equation of the first kind, the problem of finding its numerical solution is ill-posed. However, under certain conditions, the effects of ill-posedness can be neglected. The new method for obtaining a Born section is called the naive method.

ISRSolver toolkit was developed in order to implement the naive method for obtaining of a Born cross section. Also, to obtain a regularized numerical solution of the corresponding integral equation, an implementation of the Tikhonov regularization method was added to the ISRSolver toolkit. However, it should be noted that the Tikhonov method cannot be used for precise obtaining of a Born cross section, in contrast to the naive method. The reason lies in the bias of a regularized numerical solution. The bias of a regularized numerical solution leads to a non-correct covariance matrix of a Born cross section. Nevertheless, the Tikhonov regularization method is convenient to use in order to demonstrate the difference between a regularized and an unregularized numerical solutions (it is assumed that an unregularized numerical solution is obtained using the naive method).

It should be noted that the naive method is model-independent if a two-dimensional detecton efficiency epsilon(x, s) is used.

The ISRSolver toolkit can also be used to verify the results of finding a numerical solution, as well as for convolution of an arbitrary line shape of a Born crosss section with the kernel function F(x, s).

The utilities are available to the user in the form of executable files that can be run with a set of command line options. The ISRSolver can be also used in a custom C++ (cmake) or Python project.

Important

1. The accuracy of the naive method depends on the presence of cross section measurement points near the threshold. The farther from the threshold are the points with the lowest c.m. energy, the lower the accuracy.
2. Since the naive method relies entirely on visible cross section data, the smaller the statistics, the lower the accuracy of the method.
3. The naive method can be used only if the energy spread is significantly less than the distance between the energy points. On the other hand, the density of the energy points should be sufficient in order to provide the desired quality of a numerical solution interpolation. Otherwise, one of the conventional methods should be used.
4. There are several typos in the function F(x,s) from eq. (1.3) in the paper JHEP11(2021)203. There are no such typos in the source code and in the arXiv version arXiv:2108.07539.

Quick start using Docker

Installation using a pre-built image

1. Install and setup docker and docker-compose.
2. Make sure the Docker service is running. You can do this using systemctl, for example:

systemctl status docker.service

3. Download ssgribanov/isrsolver image from the official Docker repository:

docker pull ssgribanov/isrsolver

4. Check that the ssgribanov/isrsolver image is actually downloaded:

docker images

5. Go to the directory where you want to download the ISRSolver source code and run the following console commands:

git clone https://github.com/sergeigribanov/ISRSolver
cd ISRSolver
mkdir shared
docker-compose up -d

6. Check that the container isrsolver_isrsolver_1 is actually running:

docker ps

Manual image build

1. Install and setup docker and docker-compose.
2. Make sure the Docker service is running. You can do this using systemctl, for example:

systemctl status docker.service

3. Go to the directory where you want to download the ISRSolver source code and run the following console commands:

git clone https://github.com/sergeigribanov/ISRSolver
cd ISRSolver
mkdir shared

4. Start image building:

docker build -t ssgribanov/isrsolver:latest .

5. After the build is complete, check that the ssgribanov/isrsolver image was actually built:

docker images

6. Run container using the following command:

docker-compose up -d

7. Check that the container isrsolver_isrsolver_1 is actually running:

docker ps

Usage (Jupyter Notebooks)

1. Check the container IP:

docker inspect isrsolver_isrsolver_1 | grep IPAddress

The container tag may differ from the standard one (isrsolver_isrsolver_) if it was launched in a directory other than ISRSolver. In the previous command, you need to use the actual container tag.

2. Connect to Jupiter Notebook using your internet browser. In order to do this, use the ip-address from the last point and port 8765. For example, if the ip-address is 172.24.0.2, then you should enter the following URL request in the browser: 172.24.0.2:8765.
3. Enter the default password for Jupyter Notebook is qwedcxzas.
4. After the previous command, two directories will be available in the browser window: notebooks and shared. The shared directory is intended for files that you want to export or import into the container. This directory corresponds to the host directory created at the step 5 of the Installation using a pre-built image section or at the step 3 of the Manual build section. The notebooks directory contains a collection of Jupiter Notebooks that you can open and run.

Usage (Console)

1. Run the /bin/bash command inside the existing container:

docker exec -it isrsolver_isrsolver_1 /bin/bash

2. Now you able run any ISRSolver executable files, for example:

isrsolver-SLE -t 0.827 -i notebooks/data/gen_visible_cs_etapipi_simple_model_no_energy_spread.root -o shared/test.root

The shared directory has the same meaning as in the section above. Detailed information on running ISRSolver executable files is given below in section Usage.

Installation

1. Make sure that packages ROOT (C++11), GSL, Eigen 3, Boost, NLopt, nlohmann_json and Minuit2 stand-alone are installed.
2. In the following we assume that you have the following directory tree:

• $HOME/source - the source code directory,
• $HOME/build - the build directory,
• $HOME/packages - the installation directory.

3. Download the ISRSolver source code:

git clone https://github.com/sergeigribanov/ISRSolver $HOME/source/ISRSolver

4. Create a directory $HOME/build/ISRSolver and change to it:

mkdir $HOME/build/ISRSolver
cd $HOME/build/ISRSolver

5. Setup ROOT environment.
6. Run the following command:

cmake -DCMAKE_INSTALL_PREFIX=$HOME/packages/ISRSolver $HOME/source/ISRSolver

7. Please note that cmake sometimes cannot find some packages depending on how they were installed. If an error occurs that cmake cannot find a particular package, you should to run cmake with the appropriate options. TO-DO: insert these commands and describe options
8. Build and install:

make -j8
make install

Jupyter Notebooks without Docker

1. Setup ROOT environment.
2. Setup ISRSolver environment:

source <ISRSolver installation prefix>/bin/env.sh

3. Install required python (Python 3) packages and modules:

pip install --user numpy pandas matplotlib seaborn scikit-hep jupyter

4. Go to the notebooks directory:

cd <ISRSolver source code prefix>/notebooks

5. Make directory ../shared. This directory is used in some examples to save results.

mkdir ../shared

6. Download archive with data for numerical experiments https://disk.yandex.com/d/XEes97fR2OsAqQ to the notebooks directory.
7. Decompress the archive:

tar -xf data.tar.gz

8. Run Jupyter Notebook:

jupyter notebook

Usage

Suppose you have a .root file that stores a visible cross section in the form of TGraphErrors object and a detection efficiency in the form of 2D TEfficiency object. Suppose this file is called input.root, the visible cross section graph is called vcs and the detection efficiency object is called efficiency. In what follows, it is assumed that the vertical error bars on the vcs graph represent visible cross section uncertainties, and the horizontal error bars represent c.m. energy spread. The detection efficiency is a function of two variables. The first variable is x, while the second variable is a c.m. energy.

Naive method

1. Setup ROOT environment:

source <path to ROOT installation>/bin/thisroot.sh

2. Setup ISRSolver environment:

source <path to ISRSolver installation>/bin/env.sh

3. Run the following command:

isrsolver-SLE -t <threshold energy> -g -v vcs -e efficiency -i <path to input.root> -o output.root

Option -t is used to set a threshold energy in GeV, option -i is used to set a path to the input file and option -o is used to set an output file path. Option -v is used to set the name of the visible cross section graph stored in the input file. If this name is vcs this option can be omitted. Option -e is used to set the name of the detection efficiency object stored in the input file. If the option -e is omitted, then it is assumed that the detection is equalt to 1 or the visible cross section is already divided by the one-dimensional detection efficiency. Option -g is used to take into account c.m. energy spread. If this option is omitted, the c.m. energy spread is not taken into account even if the visible cross section graph has horizontal error bars.

By default, the Born section is interpolated using a piecewise linear interpolation. To change the type of interpolation, option -r can be used to set a path to a .json file with interpolation settings:

isrsolver-SLE -t <threshold energy> -g -v vcs -e efficiency -i <path to input.root> -o output.root -r interp-settings.json

Suppose there are 50 c.m. energy points at which a visible cross-section is measured. Suppose also that we want the interpolation to be piecewise linear on the interval from the threshold energy to the first measurement point, and interpolation using a cubic spline at the intervals between the other measurement points. In this case, the config file interp-settings.json will be like this

[
[false, 0, 0], 
[true, 1, 49]
]

Each inner list in this file describes interpolation type at a certain set of consecutive c.m. energy intervals. false means that the interpolation is piecewise linear, true means cubic spline interpolation. The first number in each inner list is the index of the first c.m. energy interval, and the second number is the index of the last interval. Index 0 is the index of c.m. energy interval between the threshold energy and the first c.m. energy point.

Tikhonov regularization

Regularization leads to a biased numerical solution, so the covariance matrix of the Born cross section is incorrect.

Solving using the manual regularization parameter

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-Tikhonov -t <threshold energy> -l 1.0 -i <path to input.root> -o output.root

Option -l is used to set the regularization parameter manually. Options -t, -i and -o are the same as in the case of the isrsolver-SLE utility. Options -g, -e, -v and -r are also the same as in the case of the isrsolver-SLE utility and should be used if needed. By default, the regularization term contains the square of the norm of the numerical solution derivative. To use the square of the norm of the numerical solution as a regularization term, option -s should be enabled.

L-Curve and L-Curve curvature plots

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-LCurve-plot -t <threshold energy> -m <min reg. param.> -x <max reg. param.> -n <number of reg. param. points> -i <path to input.root> -o output.root

Options -m and -x are used to set minimum and maximum values of the regularization parameter, respectively. Option -n is used to set number of steps in the regularization parameter. Options -t, -i and -o are the same as in the case of isrsolver-Tikhonov utility. Options -g, -e, -v, -r and -s are also the same as in the case of isrsolver-Tikhonov utility and should be used if needed.

Solving using the L-Curve criterion

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-Tikhonov-LCurve -t <threshold energy> -l <initial reg. param.> -i <path to input.root> -o output.root

Option -l is used to set an initial value of the regularization parameter. It is better to choose this value close to the point of maximum curvature of the L-Curve. Options -t, -i and -o are the same as in the case of the isrsolver-Tikhonov utility. Options -g, -e, -v, -r and -s are also the same as in the case of the isrsolver-Tikhonov utility and should be used if needed.

Validation

The numerical solution validation can be performed using the model data. The model data should be prepared as follows:

1. Model dependence of the Born crosss section on c.m. energy is known.
2. The model visible cross section is calculated using the model Born cross section, efficiency, and energy spread at a given c.m. energy points.
3. "Experimental visible cross section" values at points are generated according to the model visible cross section and a given uncertainties of the visible cross section.
4. The "experimental visible cross section" and the detection efficiency are recorded to a file (cross section - TGraphErrors, efficiency - TEfficiecny).
5. The model Born cross section is evaluated at the given c.m. energy points and stored in the form of TGraphErrors to a file. The model visible cross section is also stored to the same file in the form of TGraphErrors.

Chi-square test

Naive method

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-SLE-chi2-test -t <threshold energy> -u <path to the file with model Born and visible cross sections> -b <name of the model Born C.S. graph> -c <name of the model visible C.S. graph> -i <path to the file with the "experimental visible C.S." and the detection eff. (if the efficiecny is used)> -v <name of the "experimental visible C.S. graph> -e <name of the detection eff. object (if the efficiency is used)> -n <number of toy Monte Carlo events> -o output.root

Option -u is used to set the path to the file with model Born and visible cross section graphs. Option -b is used to set the name of the model Born cross section graph in this file, while option -c is used to set the name of the model visible cross section, which is also stored in this file. Option -i is used to set the path to the "experimental visible cross section" and the detection efficiency (in case if the detection efficiency is used). Option -v is used to set the name of the "experimental visible cross section" graph, while option -e is used to set the name of the detection efficiency object. In the case if the detection efficiency not used, the option -e should be omitted. Option -n is used to set a number of toy Monte Carlo evants. The utility creates a chi-square histogram. This histogram is then fitted with the appropriate distribution. To set the initial amplitude of this distribution, option -a can be used. Options -g and -r are the same as in the case of the isrsolver-SLE utility and should be used if needed.

Tikhonov regularization

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-Tikhonov-chi2-test -l <reg. param.> -t <threshold energy> -u <path to the file with model Born and visible cross sections> -b <name of the model Born C.S. graph> -c <name of the model visible C.S. graph> -i <path to the file with the "experimental visible C.S." and the detection eff. (if the efficiecny is used)> -v <name of the "experimental visible C.S. graph> -e <name of the detection eff. object (if the efficiency is used)> -n <number of toy Monte Carlo events> -o output.root

Option -l is used to set the regularization parameter. Other options are the same as in the isrsolver-SLE-chi2-test utility. Options -a, -g, -r and -s can be used if needed.

Ratio test

Naive method

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-SLE-ratio-test -t <threshold energy> -n <number of toy Monte Carlo events> -u <path to the file with model Born and visible cross sections> -b <name of the model Born C.S. graph> -c <name of the model visible C.S. graph> -i <path to the file with the "experimental visible C.S." and the detection eff. (if the efficiecny is used)> -v <name of the "experimental visible C.S. graph> -e <name of the detection eff. object (if the efficiency is used)> -o output.root

Options -g and -r are the same as in the case of the isrsolver-SLE utility and should be used if needed.

Tikhonov regularization

1. Setup ROOT and ISRSolver environments.
2. Run the following command:

isrsolver-Tikhonov-ratio-test -l <reg. param.> -t <threshold energy> -n <number of toy Monte Carlo events> -u <path to the file with model Born and visible cross sections> -b <name of the model Born C.S. graph> -c <name of the model visible C.S. graph> -i <path to the file with the "experimental visible C.S." and the detection eff. (if the efficiecny is used)> -v <name of the "experimental visible C.S. graph> -e <name of the detection eff. object (if the efficiency is used)> -o output.root

Option -l is used to set the regularization parameter. Other options are the same as in the isrsolver-SLE-chi2-test utility. Options -g, -r and -s can be used if needed.