TELESIS

Progress that is intelligently planned and directed: the attainment of desired ends by the application of intelligent human effort to the means
                                       -Webster's Ninth New College Dictionary

Telesis Introduction / Summary

Introduction.

Telesis contains:

Important points:


History.

Trklst Track Subtype 3 contains an approximate error matrix for each charged track, calculated assuming the track to be a pion. Mark III has developed a software package TELESIS to take the DEDX, MCS and BMFIT into consideration.We have adjusted them to the BES spectator and BES software enviroment.The main changes can be listed as follows:

Source code.

List of source files and members:
  1. Bmfit Fortran: Bmfit
  2. Bmfit0 Fortran: Bmfit0
  3. Bsplit Fortran: banaspi, banaspig
  4. Fudge Fortran: superfug, Fudge
  5. Ggfit Fortran: Ggfit
  6. Gascatr2 Fortran: supergas, Block Data Gscatrcoulom
  7. Icecream Fortran: superice, positdef
  8. Klam Fortran: klamcopy, klamcorr
  9. Newsquid Common
  10. Newsquid Fortran: Psinit, Psinitjr, pstrkcp, psextern, psdotrkc, psdobmft, psres2, psres3, psres4, psres5, psres6, psres7, psres8, psres9, psres10, Newsquid, kfinitl, kfupdtl, Squidjr, kfinitjr, kfupdtjr, squidpul, dmpsqdl, squidfat
  11. Sundae Fortran: Sundae, Sundaeg, Sundae0, supersd, supersdg
  12. Televers Fortran: telever, Block Data Firstcall
  13. Waiter Fortran: Waiter, Waiterg, Waiter0
The kinematic fitting routines are all contained in Newsquid Fortran.

Reference list of subroutines with arguments

Alphabetical listing of Telesis routines.

