%format: latex  %hyphen: english
%
%
%              LEAR Crystal Barrel Experiment, PS 197
%
%                CRYSTAL BARREL PI0 IDENTIFICATION
%                =================================
%
%         This documentation is available as CB-Note 133
%
%  used format:
%  banks: {\bf BANK}
%  commons,variables: {\sc /common/} {\sc var}
%  subroutine: NAME
%
\documentstyle[twoside]{article}
%\documentstyle[12pt,twoside]{article}
 
 
%   DINA4 format DESY
%\newlength{\dinwidth}
%\newlength{\dinmargin}
%\setlength{\dinwidth}{21.0cm}
%\textheight24.2cm \textwidth17.0cm
%\setlength{\dinmargin}{\dinwidth}
%\addtolength{\dinmargin}{-\textwidth}
%\setlength{\dinmargin}{0.5\dinmargin}
%\oddsidemargin -1.0in
%\addtolength{\oddsidemargin}{\dinmargin}
%\setlength{\evensidemargin}{\oddsidemargin}
%\setlength{\marginparwidth}{0.9\dinmargin}
%\marginparsep 8pt \marginparpush 5pt
%\topmargin -42pt
%\headheight 12pt
%\headsep 30pt \footheight 12pt \footskip
%24pt
% end dina4p definition
 
%
%       Zurich Definition:
%
\setlength{\unitlength}{1pt}
\textwidth=433pt
\topmargin=-21.57pt
\oddsidemargin=7.53pt
\evensidemargin=7.53pt
\footheight=36pt
\textheight=650pt
\renewcommand{\baselinestretch}{1.1}
 
\title{ \makebox[\textwidth][r]{\normalsize CB-Note 133}\\[2cm]
        LEAR Crystal Barrel Experiment, PS 197\\
      Pi0 Reconstruction And Optional Fitting Software (PI0FND) Ver. 2.0}
 \author{P. Schmidt\\
         I.\,Institut f\"ur Experimentalphysik\\
         Universit\"at Hamburg}
\date{June 24, 1992}
\begin{document}
%
 \maketitle
\newpage
%
 \tableofcontents
%
% \listoftables
% \listoffigures
\newpage
%
 \section{Introduction}
This document describes the {\em $\pi^{0}$ reconstruction software PI0FND}.
The routine package was written by John Tompkin and used at the {\em Crystal
Ball Collaboration} under the name of {\em PHYSAC}.
 In the first step merged $\pi^{0}$'s (two photons resulting in one
cluster) are searched by using the showermass of a cluster. Afterwards
the other $\pi^{0}$'s are reconstructed by using the four-momentum of the two
decay photons and their angular and energy resolution. In order to run the
package the user has to call {\sc piinit} once in routine {\sc usinit} where
all necessary parameters are initialized with default values (see below).
 The user can extend the number of particles to be
reconstructed up to ten different particles. In the current version PI0FND is
 able to handle 20 photons per event.
 This figure should not be exceeded. The values of the
