source: ZHANGProjects/ICOSIM/CPP/trunk/doc/ICOSIM++manual.tex @ 2

\documentclass[11pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english]{babel}
\usepackage{verbatim}
\usepackage{amssymb}
\usepackage{amsmath}
\usepackage{amsthm}
\usepackage{lmodern}
\usepackage{graphicx}
\usepackage{subfigure}
\usepackage{array}
\usepackage{a4wide}
\usepackage{float}

\setlength{\extrarowheight}{0.6cm}


\newtheorem{defin}{Définition}[section]
\theoremstyle{remark}\newtheorem{rem}[defin]{Remark}
\newtheorem{theorem}{ThéorÚme}[section]
\newtheorem{lemma}{Lemme}[section]
\begin{document}

\begin{center}
EUROPEAN ORGANIZATION FOR NUCLEAR RESEARCH
\end{center}

\begin{center}
CERN
\end{center}

\vspace{5cm}


\begin{center}
\Huge  ICOSIM++: a tracking program for collimator studies
\end{center}

\vspace{2cm}

\begin{center}
\huge Manual for version 1.0
\end{center}

\vspace{5cm}

\begin{center}
\LARGE Joël Clivaz
\end{center}

\begin{center}
\normalsize december 2011
\end{center}

\vspace{2cm}



\newpage

\section{Introduction}

ICOSIM++ is a tracking program derived from ICOSIM and written in C++. It is used for collimator studies of a beam of nuclei or protons. In this manual, we give some explanation on how to install and run it. We also explain quickly how it is working, without going into details. A big part of this manual comes directly from \cite{a1}.

A simulation done with ICOSIM++ begins with the generation of a bunch of particles or the reading of initial coordinates from a file. Then a linear tracking can be done between the primary collimators and finally a detailed tracking is performed between all the elements of the lattice. During that part of the simulation, we apply some special treatments to the collimators and we make aperture checks all along the ring.

\section{General description}

In this section, we make a quick explanation on what the program is doing, without going into details.

\subsection{Reading of the input parameters}

The very first step of a simulation with ICOSIM++ is the reading of needed parameters from input files. Two files are containing this kind of information: the collimator file and the optics file. Those two files are mandatory for every run. They are detailed further.

\subsection{Generation of particles}

Once the input parameters read, the program will generate initial particles coordinates using one of the following distribution: KV (Kapchinski-Vladimirski), waterbag, r1r2 or Gaussian. The choice of the type of distribution as well as the number of particles must be set in the collimator file.

Note that the user can also choose to read the initial coordinates from a file.

\subsection{Tracking}

The particle coordinates are transformed element by element. The tracking is done with linear transfer matrices in $x$, $y$, $ \frac{dx}{ds}$, $ \frac{dy}{ds}$, $t$ and $\frac{\delta p}{p}$, linear dispersion in bending magnet, chromaticity in quadrupoles to leading order, sextupoles in thin element kick approximation and no acceleration. A definition of the particle coordinates can be found in the appendix.

To be more accurate, the tracking is following two different steps.

\subsubsection{Tracking between the primary collimators}

The first tracking is done only between the primary collimators (TCP, CRYSTAL or TCRYO collimators). When a particle hits a collimator, its starting coordinates in this turn are saved. The transport of the particles is done by Twiss transforms. A blowup of the beam is done if the blow up period divides the revolution number.

\subsubsection{Detailed tracking}
Then, a second more detailed tracking is done between all the elements of the accelerator lattice, using as input coordinates the ones saved during the first tracking (coordinates at the beginning of the turn in which the particle hit a primary collimator). During that tracking, we apply some special treatment to the collimators to simulate precisely the interactions between the particles and the collimator's material. We also determine if some particles hit the aperture during the run.

Note that it is possible to directly do a detailed tracking between all the elements, without primary tracking.

\subsection{Special treatments for the collimators during the detailed tracking}

As explained before, during the second detailed tracking, the collimators are studied more in detail. To do that, it exist four different ways of describing the effect of collimators.

\subsubsection{Standard collimators}

This treatment can apply to a collimator with amorphous material. To describe the interaction between the particles and the material, we use cross-section tables for nuclear fragmentation and electromagnetic dissociation processes which are produced separately with FLUKA. If there is no cross-section table for an isotope, an analytical approximation is calculated. The ionization energy loss is modelled by the Bethe-Bloch formula for heavy ions with shell and density corrections. The multiple scattering is described using a Gaussian approximation of the scattering distribution. The effective particle path $L_{eff}$ is calculated at impact time for each particle. Then, if $L_{eff} > 10 L_{int}$ , with $L_{int}$ the interaction length, the particle is assumed to be absorbed, otherwise the probability for a fragmentation process is randomly computed using the cross-section tables. Here, in the case of a fragmentation, only the heavier isotope is kept.

\subsubsection{Magnetic collimators}

This treatment is similar to the previous one, except for the fact that a magnetic field is here present. Also note that, during the detailed tracking, the distance between the collimator's edge is increased.

\subsubsection{Fluka collimators}

For this treatment, we use the program FLUKA to describe the interaction between the collimator and the particles. It can be applied to collimators with amorphous material.

\subsubsection{Crystal collimators}