banaspi (itrack,xmas,irc,ichg,bchisq,xi0,tkp,err,iversion)
Performing DEDX , MCS correction and BMFIT, Call WAITER, superice, superfug, BMFIT0, Called by psdobmft.
banaspig (itrack,xmas,irc,ichg,bchisq,xi0,tkp,err,iversion)
Performing DEDX , MCS correction and BMFIT, Call WAITERG, superfug, BMFIT0, Called by psdobmft. It is available for iversion >=8 only.
bmfit (itrack,b,bchisq,iversion)
Performing BMFIT, Called BMFIT0
bmfit0 (ichg,tkpar,error,b,bchisq,xi0)
Mathematical realization of BMFIT, called by BMFIT
dmpsqdl (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
Print out all the input message after invoking the kinematic fit.
fudge (xmas,tkpar,ichg,bc,pm,seclm,iversion)
Performing DEDX and MCS for the track parameters, but not for the error matrices.
ggfit (itk1,itk2,ggmass,irc,rawmgg,rawcos, chisq,fitcos,fitpg1,fitpg2,fitpgg)
1-c kinematic fitting for M(gamma1 gamma2)=ggmass (ggmass can be the mass of pi0, eta,...)
kfinitl (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
Initialization of the array xm in the kinematic fit, Called by NEWSQUID
kfinitjr (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
Initialization of the array xm in the kinematic fitting of resonance, Called by SQUIDJR.
kfupdtl (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
Update the array xm in the kinematic fit, entry point in kfinitl.
kfupdtjr (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
Update the array xm in the kinematic fit of a resonance, entry point in kfinitl.
newsquid (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
the main program of doing kinematic fitting, Call kfinitl and kfupdtl
positdef (error)
make the modified error matrix postive definite.
psdotrkc (i_squid,mass_i,spec1,spec2,spec3,spec4, n_part,mass,p_spec,rc,iversion)
Performing DEDX and MCS corrections, Call SUNDAE.
psdobmft (i_squid,mass_i,spec1,spec2,spec3,spec4, n_part,mass,p_spec,rc,bchisq,xi0,iversion)
Performing DEDX, MCS and BMFIT, Call banaspi.
psextern (i_squid, mass_i, spec1, spec2, spec3, spec4, type_i, tkp,err, n_part, mass, p_spec, rc, iversion)
The daughter track from K0 or lambda, or any other track with the certain correction been imposed on.
psinit (sqrt_s,n_part,n_res,rc)
Initialization of the energy of center mass system(sqrt_s), n_part, n_res and rc before doing the kinematic fit.
psinitjr (n_part,n_res,rc)
Initialization of n_part, n_res and rc before doing the kinematic fit with a resonance.
psres2 (m_res_i,i1,i2, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with two particles.
psres3 (m_res_i,i1,i2,i3, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with three particles.
psres4 (m_res_i,i1,i2,i3,i4, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with four particles.
psres5 (m_res_i,i1,i2,i3,i4,i5, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with five particles.
psres6 (m_res_i,i1,i2,i3,i4,i5,i6, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with six particles.
psres7 (m_res_i,i1,i2,i3,i4,i5,i6,i7, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with seven particles.
psres8 (m_res_i,i1,i2,i3,i4,i5,i6,i7,i8, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with eight particles.
psres9 (m_res_i,i1,i2,i3,i4,i5,i6,i7,i8,i9, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with nine particles.
psres10 (m_res_i,i1,i2,i3,i4,i5,i6,i7,i8,i9,i10, n_res,m_res,p_mem,mem,rc)
Specification of a resonance with ten particles.
pstrkcp (i_squid, mass_i, spec1, spec2, spec3, spec4, n_part, mass, p_spec, rc,iversion)
Copy the track parameters and error matrices from track list subtype 3
NOTES:
squidjr (n_part,mass,p_spec,n_res, m_res,p_mem,mem,rc,chisq,p_fit)
Main program for doing kinematic fitting with resonance.
squidpul (p_spec,rc,pull)
Output the pull distribution of all the fitted quantities after kinematic fitting.
squidfat (code,i1,i2)
Output the fatal error when the kinematic fitting falied.
sundae (itrack,xmas,irc,ichg,tkp,err,iversion)
Performing DEDX,MCS correction (with only six error matrices logout), Call WAITER, superice and superfug, Called by psdotrkc.
sundaeg (itrack,xmas,irc,ichg,tkp,err,iversion)
Performing DEDX, MCS correction, Call WAITERG, superfug, It is only available for iversion>=8.
sundae0 (itrack,xmas,irc,ichg,tkp,iversion)
Performing DEDX, MCS correction for the momentum only. Call WAITER0, FUDGE
superfug (xmas,tkpar,ichg,bc,pm,seclm,error, rm,mfit,mzfit,ifit,cd,iversion)
Performing DEDX and MCS correction.Call supergas.
supergas (xmas,tkpar,ichg,bc,pm,seclm,error, rm,mfit,mzfit,ifit,cd,iversion)
Performing MCS correction for gas in MDC, Called by superfug
superice (tkpar,ichg,bc,pm,seclm,error, rm,mfit,mzfit,ifit,cd,iversion)
Recover the geometrical error matrix be removed the effect from PQSCAT and SCATR at BES7. At present, we can only do this approximately as some quantities are not logged out for iversion.le.7
supersd (itrack,xmas,irc,ichg,tkpar,error,iversion)
Performing DEDX and MCS correction, Call WAITER, superice and superfug
supersdg (itrack,xmas,irc,ichg,tkpar,error,iversion)
Performing DEDX and MCS correction, Call WAITERG and superfug
telever
Tell you the telesis version you are using now.
waiter (itrack,irc,tkpar,ichg,bc,pm,seclm,error, rm,mfit,mzfit,ifit,cd,iversion)
Copy the track parameters and error matrices from track list subtype 3.
waiterg (itrack, irc, tkpar, ichg, bc, pm, seclm, error, rm, mfit, mzfit, ifit, cd, iversion)
Copy the track parameters and geometrical error matrices from track list subtype 3. It is available for iversion>=8 only.
waiter0 (itrack,irc,tkpar,ichg,bc,pm,seclm,iversion)
Copy the track parameters from track list subtype 3.

Variable Declarations

Integer cd, code, ichg, ifit(2), irc, itk1, itk2, itrack
Integer i1, i2, i3, i4, i5, i6, i7, i8, i9, i10
Integer i_squid, mem(*), mfit, mzfit, n_part, n_res
Integer p_mem(*), p_spec(4,*), q1, q2, rc
Integer spec1, spec2, spec3, spec4, type_i

Logical newsquid, squidjr

Real bc, bchisq, chisq, chi2xy, chi2z, crxy(2), ct
Real err(6), error(15), ers1(6), ers2(6), er1(15), er2(15)
Real fitcos, fitpgg(4), fitpg1(4), fitpg2(4), ggmass, lxy
Real m_res(*), m_res_i, mass(*), mass1, mass2, mass_i, mpar
Real p_fit(4,*), pm(5), pull(*), pxyz, p4par(4), rawcos
Real rawmgg, rm, seclm(4), sqrt_s, tkp(3), tkpar(6)
Real tks1(3), tks2(3), tk1(6), tk2(6), xi0, xmas, zswum(2)

Real*8 b(5,6)

In case it doesn't work...

Debugging programs which use Telesis.

Here are some reminders and suggestions for you to consider when your Telesis application is exhibiting undesirable behavior.
  1. * * * N O T E * * *

    This is the source of > 90% of all Telesis problems!

    TRY THIS FIRST!

    Telesis routines have lots of arguments, so the chances of making a mistake with an argument list are increased.

  2. Telesis is designed to work on data in Dcfind format at BES(LHB).
  3. Some errors in the use of Newsquid and Squidjr are trapped during execution. In such cases your job will be stopped by 'SqdFatal' with return code 999. A message will be printed describing the symptoms. You probably made a mistake in your pre-squid calls----give specification to every track in the final decay state. If you can't find a mistake, you may need to read the kinematic fitting instructions, or your data may contain corrupted Trklst information. (The latter circumstance has never been observed, however.)
  4. If you find that little or nothing is passing your Newsquid or Squidjr fits, but no crashes occur, here are some possibilities:
If none of these apply, then you should print out the value of the return code rc after unsuccessful calls to Newsquid or Squidjr. This return code is set during the presquid calls or by Newsquid or Squidjr. Here is a summary of the rc definitions:
rc = 0   Successful fit.
     1   Neutral track or missing track specified with
           inappropriate routine.  (Sould only Use pstrkcp or
           psextern for these kinds of tracks.)
     2   Charged track did not have MFIT=2 at BES.
     3   Beam fit failed.
     6  Newsquid or Squidjr failed because the error matrix
           passed to Leqt2p (IMSL routine) was not positive-
           definite.  It is normal for this to occur
           occasionally.  (However the two error messages are not
           printed at BES for save the space of log file)
     7   Newsquid or Squidjr failed because chi-squared > 50.
           This should be the most common reason for failure.
NOTE:  rc can not equal 4 or 5 for this version of telesis at BES now. 
If you still can't get your kinematic fits to work, the routine dmpsqdl may be useful for dumping the input and output info, and some of the contents of the Newsquid Common block.

Getting started with Telesis kinematic fitting.

19 Feb., 1993 With Telesis, two broad classes of kinematic fits are possible. Newsquid is used when total event four-momentum constraints (with or without resonance constraints) are desired. Squidjr is used to impose resonance constraints ONLY.

Performing a kinematic fit with Telesis requires a sequence of subroutine calls in which all of the particles and resonances are specified. The sequence of calls FOR EACH FIT must have the following elements:

  1. Initialization:
    Psinit or Psinitjr, giving value of the energy of center mass system, and initialize the value of npart, nres and rc.
  2. Particle and resonance specification:
    pstrkcp, psdotrkc, psdobmft, psextern, psres2, psres3, psres4, psres5, psres6, psres7, psres8, psres9, or psres10
  3. Invoking the fit:
    Newsquid or Squidjr
  4. An optional final step is Calculation of pulls:
    squidpul: Check the goodness of fit. All the fitted quantities should have a Gaussian distribution with the mean value of 0 and width of 1 theo- retically.
Special Newsquid capabilities:

Kinematic fitting: Examples

Please send questions, comments, and corrections to Lanhb and Chensj.

List of examples in this file:

Newsquid fits (i.e. total event four-momentum constraints imposed)
Example 1.
e+e- -> K+ K- K+ K- (4-C fit) using uncorrected track parameters and do DEDX and MCS modification for the track parameters.
Example 2.
e+e- -> gamma eta eta -> gamma (pi+ pi- pi0) (gamma gamma), pi0 -> gamma gamma (7-C fit) doing DEDX, MCS and BEAM fit for the charged pions.
Example 3.
e+e- -> K0 K+ mu- nu, K0 -> pi+ pi- (2-C fit) using Klamcorr and psextern for the K0 and performing DEDX and MCS corrections and beam fit on the mu; the neutrino is missing, of course.
Example 4.
e+e- -> K1 pi1 K2 pi2 with Mass(K1 pi1) = Mass(K2 pi2) (5-C fit).
Example 5.
e+e- -> K K pi X with X missing and Mass(KKpi)= Mass(X) (1-C fit). The DEDX and MCS corrections are done before looping over all tracks. psextern is used to load the track parameters into Newsquid.
Squidjr fits (i.e. resonance constraints only)
Example 6.
pi0 -> gamma gamma (1-C fit).
Example 7.
K0 -> pi+ pi- (1-C fit, using Klamcorr).
Example 8.
Ds+ -> eta-prime pi+, eta-prime -> eta pi+ pi-, eta -> gamma gamma (3-C fit).

It is also assumed that XMCHTY COMMON has been included in your program, so the particle masses xmpich, xmk0, etc. are defined. (Naturally you may input the necessary masses in any way.)

For Newsquid fits it is assumed that the center-of-mass energy has been looked up (and corrected if desired), and is contained in the real variable 'energy'.

It is also assumed that the user is looping over some set of candidate track combinations, or that one particular combination has been chosen. The pions are Trklst track numbers ip1, ip2, ...; the kaons are ik1, ik2, ...; the gammas are ig1, ig2, ..., etc.


Example 1.

e+e- -> K+ K- K+ K- (4-C fit) taking the uncorrected track parameters from Trklst track subtype 3, doing DEDX and MCS corrections for the tracks.
      Call psinit(energy,npart,nres,rc)
      Call psdotrkc(1,xmkch,1,1,1,ik1,npart,mass,pspec,rc,iversion)
      Call psdotrkc(2,xmkch,1,1,1,ik2,npart,mass,pspec,rc,iversion)
      Call psdotrkc(3,xmkch,1,1,1,ik3,npart,mass,pspec,rc,iversion)
      Call psdotrkc(4,xmkch,1,1,1,ik4,npart,mass,pspec,rc,iversion)

      If (.not. newsquid(npart,mass,pspec,nres,
     *                  mres,pmem,mem,rc,chisq,pfit)) go to 100

Example 2.

e+e- -> gamma eta eta -> gamma (pi+ pi- pi0) (gamma gamma), pi0 -> gamma gamma (7-C fit) using beam fit track parameters from subtype 3 for the charged pions.
      Call psinit(energy,npart,nres,rc)
      Call pstrkcp(1,0.,1,1,1,ig1,npart,mass,pspec,rc,iversion)
      Call psdobmft(2,xmpich,1,1,1,ip1,npart,mass,pspec,rc,bchi1,xi1,
     *iversion)
      Call psdobmft(3,xmpich,1,1,1,ip2,npart,mass,pspec,rc,bchi2,xi2,
     *iversion)
      Call pstrkcp(4,0.,1,1,1,ig2,npart,mass,pspec,rc,iversion)
      Call pstrkcp(5,0.,1,1,1,ig3,npart,mass,pspec,rc,iversion)
      Call pstrkcp(6,0.,1,1,1,ig4,npart,mass,pspec,rc,iversion)
      Call pstrkcp(7,0.,1,1,1,ig5,npart,mass,pspec,rc,iversion)
      Call psres2(xmpi0,4,5,nres,mres,pmem,mem,rc)
      Call psres4(xmeta,2,3,4,5,nres,mres,pmem,mem,rc)
      Call psres2(xmeta,6,7,nres,mres,pmem,mem,rc)

      If (.not. newsquid(npart,mass,pspec,nres,
     *                  mres,pmem,mem,rc,chisq,pfit)) go to 100

Example 3.

e+e- -> K0 K+ mu- nu, K0 -> pi+ pi- (2-C fit) using Klamcorr and psextern for the K0 and performing DEDX, MCS corrections and beam fit on the mu and Kaon (not pi from K0); the neutrino is missing, of course.
C     These additional declarations and dimensions are needed:

      Integer irc
      Real tks1(3), tks2(3), ers1(6), ers2(6)
      Real crxy(2), zswum(2), p4k0(4), mpipi, pxyz
      Real chi2xy, chi2z, lxy, ct
      .
      .

C     Selection of K0 candidates:
clhb  The two pion couple or pion-proton couple have been identified
c      before you call klamcorr to find the k0 candidate.
      Call Klamcorr (ip1,ip2,xmpich,xmpich,
     *irc,tks1,tks2,ers1,ers2,crxy,zswum,p4k0,mpipi,pxyz,chi2xy,
     *chi2z,lxy,ct,chisqfit,fitflag,iversion)
clhb-----if fitflag=.true.,then do the kinematical fitting for the
clhb-----found k0(lambda0) vertex by Call FITVEE,the chi square of
clhb-----this fit is chisqfit,otherwise,not do the kinematic fitting
clhb-----and the chisqfit=999. by default.

      If (irc .ne. 0) go to 100

C     Cut on swum pi pi mass, momentum alignment, etc. if desired:
      If (abs(mpipi-xmk0) .gt. 0.100) go to 100
      probxy = prob(chi2xy,1)
clhb-------the following condition can vary depending on the different
      things you are doing.
      If (probxy .lt. 0.01) go to 100

C     Kinematic fit:

      Call psinit(energy,npart,nres,rc)
      Call psextern(1,xmpich,1,1,1,ip1,1,tks1,ers1,
     *                                       npart,mass,pspec,rc)
      Call psextern(2,xmpich,1,1,1,ip2,1,tks2,ers2,
     *                                       npart,mass,pspec,rc)
      Call psdobmft(3,xmkch,1,1,1,ik1,npart,mass,pspec,rc,bchik,xik,
     *iversion)
      Call psdobmft(4,xmmu,1,1,1,imu,npart,mass,pspec,rc,bchimu,
     *ximu,iversion)
      Call pstrkcp(5,0.,0,0,0,0,npart,mass,pspec,rc,iversion)
        if(.not.fitflag)then
      Call psres2(xmk0,1,2,nres,mres,pmem,mem,rc,iversion)
        endif
      If (.not. newsquid(npart,mass,pspec,nres,
     *                  mres,pmem,mem,rc,chisq,pfit)) go to 100

Example 4.

e+e- -> K1 pi1 K2 pi2 with Mass(K1 pi1) = Mass(K2 pi2) (5-C fit). Doing DEDX, MCS corrections for the K and pi tracks and imposing the equal mass constraints.
      Call psinit(energy,npart,nres,rc)
      Call psdotrkc(1,xmkch,1,1,1,ik1,npart,mass,pspec,rc,iversion)
      Call psdotrkc(2,xmpich,1,1,1,ip1,npart,mass,pspec,rc,iversion)
      Call psdotrkc(3,xmkch,1,1,1,ik2,npart,mass,pspec,rc,iversion)
      Call psdotrkc(4,xmpich,1,1,1,ip2,npart,mass,pspec,rc,iversion)
      Call psres2(-1.,1,2,nres,mres,pmem,mem,rc)
      Call psres2(-1.,3,4,nres,mres,pmem,mem,rc)

      If (.not. newsquid(npart,mass,pspec,nres,
     *                  mres,pmem,mem,rc,chisq,pfit)) go to 100

Example 5.

e+e- -> KKpi X with X missing and Mass(KKpi) = Mass(X) (1-C fit). The DEDX and MCS corrections are done before looping over all tracks. psextern is used to load the track parameters into Newsquid.
C     These arrays are defined to save the track parameters and
C     error matrices.

      Real tkpi(3,50), errpi(6,50), tkk(3,50), errk(6,50)
      Integer irc, ichg
      .
      .

C     The DEDX and MCS corrections are done once and for all.
C     (ichg is just discarded.)

      Do 50 i=1,ncharged

        If (i is a pion candidate)
     *        Call Sundae (i,xmpich,irc,ichg,tkpi(1,i),errpi(1,i),iversion)
        okpi(i) = (irc .eq. 0)

        If (i is a kaon candidate)
     *        Call Sundae (i,xmkch,irc,ichg,tkk(1,i),errk(1,i),iversion)
        okk(i) = (irc .eq. 0)

  50  Continue
      .
      .
C     Now we are looping over all pi and K candidates which
C     had okpi or okk=true.

      Call psinit(energy,npart,nres,rc)
      Call psextern(1,xmkch,1,1,1,ik1,1,tkk(1,ik1),errk(1,ik1),
     *                                         npart,mass,pspec,rc)
      Call psextern(2,xmkch,1,1,1,ik2,1,tkpi(1,ik2),errk(1,ik2),
     *                                         npart,mass,pspec,rc)
      Call psextern(3,xmpich,1,1,1,ip1,1,tkpi(1,ip1),errpi(1,ip1),
     *                                         npart,mass,pspec,rc)
      Call pstrkcp(4,-1.,0,0,0,0,npart,mass,pspec,rc,iversion)
      Call psres3(-1.,1,2,3,nres,mres,pmem,mem,rc)

      If (.not. newsquid(npart,mass,pspec,nres,
     *                  mres,pmem,mem,rc,chisq,pfit)) go to 100

Example 6.

pi0 -> gamma gamma (1-C fit).
      Call psinitjr(npart,nres,rc)
      Call pstrkcp(1,0.,1,1,1,ig1,npart,mass,pspec,rc,iversion)
      Call pstrkcp(2,0.,1,1,1,ig2,npart,mass,pspec,rc,iversion)
      Call psres2(xmpi0,1,2,nres,mres,pmem,mem,rc)

      IF (.not. squidjr(npart,mass,pspec,nres,
     *                     mres,pmem,mem,rc,chisq,pfit)) go to 100


C     Alternative:  Use the routine Ggfit, which does the
C     kinematic fit and returns raw mass, decay angles, etc.

      Integer irc
      Real rawmgg, rawcos
      Real chisq, fitcos, fitpg1(4), fitpg2(4), fitpgg(4)
      .
      .
      Call Ggfit (ig1,ig2,xmpi0,irc,rawmgg,rawcos,
     *                   chisq,fitcos,fitpg1,fitpg2,fitpgg)

Example 7.

K0 -> pi+ pi- (1-C fit, using Klamcorr).
C     These additional declarations and dimensions are needed:

      Integer irc
      Real tks1(3), tks2(3), ers1(6), ers2(6)
      Real crxy(2), zswum(2), p4k0(4), mpipi, pxyz
      Real chi2xy, chi2z, lxy, ct
      .
      .

C     Swim to crossing point, calculate various quantities:

      Call Klamcorr (ip1,ip2,xmpich,xmpich,irc,tks1,tks2,ers1,ers2,
     *crxy,zswum,p4k0,mpipi,pxyz,chi2xy,chi2z,lxy,ct,chisqfit,
     *fitflag,iversion)

Example 8.

Ds+ -> eta-prime pi+, eta-prime -> eta pi+ pi-, eta -> gamma gamma (3-C fit).
      Call psinit(energy,npart,nres,rc)
      Call pstrkcp(1,0.,1,1,1,ig1,npart,mass,pspec,rc,iversion)
      Call pstrkcp(2,0.,1,1,1,ig2,npart,mass,pspec,rc,iversion)
      Call psdobmft(3,xmpich,1,1,1,ip1,npart,mass,pspec,rc,bchi1,
     *xi1,iversion)
      Call psdobmft(4,xmpich,1,1,1,ip2,npart,mass,pspec,rc,bchi2,
     *xi2,iversion)
      Call psdobmft(5,xmpich,1,1,1,ip3,npart,mass,pspec,rc,bchi3,
     *xi3,iversion)
      Call psres2(xmeta,1,2,nres,mres,pmem,mem,rc)
      Call psres4(0.95757,1,2,3,4,nres,mres,pmem,mem,rc)
      Call psres5(1.9714,1,2,3,4,5,nres,mres,pmem,mem,rc)

      IF (.not. squidjr(npart,mass,pspec,nres,
     *                     mres,pmem,mem,rc,chisq,pfit)) go to 100

Kinematic fitting: Detailed reference

Contents:

1.
Definitions.
2.
General considerations.
3.
How to set up a kinematic fit.
A.
Initialization.
B.
Particle and resonance specification.
C.
Invoking the fit.
D.
Calculating pulls. (optional)
4.
About the return codes.
5.
Equal-mass constraints.

1. Definitions.

Throughout this document the following definitions apply:
'track'
a charged stable object observed and measured with the drift chamber, or a neutral stable object observed with the shower counter.
'particle'
Throughout all of Squiddom, 'particle' means a track, or a missing object of a particular mass, or a missing object whose mass is constrained to be equal to the invariant mass of a collection of tracks.
'resonance'
refers to an object which decayed into a group of particles. The mass of a resonance is constrained to a particular value, or to be equal to the mass of a missing track or the mass of another resonance. Defining resonances in Squid normally is useful only for states having width much smaller than the detector resolution.

2. General considerations.

A. Objectives.

Kinematic fits are used to reject backgrounds and to provide improved resolution on track measurements. This is accomplished by imposing constraints on the track momenta so that (a) the total four-momentum of all particles in the event is equal to [0,0,0,sqrt(s)] and/or (b) the invariant masses of subsets of two or more tracks satisfy some resonance conditions.

B. Procedure.

The kinematic fitting routines in Telesis are descendents of Squat by Toby Burnett. The fitting procedure can be summarized as follows: Track momentum or energy measurements are expressed using three parameters per track. The parameters for all tracks form a vector xm. These parameters are varied by the fit to achieve the constraint conditions. This variable vector is called x. The constraint conditions are expressed as Fk(x)=0, where k=1, 2 ... NC (number of constraints) and the Fk are non-linear functions.

A fit usually involves several iterations, as follows:

  1. At each iteration of the fit, x is used to compute the track four-momenta and the derivatives dPi/dxj.
  2. The values of Fk and the derivatives dFk/dxj are computed.
  3. If the Fk are equal to zero (within some tolerance which roughly corresponds to <1 MeV in the track momenta) then the fit is considered to have converged and the latest chi-squared and four-momenta are returned.
  4. The chi-squared (which depends on x-xm and the input errors on xm) is minimized by a matrix calculation in which the Fk are assumed to be locally linear.
  5. If the chi-squared after minimization is over 50 then the fit is considered to have failed and the fitter stops. Otherwise we go back to step 1.

C. Determining the Number of Constraints.

Having determined the type of fit one wants to make, the number of constraints in the fit, Nc, may be calculated by using one of several approaches. A kinematic fit is an attempt to combine redundant information about event kinematics. The number of constraints is the number of redundant items of information. I will show how Nc may be obtained from 'first principles' for a Newsquid fit.

Suppose there are Npart particles in our fit. The outputs of the fit are the fit four-momenta of these particles or 4*Npart numbers. (Of course the chi-squared is also output, but that doesn't count here.)

The inputs to the fit are: the measured track momenta (3*Npart numbers), the assumed masses of the particles (Npart numbers), and the four-momentum of the entire event (four numbers; we must assume e+e- annihilation, of course). In addition, we may impose resonance mass constraints which give one input quantity per resonance.

We therefore obtain

        Nc  =  [3*Npart + Npart + 4 + Nres] - [4*Npart],
or
        Nc  =  4 + Nres,
where Nres is the number of resonance constraints.

You may just think that for an e+e- events, there is only one energy conservation law exists (so we have 4 constraints), if we have Nres independent resonances among these final state, then we come to

        Nc  =  4 + Nres,
The following complications must also be considered: For Squidjr fits (without event four-momentum constraints) these special cases are not allowed. The number of constraints is always Nres.

D. Number of Degrees of Freedom.

The chi-squared which is returned by the fitter describes the consistency of the input track information with the fit hypothesis. To interpret the goodness of fit, we need to know the number of degrees of freedom which characterizes the chi-squared variable. Paradoxically, the number of degrees of freedom is equal to the number of constraints.

3. How to set up a kinematic fit.

Newsquid is used to constrain the total event momentum and energy to (0,0,0,sqrt_s). The complete event topology hypothesis must be specified, allowing at most one missing particle.

Squidjr is used to impose resonance (mass) constraints on some subset of the tracks in an event.

Performing a kinematic fit with Telesis requires a sequence of subroutine calls in which all of the particles and resonances are specified. The sequence of calls FOR EACH FIT must have the following elements:

4. About the return codes.

In Telesis it is important to CHECK THE RETURN CODES. However, checking the return code of every pre-squid call would be unbearable, so the following scheme was implemented. The initialization call sets the variable rc equal to zero. All of the pre-squid routines, as well as Newsquid and Squidjr, give rc=0 if successful, and rc>0 if not. In each of the pre-squid subroutines, the INPUT value of rc is checked. If it is not equal to zero, it means that something has gone wrong in a previous pre-squid call, and there is no sense in continuing with the fit. The pre-squid routine returns without doing anything. If the input value of rc is zero, the pre-squid routine does its business. When Newsquid or Squidjr are finally invoked, the input value of rc is again checked. If rc=0 (i.e. all of the pre-squidding was successful) the fit is attempted. Newsquid or Squidjr = .TRUE. only if the fit and all of the pre-squidding was OK.

5. Equal-mass constraints.

It is possible to impose an equal mass constraint in Newsquid (but not in Squidjr). There are two cases: The mass to which the two objects converge is an output of the fit. To impose such a constraint, specify the mass of the objects to be -1.0 (GeV)(NOT -1). (The missing particle mass is to be specified in pstrkcp, and the resonance mass in one of the psres routines.)

DEDX and MCS corrections: background and instructions

Introduction.

Telesis includes routines to perform energy loss (DEDX) and multiple Coulomb scattering (MCS) corrections of charged track momenta and error matrices. The size of the corrections depends on the particle mass assumed. All five track parameters and the full 15 element error matrix can be treated.

The first 42 words of Trklst track subtype 3 contain the UNCORRECTED track momentum and an error matrix which is computed assuming the particle is a pion. The first six elements of this matrix are reasonable under this assumption, but the last nine elements are not correctly calculated. Since the kinematic fitters in BES only use the first six elements, good results are usually obtained by simply correcting the magnitude of the track momentum for DEDX before performing fits. The chi-squared distributions are incorrect when any charged tracks other than pions are involved, but the fit momenta come out pretty good. [Notice that track subtype 8 vertex-constrained fits are performed assuming all tracks are pions, and using the incorrect track error matrix elements which pertain to xi and eta.]

Energy loss corrections to charged-track momenta.

The legendary memo of Dave Hitlin (Mark III 6/83-4) contains a formula to approximately characterize the mean momentum loss of a track passing through the detector, independent of species. The form is simply
       delta(P) = A * (P/Pxy) / beta**u,     (beta<0.94)
       delta(P) = A * (P/Pxy) / 0.94**u,     (beta>=0.94)
where A is determined from the amount of matter traversed (a radial path from the beampipe through Layer 5 was considered) and u=2.74, as determined from a plot of the more complicated phenomenological function. As mentioned in the memo, slow tracks could be more accurately treated by dividing the material into several parts and accounting for the changing beta of the particle as the material is traversed.

Energy loss corrections to charged-track error matrices.

For rigorous kinematic fitting, the charged-track error matrices also need to include the effects of DEDX and multiple Coulomb Scattering (MCS). One begins with the matrix which describes the drift chamber measurement errors only (the so called 'geometric' error matrix), then the DEDX and MCS contributions are added. Unfortunately, until version 8 of BES(1993) the geometric error matrix was not saved in Trklst. Thus the DEDX and MCS correctiones are not considered completely before BES8.

The Telesis routine superice recovers(approximately)the geometrical error matrix from the trklst track subtype 3 error matrix by removing the 'corrections' applied by SCATR and PQSCAT (at BES7).Because some intermediate results are not available when reading back the reconstructed event, only an approximate inversion is possible. (It is good enough, though.)

In Sundae the mean momentum loss is calculated by integrating the Hitlin formula and referring to a look-up table, yielding good accuracy and considerable speed. (For beta>=0.94 the Hitlin formula is retained.) Let X (running from 0 to 1) denote the fractional amount of material traversed. We have (for beta<0.94)

               dP = dX * A * (P/Pxy) / beta**u,
or
        beta**u
   ------------------ * d(beta)  =  dX * A * (P/Pxy) / M,
   (1 - beta**2)**1.5
where M is the hypothesized mass of the particle. The left-hand side of this equation is numerically integrated and saved in the array F1. The index of this array is 1000*beta at the upper limit of integration. (The lower limit is zero.) The material in the detector is divided into four parts (to accomodate the multiple scattering calculations described below), so the A is replaced with an Ai for each part. To determine the momentum correction for a track passing through one of the scatterers, the quantity Ai*(P/Pxy)/M is calculated and the value of the integral corresponding to the exit value of beta is interpolated (linearly) from the array F1. The sum of these quantities is the value of the integral corres- ponding to the entrance value of beta. This beta is determined from F1 and the new momentum is computed from beta.

the track phi correction is

  d(phi) = CHG * PATHXY * 0.03 * B * (1/PxyNEW - 1/PxyOLD),

Assuming the tracks are straight when computing PATHXY.

The DEDX error matrix adjustments are as follows:
    sigma(k) = 2*alpha*t*sec(lambda) / beta**3 / P**2,
with sigma(phi), and the error matrix contributions as before.

Multiple scattering corrections to charged-track error matrices.

For multiple scattering we make no adjustment to the track parameters, but terms are added to the error matrix. As in the case of DEDX corrections, the size of these adjustments has a strong momentum dependence which is not accurately treated by simple procedures when the particle momentum is changing considerably within a scatterer. The quantity DELTH2 is calculated for each scatterer, from which the error matrix corrections are derived. We have
                 (14.1 MeV)**2
     d(DELTH2) = ------------- * RADLi * (P/Pxy) * dX,
                  (beta*P)**2
where RADLi is the number of radiation lengths of material in a radial path through the scatterer. Inserting d(beta)/dX from above, we obtain
            (14.1 MeV)**2 * RADLi              d(beta)
d(DELTH2) = --------------------- * -----------------------------
                   M * Ai           beta**(4-u) * SQRT(1-beta**2)
The integral of the second factor on the right-hand side is evaluated up to various values of beta and tabulated in the array F2. Since the integral diverges when the interval includes beta = 0, I "renormalize" by setting the integrand to zero at this point. (Adding a constant to the values in F2 does not affect the subsequent calculations.) To determine DELTH2 for the passage of a track through scatterer i, we look up the values of F2 corresponding to the entrance and exit betas determined from the DEDX section. (Again the array index is 1000*beta.) For beta>0.94 we are safe to treat beta and P as constants in the first equation of this section. From DELTH2 the error matrix adjustments are found as before.

Beam fits (one-track 'vertex' constraint fits)

Bmfit is included in Telesis, with the appropriate interfaces to allow the use of track information which is corrected for energy loss and multiple scattering according to the user-specified particle mass hypothesis.

Important beam fit outputs:

xi0
distance of closest approach of the track to the beam axis (AFTER DEDX and MCS corrections but BEFORE the beam fit)
bchisq
beam fit chi-squared (one degree of freedom)

These quantities provide useful track selection criteria. To select tracks which are consistent with coming from the interaction region, a cut of Prob(chisq,1) > 0.001 or 0.01 is very effective. You may also wish to apply a very loose cut on xi0 (< 0.025 meters, for example) to eliminate tracks which have small bchisq because they have enormous errors on impact distance. Naturally it is a mistake to make such cuts or to use beam fit momenta if you are looking for the pions coming from K0 decays. Beam fits may be useful to reject some K0 daughters, however.

Beam fit track information is easy to use in kinematic fits under Telesis.

To perform beam fits for use outside of kinematic fits, the routine banaspi is usually most convenient. The user specifies only the Trklst track number and the desired particle mass. The outputs include the fit track parameters, xi0, and bchisq.

Klamcopy: K0 and Lambda finder / track swimmer

Klamcopy is used to select candidates for K0 -> pi+ pi- or Lambda -> p pi-. The user inputs the Trklst track numbers of two charged tracks to be considered, and the assumed masses of these tracks. The routine looks up the DEDX and MCS-corrected track parameters in Trklst subtype 3 and determines the crossing points of the track circles projected onto the xy-plane. The correct crossing point is chosen and the track parameters and error matrices are swum and fitted (or not) to that point. This information can easily be loaded into Newsquid or Squidjr using psextern. The pi pi or p pi four-momentum and invariant mass is computed. The decay length is determined using the Decay Length Formalism described in Mark III Memo 11/86-4 by Wasserbaech and Bolton. Quantities are also returned which measure consistency of the measured parent (K0 or Lambda) momentum direction with that of the segment joining the interaction point and the crossing point, and consistency of the z coordinates of the two tracks at their crossing point.

APPENDIX A-----Different Treatment Between NEWSQUID and SQUID

In this Appendix, we just demonstrate the different treatment between the NEWSQUID and SQUID, this is especially useful for those who are familar with SQUID, they can only just to see this appendix and then try to invoke the NEWSQUID directly.

____________________________________________________________________________
            NEWSQUID                      |          SQUID
A.In general
A.0.NEWSQUID and SQUID are the same in    |  
logical, but NEWSQUID has a more variable |  
 'rc' to charactrize the return mode:     |  
OKSQ=NEWSQUID(npart,mass,pspec,nres,mres  |   OKSQ=SQUID(npart,mass,pspec,nres,
,pmem,mem,rc,sqchi,pfit)                  |   mres,pmem,mem,sqchi,pfit)
                                          |  
A.1 One more equal mass constraints       |   Not available in the old code 
    can be treated:                       |  
    Assuming there is four(real or miss   |  
    ing) particles in the final state,we  |  
    can impose                            |  
     M(X1X2)=M(X3X4) or M(X1)=M(X2X3X4)   |                 
A.2.It can deal with vary kinds of track  |   It can only treat  the track from
    with DEDX,MCS and BMFIT correction    |   Track list,and do a mean DEDX
    or Track from K0 or Lambda directly.  |   correction for the chrged track
    It does not do any DEDX correction    |   in subroutine kfinit for the
    in subroutine kfinitl!!!              |   amendment.    
__________________________________________|_____________________________________

B. Method of INPUT and OUTPUT
B.1.INPUT
  Assuming there are Npart(real and missing) particles in the final state.
  the first two particles are pion and kaon,and the final particle is kaon.

             NEWSQUID                           SQUID
o Energy of Center Mass System(can vary)  |      Etot=Certain value specified in
  Call Psinit(Etot,npart,nres,rc)         |      Kfinit
*:you just give the value to Etot(4.03,   |  
  or 3.097 or 3.77),the other variable    |  
  s are output                            |  
                                          |                         
o Array Pspec(4,npart) and Mass(npart)    |       DO i=1,npart
  Call pstrkcp(1,0.1396,1,1,1,itrk1,      |       Do J=1,3
  npart,mass,pspec,rc,iversion)           |       Pspec(j,i)=1
  Call pstrkcp(2,0.49367,1,1,1,itrk2,     |       enddo
  npart,mass,pspec,rc,iversion)           |       enddo
       ...                                |       Pspec(4,1)=itrk1
       ...                                |       pspec(4,2)=itrk2
  Call pstrkcp(npart,0.49367,1,1,1,       |       ...
 itrknpart,npart,mass,pspec,rc,iversion)  |       ...
*:where itrk1,itrk2 and itrknpart are     |       Pspec(4,npart)=itrknpart
the track number of the first,second and  |  
the last track.                           |       Mass(1)=0.1396
*:iversion is the reconstruction version  |       Mass(2)=0.49367   
 it can be 5,6,7 or 8(now the highest     |       ...
 version)                                 |       ...
*:the other variables are output          |       Mass(npart)=0.49367
*:pstrkcp just take the track paramete    |  
rs from track list,it can be substituted  |  
by:                                       |  
1.psdotrkc(...,iversion):Doing DEDX       |  
and MCS correction for the tracks.        |  
2.psdobmft(...,bchk1,xik1,iversion):      |         
 Doing DEDX,MCS and BMFIT for the track.  |  
the '...' are the same as that in         |  
pstrkcp.                                  |  
the bchk1 characterize the BMFIT chi      |  
square,and Xik1 is just the closet        |  
distance of the track to the I.R. point   |  
3.psextern(1,0.1396,1,1,1,itrk1,ktype,    |  
  tkp,err,npart,mass,pspec,rc):           |  
 Any tracks that are modified or swimmed  |  
by any means.                             |  
*:ktype has the same meannig as that in   |  
SQUID(NEWSQUID),the origin of the track   |  
MDC,ESC or WSC                            |  
__________________________________________|___________________________________
o Resonance array Mres(Nres),Pmem(...), Mem(pmem(...)+...),assuming we
consider the decay e+e- -----> gamma eta(gammagamma)eta(gammagamma):
                                          |  
                NEWSQUID                  |                 SQUID
Call psres2(0.54745,1,2,Nres,Mres,        |         Nres=2
pmem,mem,rc)                              |         Mres(1)=0.54745
Call psres2(0.54745,3,4,Nres,Mres,        |         Mres(2)=0.54745
pmem,mem,rc)                              |         Pmem(1)=1
*:the Nres,mres,pmem,mem and rc are       |  
  output                                  |         Mem(pmem(1)+0)=2        
*:psresN means there are N partic-        |         Mem(pmem(1)+1)=1
les in this resonance,the telesis can     |         Mem(pmem(1)+2)=2
deal with N up to 10.                     |         Pmem(2)=4
                                          |         mem(pmem(2)+0)=2
                                          |         mem(pmem(2)+1)=3
                                          |         mem(pmem(2)+2)=4
__________________________________________|______________________________________
o equal mass constraints.
                NEWSQUID                  |                 SQUID
1.for the above example,we can require    |  
     M(gamma1gamma2)=M(gamma3gammma4):    |  
Call psres2(-1.,1,2,nres,mres,pmem        |         It could not deal with
,mem,rc)                                  |         this kind of constraint.
Call psres2(-1.,3,4,nres,mres,pmem        |  
,mem,rc)                                  |  
2.for the decay e+e----kkpiDs we can      |  
require(assuming the missing Ds is the    |         
fourth particle)                          |  
   M(KKPI)=M(Ds)                          |  
Call pstrkcp(4,-1.,0,0,0,npart,mass,      |  
pspec,rc)                                 |  
Call psres3(-1.,1,2,3,nres,mres,          |  
pmem,mem,rc)                              |  
__________________________________________|_______________________________________
B.2.OUTPUT
o Return code
                NEWSQUID                  |                 SQUID
In every steps,there is the rc parameter  |         You can only know  whether
,so it can tell you whether that step is  |         the fitting is ok by seeing the
ok.                                       |         chi square in the final step.
__________________________________________|_______________________________________
B.3.CHECKING
                NEWSQUID                                SQUID
You can                                   |         Not available   
Call squidpul(pspec,rc,pull)              |  
to check the goodness of the fit          |  
*:a reasonable fitting results should     |  
give the pull distribution of the momen-  |  
tum not far from a Gaussian distribution  |  
with the 0 mean value and 1 width         |  
__________________________________________|_______________________________________