four-momentum  as well as the values of resolution are taken
from the Global-Tracking Bank TTKS where the main results are returned, such as
the indices of the two $\pi^{0}$ decay photons (or the cluster id for
merged $\pi^{0}$'s), the four-momentum vector of the
$\pi^{0}$, $\Phi$ and $\Theta$ of the $\pi^{0}$ and square-root of $\pi^{0}$
energy. {\bf The errors are filled for a future version of the
kinematic fitting package, which can fit $\pi^{0}$'s.}
 The index of the two decay photons is defined as \[{\em index} =\gamma_{1}
\cdot 1000 + \gamma_{2}\]
The two photon indices are the TTKS-particle numbers.
 The flow of the software is shown in figure 1.
 Note that the global
identification character for the {\em $\pi^{0}$ reconstruction
software} is 'PI'.

\begin{center}
{\bf Note:}
\end{center}
\begin{quote}
{\bf This version requires at least BCTRAK 1.42.}
Major change since version 1.0: Before the $\pi^{0}$ reconstruction
all clusters are searched for merged $\pi^{0}$'s and are not included in the
following $\pi^{0}$ search (can be disabled by setting {\sc qmrgpi} to
{\tt .FALSE.}). The {\sc vetopi} array is enlarged to dimension 70.
Reconstruction is not possible for events with more than 70 particles in
the global track bank.
{\bf If QMRGPI is true you need a GTRACK version greater 1.20/03 or
you need some banks from BCTRAK. Watch out for error messages!}
PI0FND cannot be called twice on the same event.

Note that for this package it is essential to have the errors of the
measured variables. So it is not possible to do first a kinematic fit
and then to use PI0FND because you don't have errors from the fit.
\end{quote}

Please report any errors found in the
software immediately to:
\begin{description}
\item[Gunter Folger] (GUNTER@CERNVM)
\item[Fritz-Herbert Heinsius] (F31HEI@DHHDESY3)
\end{description}

 \section{For Urgent Usage}
Call {\em PIINIT} in routine {\em USINIT}. In case you want to alter any values
of parameters given in {\em PIINIT} (default values see {\sc common /piuser/})
do so after calling {\em PIINIT}. {\em PI0FND} has to be called in your own user
routine. If you need more output informations than given  in the TTKS-Bank use
common blocks {\sc /piuser/ , /pibest/}. You will get a better review by reading
the descriptions of subroutines  {\em PIINIT, PI0FND}, {\sc /piuser/}.
 Note:
\begin{enumerate}
\item The optional kinematic fitting
 routine {\em PIFITS} is not sufficiently tested.
Do not use it in this version!
\item If you exclude photons from reconstruction by using the VETOPI(I)-array,
please
reset VETOPI(I)=.FALSE. after PI0FND.(see example)
\item The default value of the variable CMAXPI for the first $\chi^{2}$-cut is
9 (corresponding to a 3$\sigma$ value), the value of CONLPI 2.7\% (CONLPI being
the value for the confidence-level-cut and being the equivalent to a
3$\sigma$-value). If you want to change the cut value CMAXPI you should also
change the value of CONLPI (the higher CMAXPI the lower CONLPI)
\item In case $\eta$'s should be reconstructed please set QETAPI=.TRUE. after
calling PIINIT (default value =.FALSE.).
\item In case you don't wish to reconstruct merged  $\pi^{0}$'s by using
their showermass you should set QMRGPI=.FALSE. after
calling PIINIT (default value =.TRUE.).
\end{enumerate}
Example:
\begin{verbatim}
      SUBROUTINE USER
+SEQ,PIUSER
+SEQ,PIBEST
etc.
*     reset the VETOPI array (only needed if set to .TRUE. in the last call)
      DO 10 I=1,70
         VETOPI(I)=.FALSE.
10    CONTINUE
         .
         .
*  in case certain photons(i) are excluded from reconstruction
      VETOPI(I)=.TRUE.
         .
      CALL PI0FND
         .
*       if IQ(LTTKS+2).EQ.2 then pi0/eta
         .
      END
      SUBROUTINE USINIT
+SEQ,PIUSER
      CALL PIINIT
*  Change parameters of PIINIT here:
*  e.g. if you written output:
      NDMPPI=1
*  e.g. to change Pi zero mass
      FMASPI(1)=134.96**2
         .
      END
\end{verbatim}
If you want to reconstruct $\eta$'s as well:
\begin{verbatim}
      SUBROUTINE USINIT
+SEQ,PIUSER
      CALL PIINIT
* Change default values of mass-flag etc.
* default value of Eta mass = 2.689626E+05
      LISTPI(2)=2
      LTOTPI=2
      QETAPI=.TRUE.
         .
         .
         .
      END
\end{verbatim}
\newpage
\section{Description of Output-Banks}
For more detailed description of the TTKS-Bank see {\em CB-Note 118}. Here are
listed the output parameters which are stored in the TTKS-Bank.
The contents of the bank are as shown and described below (as far as the
$\pi^{0}$'s are concerned).
\begin{table}[htbp]\centering
\begin{tabular}{|c|c|l|}\hline
{\sl Offset} & {\sc type} & {\sl Quantity} \\ \hline
$+1$ & {\sc integer} & {\sl Number of particle} \\
$+2$ & {\sc integer} & $=2$ {\sl if PI0FND reconstr. particle} \\
$+3$ & {\sc integer} & {\sl Part. id} $\pi^{0} = 7 ,\eta = 17$ \\
$+4$ & {\sc integer} & {\sl not filled} \\
$+7$ & {\sc integer} & {\sl ....} \\
$+8$ & {\sc integer} & {\sl orig. vertex, not yet defined} \\
$+9$ & {\sc integer} & 2 PED $\pi^{0}$: $\gamma$ {\sl index}
                     $=\gamma_{1}\cdot 1000 + \gamma_{2}$ \\
     &               & merged $\pi^{0}$: {\sl - cluster id (negativ)}  \\
$+10$ & {\sc ....} & {\sl not filled} \\
$+11$ & {\sc integer} & merged $\pi^{0}$: {\sl see TTKS manual}  \\
$+12$ & {\sc integer} & merged $\pi^{0}$: {\sl see TTKS manual}  \\
$+13$ & ...     & ... \\
$+14$ & {\sc real} & {\sl Momentum, P of} $\pi^{0}$ \\
$+15$ & {\sc real} & {\sl Energy of} $\pi^{0}$ \\
$+16$ & {\sc real} & $Px$ {\sl of} $\pi^{0}$ \\
$+17$ & {\sc real} & $Py$ {\sl of} $\pi^{0}$ \\
$+18$ & {\sc real} & $Pz$ {\sl of} $\pi^{0}$ \\
$+..$ & ... & {\sl words 19 - 23 errors} \\
$+..$ & ... & {\sl words 24 - 30 are not filled for} $\pi^{0}$ \\
$+31$ & {\sc real} & 2 PED $\pi^{0}$: {\sl opening angle} \\
$+35$ & {\sc real} & {\sl reconstructed} $\pi^{0}${\sl mass} \\
      &            & {\bf for GTRACK less 1.20/00 take IQ(-4)} \\
$+..$ & ... & {\sl words 36 - 42 are not filled for} $\pi^{0}$ \\
$+43$ & {\sc real} & $\Phi$ {\sl angle in XY plane for} $\pi^{0}$ \\
$+44$ & {\sc real} & $\Theta$ {\sl angle for} $\pi^{0}$ \\
$+45$ & {\sc real} & $\sqrt {E}$ {\sl of} $\pi^{0}$ \\
$+..$ & ... & {\sl words 46 - 51 covariance matrix} \\ \hline
\end{tabular}
\caption{Data in the {\bf TTKS} sub-bank }
\label{tablevt}
\end{table}
$\pi^{0}$ with number N can be reached by looping through all particles
and selecting those with particle identity $=7$.(How to do it see CB-Note 118)

 The number of particles in
{\em word 1} is enlarged by the reconstructed $\pi^{0}$'s (also in {\bf
HTRK} bank word 3). {\em word 4} gives number of merged $\pi^{0}$'s,
{\em word 5} gives number of 2 PED $\pi^{0}$'s.
In {\em word 4} of the {\bf HTRK} bank you find the PI0FND version
number.
 \section{Common Blocks}

 \subsection{Description of the PI0FND Common Blocks}
All common blocks can be included with the patchy {\tt +SEQ,{\em name}.}
command. Only the {\sc piuser} common block should be accessed from
user routines.

 \subsection{PIUSER}
In the {\sc /piuser/} common block are some changeable input and some output
parameters stored:
\begin{verbatim}
      INTEGER MASSPI,NTOTPI,LISTPI,IPI0PI,LPI0PI,NDMPPI,
     +        IVNTPI,IBSTPI,LTOTPI,NPI0PI,
     +        IPIZPI,MFLAPI,METAPI,MPI0PI,IRETPI,IVERPI
      REAL    PAIRPI,CHITPI,FMASPI,CONLPI,CMAXPI,XMLTPI,RMINPI,RMAXPI
      LOGICAL VETOPI,QETAPI,QMRGPI
      COMMON /PIUSER/ PAIRPI(20,20,3), CHITPI(20,10),NTOTPI,IBSTPI,
     +  FMASPI(10),MASSPI,LISTPI(10), LTOTPI,CONLPI,CMAXPI,
     +  IVNTPI,XMLTPI,IPI0PI(2,50),LPI0PI(50),VETOPI(70),NDMPPI,NPI0PI,
     +  IPIZPI(2,50),MFLAPI(50),
     +  METAPI,MPI0PI,QETAPI,QMRGPI,IRETPI,RMINPI,RMAXPI,IVERPI
\end{verbatim}
All figures in brackets () are default values.
List of input parameters:
\begin{itemize}
\item {\sc fmaspi(k)}-array stores in elements of K($\leq$10) the fit
square-masses of the particles to be reconstructed. It is filled in {\sc
piinit} (fmaspi(1)=134.4**2, fmaspi(2)=551.6**2, fmaspi(3)=963.9**2)
\item {\sc masspi} is the number of fit masses in {\sc fmaspi} (3)
\item {\sc listpi(i)} is the array which stores the flags for the fit-masses
in {\sc fmaspi}. I=1 means $\pi^{0}$, I=2 $\eta$ and I=3 $\eta$'. Is initialized
in {\sc piinit} (LISTPI(1)=1)
\item {\sc ltotpi} is the number of particles to be reconstructed (1). Used by
array {\sc listpi}.
\item {\sc conlpi} is the minimum confidence-level value which is required for
each configuration in {\sc piconf}. {\sc conlpi}-value can be changed by User
(0.0027)
\item {\sc cmaxpi}-value is the max $\chi^{2}$-value. {\sc pi0fnd} requires that
the $\chi_{\gamma\gamma}^{2}$-value of each photon-photon pair is lower than
{\sc cmaxpi}. Can be changed by User in {\sc piinit} (9.)
\item {\sc xmltpi} is a dummy parameter which initializes the optional kinematic
fit-routine {\sc pifits} if {\sc xmltpi}$>0$ (0)
\item {\sc ndmppi} is a dummy parameter. {\sc ndmp}$\geq 1$ {\sc pi0fnd}
will give
written output.(0)
\item {\sc vetopi(70)}is a logical array. By setting {\sc vetopi(i)}=.
{\sc true}. the user can sort out photons from the reconstruction process.
This is done in {\sc pimrgd}. (.FALSE.)
\item {\sc qmrgpi} is a logical if PIMRGD should be called to search for
merged $\pi^{0}$'s (.TRUE.)
\item {\sc rminpi} is the lower bound for the showermass of merged
$\pi^{0}$'s
\item {\sc rminpi} is the upper bound for the showermass of merged
$\pi^{0}$'s
\end{itemize}
These are the output parameters:
\begin{itemize}
\item {\sc pairpi(ii,jj,k)} is an array which stores for all photon-photon pairs
with index {\sc ii,jj} in element of {\sc k} the following informations:
\begin{enumerate}
\item K=1 inv.mass of photon-photon pair
\item K=2 mass-flag of the fit mass corresponding to inv. pair mass
\item K=3 $\chi_{\gamma\gamma}^{2}$-value of each pair
\end{enumerate}
Note: the indices {\sc ii,jj} of the photons are the {\sc pi0fnd} internal
indices.
\item {\sc chitpi(nsave,max)}-array stores for each configuration {\sc nsave}
with number of pairs {\sc max} the $\chi_{\Sigma}^{2}$-value which is the sum
of all $\chi_{\gamma\gamma}^{2}$-values of each pair
\item {\sc ntotpi} is the number of configurations
\item {\sc ibstpi} help parameter to select configurations in {\sc piconf}
\item {\sc ipi0pi(2,k)}contains in elements(1,K) and (2,K) the indices of
 the two
gammas that form the reconstructed particle No.K. Note the ordering condition:
{\sc ipi0pi(1,k)}$<${\sc ipi0pi(2,k)}
Note: photon indices according to Global-Track Bank ordering
\item {\sc lpi0pi(ng)}contains in elements J the no.K of the reconstructed
particle to which gamma no.J is assigned.{\sc ng} is the number of all gammas in
one event
\item {\sc npi0pi} is the number of reconstructed not-merged $\pi^0$'s.
\item {\sc mpi0pi} is the number of reconstructed merged $\pi^0$'s.
\item {\sc ipizpi(2,k)}contains in elements (1,K) and (2,K) the {\sc pi0fnd}
internal photon indices of the two decay gammas from particle number K.
\end{itemize}
In case the user wants to reconstruct $\eta$'s here is the output parameter:
\begin{itemize}
\item {\sc metapi} is the number of reconstructed $\eta$'s
\item {\sc iretpi} is the return code: -1: pi0fnd already called before
on this event; 1=no TTKS bank; 2=too many particles in event; 3=too low
number of PEDs; 4=more than 20 accepted PEDs; 5=PIRECO returned more
pairs than possible.
\item {\sc iverpi} PI0FND version number.
\end{itemize}
\subsection{PIOPTI}
In the {\sc /piopti/} common block are some variables stored, which
the program needs for the optional kinematical fitting.
\begin{verbatim}
      REAL GGOPPI,BOPTPI,C0OPPI,COPTPI,XXOPPI,XOPTPI,GBOPPI,XTSTPI
      COMMON /PIOPTI/ GGOPPI(6,6),BOPTPI(6),
     +      C0OPPI(6),COPTPI(6), XXOPPI(6),XOPTPI(6),
     +      GBOPPI(6),XTSTPI(20,20)
\end{verbatim}
\begin{itemize}
\item {\sc ggoppi(i,j)} contains in elements {\sc i,j} the values of the
energy and
angular resolution of the two photons of each pair
\item {\sc boptpi(i)} contains in elements the derivatives for the
calculation of the
square mass resolution
\item {\sc c0oppi(i)} array which stores the differences between the
original values
of the energy and angle of each photon and the fitted values
\item {\sc coptpi(i)} array which contains in elements of I the
fitted values of the
resolution
\item {\sc xxoppi(i),xoptpi(i)} arrays contain in elements of I the energy
and $\Theta$,
$\Phi$ of each photon
\item {\sc gboppi(i)} help array in order to calculate the fitted resolution
\item {\sc xtstpi(igam,jgam)} contains in elements of {\sc igam,jgam} the
cos$\Theta$ of the angle between the two photons of each pair combination
\end{itemize}

\subsection{PIBEST}
In the {\sc /pibest/} common block are the values of the best reconstructed
configurations stored.
\begin{verbatim}
      REAL    PPAIPI,PMASPI,PCHIPI,XLEVPI
      LOGICAL QGAMPI
      INTEGER PFLGPI,JGAMPI,NPRMPI
      COMMON /PIBEST/ PPAIPI(5,10),PMASPI(10),PFLGPI(10),PCHIPI(10),
     +          JGAMPI(2,10),NPRMPI(10),XLEVPI,QGAMPI(20)
\end{verbatim}
\begin{itemize}
\item {\sc ppaipi(jj,ip)}-array contains for all reconstructed pairs with index
{\sc ip} the sum of each four-momentum  component if JJ$\leq 4$. JJ=4 contains
the total momentum of the reconstructed particle.
\item {\sc pmaspi(ip)} contains in elements IP the inv. mass of the
reconstructed particle
\item {\sc pchipi(ip)} array where the $\chi_{\gamma\gamma}^{2}$ value of the
reconstructed particle is stored
\item {\sc xlevpi} variable which gives the confidence-level
of the reconstructed
pair
\item {\sc qgampi} logical parameter which helps to find best configuration
\item {\sc pflgpi(ip)} stores the mass-flag of the fit mass to which the
reconstructed particle is assigned
\item {\sc jgampi(k,ip)} contains the indices of the photons reconstructed as
decay photons in the array of the best configuration
\item {\sc nrpmpi(ipmf)} array which is used to find the fit-mass which is to be
assigned to the reconstructed particle
\end{itemize}

\subsection{PIINPT}
In the {\sc /piinpt/} common block are the necessary input values stored
\begin{verbatim}
      REAL    PGAMPI,BESTPI,MFLGPI,ERR4PI
      INTEGER NGANPI,NCMBPI
      COMMON /PIINPT/ PGAMPI(20,4),BESTPI(20,2),NGANPI,
     +   NCMBPI(20,10,20),MFLGPI(20,20),ERR4PI(20,4)
\end{verbatim}
\begin{itemize}
\item {\sc pgampi(ng,k)} contains in elements of K the four momentum of each
photon NG
\item {\sc bestpi(i,2)} array which contains in {\sc bestpi(i,1)} the index of
the configuration and in {\sc bestpi(i,2)} the $\chi^{2}$-sum value of this
configuration
\item {\sc mflgpi(ncon,i)} stores the mass-flag which is associated to each pair
in configuration no.{\sc ncon}
\item {\sc err4pi(ng,j)} contains in elements of J the values of the
direction and
energy resolution for each photon NG
\item {\sc nganpi} is the number of gammas
\item {\sc ncmbpi(ntot,max,k[m])} is the array where the
selected configurations are
stored. Element {\sc ntot} = index of configuration,{\sc max}= number of pairs
in this configuration and {\sc k} = the {\sc pi0fnd}-index of the photons
belonging to a pair combination.
\end{itemize}

\subsection{PISAVE}
\begin{verbatim}
      INTEGER NPRIPI,IPRIPI
      REAL    PRVCPI
      COMMON /PISAVE/ NPRIPI,IPRIPI(2,400),PRVCPI(6,400)
\end{verbatim}
\begin{itemize}
\item {\sc npripi} is the number of photon-photon pairs with a
$\chi_{\gamma\gamma}^{2}$ value which is less than {\sc chimax}
\item {\sc ipripi(2,400)} array stores the indices of the preselected photons
($\chi_{\gamma\gamma}^{2} <${\sc chimax})
\item {\sc prvcpi(6,400)} array stores the energy and $\Theta,\Phi$ of the above
mentioned preselected photons of each pair
\end{itemize}

\subsection{PIBRAI}
\begin{verbatim}
      INTEGER IBRAPI,NGAMPI
      COMMON /PIBRAI/ IBRAPI(20),NGAMPI
\end{verbatim}
\begin{itemize}
\item {\sc ibrapi(n)} array which translates the {\sc pi0fnd} photon index back
to photon index due to {\sc global track }- bank
\item {\sc ngampi} the number of gammas
\end{itemize}
%%%%%%%%%%%%%%%%%%% Subroutines description
 \section{Subroutines}



 \subsection{PIINIT}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                  \\
%{\bf Call Arguments:}        \\
{\bf Common Blocks Used:} {\sc piuser}\\
%{\bf Subroutines Referenced:} {\sc }\\

This subroutine must be called by the user once in {\sc usinit}.{\sc
piinit} initializes values necessary for the reconstruction work. In here  the
number of particles {\sc masspi} to be reconstructed and the "theoretical value"
of the square mass of each particle in  array {\sc fmaspi} are evaluated.
The theoretical value is taken from a fit mean value. Other important
values are the minimum confidence-level {\sc conlim} and the maximum value of
the difference between theoretical and calculated invariant mass in units of
 the mass
resolution {\sc cmaxpi}. If the user doesn't want to use default values they
 can be
altered after {\sc call piinit}. For instance:
With {\sc xmltpi} the user can use the kinematical
fitting routine {\sc pifits} by setting {\sc xmltpi}$>0$. {\sc ndmppi}$> 0$
means {\sc pi0fnd} will give written output.

 \subsection{PI0FND}
%{\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                  \\
%{\bf Call Arguments:}        \\
{\bf Common Blocks Used:} {\sc cblink,cbstop,piopti,piuser,pibest,piinpt,pisave,
pibrai}\\
{\bf Subroutines Referenced:} {\sc pireco,pioutp,pimrgd, bcnctp, bcnptc}\\
This routine called in the user's main routine  is the frame routine for
the reconstruction work. First PIMRGD is called to search for merged
$\pi^{0}$'s (if {\sc qmrgpi} is true).
Afterwards {\sc pi0fnd} is taking the four-momentum vector and the
corresponding values of the resolution from the {\sc ttks} bank. In the current
version {\sc pi0fnd} can handle max. 20 photons. The main reconstruction work is
done in {\sc pireco} (former name {\sc physac}) and {\sc pioutp}.The results are
stored again in the {\sc ttks} bank (see section {\em Description of Output
Banks}).
 {\sc npi0} being the number of $\pi^{0}$'s
, {\sc ipi0} being the array which stores the indices of the photons  of a
$\pi^{0}$ decay. These two variables are stored in the {\sc /piuser/} common
block. Note that there are two kinds of indices in use: the number of particles
used by the {\sc ttks}-Bank and the {\sc pi0fnd} internal indices. The latter
are "translated" back at the end of the routine by array {\sc ibrapi}.
You can get a return code in variable {\sc iretpi} (see description of
common {\sc /piuser/}).

 \subsection{PIMRGD}
%{\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                  \\
%{\bf Call Arguments:}        \\
{\bf Common Blocks Used:} {\sc cblink,cbunit,piuser,pi2pi,bcflag}\\
{\bf Subroutines Referenced:} {\sc bitopt, bcoscl, bcvcor, bcecor,
bcttks, mzpush, mzform, mzbook}\\

This routine searches for merged
$\pi^{0}$'s (i.e. two photons in one cluster). The found $\pi^{0}$'s are
added to the global track bank. For the corressponding PEDs the array
{\sc vetopi} is set to false. Note that you need BCTRAK output banks if
the data is produced before GTRACK version 1.20/04.
If the data to calculate the $\pi^{0}$ energy and direction is not
available, the variable {\sc qmrgpi} is set to false and this subroutine
will not called again.

 \subsection{PIRECO}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                  \\
{\bf Call Arguments:} {\sc npif}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc picomb,pifits,piconf,pisort} \\
In {\sc pireco} the main reconstruction work is done. In a first step {\sc
pireco} calculates for all photon-photon pair combinations the square invariant
 mass
, the corresponding theoretical square mass value (if more than one particle is
chosen for reconstruction) and a $\chi^{2}$ value being calculated from:
\( \chi_{\gamma\gamma}=\frac{m_{th}^{2} - m_{inv}^{2}}{\sigma_{\gamma\gamma}}\).
$\sigma_{\gamma\gamma}$ is the value of the square mass resolution.
Next {\sc pireco} is choosing only those photon-photon pairs for further
reconstruction, if $\chi_{\gamma\gamma}^{2} \leq \chi_{max}^{2}$. In the next
step {\sc pireco} is forming groups of pairs under the condition that the
involved photons are used only once for a pair combination. The routine then
sums up the $\chi_{\gamma\gamma}^{2}$ values to a $\chi_{\Sigma}^{2}$ sum which
corresponds to a confidence-level. In the last cut {\sc pireco} is forming
configurations of these groups in case the confidence-level-value is higher
than the given minimum value {\sc conlim} and the number of pairs in this group
is
the highest possible one. The array of the configurations is {\sc ncmbpi}.
{\sc pireco} offers a set of configurations (not more than 20) as a final
result. These are sorted after the $\chi^{2}$-sum value in array {\sc bestpi}.
 \subsection{PICOMB}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                  \\
{\bf Call Arguments:} {\sc igam,jgam,*mass2,*ermm2,*mflg,*mfit,*cthet,*chisq }\\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
This routine is called by {\sc pireco} and calculates for all photon-photon
pair combinations ({\sc igam,jgam} being the indices of the two photons), the
square inv.mass {\sc mass2}, the square mass resolution {\sc ermm2} and the
{\sc chisq} value being the $\chi_{\gamma\gamma}^{2}$-value mentioned above.
{\sc mfit} is the "theoretical" mass value, corresponding to a mass flag {\sc
mflg}. If more than one particle is chosen for reconstruction {\sc picomb} is
taking the {\sc mfit,mflgpi} values which are closer to the calculated {\sc
mass2}-value.
 \subsection{PIFITS}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                  \\
{\bf Call Arguments:} {\sc xmp2,mipzr2,ii,jj,chifit}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc pierrs,pimfit,pisfit} \\
This routine is optional. {\sc pifits} is a kinematical fitting routine which
can be included by the user with setting {\sc xmult}$ >0$ in {\sc piinit}. {\sc
pifits} returns the fitted square-mass value {\sc xmp2} and the fitted
$\chi_{\gamma\gamma}^{2}$-value {\sc chifit} for a given photon-photon pair
with indices {\sc ii,jj} and a given fit mass {\sc mipzr2}.

 \subsection{PIERRS}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc ii,jj}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc } \\
