How to use this matching package


Please note that this matching package which is described here was released together with a version of tfevnt() and some of its subroutines dedicated to the '98 taskforce studies in 1997. That way, the lepton seed for the upstream propagation out of the RSEG table.

This version also relies on the new RK routines, which are provided with ARTE-08-01-r2 (and propably later)

The libmatch98.a routines

The matching itself needs only to routines:

MATCHing 98 INITialization

  CALL match98init()
This does some initialization and has to be called by usinit().


MAtch with VerteX
and fill into RTRA table

  INTEGER resgc,rsegs(),igtar
  CALL mavxrtra(rsegc,rsegs,igtar)
This is meant to be the very routine called in usevnt() to actually do the matching with SVD segments and create RTRA table entries for the matched segments. It needs as input an array of integers rsegs(), that contains the RSEG row numbers of the segments to be matched with a SVD segment. The input argument rsegc indicates the last entry in rsegs() containing a valid RSEG row number. Also the target wire from which the decay in question originated has to be provided for the target constraints used in the matching procedure. In case of missing information about the target wire, the routine can be called more than once, each time with a different target wire. (This is of course not the optimal solution, but serves as a workaround for the time being)
To make things easier for you, there are some additional tools. E.g. to fill the rsegs() array, you can use mafilepseg(), the GTAR row number can be obtained with maselgtar()/magetgtar(). In general, the variable ierr returns a status indicating success when the value is zero. For more details on ierr you have to refer to the source code or to ask me :-).

MAtchlib: FInd
LEPton SEGments
  INTEGER rsegc_max,rsegs(rsegc_max),rsegc,cmp
  CALL mafilepseg(rsegc_max,rsegs,rsegc,cmp) 
Collects all segments which have been reconstructed have a bit pattern in the table entry RSEG_CMP which matches the argument cmp and puts them in the array rsegs(), which has to be at least of length rsegc_max. The bit pattern (up to now) may consist of a combination of
rsegc_vxd Vertex Detector
rsegc_patt Pattern Tracker
rsegc_magt Magnet Tracker
rsegc_muon Muon Detector
rsegc_ecal Ecal Segment
rsegc_tar Target Constraint
which are defined in the include file (You should never use numerical values and never invent new bit pattern definitions yourself!) If you want an OR-wise combination of bit patterns, you have to invoke mafilepseg() for each bit pattern separately. mafilepseg() starts to fill the array at position rsegc+1 and returns in rsegc the last row filled (so rsegc is as well input as output)

maselgtar(,) (function)

MAtchlib: SELect 
GTAR row number
  INTEGER ngold,ierr,maselgtar
This function tries to estimate from the ngold'th decay stored in ma_pstat(,) which target wire was the origin of the decay in question and returns the row number of the wire in table GTAR (hence igtar). How the wire is selected (i.e. the contents of ma_pstat(,)) depends heavily on the setting of MATCH98/LEPTONMODE.

maselgtar() makes use of magetgtar().

magetgtar(,) (function)

MAtchlib: GET
GTAR row number
  INTEGER imtra,ierr,magetgtar
This routine selects the row number igtar of the target wire which is closest to the BVER of the MC track with given row number imtra.

The following routines are not connected to the matching directly, but might be handy if you want to use MC track information for the lepton seed instead of the MUREC or CARE output:

MAtchlib: convert MC information
TO LEPton SEGments
  CALL mamc2lepseg()
This routine fills the RSEG table with information from the MTRA table in order to provide a lepton seed for the Ranger upstream algorithm without having a (real) lepton detector simulation. Of course, the MC information is smeared with appropriate factors. It makes use of the routines mamuseg_mtra() and maelseg_mtra(). After mamc2lepseg() has been called, tfevnt() (the adapted version) can be called for the upstream propagation. Please note, that the covariance matrix of the RSEG entry for CARE output is not given properly yet.


MAtchlib: create MUon
SEGment from MTRA table row
  CALL maelseg_mtra(imtra,ierr)
Makes an entry in the RSEG table for the one given MTRA table entry (imtra = MTRA row number) trying to simulate CARE output. The CARE package provides only cluster information from which a zero length segment with direction information gained by a target constraint can be constructed.


MAtchlib: create MUon
SEGment from MTRA table row
  CALL mamuseg_mtra()
Makes an entry in the RSEG table for the one given MTRA table entry (imtra = MTRA row number) trying to simulating MUREC output.

No other routine of the package is intended to be used by a non-expert. The internal structure with respect to which subroutines is called by which subroutine can be seen in README.hierachy.

The KUIP commands

If you want to use (you probably have to) the KUIP commands of the '98 matching you have to put the line
   #include "match98.cdf"
in your uskuip.cdf file. Then you have the KUIP menu MATCH98 available, which contains the following commands:


MATCH98/CUTS xcut ycut txcut tycut [xoffset yoffset txoffset tyoffset]

Set cuts for SVD segment matching. Shows values without arguments.
The offsets are meant to be used if you want to use asymmetric
cut windows, they are not well tested yet.


Show same settings and statistics of
the matching stuff. Note that the abbreviation SH, often
used for KUIP/SHELL becomes ambiguous.


Set which decay is used for selecting Leptons in mamc2lepseg() and the target wire in
maselgtar(). Recognized values are
GOLD for golden decays of B0
JPSI J/Psi -> l+l-
B for golden-like decays of other Bs.
Y or UPSILON Y -> l+l-
BSEM semileptonic b decays
CSEM semileptonic c decays.
Apart from "GOLD" I do not guarantee for proper results ...


Way to simulate the ECAL, should be 1, which means that
maelseg_mtra will use the information stored in the MCAL

MATCH98/DE dE [seed1 seed2]

Set the width for simulating the calibration error of the ecal. If given,
the parameters seed1 seed2 are used to initialize the
random generator (NORRAN()), otherwise there is no
initalisation by the matching package. (The latter is what you want in
most cases)

Select lepton detector to be used in mamc2lepseg(). Recognized
values are "ECAL", "MUON" and "BOTH"

MATCH98/SAMP e1samp e2samp e5samp

Change sampling factors for ECAL used in maelseg_mtra()
if mode (see ECALMODE above) is 1;
factors are given separately for 1 x 1, 2 x 2 and
5 x 5 division blocks. There should normally no need to use


MATCH98/RK x y tx ty fstep iter rlenx rleny rlentx rlenty rlenp

Set parameters for the Runge Kutta routines by T. Oest and radiation
length values to be assumed for adding additional errors for covariance matrix
x Precision in x over full distance (RK parameter)
y Precision in y over full distance (RK parameter)
tx Precision in tx over full distance (RK parameter)
ty Precision in ty over full distance (RK parameter)
fstep Fstep (RK parameter)
iter Number of Iterations (i.e. invocations of RK)
rlenx rad. length for adding MS to RK error in x for tangent fit
rleny rad. length for adding MS to RK error in y for tangent fit
rlentxrad. length for adding MS to RK error in tx for tangent fit
rlentyrad. length for adding MS to RK error in ty for tangent fit
rlenp rad. length for adding MS to RK error for p fit


Set verbosity of the match package. Default is
level=4 (errors), 5 gives you also minor errors,
10 is already quite verbose. Without argument, it is set to 10.