Paul Avery CBX- Sep. 10, 1996

Data Analysis and Kinematic Fitting With the KNLIB Library

1. Introduction

This document describes the second version of the knlib library that has been used since 1992 for CLEO data analysis. knlib has a number of powerful features which together provide a complete framework for data analysis (the user interface routines are documented elsewhere):

• All particles (QQ tracks, charged particles, photons, pizeros, kshorts, Lambdas and virtual particles such D and B mesons) are stored in a single list (basically, the user sees particles as track indices). This feature alone is worth the price of entry. An optional correction for energy loss is applied to charged particles before they are put into the track list.
• The basic quantities stored in the track list are the 4-momentum, position, mass, particle type and covariance matrix. This information format greatly simplifies physics analysis and can be manipulated by a host of support routines.
• knlib has strong support for kinematic fitting, including constraints based on mass, energy, vertexing, total momentum, 4-momentum, 3-momentum and a number of others. For example, one can fit the decay sequence shown below (the measured particles are shown in boldface) by combining particles starting at the bottom and building up the chain:

• There are a number of valuable support routines, such as those which transport particles through magnetic fields, combine the 4-momenta of a set of particles at a given point (including the magnetic field bend), return the error of quantities such as momentum, energy or angle after a fit, and allow a user to tell whether a given particle passes through the beam spot or any other vertex.

Note: Knlib currently has 1000 tracks and 100 vertices defined. These numbers may have to be increased if analyses with large combinatorics are attempted. Please let me know if the dimensions are adequate.

2. Where to find files and documentation

There are approximately 100 subroutines in the knlib user interface. The file locations for the source, libraries and include files are shown in the table below. All file locations are relative to the directory $C_CVSSRC/. No other files should be used directly in your code. There are access routines to return any information you will need. If you believe that I have not included enough access routines, please let me know and I will extend the list.

	Single precision	Double precision
Library	libknlib.a	libknlibd.a
Track list	seq/clinc/kwtrak.inc	seq/clinc/kwtrak.inc
Vertex list	knlib/seq/kwvrtx.inc	knlib/seq/kwvrtx.inc
Source	knlib/*

Note the presence of both single and double precision libraries. I found the double precision version useful for kinematic fitting, because the final covariance matrix is obtained by subtraction of two matrices containing large magnitude terms. This might become more of a problem in the silicon data since we will be tracking over a large region with microscopic errors.

Double precision is incorporated in the source code through C preprocessor commands, e.g.

#if !defined(CLEO_DOUBLE)
      REAL MASSKP, CHRGKP, CTAUKP
#endif
#if defined(CLEO_DOUBLE)
      DOUBLE PRECISION MASSKP, CHRGKP, CTAUKP
#endif

3. Differences from version 1

Version 1 of knlib was released in 1991 and described in CBX 91-12 and CBX 91-13. Although this is the version with which most of you are familiar, I strongly urge you to switch to version 2 as early as possible. There are a number of good reasons to switch.

1. Every track in version 1 is stored in three formats, "just in case I need them". Boy, that was a dumb thing to do. Worse, the W format which I really needed (because it includes energy), and which is the only one used in version 2, was not included. The W format has tremendous advantages for physics computation and transporting through magnetic fields.
2. Every track in version 1 not only had a generic 4-momentum, but it had 7 other 4-momenta (e, mu, pi, K, p, Ks, Lambda) computed with the corresponding mass hypothesis. This turned out to be a deadly flaw in the program. Every fitting routine had to worry about updating 7 versions of the 4-momentum and 3 formats, a situation that got so complicated that I finally gave up in disgust. Version 2 solves this problem by having a single track list trkwkn (which is equivalenced to p4kn). Different mass hypotheses are represented by different track indices, the way God intended.
3. Version 1 uses the include file seq/clinc/kntrak.inc and version 2 uses seq/clinc/kwtrak.inc.

Note: since many of the routines in version 1 are found in version 2, you must never use them together. Version 1, which was originally part of libftlib.a, has been moved to its own library libftknlib.a so as not to compromise the use of ftlib with knlib. The examples later in the document show clearly how the new version ought to be used. See me if you have difficulties.

4. Examples of how to use KNLIB

A simple demonstration of how to call the routines is shown in Example 1. I will add further examples over time.