This (optional) routine calculates, in case the user installes {\sc pifits}, the
error of the square-inv.mass together with the following other two routines
{\sc pimfit,pisfit}. In array {\sc ggoppi} are stored the sigmas of
the energy and
angle of photon no. {\sc ii} and {\sc jj}.
 \subsection{PIMFIT}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc x,xms,xmfit2,con}       \\
{\bf Common Blocks Used:} {\sc }\\
{\bf Subroutines Referenced:} {\sc} \\
Routine calculates the square inv.mass {\sc xms} of each photon-photon pair
and the difference {\sc con} between fit-mass {\sc xmfit2} and {\sc xms}.
 \subsection{PISFIT}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc x,b}       \\
{\bf Common Blocks Used:} {\sc}\\
{\bf Subroutines Referenced:} {\sc } \\
{\sc pisfit} calculates the necessary derivatives due to error progression.

 \subsection{PICONF}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc ichi,chi,max}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc pichek} \\
Routine {\sc piconf} is forming so-called configurations under the limiting
condition that photons are used only once for a pair combination. In order to do
so {\sc piconf} takes only those photon-photon pairs stored in {\sc ichi} if
$\chi_{\gamma\gamma}^{2} < \chi_{max}^{2}$. For each configuration {\sc piconf}
a $\chi$-sum value is calculated which corresponds to a confidence-level value.
{\sc piconf} then requires a minimum confidence-level {\sc conlim} for each
configuration {\em and} a maximum number {\sc max} of photon-photon pairs .
All configurations surviving this cut are stored in array {\sc ncmbpi}.
{\sc piconf} can handle up to 20 configurations. If there are more than 20 {\sc
pichek} is called.
 \subsection{PICHEK}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc ii,chinew,nsave}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc } \\
