Data Analysis and Kinematic Fitting With the KWFIT Library

1. Introduction

This document describes the third version of the kinematic fitting library that has been used since 1992 for CLEO data analysis. Kwfit has a number of powerful features that 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.
• The basic quantities stored in the track list are the 4-momentum, position, mass, charge, covariance matrix and a few others. This information format greatly simplifies physics analysis and can be manipulated by a host of support routines.
• There is 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:

• A number of valuable support routines exist that (1) transport particles through magnetic fields; (2) build virtual particles; (3) perform vertex constraints; (4) return the error of quantities such as momentum, energy or angle after a fit; and (5) allow a user to tell whether a given particle passes through the beam spot or another vertex.

Note: kwfit currently has 5000 tracks defined. The number 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

This web document and its links serve as the documentation for kwfit. It is mirrored at Florida and Cornell for greater access speed for users at these different locations:

There are over 100 routines in the kwfit user interface. The file locations for the sources and libraries are shown in the table below. No include files except for the one listed in the table below should be used directly in your code. There are access routines to return any information you will need.

Remember that the kwfit library is completely double precision. You must take care not to call kwfit routines with single precision arguments such as BMPOS or BFIE.

3. Differences from KNLIB

Many of you are familiar with knlib (which in turn replaced an older version called ftknlib) which has seen increasing use in CLEO because of the advent of silicon tracking and improved Kalman fitting of charged tracks. Kwfit has several improvements over knlib:

1. Kwfit replaces the 6 letter names in knlib with more readable names; e.g. kvrtx3 becomes kvtx_unknown.
2. Kwfit uses a purely double precision interface and internals. Higher accuracy is needed for some fits and new capabilities will require extensive use of it. Moreover, moving tracks from one part of the detector to the silicon detector requires resolutions of a few microns, a difficult achievement in single precision.
3. Kwfit does not publish its track list, unlike knlib. This means that setting and getting track information must be done through access routines, e.g., kget_track_xxxxx. These access routines are extremely easy to use and permit me to update the internal structure of kwfit without interfering with users. The access routines are very easy to use and actually make your code more readable because multiply indexed arrays are virtually eliminated.
4. There are more utility routines in kwfit, including functions that move tracks and covariance matrices to surfaces and points. For example, the routine

ktrk_move_arc(ktrk, arc, error)

moves the parameters and covariance matrix of track "ktrk" by the distance "arc", returning a non-zero error code if there is a problem.

5. I plan to add the capability of fitting entire decay sequences in the future. This capability requires extensive use of double precision.

4. Format of track information

This information is probably already familiar to you if you have used knlib previously. Track information is stored in a 10 dimensional format known as the "W representation", obtained through by calling

as discussed in the next section. The quantities w(1-10) are described below

The momentum is evaluated at the (x, y, z) position. When a CLEO track is converted to the W representation, the track is created at the point of closest approach to the beam spot for that run (BMPOS). Note that only the first 7 components of a W are used in fits. Thus the covariance matrix corresponding to a W track is a 7 x 7 matrix.

