Documentation in progress...
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.
- 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.
- Since the naive method relies entirely on visible cross section data, the smaller the statistics, the lower the accuracy of the method.
- 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.
- 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.
- Install and setup docker and docker-compose.
- Make sure the Docker service is running. You can do this using
systemctl
, for example:
systemctl status docker.service
- Download
ssgribanov/isrsolver
image from the official Docker repository:
docker pull ssgribanov/isrsolver
- Check that the
ssgribanov/isrsolver
image is actually downloaded:
docker images
- 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
- Check that the container
isrsolver_isrsolver_1
is actually running:
docker ps
- Install and setup docker and docker-compose.
- Make sure the Docker service is running. You can do this using
systemctl
, for example:
systemctl status docker.service
- 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
- Start image building:
docker build -t ssgribanov/isrsolver:latest .
- After the build is complete, check that the
ssgribanov/isrsolver
image was actually built:
docker images
- Run container using the following command:
docker-compose up -d
- Check that the container
isrsolver_isrsolver_1
is actually running:
docker ps
- 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.
- 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
. - Enter the default password for Jupyter Notebook is
qwedcxzas
. - After the previous command, two directories will be available in the browser window:
notebooks
andshared
. Theshared
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. Thenotebooks
directory contains a collection of Jupiter Notebooks that you can open and run.
- Run the
/bin/bash
command inside the existing container:
docker exec -it isrsolver_isrsolver_1 /bin/bash
- 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.
- Make sure that packages ROOT (
C++11
), GSL, Eigen 3, Boost, NLopt, nlohmann_json and Minuit2 stand-alone are installed. - 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.
- Download the ISRSolver source code:
git clone https://github.com/sergeigribanov/ISRSolver $HOME/source/ISRSolver
- Create a directory
$HOME/build/ISRSolver
and change to it:
mkdir $HOME/build/ISRSolver
cd $HOME/build/ISRSolver
- Setup
ROOT
environment. - Run the following command:
cmake -DCMAKE_INSTALL_PREFIX=$HOME/packages/ISRSolver $HOME/source/ISRSolver
- 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
- Build and install:
make -j8
make install
- Setup
ROOT
environment. - Setup
ISRSolver
environment:
source <ISRSolver installation prefix>/bin/env.sh
- Install required python (Python 3) packages and modules:
pip install --user numpy pandas matplotlib seaborn scikit-hep jupyter
- Go to the notebooks directory:
cd <ISRSolver source code prefix>/notebooks
- Make directory
../shared
. This directory is used in some examples to save results.
mkdir ../shared
- Download archive with data for numerical experiments https://disk.yandex.com/d/XEes97fR2OsAqQ to the
notebooks
directory. - Decompress the archive:
tar -xf data.tar.gz
- Run Jupyter Notebook:
jupyter notebook
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
.
- Setup
ROOT
environment:
source <path to ROOT installation>/bin/thisroot.sh
- Setup
ISRSolver
environment:
source <path to ISRSolver installation>/bin/env.sh
- 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.
Regularization leads to a biased numerical solution, so the covariance matrix of the Born cross section is incorrect.
- Setup
ROOT
andISRSolver
environments. - 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.
- Setup
ROOT
andISRSolver
environments. - 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.
- Setup
ROOT
andISRSolver
environments. - 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.
The numerical solution validation can be performed using the model data. The model data should be prepared as follows:
- Model dependence of the Born crosss section on c.m. energy is known.
- The model visible cross section is calculated using the model Born cross section, efficiency, and energy spread at a given c.m. energy points.
- "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.
- The "experimental visible cross section" and the detection efficiency are recorded to a file (cross section -
TGraphErrors
, efficiency -TEfficiecny
). - 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 ofTGraphErrors
.
- Setup
ROOT
andISRSolver
environments. - 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.
- Setup
ROOT
andISRSolver
environments. - 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.
- Setup
ROOT
andISRSolver
environments. - 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.
- Setup
ROOT
andISRSolver
environments. - 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.