This routine is called by {\sc piconf} in case there are more than 20
configurations. {\sc pichek} then sorts out those configurations with the lowest
confidence-level ({\sc cl}) value and returns the 20 configurations with the
highest {\sc cl}-value.
 \subsection{PISORT}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc npif}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc } \\
{\sc pisort} is the last routine in the {\sc pireco} package. The configurations
stored in array {\sc ncmbpi} are sorted due to their confidence-level value.
The sorted configurations with the number of pairs {\sc npif} are stored in
array {\sc bestpi}.
 \subsection{PIOUTP}
% {\bf Author:}        \\
%{\bf Creation Date:}  \\
%{\bf References:}                   \\
{\bf Call Arguments:} {\sc npair,qeta}       \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
{\bf Subroutines Referenced:} {\sc } \\
This routine is called by {\sc pi0fnd} after the main reconstruction work is
done by {\sc pireco}. Because the photon-photon pairs are referred to in {\sc
pireco} by their indices the information of the best configuration {\sc pireco}
has reconstructed is decoded in this routine. {\sc npair} gives the number of
reconstructed photon-photon pairs. {\sc qetapi} is a logical variable
which helps
to find the best configuration. It is set {\sc .false.} if there is only one
particle to be reconstructed.
 The photon-photon pairs are identified as the
