
	etter
		Fit

With the start of LEP2 the method of constrained kinematic fitting has become a major subject, never really understood, but everybody with any respect for their analysis must use it.

Here there will not be made any attempt to clarify the situation - on the contrary - a new fitting package, more general than ever and with exponential rising degrees of freedom for the user, will be introduced.

Description of the ABCfit package

The ABCFIT package is designed to do constrained kinematic fitting of multi-particle events. In contrast to the other kinematical fitting packages available within ALEPH, the ABCFIT package employs an analytical approach by means of Newton-Raphson minimisation combined with Lagrange multipliers, resulting in an iterative algorithm. The analytical nature of the package ensures high speed, efficiency and reliability. In its present form the generality of the package has gone far beyond that of its precessor, while at the same time improving the speed and reducing significantly the program size. The ABCFIT package is fully backward compatible with its precessor in both functionality and reliability, and reproduces identical results within machine precision for equal input. The key features include:

Variable number of particles (at present maximum 7 are allowed; limited by array definitions)
The concept of unmeasured particles, e.g. neutrinos or neutralinos, have been introduced allowing a correct treatment of all types of events
Numerous parameterisations are included AND it is straightforward to introduce additional
Number of parameters per particle can be variable
Non-diagonal input covariance matrices of fit parameters
Parameter values and covariance matrices can be determined as a function of true or measured quantities
User specified constrain values
Fully configurable constrains and generalised mass-constrains with user specified multi-particle mass-combinations
Gaussian or Breit-Wigner behaviour of masses
ISR collinear with beam-axis following lowest order Q.E.D.
Event-by-event errors for any parameterisation implemented (and future), for particle 4-momenta and any user specified multi-particle mass-combinations
Main program is ALPHA independent. ALPHA interface is provided.
Package compiles and runs on Linux, Digital OSF1, HP and Silicon Graphics
The ABCFIT package comes bundled with a fairly easy-to-use parameterisation making tool for any parameterisation implemented (and future) in ABCFIT

But it will (still) not make coffee........
Availability
The source code of the ABCFIT package is organised in several separate files each related to a specific part of the package. To get an overview of the source code and a feeling of the general program-flow across the different files have a look at the program flow-diagram. The present version (0.99999999B) consists of the fortran files:

abcfit.F contains the various user entry points and the kernel fitting code
abcfit_bmatrix.F holds the different routines to deal with parameterisations and constrain handling
abcfit_aibi_evol.F contains the routines for initialisation of the fit parameters and the optional user parameter initilisation routine.
abcfit_aibi_evol_mathkine.F contains the optional user parameter initilisation routine with an interface to the old MATHKINE aibi_evol routines. Remember that only ONE aibi_evol_user routine must exist. Important: Remember to get parameterisation files (O.Buchmuller).
abcfit_alpha.F is the optional ALPHA interface

and the include files:

The main package requires CERNLIB and the optional ALPHA interface requires the usual qdecl.h, qcde.h and qmacro.h ALPHA include files.
The parameterisation making tool uses several routines from abcfit_bmatrix.F in order to avoid redundant code and to ensure coherence of abcfit and the parameterisations.

Usage
The high degree of freedom for the user and generality of the ABCFIT package demand a rather long calling structure, which to the un-familiar user may seem very complicated. Unfortunately this is necessary in order to allow a user to make optimal usage of the package. Simple interfaces can be made upon request for users who prefer crude simplicity rather than the full power of the package. The description of the ABCFIT calling structure is given here. A description of the parameterisation tool can be found here. Several examples using ABCFIT exists:

EXAMPLE 1: QQQQ (NJET=4, NUP=0, ALEPH PAR, 4C)
EXAMPLE 2: QQQQ (NJET=4, NUP=0, ALEPH PAR, 4C, FIXED JET MASSES)
EXAMPLE 3: QQQQ (NJET=4, NUP=0, DELPHI PAR, 5C + 3 TIMES MINDEX)
EXAMPLE 4: QQQQ (NJET=4, NUP=0, DELPHI PAR, 6C (ZZ CONSTRAINTS) WITH ALPHAS)
EXAMPLE 5: LLQQ (NJET=4, NUP=0, DELPHI PAR, 5C (ONE Z CONSTRAINT))
EXAMPLE 6: QQLV (NJET=4, NUP=1, DELPHI PAR, 1C, RECO BINNING)
EXAMPLE 7: QQLV (NJET=4, NUP=1, DELPHI PAR, 2C("EQUAL ENERGY"), TRUE BINNING)
EXAMPLE 8: QQLV (NJET=4, NUP=1, DELPHI PAR, 2C("EQUAL MASS"), TRUE BINNING)
EXAMPLE 9: QGQLV (NJET=5, NUP=1, DELPHI PAR, 1C, RECO BINNING)
EXAMPLE 10: (Q+Q)LV (NJET=3, NUP=1, DELPHI PAR, 1C, RECO BINNING)
EXAMPLE 11: (Q+Q)LV (NJET=3, NUP=1, DELPHI PAR, MINDEX, 2C, RECO BINNING)
EXAMPLE 12: QQGAMMA (NJET=2, NUP=0, DELPHI PAR, 3C (NO PZ), RECO BINNING)

To compile and run to full example program download the full example program and the makefile (check/edit if needed).

The event-by-event errors on fit parameters, particle 4-momenta and multi-particle mass combinations are returned via a call to a dedicated routine to be called after each successful fit. It is possible to call the routine several times (after a fit) using different mass combinations (e.g. all three possible W-W di-jet combinations of a hadronic WW event or total centre-of-mass). The event-by-event errors are calculated using error propagation. The relevant routine is named CY02PM (a version for rescaled masses exists: CY02MR) and the description of its calling structure is given here. Example on its use is here.

History

October 1998: Release of version 0.99999999B. Missing feature is ISR.

Other packages
In principle there exists three different ways to do constrained kinematic fitting. In ALEPH all three approaches have been implemented in kinematic fitting packages. The official fitting packages available in ALEPH are:

KINFIT is a MINUIT based kinematic fitting package where the choice of parameters ensures automatic satisfaction of the constrains -- "parameterising the constrains away". The package is a dedicated WW fitting package using four parameters to describe a particle.
MATHKINE is the fitting package upon which ABCFIT is based. Many features have been implemented in MATHKINE, but the philosophy behind the programing makes the program very tedious to generalise. Consequently, it was decided to rewrite MATHKINE to allow a much more general package - ABCFIT was born.
QFITWW is a MINUIT based kinematic fitting package like KINFIT. Although less impressive in its WW performance (due do more general parameter definitions) the package is considerably more general than KINFIT. In contrast to KINFIT, QFITWW imposes constrains via the concept of penalty functions.

References

V.Blobel in "Formulae and Methods in Experimental data evaluation", by the European Physical Society (1983), vol. 3, p. L1. For anyone interested in general least squares minimisation this is simply THE BIBLE. Unfortunately it is rather difficult to find.
R.J.Cavanaugh, "An ALPHA Tool for Constrained Kinematic Fits to W⁺W^- events: QFITWW", ALEPH 96-129 (PHYSIC 96-118).
R.J.Cavanaugh and M.J.Corden, "A Kinematic Fit to Semi-leptonic WW events without Jet Finding", ALEPH 97-087 (PHYSIC 97-077).
A.Tilquin, "Constrained fit and Initial State Radiation in Four Jet Events at LEPII", ALEPH 95-129 (PHYSIC 95-111).

Comments/suggestions to O.Buchmuller or J.B.Hansen
#5 10-10-1998