This is a specific treatment for crystals used as collimators. The routine used to simulate interaction between particles and a crystal collimator has been written by Yannick Bel-Hammar, derived from a routine written in FORTRAN77 by Valentina Previtali based on an original algorithm of I.A. Yazynin.

\subsection{Outputs}

At the end of the run, some scripts are created. They can be directly read with Gnuplot to have some graphical output related to the run. Some other files are also created to give other information about the previous run.

\section{How to install and compile ICOSIM++}

ICOSIM++ can be installed on every Unix plateform running the g++ compiler. To use it at its best level, the user will also have to install a version of the FLUKA program (to do that, please find more info on \textit{http://www.fluka.org/fluka.php}). The library FlukaIO is also needed to link ICOSIM++ with FLUKA. This library can also be found on svn \textit{https://svnweb.cern.ch/world/wsvn/FlukaIO} and check out from \textit{https://svn.cern.ch/reps/FlukaIO}.

\vspace{0.5cm}

The first part to be compiled must be the FlukaIO library. To do that, the user will just have to follow the instructions in the \textit{README} of FlukaIO. Be careful to have the paths well defined in the Makefile.

\vspace{0.5cm}

The next step is to compile the part in \textit{branches/flukaIntegration/fluka}. Before doing it, the user must be sure to have Fluka well installed and the environnemental variable FLUPRO well defined. Be careful to also redefine the paths at the beginning of the Makefile. Please see the Fluka documentation for more infos. If Fluka is installed and FLUPRO defined, then the only thing to do is to type:

\begin{verbatim}
make
\end{verbatim}
under \textit{flukaIntegration/fluka}.

Note that if you don't want to use ICOSIM++ coupled with FLUKA, you can skip that point and just install FlukaIO.

\vspace{0.5cm}

The final compilation must be done under the (\textit{source}) directory. First of all, in the \textit{makefile}, set the right path to the FlukaIO directory (FLUKAIOlib). Be carefule that the library name could contain 32 or 64 depending on which machine you run FlukaIO. Then, if you want to build ICOSIM++ with files that can be used to test the code (for programmers), just call the makefile with

\begin{verbatim}
make
\end{verbatim}

If you just want to use ICOSIM++, you can type

\begin{verbatim}
make partial
\end{verbatim}

and you will have only the executables used to run ICOSIM++.

\vspace{0.5cm}

Using ICOSIM++, you will have the possibility to make all the files related to a run appear in one folder specific to that run. This will allows you to make other simulations without crashing any previous result or to redo the same simulation being sure to use the right files. It could be also very useful when studying several runs to be sure that right files are corresponding to the right runs. To use this feature, you will have to run ICOSIM++ with the scripts provided in the \textit{script} folder.

To use the scripts, before running ICOSIM++, you will have to rename them from \textit{script\_name.sh.sample} to \textit{script\_name.sh} under the \textit{script} directory. You may also have to change the mode of these scripts to execute them. To do that type:

\begin{verbatim}
chmod +x runicosim++.sh
chmod +x runwithfluka.sh
\end{verbatim}

\begin{rem}
If you are running ICOSIM++ on a Mac (at any cas on OSX Lion), you will have to modify a line in the scripts. Please change the line:

\begin{verbatim}
RUNDIR=$(mktemp -d -p $PWD ${1}.XXX)
\end{verbatim}
to
\begin{verbatim}
RUNDIR=$(mktemp -d $PWD ${1}.XXX)
\end{verbatim}
\end{rem}

\begin{rem}
If you want to use ICOSIM++ coupled with FLUKA, you will have to use the script \textit{runwithfluka.sh}.
\end{rem}

\begin{rem}
It is clear that these two scripts are just examples that can be used as a basis to construct more elaborated ones.
\end{rem}

\begin{rem}
Don't forget to decompress the cross section folder in the sample repository before running ICOSIM++.
\end{rem}

\section{How to run ICOSIM++}

There are different ways of running ICOSIM++, using different inputs. So let's first have a look at the input files.

\subsection{Input files}

The most imprtant input files needed by ICOSIM++ are the collimator file and the optics file, the first one describing the collimators and the second one the optics. Some examples of such files are already in \textit{trunk/sample}. The user must in any case check that the values in these files correspond to what he wants to simulate. We describe those files in this section.

It exists also some other input files that are also quickly described below.

The input files must be in the same directory, which has to be given to the program in the collimator file.

\subsubsection{The collimator file}

The collimator file is the input file used to describe specifically the collimators. It is a .csv (comma separated) file and its name MUST be \textit{collimatorfile\_<specific name>.csv}. The \textit{<specific name>} stand for the name chosen by the user. The collimator file decomposes in two parts. 

\vspace{0.5cm}

The first half of it is a list of parameters with their values. At least, the following parameters must be there:

\begin{itemize}
\item OPTICSPATH: name of the optics file;
\item INPUTPATH: path where the input files are;
\item BEAMFLAG: circulating direction in which the particles turn into the machine (1 if in the sense of the MAD element sequence, 2 if the opposite);
\item MASSNUMBER: number of nucleons in the projectile;
\item CHARGESTATE: charge of projectile;
\item MASS: rest mass of the projectile [GeV/$c^{2}$];
\item ENERGY: total energy of the projectile, [GeV];
\item EX: emittance in $x-x'$ plane [m $\cdot$ rad];
\item EY: emittance in $y-y'$ plane [m $\cdot$ rad];
\item NPART: number of particles per bunch in the beam;
\item KBUNCH: number of bunches;
\item SIGDPP: standard deviation $\displaystyle \frac{p-p_{0}}{p_{0}}$ for an ion in the beam, where $p$ is the momentum of a particle, and $p_{0}$ is the momentum of the reference particle;
\item TAUBEAM: expected lifetime of the beam [s];
\item NPARTI: number of particles we consider in the simulation;
\item PARTDISTR: initial particle distribution (kv, waterbag, r1r2 or gauss);
\item R1R2SKIN: describes the thickness of the initial distribution shell when PARTDISTR = "r1r2";
\item NREV1: number of revolutions for the linear tracking;
\item NREV2: number of revolutions for the nonlinear tracking;
\item BLOWUP2: the square of the blow-up parameter that determines the diffusion in the linear tracking;
\item BLOWUPPERIOD: the beam diffuses every BLOWUPPERIOD revolution during the linear tracking;
\item STOPLINEARTRACKING: in the beginning of the first revolution of the nonlinear tracking, the transformation between the elements is linear, STOPLINEARTRACKING is the name of the element where the linear tracking stops;
\item SCALEORBIT: scaling factor for closed orbit coordinates;
\item WECOLLI: tilt angle of the collimators [rad];
\item NSIGI: size of the initial beam distribution [sigma];
\item CROSSSECTIONPATH: path to the folder containing cross sections data;
\item PLOTFLAG: 'Yes' to make the plot of the trajectory, 'No' otherwise;
\item THICKNESSMAGNETICFIELD: distance from the edge of a magnetic collimator to the point where the field strength is about 10\%  of BMAX [m];
\item BMAX: maximum strength of the magnetic field [T];
\item DELTAGAP: how much we move the collimator edge when using magnetic collimators [m];
\item FREQRF: frequency of the rf cavity [Hz];
\item RFVOLTAGE: voltage of the rf cavity [V];
\item RFHARMONBER: harmonic number for the rf cavity;
\item RUNNINGFLAG: choice of the type of tracking (see below);
\item IDPART: choice of a particle to spy (see below);
\item IDELT: choice of an element after which print some coordinates (see below);
\item OUTCOORD: choice of the type of coordinates printing (see below);
\end{itemize}

This parameters can come in any order, and the file may also contain other parameters.

\vspace{0.5cm}

The second part of the collimator file is a list of the collimators that are in the lattice. For each of them, we have the parameters:

\begin{itemize}
\item NAME: name of the collimator as in the optics file (this name MUST finish with \textit{.B1} or \textit{.B2}, this corresponding to the BEAMFLAG parameter. (Note that if the name of the collimators in the optics file don't finish with \textit{.B1} or \textit{.B2}, the user will have to change it manually));
\item ANGLE: postition angle of the collimator in the vacuum chamber (horizontal, vertical or skew) [deg]. The angle should be zero if you are using Fluka;
\item LENGTH: length of the collimator;
\item NSIG: opening gap of the collimator jaws [sigma];
\item MATERIAL: collimator's material, which is also the name of the folder where we can find material parameters and cross sections information  (carbon, copper, iron, MARS or tungsten);
\item METHOD: the kind of collimator we are considering (standard, magnetic, crystal or fluka).
\end{itemize}

The order of these parameters must be this given above. Be careful to have a header line between the two parts of the collimator file, containing the name of the parameters of the second part. All the parameters must be written in capital letters.

\begin{rem}
If we use a crystal collimator, the only important values in the second part of the collimator are the name and the method, but it must be seven values for each collimator in that file. So for a crystal collimator please use dummy values for the angle, length, phase, nsig and material.
\end{rem}

\begin{rem}
Note that ICOSIM++ is also working with the collimator files used for ICOSIM. In that case, it is not possible to print the coordinates of the particles, the RF cavity is seen as another element and all the input files must be in the same directory as the source code.
\end{rem}

\begin{rem}
If the user wants to make a simulation without computing the effect of the RF cavity, he could do it by deleting the RF parameters in the collimator file.
\end{rem}
\subsubsection{The optics file}

The second input file is the optics file, which is basically describing in detail the lattice of the accelerator. It is also a .csv file and stand in two parts. It's name MUST be \textit{opticsfile\_<specific name>.csv} and the \textit{<specific name>} must correspond to the one chosen for the collimator file.

\vspace{0.5cm}

The first part contains a list of parameters which are not described here, because we don't use them in the simulation. Anyway, these parameters can be useful to have a more precise idea on the run.

\vspace{0.5cm}

The second part of the optics file is a list of all the elements in the lattice. For each element, we have the following parameters:

\begin{itemize}
\item NAME: name of the element;
\item KEYWORD: keyword;
\item PARENT: parent;
\item S: position of the element measured as the distance along the accelerator [m];
\item L: length of the element [m];
\item K0L: $K0L = K0 \cdot L$, where $K0$ is the normal dipole coefficient, and $L$ the magnetic length;
\item K0SL: $K0SL = K0S \cdot L$, where $K0S$ is the skew dipole coefficient, and $L$ the magnetic length;
\item K1L: $K1L = K1 \cdot L$, where $K1$ is the normal quadrupole coefficient, and $L$ the magnetic length;
\item K1SL: $K1SL = K1S \cdot L$, where $K1S$ is the skew quadrupole coefficient, and $L$ the magnetic length;
\item K1L: $K2L = K2 \cdot L$, where $K2$ is the normal sextupole coefficient, and $L$ the magnetic length;
\item K1SL: $K2SL = K2S \cdot L$, where $K2S$ is the skew sextupole coefficient, and $L$ the magnetic length;
\item XC: horizontal position $x$ of the closed orbit referred to the ideal orbit [m];
\item PXC: horizontal canonical momentum $p_{x}$ of the closed orbit referred to the ideal orbit, divided by the reference momentum;
\item YC: horizontal position $y$ of the closed orbit referred to the ideal orbit [m];
\item PYC: horizontal canonical momentum $p_{y}$ of the closed orbit referred to the ideal orbit, divided by the reference momentum;
\item TC: $TC = -c \cdot t$, velocity of light times the negative time difference with respect to the reference particle [m]. A positive $TC$ means that the particle arrives ahead of the reference particle;
\item PTC: $PTC = \displaystyle \frac{\Delta E}{p_{s}c}$, energy error divided by the reference momentum times the velocity of light;
\item BETX: amplitude function $\beta_{x}$ [m];
\item ALFX: correlation function $\alpha_{x} = -0.5 \beta_{x}'(s)$;
\item MUX: phase advance $\mu_{x}$ [$2\pi$];
\item DX: dispersion of $x$ [m];
\item DPX: dispersion of $p_{x}$;
\item BETY: amplitude function $\beta_{y}$ [m];
\item ALFY: correlation function $\alpha_{y} = -0.5 \beta_{y}'(s)$;
\item MUY: phase advance $\mu_{y}$ [$2\pi$];
\item DY: dispersion of $y$ [m];
\item DPY: dispersion of $p_{y}$;
\item APERTYPE: type of aperture (RECTANGLE, ELLIPSE, CIRCLE, RECTELLIPSE or NONE);
\item APER\_1: aperture parameter;
\item APER\_2: aperture parameter;
\item APER\_3: aperture parameter;
\item APER\_4: aperture parameter.
\end{itemize}

The optics file comes in fact from the program MAD-X, so more detailed explanation of these parameters must be found in the MAD-X documentation. See for example \cite{a2}.

Note that the parameters above can appear in any order in the optics file, but that it must be a header line just before the beginning of the list of the lattice elements containing the parameter names and giving the order used below.

Giving a Twiss file (a direct output of MAD-X), the user can transform it in an optics file compatible with ICOSIM++ using the routine \textit{twiss\_optics}, included in ICOSIM++. To do it, just type

\begin{verbatim}
./twiss_optics
\end{verbatim}
and follows the indication the program will give to you.

\subsubsection{Input parameters for crystal collimators}

If we make a simulation with one or more crystal collimators, we must have another input file giving their parameters. This file is named \textit{crystalinfo.csv}. In this file, each line represent a crystal and for each crystal, we have the following parameters in this order:

\begin{itemize}
\item NAME: name of the crystal as in the collimator file;
\item C\_orient: crystal orientation (1 for 110, 2 for 111);
\item IS: integer that define the substance (0 for Si, 1 for W, 2 for C, 3 for Ge) for a crystal;
\item C\_xmax: maximum in the $x$ direction (dimension of the crystal) [m];
\item C\_ymax: maximum in the $y$ direction (dimension of the crystal) [m];
\item Cry\_length: crystal length [m];
\item Rcurv: curvature radius of the crystal [m];
\item C\_rotation: rotation angle vs vertical axis and crystal axis [rad];
\item C\_aperture: total aperture of the crystal collimator [m];
\item C\_offset: if the crystal is considered contained in a box, shift made from a face of that box touching the lateral axis of the crystal in order to lay on the bottom corner between the lateral and the entrance face of the crystal [m];
\item C\_tilt: angle between the entrance of the crystal and the vertical axis [rad];
\item Cry\_tilt: crystal tilt [rad].
\end{itemize}

The last parameters are related to the position of the crystal. The change of referential used in the crystal routine is detailed in the appendice to have a better understanding of these parameters.

\subsubsection{Input file for the graphical output}

Some parameters related to the final graphical outputs have to be set in the file \textit{infoPlotLossSpectra.csv}. This file contains the following parameters used in the method \textit{PlotLossSpectra}:

\begin{itemize}
\item interactionPoint: which IP we choose for the plot (the name of an IP element);
\item d1: starting point (distance after IP [m]);
\item d2: ending point (distance after IP [m]);
\item selflag: to indicate if we want to show the difference between the different isotopes ('Yes' or 'No');
\item fragcutoff: cutoff if selflag is 'Yes';
\item PowerOrPartFlag: determine if the plot shows power of particles ('Power' or 'Particles');
\item decdPoP: determine if the plot shows particles with charge-mass ratio ('Anything', 'Bigger than reference particle' or 'Smaller than reference particle');
\item s1: starting point [m] (if no IP element is specified);
\item s2: ending point [m] (if no IP element is specified).
\end{itemize}

\subsubsection{Cross section folder}

The cross section folder contains information used if interaction happens between particles and a standard or a magnetic collimator. It contains files related to different kind of material (carbon, copper, iron, MARS and tungsten). In each of these files, we have a file called \textit{materialinfo.csv} which contains the parameters

\begin{itemize}
\item stre: total EMD cross section for the main projectile particle on the collimator material;
\item strh: total hadronic cross section for the main projectile particle on the collimator material;
\item atarget: mass number of the target material;
\item ztarget: atomic number of the target material;
\item rho: material density [g/$\textrm{cm}^{2}$];
\item abbreviation: chemical symbol of the material, which is also the first letters of the cross section files;
\item X0: Sternheimer parameter needed for density correction in the Bethe-Bloch formula;
\item X1: Sternheimer parameter needed for density correction in the Bethe-Bloch formula;
\item m: Sternheimer parameter needed for density correction in the Bethe-Bloch formula;
\item a: Sternheimer parameter needed for density correction in the Bethe-Bloch formula;
\item C: Sternheimer parameter needed for density correction in the Bethe-Bloch formula.
\end{itemize}

Every material file also contains cross section files. The name of such files has the structure:

\begin{center}
chemical symbol - projectile mass number $Apr$ - projectile atomic number $Zpr$ - "nuclEM.dat" 
\end{center}

They contain tabulated total cross sections (hadronic and EMD) for the production of different isotopes. We can see in the first row the negative of $Apr$, the negative of $Zpr$ and the total cross section in this order. The following rows contain the change in mass number, the shift in atomic number and the partial cross section for the production of each possible daughter.

\subsubsection{FLUKA input file}

For a use of ICOSIM++ with a Fluka collimator, the program needs an specific input file for the program FLUKA. It must be a .inp file and be written as described in the FLUKA documentation (see for example the online documentation on \textit{http://www.fluka.org/fluka.php}). Please note that you must use the SOURCE card at the beginning of your input file and the USRBDX at the end of it, to permit the connection between ICOSIM++ and FLUKA. The rest of the FLUKA input file depends on the element you want to describe.

\subsubsection{Initial description of the particles in a file}

ICOSIM++ offers the possibility not to generate the initial bunch of particles, but to take it from a file. This possibility can be useful if the user wants to use special particles for its run. To do that, he must put the particles coordinates in the file \textit{initial.dat}. In this file, every line will correspond to a particle and the parameters needed for each particle are, in this order:

\begin{itemize}
\item $x$ position of the particle [m];
\item $x'$ of the particle;
\item $y$ position of the particle [m];
\item $y'$ of the particle;
\item $\delta = \displaystyle \frac{p-p_{0}}{p_{0}}$: relative momentum offset [GeV/c].
\end{itemize}

\begin{rem}
Please note that some problems can appear during the reading of the input files regarding the exploitation system on which you are running ICOSIM++ and the coding of the input files. Please be sure that the input files have the right encoding corresponding to your exploitation system. If it is not the case, you can convert the files from an encoding to another using Perl or another converter. For example, to convert a Mac OS text file to a Unix text file at the Unix shell prompt, enter

\begin{verbatim}
perl -p -e 's/\r/\n/g'  < macfile.txt > unixfile.txt
\end{verbatim}

To convert a Unix text file to a Mac OS text file, at the Unix shell prompt, enter

\begin{verbatim}
perl -p -e 's/\n/\r/g' < unixfile.txt > macfile.txt
\end{verbatim}

To convert a Windows text file to a Unix text file, enter

\begin{verbatim}
perl -p -e 's/\r$//' < winfile.txt > unixfile.txt
\end{verbatim}

and to convert a Unix text file to a Windows text file, enter

\begin{verbatim}
perl -p -e 's/\n/\r\n/' < unixfile.txt > winfile.txt
\end{verbatim}

\end{rem}

\subsection{Running ICOSIM++}

In this section, we see more in detail how to run ICOSIM++ and how to use ICOSIM++ with his full possibilities.

First of all, you must set the variable RUNNINGFLAG into the collimator file. Set it to:

\begin{itemize}
\item 1 if you want to generate a bunch of particle and to compute first a linear tracking between the primary collimators and next a non linear tracking between each elements of the particles hitting primary collimators;
\item 2 if you want to do the same kind of tracking as above, but with initial particles coordinates taken from the file \textit{initial.dat};
\item 3 if you want to generate a bunch and directly do a non linear tracking with all the particles between each elements of the lattice;
\item 4 if you want to do the same kind of tracking as 3, but with initial particles coordinates taken from the file \textit{initial.dat}.
\end{itemize}

Basically, there are two different ways to run ICOSIM++, depending on the kind of collimators that you want to simulate, and depending on if you have to link ICOSIM++ with Fluka or not.

\subsubsection{Direct run with only standard, magnetic or crystal collimators}

The first possibility is to run ICOSIM++ using only standard, magnetic or crystal collimators. To do it directly, without using any script, you will just have to type

\begin{verbatim}
./icosim++ <collimator file path> <output path>
\end{verbatim}
under the \textit{source} directory. Here \textit{<collimator file path>} is a path to the collimator file that you want to use for the simulation and \textit{<output path>} is a path to the folder in which you want to have the outputs.

\subsubsection{Run with only standard, magnetic or crystal collimators using the script \textit{runicosim++.sh}}

To run ICOSIM++ in that way, go under the \textit{script} directory and type

\begin{verbatim}
./runicosim++.sh <specific name>
\end{verbatim}
with <specific name> corresponding to the specific name used for the collimator and optics files.

All the files related to the run are then put under the directory \textit{<specific name>.*}. This allows you to make another run without crashing anything from the previous one. All the information related to the run number * will stay under its own repository.

%\begin{rem}
%If you do not use Fluka collimators, you can debug ICOSIM++ using gdb. To do that, you will have to comment the first line of the makefile and to decomment the second one. After that, do not forget to
%\begin{verbatim} 
%make clean
%\end{verbatim}
%and
%\begin{verbatim}
%make
%\end{verbatim}
%\end{rem}

\subsubsection{Run with a Fluka collimator}

If you want to run ICOSIM++ with a Fluka element, you will have to use the script \textit{runwithfluka.sh}.

To run ICOSIM++ in that case:

\begin{verbatim}
./runwithfluka.sh <FLUKA input file> <specific name>
\end{verbatim}
with <FLUKA input file> the name of the FLUKA input file describing the Fluka collimator, without .inp, and <specific name> corresponding to the specific name used for the collimator and optics file.

Here too, a repository named this time \textit{<FLUKA input file>.*}, is created with all the output files.

%\begin{rem}

%You can use the script \textit{runtest.sh} to test the connection between ICOSIM++ and a test server. To do that use the port 14999. %Set it in \textit{simulation.cc} around line 12.
%\end{rem}

\subsection{Output files}

We will now describe the ouptuts of ICOSIM++.

\subsubsection{Standard output}

The most standard output is the file \textit{output.txt} which is created at each run. This file gives information about the run and the hitting positions of particles. We can see in this file:

\begin{itemize}
%\item s: the position of all the elements in the lattice;
%\item NAME: the name of all the elements;
%\item KEYWORD: the keyword of all the elements;
%\item BETX: $\beta_{x}$ for all the elements;
%\item BETY: $\beta_{y}$ for all the elements;
%\item DX: $D_{x}$, the dispersion of $x$ for each element;
%\item DY: $D_{y}$, the dispersion of $y$ for each element;
%\item APERX: the aperture in $x$ for each element;
%\item APERY: the aperture in $y$ for each element;
\item ip: position of the \textit{TCP, CRYSTAL} and \textit{TCRYO} collimators in the lattice;
\item is: position of the \textit{TCS} collimators in the lattice;
\item ips: position of all the collimators in the lattice;
%\item hgap: half the distance between the two edges of the collimators, at the beginning of the collimators;
%\item hgap2: half the distance between the two edges of the collimators, at the end of the collimators;
\item nsig: initial size of the beam [m];
%\item sh: vector used to store the position of the elements during the computation;
%\item aperx1: aperture in $x$ at the beginning and at the end of each elements;
%\item apery1: aperture in $y$ at the beginning and at the end of each elements;
%\item xorbit: XC for each element;
%\item yorbit: YC for each element;
%\item emix: emittance in $x$;
%\item emiy: emittance in $y$;
\item Apr: mass number of the reference particle;
\item Zpr: charge of the reference particle;
\item nparti: number or particles in the simulation;
%\item beamflag: BEAMFLAG;
\item PlossPb: average power loss of the beam;
%\item i0: start element for the tracking;
%\item im: end element for the tracking;
%\item npart: number of particle per bunch;
%\item kbunch: number of bunches;
\item Aphit: mass for particles hitting the aperture;
\item Zphit: charge for particles hitting the aperture;
\item asumrem: number of particles staying in the accelerator for each turn;
\item asumhitcolli: number of particles that have hit a collimator during the current turn or a preceding one at each turn;
\item asumhits: number of particles that have hit another element during the current turn or a preceding one at each turn;
\item nhitcolli: number of particles that have hit the collimators, for each collimator;
\item hits: hit position along the accelerator for the particles that have hit another element than a collimator;
\item taubeam: expected lifetime of the beam [s].
\end{itemize}

Note that \textit{asumrem, asumhitcolli} and \textit{asumhits} are not updated during the linear tracking at the beginning of the first revolution.

You can also follow the run of the simulation in the file \textit{tracker.log} under \textit{<specific name>.*} or \textit{<FLUKA input name>.*}. If you are running ICOSIM++ with FLUKA, the file \textit{server\_1.log} will show you how FLUKA has been used as the server. In that case, more details on the particle exchange between ICOSIM++ and FLUKA can be found in the file \textit{<FLUKA input file>001.out} under the directory \textit{1}. You can follow there the run of FLUKA.

\subsubsection{Special output for a run with a crystal collimator}

When runned with a crystal collimator, ICOSIM++ also produces the file \textit{crystal\_output.out}. This file gives more detailed information on the crystal and on the passage of the particles throught it (number of particles in amorphous, dechanneling, channeling, volume reflexion, volume capture mode).


%\subsubsection{Roman pots files}

%If the lattice contains two roman pots named ROMANPOT1 and ROMANPOT2, the $x$, $y$, $x'$, $y'$ coordinates, $\displaystyle \frac{p-p_{0}}{p_{0}}$ and the revolution number at the position of the roman pots are displayed in this order in two files \textit{romanpot1.txt} and \textit{romanpot2.txt}.

\subsubsection{Graphical outputs}

At the end of each run, the scripts \textit{PlotRunSummary1.p}, \textit{PlotRunSummary2.p}, \textit{PlotRunSummary3.p} and \textit{PlotLossSpectra.p} are created. If the parameter PLOTFLAG is set to 'Yes' in the collimator file, we also have the scripts \textit{PlotTrajectory1.p} and \textit{PlotTrajectory2.p}.

This scripts contains commands that can be read by Gnuplot to produce some graphical outputs. To print some plot, just open Gnuplot and load the script typing in the Gnuplot terminal:

\begin{verbatim}
load 'script_name.p'
\end{verbatim}

We have some examples of the different graphical outputs in the appendix.

The three first plots gives a good summary of the run.

The script \textit{PlotRunSummary1.p} produces a plot of the power loss in the ring as a function of \textit{s}. The position of the IP elements is also shown on the plot.

The script \textit{PlotRunSummary2.p} produces a plot of the power load on each collimator averagely during the beam lifetime.

A plot representing how many particles are left in the beam, how many particles have been lost on a collimator and how many particles have been lost on the aperture as a function of the number of revolutions can be drawn using the script \textit{PlotRunSummary3.p}.

The second kind of graphical output is related to the losses on the aperture along the ring during the last turn. The plot is obtained using the script \textit{PlotLossSpectra.p} and depends on the parameters in the file \textit{infoPlotLossSpectra.csv}. On this plot, we can see the power load or particle loss rates along the ring, which can differentiate the different isotope or no. We have also on this plot the aperture, the dispersion function and the beta function (in the x direction). The position of the IP elements is marked as well as the position of the RBEND, SBEND, QUADRUPOLE and RCOLLIMATOR. These kind of elements are represented by a box which width is equal to the distance between that element and the previous one.

The last kind of possible graphical outputs are plots showing the trajectory of the particles, the trajectory of the reference particle, the beam envelope, the aperture and the collimators for the last turn. These plot can be obtain using \textit{PlotTrajectory1.p} for the x-direction and \textit{PlotTrajectory2.p} for the y-direction. Let's note that the parameter PLOTFLAG must be set to 'Yes' in the collimator file to have this kind of plots.

\subsubsection{How to print the coordinates of the particles}

There are three useful parameters that are made for printing the coordinates of a chosen particle at special moments (IDPART, IDELT and OUTCOORD). They can be modified in the collimator file.

The first one is the parameter IDPART. This parameter represent the ID of the particle which will be spied.

With the parameter IDELT, the user can set the number of the element after which he wants to have the coordinates.

The parameter OUTCOORD determine the kind of printing.

Using them, the user can see the coordinates of the particles trough different methods.

The first one is the function \textit{outCoord}, which prints the coordinates for a chosen particle between every element in the file \textit{coordinates.dat}. To use it, you must first of all set the particle that you want to track. To do it, set the parameter IDPART to the identification corresponding to the particle that you want to track and set the parameter OUTCOORD to 3.

The second funtion is \textit{outPunctual}, which print the coordinates at each turn at a certain point of the accelerator. To do it, you will have to choose the particle that you want to track as above and to choose the number of the element after which you want the coordinates using the parameter IDELT. Then set OUTCOORD to 4 and the coordinates will appears at the end of the run in the file \textit{coordinates\_punctual.dat}.

The user can also print the coordinates of all the particles after a chosen element. To do that, he will have to set IDELT with the chosen element and OUTCOORD to 2.

Another very useful way to track the particles coordinates during the run is to set OUTCOORD to 1. This produces an output of the 6 coordinates at each element for all particles during all the simulation. Basically, doing that you will have the coordinates of the particles at every time at every place around the accelerator. This output can be seen in the file \textit{tracker.log} if we use the scripts to run ICOSIM++ or directly in the terminal. Note that doing some kind of printing will make the running time grows.

If the user do not want any output of the coordinates of the particles, he will have to set OUTCOORD to 0.

The coordinates printed are ($x$, $y$, $x'$, $y'$ and $\displaystyle \frac{p-p_{0}}{p_{0}}$, $t$) in columns in this order.

We can see a summary of the different ways of printing coordinates in the Table \ref{Table 1}.

\setlength{\extrarowheight}{0.0cm}

\begin{table}[H]
\hspace{-1cm}
\begin{tabular}{|c|c|c|c|c|}
\hline
\textbf{To print} & \textbf{OUTCOORD} & \textbf{IDPART} & \textbf{IDELT} & \textbf{In the file} \\
\hline
Nothing & 0 & - & - & - \\
All the part. after all the elts & 1 & - & - & tracker.log \\
All the part. after a chosen elt & 2 & - & Elt nber & coordinates\_elt.dat \\
One part. after all the elts & 3 & Part. nber & - &  coordinates.dat \\
One part. after a chosen elt & 4 & Part. nber & Elt nber & coordinates\_punctual.dat \\
\hline
\end{tabular}
\caption{\label{Table 1}Different ways to print the coordinates of particles during the simulation.}
\end{table}
\setlength{\extrarowheight}{0.6cm}

%\section{Important note}

%Note that the collimation system descibed using RUNNINGFLAG=1 or 2 will be the one of the LHC (Large Hadron Collider) at CERN. If you want to describe another accelerator's collimation system, you will have to adapt the program, setting new names for the primary collimators, for examples, corresponding to that accelerator's lattice. This can be quite easily done in the file \textit{simulation.cc} where the different kind of collimators are set.

%In any case, you can simulate particle along any accelerator using RUNNINGFLAG=3 or 4, but this will not take into account the difference between primary, secondary or tertiary collimators.

\section{Others executables created by the makefile}

By typing \textit{make} in the source directory, the user will also create some other executables which can be used to test or debug different part of the program. For all of them, the interest is that they can be used to test some modifications of the code without the need to make these modifications directly in the source code and using the fact that these files are already built in the makefile and that the necessary files are already included. They could be useful especially for people who wants to make further development of ICOSIM++ and other programmers. To run one of these executables, just type

\begin{verbatim}
./executable_name
\end{verbatim}

These files are detailed there.

\subsection{testParticle}

In the main of that file, we can test the generation of particles and the coordinates just after the generation.

\subsection{testLattice}

This file can be used to test the construction of a test lattice composed with elements and collimators and to test the lattice's attributs and methods.

\subsection{testElement}

We can use this file to test the constructors of the class Element.

\subsection{testCollimator}

It can be used to test the different methods and attributs of the class Collimator.

\subsection{debug}

This file can be used to debug or test some part of the code.

\newpage

\appendix

\section{Coordinates used}
The coordinates used to described each particle are:

\begin{itemize}
\item $x$: transverse horizontal position (relative to the orbit) [m];
\item $x' = \displaystyle \frac{dx}{ds}$ (with $s$ the distance along the accelerator);
\item $y$: transverse vertical position (relative to the orbit) [m];
\item $y'=\displaystyle \frac{dy}{ds}$  (with $s$ the distance along the accelerator);
\item $t$: time [s];
\item $\delta = \displaystyle \frac{p-p_{0}}{p_{0}}$: relative momentum offset.
\end{itemize}

\section{Examples of graphical outputs}

We show here some examples of the different graphical outputs that can be obtained using ICOSIM++.

\begin{figure}[H]
\begin{center}
\includegraphics[height=11cm]{PlotRunSummary1.jpeg}
\caption{Power loss in the ring as a function of \textit{s}.}
\label{fig:1}
\end{center}
\end{figure}

\begin{figure}[H]
\begin{center}
\includegraphics[height=9.3cm]{PlotRunSummary2.jpeg}
\caption{Power load on each collimator.}
\label{fig:2}
\end{center}
\end{figure}

\begin{figure}[H]
\begin{center}
\includegraphics[height=9.3cm]{PlotRunSummary3.jpeg}
\caption{Behaviour of the particles during the run.}
\label{fig:3}
\end{center}
\end{figure}

\begin{figure}[H]
\begin{center}
\includegraphics[height=9.3cm]{PlotLossSpectra.jpeg}
\caption{Losses on the aperture.}
\label{fig:4}
\end{center}
\end{figure}

\begin{figure}[H]
\begin{center}
\includegraphics[height=9.3cm]{PlotTrajectory1.jpeg}
\caption{Particles trajectories.}
\label{fig:5}
\end{center}
\end{figure}

\newpage

\section{Change of referential in the crystal routine}

More information concerning the crystal routine as well as this plot can be found in \cite{a3}. The crystal parameters concerning the position of the crystal in the file \textit{crystalinfo.csv} are related to these different steps. 

\vspace{2cm}

\begin{figure}[H]
\begin{center}
\includegraphics[height=14cm]{crystal.jpg}
\caption{Steps used during the change of referential at the beginning of the crystal routine.}
\label{fig:6}
\end{center}
\end{figure}

\newpage

\begin{thebibliography}{5}
\bibitem{a1}\textsc{N. Holden}, \textit{Development of the ICOSIM program and application to magnetised collimators in the LHC}, http://cdsweb.cern.ch/record/1151294/files/AB-Note-2008-054.pdf.
\bibitem{a2}\textsc{F. Christoph Iselin}, \textit{The MAD Program, (Methodical Accelerator Design), Version 8.13, Physical Methods Manual}, http://project-madwindows.web.cern.ch/project-madwindows/MAD-resources/phys\_guide.pdf
\bibitem {a3}\textsc{Valentina Previtali}, \textit{Performance Evaluation of a Crystal-Enhanced Collimation System for the LHC}, ThÚse Nr. 4794 (2010), Ecole Polytechnique Fédérale de Lausanne (EPFL), Faculté des Sciences de Base, Laboratoire de Physique des Accélérateurs de Particules.
\end{thebibliography}
\end{document}