particles the user wanted to be reconstructed.


\section{List of Functions}
\subsection{PICONL}
Function {\sc piconl} calculates the confidence-level for a given $\chi^{2}$-sum
value.
\subsection{PIERRA}
{\bf Called Arguments:} {\sc pgampi,err4pi,ii,jj} \\
Function {\sc pierra} calculates for a given four-momentum vector {\sc pgampi}
 and its
corresponding values of resolution {\sc err4pi} the $\sigma_{cos\theta}$ of the
angle $\Theta$ between two photons of each photon-photon pair.
The formula for $\sigma_{\cos(\Theta)}$:
\[\sigma_{\cos(\Theta)} = (D_{1}^{2} \cdot \sigma_{\Theta_{1}} (E_{1}) +
D_{2}^{2} \cdot \sigma_{\Theta_{2}} (E_{2}) + D_{3}^{2} \cdot
(\sigma_{\Phi_{1}} (E_{1})^{2} + \sigma_{\Phi_{2}} (E_{1})^2)^{1/2} \]
The elements $D_{1},D_{2}$ and $D_{3}$ being the derivatives according to error
progression:
\[D_{1} = \frac{x_{1}x_{2} + y_{1}y_{2}}{\sin(\Theta_{1})} \cdot z_{1} -
\sin(\Theta_{1}) \cdot z_{2}\]
\[D_{2} = \frac{x_{1}x_{2} + y_{1}y_{2}}{\sin(\Theta_{2})} \cdot z_{2} -
\sin(\Theta_{2}) \cdot z_{1}\]
\[D_{3} = x_{1}y_{2} - x_{2}y_{1}\]
\subsection{PIERRE}
Function {\sc pierre} calculates the $\sigma_{E\gamma}$ of each photon. Needed
in {\sc pifits},otherwise not in use.
\subsection{PIMASS,PIPTOT}
{\bf Called Arguments:} {\sc igam,jgam,piptot,psum} \\
{\bf Common Blocks Used:} {\sc piuser,piopti,pibest,piinpt,pisave,pibrai}\\
Function {\sc pimass} calculates the square inv. mass for a photon-photon pair
{\sc igam,jgam}. {\sc psum} is an array filled with the sum of the four
components of each photon momentum vector, {\sc piptot} is the value
of the total
momentum of this pair. Both functions are needed in {\sc pioutp}.
\newpage
\setlength{\unitlength} {0.8cm}
\begin{figure}
\begin{picture}(16,28)
\put(0.5,26){\framebox(2,1){\sc usinit}}
\put(2.5,26.5){\line(3,0){3}}
\put(5.5,26){\framebox(2,1){\sc piinit}}
\put(1.5,26){\vector(0,-3){3}}
%\put(6.5,26){\line(0,-3){3}}
\put(0.5,22){\framebox(2,1){\sc user}}
\put(2.5,22.5){\line(3,0){3}}
\put(5.5,22){\framebox(2,1){\sc pi0fnd}}
\put(6.5,22){\line(0,-21){21}}
\put(6.5,20.5){\line(2,0){2}}
\put(8.5,20){\framebox(2,1){\sc pimrgd}}
\put(6.5,18.5){\line(2,0){2}}
\put(8.5,18){\framebox(2,1){\sc pireco}}
\put(9.5,18){\line(0,-13){13}}
\put(9.5,17){\line(2,0){2}}
\put(11.5,16.5){\framebox(2,1){\sc picomb}}
\put(9.5,15){\line(2,0){2}}
\put(11.5,14.5){\framebox(2,1){\sc pifits}}
\put(12.5,14.5){\line(0,-4){4}}
\put(12.5,13.5){\line(1,0){1}}
\put(13.5,13){\framebox(2,1){\sc pierrs}}
\put(12.5,12){\line(1,0){1}}
\put(13.5,11.5){\framebox(2,1){\sc pimfit}}
\put(12.5,10.5){\line(1,0){1}}
\put(13.5,10){\framebox(2,1){\sc pisfit}}
\put(9.5,8.5){\line(2,0){2}}
\put(11.5,8){\framebox(2,1){\sc piconf}}
\put(12.5,8){\line(0,-1){1}}
\put(12.5,7){\line(1,0){1}}
\put(13.5,6.5){\framebox(2,1){\sc pichek}}
\put(9.5,5){\line(2,0){2}}
\put(11.5,4.5){\framebox(2,1){\sc pisort}}
\put(6.5,3){\line(2,0){2}}
\put(8.5,2.5){\framebox(2,1){\sc pioutp}}
\put(6.5,1){\circle*{0.2}}
\put(6.5,20.5){\circle*{0.2}}
\put(6.5,18.5){\circle*{0.2}}
\put(9.5,17){\circle*{0.2}}
\put(9.5,15){\circle*{0.2}}
\put(9.5,8.5){\circle*{0.2}}
\put(9.5,5){\circle*{0.2}}
\put(12.5,7){\circle*{0.2}}
\put(12.5,13.5){\circle*{0.2}}
\put(12.5,12){\circle*{0.2}}
\put(12.5,10.5){\circle*{0.2}}
\put(8.5,9.5){\dashbox{.5}(8,6.5)}
\end{picture}
\caption{Flow Chart of the Software}
\label{usersubs}
\end{figure}
\end{document}             % End of document.