Routines exist in kwfit to transform the standard CLEO helix track parameters (so-called "C representation) to and from the W representation. The C format is described in the following table.

The helix is described by the first 5 parameters, defined relative to a reference point. In CLEO the reference point is always the origin of the coordinate system, but when moving helices to, say, a drift chamber wire or to a point in space, it is much more natural to have the reference point be at the place where you want to move the track. The parameters have a 5 x 5 covariance matrix which is converted to the 7 x 7 version when building the W track in kwfit.

5. Track information stored in kwfit

The number of tracks in the kwfit system is obtained from kget_track_number. Individual kwfit tracks are accessed straightforwardly by track index. The following list shows what information is stored, along with the name of the corresponding access routine.

1. w(1-10), the current kinematic quantities (kget_track_param). These parameters are recomputed after each fit. The current parameters are used as the expansion point when linearizing the constraint equations.
2. w0(1-10) the unconstrained parameters (parameters before any fitting is done) (kget_track_param0). When a new fit is done, it uses w0 as the starting point for the fit.
3. Vw0(7,7) the covariance matrix corresponding to w0 (kget_track_covar).
4. Mass of the particle (kget_track_mass).
5. Origin of track (kget_track_origin). This variable determines where the track came from (CD, KNVF, QQ, etc). Possible track origins can be found in $C_CVSSRC/kwfit/seq/track_types.inc.
6. Position of track in original list where it came from (kget_track_index). This is a useful way of obtaining, for example, the CD track number of a kwfit track.
7. Flag indicating if the track has a covariance matrix (kget_track_is_covar). Monte Carlo tracks, for example, do not have covariance matrices and thus cannot be used in fits.
8. Flag indicating if the track has a fixed mass (kget_track_is_mass_fixed). For example, charged particles such as pions and kaons, which are measured by helix reconstruction, have a fixed mass. In that case the energy of the track is not independent of the momentum components and the covariance matrix reflects its dependence. When the track parameters of a fixed mass particle are updated after a fit, the energy is computed from the momentum components and the fixed mass so that it is always consistent.
9. Flag indicating whether the track has valid position information (kget_track_is_position). Particles such as pizeros and gammas do not have useful position information that can be used or updated in a fit.

6. Filling the KWFIT track list

New entries in the kwfit track list can be created only by calling one of the kfil_track_xxxx routines. Each routine creates a track slot and copies over information from the corresponding track list, e.g. CD, CC, XBAL, etc. These routines are the only connection between CLEO and kwfit.

7. How fits are performed in KWFIT

All fits in kwfit are performed with the lagrange multiplier method, described in other references [1,2]. The track parameters relevant to the fit are the current values w, unconstrained values w0, and a covariance matrix V0 associated with w0. These quantities are obtained by calling kget_track_param, kget_track_param0, and kget_track_covar, respectively. Normally w is the same as w0 unless a previous fit has updated it. The fit always starts with the unconstrained parameters w0 and recomputes the current parameters w.

The fitting algorithm proceeds as follows. First, the constraint equations are linearized by expanding around the current track parameters w (w is used for the center of the expansion because the current parameters are regarded by kwfit as being closer to their "true" values. This choice of expansion point has nothing to do with the fit itself). Second, the constraint and chisquare equations are solved simultaneously using matrix algebra (see the references for details) to calculate the new parameters w and the chisquare. The constraints can be thought of as "pulling" the track parameters from their unconstrained values w0. These two steps are repeated until the change in chisquare falls below a cutoff value (default = 0.001) or the maximum number of iterations (default = 10) has been reached. Both of these conditions can be specified by the user (kset_fit_criteria).

At the end of the fit the updated track parameters are stored in a temporary area, but they are updated only if the user has set the update flag in the call to the fitting routine. The update flag can take on three values:

Note that the update=2 option resets the track irreversibly. This option should be used with great care because it can give erroneous results when multiple tracks are used in a fit (most vertex fits fall into this category, for example). The reason is that when update=2 is specified for a fit involving multiple tracks, kwfit updates the parameters and covariance matrix of each individual track correctly, but it does not keep track of the inter-track correlations. If two or more of these tracks are used in a subsequent fit the loss of these correlations will lead to incorrect results. Note that there is no problem if a single track is used in a fit, e.g., kfit_mass or kfit_energy. For example, to build a virtual particle like a D⁰ with the correct mass, the following code fragment will work:

c     Create new track entry and fill it with a D0 --> K pi combination
c     which has been vertex constrained to a common, but unknown, point
c     Do not update the input tracks
      list_d0(1) = ktrk_K
      list_d0(2) = ktrk_pi
      option_d0(1) = 2
      option_d0(2) = 2
      update = 0
      lvtx = .FALSE.
      call kfil_track_create(kd0)
      call kvir_vertex_unknown(2, list_d0, option_d0, update, lvtx, vtx,
     *                         chisq_d0, kd0, error)

c     Apply the mass constraint and update D0 parameters & error matrix
c     The D0 track now has the correct parameters and error matrix and
c     can be used in subsequent fits.
      mass_d0 = kget_track_mass(kd0)
      if(abs(mass_d0 - 1.8654) .lt. 0.010) then
        update = 2
        call kfit_mass(kd0, 1.865, update, chisq_mass, error)
      endif

8. Vertex constraints in KWFIT

With the advent of silicon tracking in CLEO, vertex fitting has become extremely important to physics analyses. However, there is no single vertex constraint method which is adequate to cover all desired cases. The mathematics for constraining tracks to a common vertex is worked out in refs. [2,3]. Kwfit distinguishes three kinds of vertex constraints when the number of tracks is n:

1. Constrain the particles to come from a common, but unknown, point. The number of degrees of freedom is 2n - 3, because three are lost determining the vertex point. A constraint of this type is used when trying to vertex daughters of particles such as K_s, D, etc. which have almost totally unconstrained origins.
2. Constrain the particles to come from a common known point described by an initial position and a covariance matrix. One sometimes says that we have "prior knowledge" of the vertex point. The number of degrees of freedom is 2n. A constraint of this type is appropriate when verticizing particles coming from the beam spot whose position and size is known. This is particularly important in CLEO where the vertical beam size is almost zero.
3. Constrain the particles to come from a common fixed point. The number of degrees of freedom is 2n. A constraint of this type is useful when trying to force a very soft track to pass through the vertex determined by a set of other tracks. It is also useful as a test routine.

The routines which carry out the vertex constraints are described in the user interface. Note that kwfit actually treats the first vertex algorithm as a special case of the second by setting the diagonal elements of the prior covariance matrix to huge values, effectively nullifying knowledge of the initial position.

All vertex routines have the prefix "kvtx_".

9. Creation of virtual particles

One of the most powerful features of kwfit is its ability to build a new particle from a set of particles using a vertex constraint. I like to call the new entity a "virtual particle". The virtual particle is created at the fitted vertex position and has the correct 4-momentum and 7x7 covariance matrix so that it can participate in future fits. Moreover, I have implemented a very flexible scheme - proven mathematically correct in ref. [3] - in which each input track can contribute to the vertex in a different way. This flexibility is necessary when handling very soft tracks and particles such as pizeros and gammas which have no position information.

There is a virtual particle creation routine corresponding to each of the vertex algorithms described in the previous section. If, in addition, you want to force the new particle to have a well defined mass, you merely impose the new constraint after the particle has been created. This two step procedure is equivalent to a simultaneous mass + vertex constraint (see ref. [1] if your masochistic urges compel you to see a proof of this assertion) and has the added advantage that the chisquares for the vertex and the mass constraints can be tested separately to help you decide if you want to keep the particle. An short example of how this is done is shown in Section 7 above.

All the virtual particle routines have the prefix "kvir_" and can only fill an existing particle slot (created by a "kfil_track_xxxx" routine).

10. A simple example of how to use KWFIT

11. More extensive examples

References

1. Paul Avery, "Applied Fitting Theory I: General Least Squares Theory", CBX 91-72 in gzipped Postscript or PDF format.
2. Paul Avery, "Applied Fitting Theory VI: Formulas for Kinematic Fitting", CBX 98-, in Word, gzipped Postscript or PDF format.
3. Paul Avery, "Applied Fitting Theory VII: Building Virtual Particles", CBX 98-, in Word, gzipped Postscript or PDF format.