Stephen Burke 24th September 1998
I've just been cleaning up my files, and I found the following, written in February 1992. This is likely to be somewhat out of date, particularly the central-forward linking where the KTREC module has been superseded by KTNREC, but it may give some help to anyone trying to maintain my code. Incidentally, I notice that documentation doesn't appear on John's task list!
The reconstruction of tracks in the forward tracker is performed by the FTREC module. The input consists of the raw data banks FRPE and FRRE, together with various steering and calibration banks. The output is a bank of track parameters (FTKR), two banks of pointers to the hits which form the tracks (FTPX and FTRX) and a bank of pointers to connect the two (FTPR). FTREC is in turn split into three sub-modules, each of which is self-contained and communicates with the others only via internal named banks. [Only true of FFKAL at the moment.] FPSEG finds track segments in the planar chambers in each of the three supermodules separately. FPTFPT similarly finds radial-based segments, and then performs a simplified helix fit to these in order to pick up associated planar segments. Finally, FFKAL performs a Kalman filter track fit on the list of hits. Bad hits may also be rejected and new hits found at this stage. Each of these stages is described in detail, followed by a description of the memory requirements, time consumption, event size, banks used and bank formats. 1. Planar Segment Finding. ========================== 2. Radial Segment Finding. ========================== 3. Linking Segments. ====================
The Kalman filter routines themselves are described in a separate document [1],
as they form a stand-alone package (although specialised for fitting tracks in
the forward tracker), and a more detailed description can be found in [2], so
only a brief description is given here. The names of these routines all start
with FK. Routines with names starting with FF, called from the FFKAL routine,
provide an interface between the reconstruction code and the Kalman filter, and
these are described below. Note that there is no difference between the
treatment of Monte Carlo and real data, except that some diagnostics are only
possible with Monte Carlo data.
4.1 The Kalman Filter.
----------------------
The Kalman filter is a comparatively new technique in particle physics, but has
been used for many years in applications such as radar tracking of missiles.
Instead of doing a global fit to all measurements at once, the measurements are
added one at a time; effectively a new least-squares fit (weighted mean) is
performed for each new measurement. This has been shown to give the optimal
solution for a linear system, and is also the optimal linear method for a
non-linear system. Adding measurements successively has obvious utility in an
application such as radar tracking, where they arrive sequentially, but there
are also features which make the technique useful in a particle physics
context.
A Kalman filter has three main advantages over a conventional track fit.
Firstly, and most importantly, multiple scattering can be taken into account
correctly without the necessity for inverting large matrices. The traditional
approach treats multiple scattering as introducing an additional measurement
error each time the track crosses a region where the scattering probability is
significant. However, because the scattering after several such regions is
cumulative, this generates correlations between all measurements. When
calculating the chi-squared between the measurements and a track it is
therefore necessary to invert an n*n matrix, where n is the number of
measurements (up to 72 in the forward tracker). The material in the forward
tracker amounts to about 0.5 X0, distributed fairly uniformly, making it
impossible to neglect multiple scattering. This is in contrast to the central
tracker, where the scattering within the two CJC rings is negligible.
The Kalman filter allows the use of a more realistic track model, in which
the helix is allowed to have a displacement and a bend each time it crosses a
region of significant multiple scattering. The fitted track therefore follows
the path of the real particle, and the correlations between measurements
disappear, so there are no large matrices to invert. This also gives an optimum
estimate of the track parameters at all points on the track, whereas a
traditional helix fit gives these at only one point. This is because a helix
does not correspond to the true path of the particle, so it can only be chosen
to intersect the true path in one place.
A further advantage of the Kalman filter is that it is relatively simple to
reject bad measurements, or add in new ones, during the fit process, without
excessively increasing the time consumed (typically a 50% increase,
approximately independent of the number of measurements added or removed).
The only significant disadvantage to the Kalman filter technique is that it
uses linear error propagation, as compared (for example) with the MINOS routine
in MINUIT which calculates accurate confidence limits even for non-linear
systems. The main implication of this is that a 'starting vector' or 'initial
state vector' with 'starting errors is required, such that the errors are
small enough for a linear approximation to the track model to be valid over the
region in parameter space spanned by the errors. Measurements many standard
deviations from the true track can also lead to instability from this cause. In
practice, these problems are solved because the pattern recognition step has in
any case to do an approximate track fit in order to link segments in different
modules, and this provides an adequate starting vector for the Kalman filter.
Measurements which have been accepted by the pattern recognition should also be
reasonably close to the track. The Kalman filter cannot, however, act as a
substitute for pattern recognition. This starting vector inevitably introduces
some bias into the result of the fit, although the starting errors are normally
large compared with the final errors. An option is provided to remove the
effect of the starting vector after the track fit is complete; this increases
the time taken by about 50%.
4.2 Initialisation.
-------------------
Initialisation is performed on the first call with BEGRUN true. FFKAL first
calls FKINIT, which initialises the Kalman filter code to default values, and
then FFTEXT. This reads the steering banks FFTS, FFTP and FFTM (see below). If
these are not found an error message is generated, but sensible defaults are
taken and execution continues. FFTEXT also prints a summary of the most
important steering parameters. Note that the Kalman filter steering common
blocks are currently filled directly, which means that no other module can use
the Kalman filter code concurrently without saving the data.
FFKAL then books histograms as necessary, in FFBKLK for monitoring histograms
and FKHBK and FFHBK for diagnostic histograms. Bank formats are defined, work
bank indices are zeroed and counters for various conditions are also zeroed.
4.3 Track Fitting.
------------------
FFKAL calls FFFIT on REVENT to perform the track fits. This just finds and
unpacks various banks and calls FFKLMN for each track in turn, which forms the
main interface to the Kalman filter code. It fills the Kalman filter arrays
with the data for a track, using routines FFPLAN and FFRAD to process the
planar and radial hits respectively. The coherence of the digi pointer lists
(FPUX and FRUX) is also checked. A track-angle correction is applied, based on
the angle of the pattern-recognised track. The Kalman filter starting vector
is taken from the output from the pattern recognition step, but the starting
errors are taken from the steering bank FFTP. If the errors from the pattern
recognition are larger than those in the FFTP bank, however, they are used
instead.
Tracks can be vetoed before fitting by the function FFRJCT, using criteria
defined in the FFTS bank (see below). FFKLMN then calls either FKLFIT or
FKLFTR, according to whether removal of the initial state vector has been
selected in FFTS, to perform the Kalman fit.
Finally, the track is added to the output banks by FFOUT, provided that the
Kalman filter ended without a fatal error, and that the chi-squared is
acceptable (see the description of the FFTS bank below). Care is taken to
ensure that no hits are used on more than one track, as the format chosen for
the FTPX and FTRX banks does not allow for this and it causes them to become
corrupt. Note that all tracks in FTKR have two sets of parameters, at the first
and last measured points. These always come one after the other, with the one
closest to the vertex first. This format is guaranteed for future releases of
the code, so it can be relied on.
An internal bank FTKX is also created; this is parallel to FTPR, and contains
the corresponding track number in FTUR. This is normally dropped at the end of
FTREC, but is added to the 'E' list if FFOUT is compiled with FFDEBUG SELECTed.
FFOUT also fills the monitoring histograms.
A final call to FFOUT is made from FFFIT after all tracks have been fitted;
this creates the final output banks from work banks. Note that the output banks
are created even if the number of tracks is zero; this is so that it is
possible for subsequent modules to tell unambiguously whether FTREC has run or
not (see section 8 below). However, a BOS error (i.e. running out of space in
/BCS/) results in all banks for that event being dropped.
4.4 Point Acquisition.
----------------------
The Kalman filter code has the option of looking for new hits at planes where
the pattern recognition found nothing. This is implemented by calling the
routine FKHUNT, which exists as a dummy in patch FT_FKALMAN, conditional on the
SELECT flag FKHUNT_DUMMY. A second version, conditional on the negation of this
flag, is in patch FT_FFKAL.
This does not allow the replacement of a point which is already in place,
although this is potentially possible, but it can replace a point which has
already been rejected. Point sharing is also disallowed; i.e. a point which is
already attached to another track cannot be picked up (even if it would give a
better fit to the new track). This is a consequence of the format chosen for
the digi pointer banks, which prevents this (otherwise reasonable) possibility.
FKHUNT uses routines FFPCEL and FFRCEL, for planars and radials respectively,
to calculate the cell number for the cell corresponding to the position of the
fitted track, and also the drift distance to the wire in that cell. Routines
FFPHNT and FFRHNT are then used to look for a hit in that cell; if more than
one is found, the one with a drift closest to the target value is taken. A
chi-squared is then calculated with respect to the fitted track, and if it
satisfies the cut given by X2CUTN in FFTP the new hit is added to the list. The
routines FFPLAN and FFRAD are again used to translate the hit information into
the form used by the Kalman filter. A track angle correction is made, based in
this case on the angle of the fitted track.
4.5 Termination.
----------------
On ENDRUN FFKAL prints the number of tracks found by the pattern recognition,
the number output in FTKR banks and gives the reasons for any difference
between the two. Possible reasons for tracks not being output are:
BOS array full: No room to create a new bank.
Bank structure corrupt: Code error in the creation of the FPUX or FRUX banks.
Bad track parameters: Track parameters in FTUR wildly wrong.
Too few planar points: Failed ISRJCT test (see below).
Too few radial points: Failed ISRJCT test (see below).
Momentum below cut: Failed PCUT test (see below).
Fatal error in fit: Error in Kalman filter (see ERRLOG summary for details).
Bad chi-squared prob: Failed CHPCUT test (see below).
On ENDJOB FKEND is called, which prints the Kalman filter summary as
controlled by the steering flag IPR (see below). Diagnostic histograms are
printed if requested. Note that the monitoring histograms are printed from the
FTREC routine.
4.6 Error Handling.
-------------------
Kalman filter error messages (as explained in [1]) are passed to ERRLOG via the
routine FKEM, which translates the internal error number into a text message.
The message also gives the routine in which the error ocurred, and indicates
whether it was a "fatal" error. Fatal errors from FKLFIT or FKLFTR indicate
that the fit failed, so the track will not appear on the output. Error messages
can also be printed during the run, and a (more cryptic) summary requested,
using the IPR and MAXERR parameters in FFTS (see below).
A few errors occur fairly routinely. Any message about multiple iterations is
for information only, and does not indicate the presence of a problem unless
very numerous. "TAN(theta)>1" is also fairly common; this indicates a problem
in the fit (except with cosmics, where there may really be steep tracks), but
an acceptable fit is usually still obtained at the end. Less common are
messages about non-positive definite covariance matrices, which indicate a
rather more serious problem. Messages such as "Invalid value" or "xxx missing"
indicate a problem with the program itself; either a bug or a CMZ problem.
Other messages should be rare or nonexistent, and if they occur with any
frequency they should be reported to the librarian.
A few other errors can be generated by the FFxxxx routines; these are fairly
self-explanatory. They mostly indicate fairly serious errors. These are passed
directly to ERRLOG.
4.7 Monitoring Histograms.
--------------------------
Some standard LOOK histograms are generated to give an idea of the quality of
the track reconstruction. The general appearance of the histograms should be as
follows (in a fairly ideal world). Note that there will be some variation
depending on the event type, and there may also be a dependence on steering
parameters (e.g. the residual distributions will have smaller tails if point
rejection is enabled).
Tracks/event: Broad distribution, extending up to 20-30
Planar hits/track: Broad distribution; spikes at 12, 24, 36
Radial hits/track: Two peaks, with spikes at 24, 36*
Hits/track vs theta: Up to 72* in the centre, falling off at the edges
Drift residuals (planars): Gaussian, peaked at zero, half-width about 0.02 cm
Drift residuals (radials): Gaussian, peaked at zero, half-width about 0.02 cm
Radius residuals (radials): Non-Gaussian, peaked at zero, half-width about 2cm
Chi-squared/DOF: Peaked at 1, some tail
Chi-squared probability: Flat (ish)
Phi: Flat
Theta: Broad distribution, peaked below 0.2
Q/Momentum: Fairly flat; symmetrical about zero
LOG(Momentum): Broad distribution, peaked between 0 and 1
Fractional error on 1/r: Peaked below 0.1; some tail
Error on theta: Broad distribution, peaked below 0.002
Error on xy: Peaked below 0.025 cm; fairly small tail
* Note that in real data the number of radial hits per track will have spikes
at 16 and 24 until the forward tracker is fully instrumented.
4.8 Diagnostics.
----------------
Diagnostics are mainly provided in the form of HBOOK histograms, controlled by
the IDIAG flag described below. Note that the default size of the /PAWC/ common
defined in the main program must be increased if these are to be used.
All HBOOK histograms are booked in subdirectories of //PAWC with names
beginning with "F", so the histogram numbers should not clash with others used
elsewhere. The current directory is reset to //PAWC at the end of the module.
Some HBOOK calls are made even if IDIAG is zero, although no histograms are
filled, so /PAWC/ must always exist and HLIMIT be called. HBOOK histograms can
be written to the stream specified by the LUNHB steering parameter, if
non-zero; this is done on ENDJOB.
Diagnostic code is concentrated into special subroutines, in patches
FT_FKDEBUG and FT_FFDEBUG, where possible. However, there are calls to HBOOK
routines and to these internal diagnostic routines scattered throughout the
code; unfortunately it is not easy to segregate this code completely, as the
diagnostics must be produced at the time that the information is available.
Most of the histograms rely on having information about the true tracks, so
they are only useful for Monte Carlo data. Also, the default setting in H1SIM
is to have all secondary tracks given the same track number as their parent,
which makes the diagnostics somewhat unreliable. To use them properly requires
a dataset simulated with the secondary momentum cut (SKECUT) set to zero for
the central and forward trackers. This results in larger output, but allows
tracks to be identified unambiguously. It is also useful to produce
forward-tracker starting track (FS) banks, which are also not made by default.
Finally, the STR, SVX, FRPX and FRRX banks must not have been removed.
There is also a built-in graphic display, the use of which requires the code
to be compiled with FFGKS SELECTed in CMZ. However, this is intended for expert
use only, as the display format is difficult to interpret.
4.9 Steering Banks.
-------------------
The operation of the Kalman filter is controlled by the steering banks FFTS,
FFTP and FFTM. The function of the various parameters is as follows. More
information on the function of many of these parameters can be found in [1].
The first item in each steering bank is a "version number", based on the date
when the format of the bank (i.e. the number, order or meaning of the other
items) was last modified. FFTEXT checks that the bank it gets contains the
right version number, to avoid problems with old versions of steering banks
being retrieved from the database by mistake. If the wrong version number is
found an error message is generated, the internal defaults are taken and
execution continues.
FFTS: Main steering flags.
LUN The unit to which all printout is directed.
IPR Printout flag. Set to 20 for maximum print level (mainly at job
termination, unless MAXERR is also large), and to 0 for minimum
printout.
MAXERR Maximum number of errors printed during execution. These are
independent of the ERRLOG mechanism, and are in a less friendly
format.
IDIAG Diagnostic flag; should normally be left at zero. Diagnostics
include various (HBOOK) histograms and an internal graphics display;
the latter needs compilation with FFGKS SELECTed, and is difficult
for a non-expert to interpret. The only histograms of any general
interest are of pattern recognition efficiency (IDIAG=00100010)
and resolutions (IDIAG=00001110). These only work for Monte Carlo
data, and need a dataset simulated with SKECUT=0. Note that the default
size of the /PAWC/ common will probably need to be increased in the
main routine if these histograms are used. In more detail, IDIAG is
interpreted as an eight-digit decimal number, where each digit can be
0 or 1, with each 1 turning on a particular feature. From right to
left, the digits control:
Graphic display
True tracks found (needed for most of the diagnostics to work)
Resolution histograms
Chi-squared and residual histograms
Detailed residual histograms for selected planes
Hit-finding efficiency/error rate histograms
Track-finding efficiency histograms
Do the previous two after the Kalman filter as well as before
PMCUT Histograms controlled by IDIAG are only filled for tracks with
momentum .GT. PMCUT (this doesn't apply to all histograms).
LPOINT Set to 1 to enable point rejection.
LBLOCK Set to 1 to enable block point rejection.
LPRINI Set to 1 to do point rejection in the first pass when removing the
initial state vector.
LRISV Set to 1 to remove the initial state vector.
JPLRSV The plane from which to start when removing the initial state vector.
ISRJCT Flag to enable tracks to be rejected before fitting. The flag is
interpreted as a decimal number abcdeef, where b is the minimum number
of planar hits/module, c is the minimum number of planar
modules/supermodule, d is the minimum number of planar supermodules,
ee is the minimum number of radial hits/module and f is the minimum
number of radial modules. If a is non-zero, planar modules which fail
the test against b have all hits removed. A value of 0 gives no
rejection.
PCUT This enables tracks to be rejected before fitting if the momentum
calculated by the pattern recognition step is .LT. PCUT.
CHPCUT Fitted tracks are not added to the output if they have a chi-squared
probability .LT. CHPCUT. This should be used with caution, as the
probability distribution may be far from flat if point rejection is
not used.
LUNHB If this is non-zero it defines a stream to which any HBOOK plots
will be written (as an RZ file).
LUNGKS This gives the stream number used by GKS if the internal graphics
display is selected.
IWKGKS Similarly, this gives the GKS workstation type ...
IDGKS ... the workstation ID used ...
LUNGKM ... the stream to which GKS metafile output will be written ...
IWKGKM ... the metafile workstation type ...
IDGKM ... and the workstation ID for the metafile.
FFTP: Steering parameters.
X2PCUT } These are the chi-squared probability cuts used in point rejection,
X2CUTB } block point rejection, point re-acquisition and new point
X2CUTA } acquisition, respectively.
X2CUTN }
X2PCTI } As above, if point rejection is enabled on the first pass when
X2CTBI } removing the initial state vector.
X2CTAI }
X2CTNI }
DSX } These are the errors used on the initial state vector, on x, y,
DSY } q/p, tan(theta) and phi respectively. They are ignored if initial
DSQOP } state vector removal is selected (the errors in the FTUR bank are
DSTTH } used in this case), or if the FTUR errors are larger.
DSPHI }
FFTM: Maps (arrays having a separate value for each wire plane).
NBLOCK This is an array giving the definitions of blocks used in block
point rejection.
LWIRE Entries should be set to 1 for each wire to be used in single
point rejection when block point rejection is also selected.
RADL Each entry is the radiation length in cm (as seen by a track parallel
to the z axis) of the material between one plane and the next (the
final value is therefore not used). If the values are negative,
multiple scattering will be neglected for that region.
LWMAP This allows whole wire planes to be mapped out to increase execution
speed (e.g. if the last four radial wires in each supermodule
are not instrumented). A value of 1 means that the plane is used,
while a value of 0 means that it is not. Errors are generated if
hits are found on a mapped-out plane.
4.10 Common blocks.
------------------
The Kalman filter common blocks are described in [1]. The only thing to note
here is that two versions of the sequences are provided, in decks FKMAC1 and
FKMAC2. By default the former is used, which puts most of the event-based data
(about 150 kb) into /H1WORK/. If FKNOWORK is SELECTed, the normal Kalman filter
common blocks are used instead. The common blocks moved into /H1WORK/ are
/FKTRUE/, /FKPROJ/, /FKFILT/, /FKSMTH/, /FKINT/, /FKRSID/ and /FKDBG/. The
definition of the /H1WORK/ common is included in sequence FKNPL, which is
always the first sequence referenced by the Kalman filter routines.
The FFKAL common blocks are as follows:
/FFSTEE/ DSX * Starting error on x
DSY * Starting error on y
DSQOP * Starting error on q/p
DSTTH * Starting error on theta
DSPHI * Starting error on phi
PMCUT * Momentum cut for diagnostics
IDIAG * Diagnostic steering flag
JPLRSV * Starting plane for initial state vector removal
LRISV * Logical flag for initial state vector removal
LWMAP * Logical flags for which planes are mapped in
JPLMAX Largest Kalman filter plane number (see below)
IRP 1 for planar, 2 for radial (indexed by JPL - see below)
JPLFT JFT-type number from JPL-type number (see below)
JFTPL JPL-type number from JFT-type number (see below)
LUNGKS * GKS output stream
IWKGKS * GKS workstation type
IDGKS * GKS workstation ID
LUNHB * HBOOK output stream
LUNGKM * GKS metafile stream
IWKGKM * GKS metafile workstation type
IDGKM * GKS metafile workstation ID
LGRAPH Logical flag for graphics display
LTRUTH Logical flag for true track information
IHFF Flag for diagnostic histograms
IHFK Flag for diagnostic histograms
ISRJCT * Track rejection flag
PCUT * Track momentum cut
CHPCUT * Chi-squared probability cut
/FFGEO/ INDG1 Indices of the FPG1 and FRG1 banks
INDLC Indices of the FPLC and FRLC banks
IDIGI Digi pointer and drift sign for each (JPL) plane
/FFSCAL/ NPFAIL Number of tracks with too few planar points
NRFAIL Number of tracks with too few radial points
NXFAIL Number of tracks failing the chi-squared probability cut
NFFAIL Number of tracks with a fatal error in the Kalman filter
NMFAIL Number of tracks failing the initial momentum cut
NBFAIL Number of tracks with a corrupt digi pointer list
NTFAIL Number of tracks with bad parameters
NWFAIL Number of tracks aborted due to insufficient space in /BCS/
/FFWBI/ INDRSX Indices of the unpacked FRPX and FRRX banks
INDX Indices of the unpacked FPUX and FRUX banks
INDKX Indices of the unpacked FTPX and FTRX banks
INDPUR Index of the unpacked FPUR bank
INDKTR Index of the unpacked FTKR bank
INDKTX Index of the unpacked FTKX bank
INDTPR Index of the unpacked FTPR bank
/FFDBG/ ITRTR True track numbers for the current event
ITRNF Tracks in the FT not found by the pattern recognition
JTRTR True track number for the current track
In /FFSTEE/, items marked * are taken directly from steering banks; the others
are derived from the steering parameters in FFTEXT. Other steering parameters
are placed directly into the Kalman filter common blocks. /FFSCAL/ contains
counters for various conditions, as printed by FFKAL at ENDRUN. /FFWBI/
contains various work bank indices.
One general point to note is that there are two kinds of "plane number".
Planes labelled by an index JFT are "absolute"; the index runs from 1 to 72,
with alternate groups of 12 referring to planars and radials. Planes labelled
by JPL are those used by the Kalman filter. Normally these are the same, but if
planes are "mapped out" (declared non-existent) in the FFTM steering bank the
JPL-type planes do not include those which have been mapped out. Arrays JFTPL
and JPLFT in /FFSTEE/ allow translation from one form to the other; the largest
JPL plane number is stored in JPLMAX, and the IRP array indicates whether a
JPL-type plane is a planar or a radial. Note that in either form the planes are
in order of increasing z.
5. Space Usage.
===============
The total size of H1REC (3.01/06, as measured on a VAX) is about 10 Mb (where
1 Mb = 10**6 bytes). Of this, code only accounts for about 1.4 Mb, of which
about 0.17 Mb is FTREC. Local variables (i.e. not in common blocks) total about
1.7 Mb, of which 0.61 Mb is in FTREC. There are about 2.5 Mb of "private"
common blocks, of which about 0.72 Mb is used by FTREC. The remainder of
the space is accounted for by the three large common blocks /BCS/ (2.4 Mb),
/COMIC/ (1.0 Mb) and /H1WORK/ (1.0 Mb). The largest user of /H1WORK/ is FTREC,
closely followed by the liquid argon crack correction code at 0.85 Mb. Thus
FTREC accounts for about 17% of the total size of the program (1.65 Mb).
Within FTREC, the planar code accounts for roughly 2/3 of the space consumed,
and the radial pattern recognition for most of the remainder. The Kalman filter
code uses only about 0.2 Mb in total, as it deals with only one track at a
time.
6. Time Consumption.
====================
The total time per event on the DESY IBM is about ??? ms, of which ??? ms is
consumed by FTREC (for ??? tracks/event). These figures are based on "typical"
(LUND NC) events.
The breakdown of the time within FTREC has been estimated using the PCA
utility on a VAX; the results are therefore not necessarily exactly
transferable to the IBM. Approximately 40% of the time is spent in the planar
pattern recogintion, 30% in the radial pattern recognition, 20% in the Kalman
filter and 10% in overheads (unpacking banks etc.). This assumes that the
Kalman filter is run without point rejection or initial state vector removal;
in the worst case, these could approximately double the time taken in the
Kalman filter.
[How do FPTFPT and FPSEG scale with the number of tracks/hits???]
The time taken by the Kalman filter is proportional to the number of tracks
fitted, and fairly independent of the number of hits on a track (varying by no
more than a factor of 2 between the shortest and longest tracks).
7. Output Size.
===============
The FTKR/FTPR banks have 44 words/track between them, so for a "typical"
10-track event these are about 2 kb/event. The FTPX and FTRX banks have
one word/hit (1/3 of the size of the digi banks themselves), contributing
something like 5 kb/event. If the digi banks are dropped the FTPR, FTPX and
FTRX banks can also be dropped, reducing the total size to below 2 kb/event
(i.e. by more than an order of magnitude if the size of the digi banks is
included).
8. Bank Existence.
==================
As a general policy, it is assumed that banks should exist even if they have no
entries; this makes it possible to distinguish, for example, the case of FTREC
running but finding no tracks and the case of FTREC not having been run. Thus
the input banks (FRPE and FRRE) are required to exist, and an error is
generated if they do not. Likewise the FTKR and FTPR banks are created (with
length 2 and word 2 set to zero) if no tracks are found, and FTPX and FTRX are
always created parallel to the (possibly empty) FRPE and FRRE banks. However,
if a serious "external" error occurs (e.g. input banks not existing, or running
out of space in /BCS/) these banks are NOT created, as FTREC has not
successfully run in this case.
9. Banks Used
=============
Note that the "MC truth" banks are only used if diagnotics are requested.
Input banks: FRPE, FRRE.
"MC truth" banks: STR, SVX, FS, FRPX, FRRX, FRPF, FRRF
Calibration banks: FGAP, FGAR, [.....]
Steering banks: FFTS, FFTP, FFTM, [....]
Internal banks: FPLC, FRLC, FPHC, FRHC, FPG1, FRG1,
FTUR, FPUR, FPUX, FRUX, FTKX.
Output banks: FTKR, FTPR, FTPX, FTRX.
10. References.
===============
[1] S. Burke, The Kalman Filter Code in FTREC, H1 Software Note ???.
[2] S. Burke and J.V. Morris, Track Fitting Using a Kalman Filter in the H1
Forward Tracker, H1 Note ???.
Appendix: Bank Descriptions.
============================
The following sections give the DDL definitions for the various banks used
in FTREC. [Do we need this? How many of these are defined in the DDL?]
Input Banks.
------------
! BANKname BANKtype !Comments
!
TABLE FRPE B16 ! Forward_Response_Planar_Event bank
! (digitisations)
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 CELLNUM I 0 1151 ! Cell Number
2 DRIFT I ! Drift time/length (.04 ns/ 10 micron)
3 QPLUS I ! charge at + wire end (eV)
! integral (dE/dx)*dx over path in cell
4 --- I ! set to zero
5 IFLAG1 I ! FADC pulse information (MC = 0)
6 IFLAG2 I ! FADC pulse information
END TABLE
!
! NOTES:
! In Monte Carlo, units are such that the contents are
! numerically equal to the drift DISTANCE in 10 microns
!
! IFLAG1 Currently set to zero in simulated data
! IFLAG2 BITS 0-3 Separation in FADC bins from
! preceding dig on wire (SEPL)
! BITS 4-7 Separation in FADC bins from
! next dig on wire (SEPR)
! BITS 8-11 Distance between first and last
! components (FADC bins)
! BITS 12-15 Number of hits in the digitisation
!
! In all cases numbers are positive and
! MIN(15,number)
! First digitisation has SEPL set to 15
! Last digitisation has SEPR set to 15
-------------------------------------------------------------------------------
! BANKname BANKtype !Comments
!
TABLE FRRE B16 ! Forward_Response_Radial_Event bank
! (digitisations)
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 CELLNUM I 0 863 ! Cell Number
2 DRIFT I 0 +INF ! Drift time/length (.04 ns / 10 micron)
3 QPLUS I 0 +INF ! charge at + wire end (eV)
4 QMINUS I 0 +INF ! charge at - wire end (eV)
! Q+ + Q- = integral (dE/dx)*dx
! over path in cell
5 IFLAG1 I ! FADC pulse information (MC = 0)
6 IFLAG2 I ! FADC pulse information
END TABLE
!
! NOTES: In Monte Carlo, units are such that the contents are
! numerically equal to the drift DISTANCE in 10 micron
!
! IFLAG1 Currently set to zero in simulated data
! IFLAG2 BITS 0-3 Separation in FADC bins from
! preceding dig on wire (SEPL)
! BITS 4-7 Separation in FADC bins from
! next dig on wire (SEPR)
! BITS 8-11 Distance between first and last
! components (FADC bins)
! BITS 12-15 Number of hits in the digitisation
!
! In all cases numbers are positive and
! MIN(15,number)
! First digitisation has SEPL set to 15
! Last digitisation has SEPR set to 15
Output banks.
-------------
! BANKname BANKtype !Comments
!
TABLE FTKR ! Forward Tracker Kombined Recon.
!
! S. Burke 22/5/91
!
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
! parameters at start point
!
1 KAPPA F -INF +INF ! signed inverse radius
2 PHI F -PI +PI ! track angle in xy-plane
3 THETA F 0. +PI ! polar angle
4 X F -999. +999. ! X
5 Y F -999. +999. ! Y
6 Z F -999. +999. ! Z at which parameters given
! (NOT a parameter)
7 IPTYP I 1 2 ! type of parametrization (=2)
8 DKAPPA F 0. +INF !
9 DPHI F 0. TWOPI !
10 DTHETA F 0. +PI ! errors
11 DX F 0. +999. !
12 DY F 0. +999. !
13 C1 F -INF +INF !
14 C2 F -INF +INF ! packed covariance (with COVCP)
15 C3 F -INF +INF !
16 C4 F -INF +INF !
17 NDF I 0 +108 ! # degrees of freedom (NOT # of hits)
18 CHSQ F 0. +INF ! chisquare
19 NX I -1 +INF ! pointer to parameterisation at end
20 NHIT I 0 +INF ! packed nr of hits:
! 65536*NPLAN + 16777216*NRAD
!
! NB These tracks always come in pairs, with start and end parameters
! successive. Thus word 19 is alternately (row # + 1) and (-1).
! The parameters are given at the z coordinate of the first and last
! measured points.
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
21 FTPR D1T1 ! pointer to pointering bank
END TABLE
-------------------------------------------------------------------------------
!
! BANKname BANKtype ! Comments
!
TABLE FTPR B16 ! Forward Tracker Pointer bank with
! pointers from FTKR to FTiX banks
! ATTributes:
! -----------
1 NHITFR I 0 +INF ! Nr of hits in forward radials
3 NHITFP I 0 +INF ! Nr of hits in forward planars
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
2 FTRX D1TM 1 ! Pointer to first hit of FTKR track in FTRX bank
4 FTPX D1TM 1 ! Pointer to first hit of FTKR track in FTPX bank
END TABLE
-------------------------------------------------------------------------------
!
! BANKname BANKtype ! Comments
!
TABLE FTPX B16 ! Forward Planars Circular Pointers
!
! ATTributes:
! -----------
1 FTPX I 0 +INF ! pointer to next hit of same track
2 DTFLAG I 0 1 ! bit 0 = 0: positive driftlength
! bit 0 = 1: negative driftlength
!
! Note that only bit 0 is defined currently, but more information
! may be added in future.
!
! RELations:
! ----------
!COL REL.name TYPE INT.bank ! Comments
! (COL)
0 FRPE D1T1 ! Pointers parallel to digis
!
END TABLE
-------------------------------------------------------------------------------
!
! BANKname BANKtype ! Comments
!
TABLE FTRX B16 ! Forward Radials Circular Pointers
!
! ATTributes:
! -----------
1 FTRX I 0 +INF ! pointer to next hit of same track
2 DTFLAG I 0 1 ! bit 0 = 0: positive driftlength
! bit 0 = 1: negative driftlength
!
! Note that only bit 0 is defined currently, but more information
! may be added in future.
!
! RELations:
! ----------
!COL REL.name TYPE INT.bank ! Comments
! (COL)
0 FRRE D1T1 ! Pointers parallel to digis
!
END TABLE
Calibration Banks.
------------------
Internal Banks.
---------------
! BANKname BANKtype !Comments
!
TABLE FTUR ! Forward Track Unconstrained
! reconstruction
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 X F ! x of point on track
2 Y F ! y of point on track
3 Z F ! z of point on track
4 VX F -1.0 1.0 ! )
5 VY F -1.0 1.0 ! ) drcn cosines
6 VZ F -1.0 1.0 ! )
7 CU F -INF +INF ! 1/radius (signed)
8 PINV F -INF +INF ! 1/momentum (1/GeV)
9 CHISQ F ! chi**2
10 NDF I ! Num degrees of freedom
11 COV1 F ! Cov Mat ( x, x)
12 COV2 F ! Cov Mat ( y, x)
13 COV3 F ! Cov Mat ( y, y)
14 COV4 F ! Cov Mat ( Vx, x)
15 COV5 F ! Cov Mat ( Vx, y)
16 COV6 F ! Cov Mat ( Vx, Vx)
17 COV7 F ! Cov Mat ( Vy, x)
18 COV8 F ! Cov Mat ( Vy, y)
19 COV9 F ! Cov Mat ( Vy, Vx)
20 COV10 F ! Cov Mat ( Vy, Vy)
21 COV11 F ! Cov Mat ( C, x)
22 COV12 F ! Cov Mat ( C, y)
23 COV13 F ! Cov Mat ( C, Vx)
24 COV14 F ! Cov Mat ( C, Vy)
25 COV15 F ! Cov Mat ( C, C)
26 NRP I ! Num Radial points on track
27 NPP I ! Num Planar points on track
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
28 FRUX D1TM 2 ! First radial digi on track
! FRUX parallel to FRRE
29 FPUX D1TM 2 ! First planar digi on track
! FPUX parallel to FRPE
END TABLE
-------------------------------------------------------------------------------
! BANKname BANKtype !Comments
!
TABLE FPUX B16 ! Forward Planar hits on Unconstrained
! tracks X-ref bank
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 DRFSGN I 0 1 ! Drift sign (1=+, 0=-)
2 INEXT I 0 1000 ! pointer to next hit in FRPE
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
0 FRPE D1T1 ! parallel bank
END TABLE
-------------------------------------------------------------------------------
! BANKname BANKtype !Comments
!
TABLE FRUX B16 ! Forward Radial hits on
! Unconstrained tracks X-ref bank
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 DRFSGN I 0 1 ! Drift sign (1=+, 0=-)
2 INEXT I 0 1000 ! pointer to next hit in FRRE
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
0 FRRE D1T1 ! parallel bank
END TABLE
The linking of tracks in the two inner trackers is performed by the KTREC
module. The input consists of the track banks CTKR and FTKR; the output is a
list of all tracks found (KTCF) and a set of track parameters for the linked
tracks (KTKR).
KTREC is organised into four sub-modules. The first two make lists of central
and forward tracks, with track parameters given at a common plane. The third
builds up a list of all associations between central and forward tracks within
a chi-squared cut, and the fourth resolves the ambiguities and creates the
output banks. The lists of track parameters and possible links are passed
between these in internal named banks.
There is no difference between the treatment of Monte Carlo and real data,
except that some diagnostics are only possible with Monte Carlo data (and the
FTAL calibration bank is in principle different for Monte Carlo and real data).
All routine and bank names start with KT (although some FTREC routines are
used).
The code is described in detail, followed by the memory requirements, time
consumption, event size and banks used.
1. Code Description.
====================
The track linking code is controlled by the KTREC routine. This deals with
initialisation and termination, and calls the KTXTRP routine to do the actual
linking. These stages are described in detail, after brief comments on
terminology and track parameters.
In the following, the term "association" is used to refer to the
(conceptually ambiguous) connections between tracks found by the KTASS routine,
and the term "link" is used to refer to tracks linked by the KTFIT routine and
added to the output banks. [According to the standard H1 terminology, a module
called KTREC should in fact only do the first of these, and the resolution of
the ambiguities should be done separately by a module called RTREC or similar.]
Various references are made to the two track parameterisations. These are:
IPTYPE 1 (central) IPTYPE 2 (forward)
Curvature 1/r 1/r
Azimuthal angle phi phi
Polar angle theta theta
Position 1 dca x
Position 2 z0 y
Location - z
These are different due to the different geometries of the two trackers; tracks
in an intermediate range of polar angles (between, say, 20 and 70 degrees) can
be represented in either form, but in general they are not interchangeable.
Note that the z coordinate in IPTYPE 2 is not a fit parameter (i.e. it has no
error); it just specifies where on the track the other parameters are given.
The equivalent parameter for IPTYPE 1 is implicit, as the parameters are always
given at the point of closest approach to the z axis.
1.1 Initialisation and Termination.
-----------------------------------
Initialisation is performed on the first call with BEGRUN true. Steering banks
KTRS and KTRP (see below) are read with a call to KTTEXT; if these are not
found an error message is generated, but sensible defaults are taken and
execution continues. KTTEXT also prints a summary of the most important
steering parameters. Histograms are booked as necessary, in KTBKLK for
monitoring histograms and KTHBK for diagnostic histograms. Bank formats are
defined, work bank indices are zeroed and counters for various conditions are
also zeroed.
On ENDRUN KTREC prints a brief summary giving the numbers of central, forward
and linked tracks (these are just the total number of non-zero entries in the
three columns of the KTCF bank). If true track information is requested (using
the IDIAG steering parameter) a set of linking performance statistics is also
printed.
On ENDJOB the monitoring histograms are printed, followed by diagnostic
histograms if requested. The diagnostic histograms may also be written to an
(RZ) file.
1.2 Event Processing.
---------------------
On REVENT KTREC first checks that both the CTKR and FTKR banks exist, and
generates an error message if not, as both CTREC and FTREC must have been run
first (see section 12 below). No further processing is done if either of these
banks is missing.
Otherwise, KTREC calls KTXTRP, provided that both forward and central tracks
exist in the event. This is a general steering routine to find associations,
link tracks and output the result. It first calls KTXTRC and KTXTRF to
extrapolate central and forward tracks to a common plane, then KTASS to look
for associations between them, and finally KTFIT to choose which links to take,
form the combined tracks and output them. More details of these stages are
given below.
A final call to KTOUT is made from KTREC after all tracks have been linked,
to add all remaining unlinked central and forward tracks to the KTCF bank.
This creates the final output banks from work banks, and also creates a dummy
KTKR bank if no tracks were linked.
Note that the ordering of tracks within the KTCF bank is linked tracks,
then unlinked forward tracks, then unlinked central tracks. Unlinked tracks are
in the same order as in the original (FTKR and CTKR) banks; i.e., the track
numbers are monotonically increasing. Linked tracks are in the same order in
the KTCF and KTKR banks (i.e., the KTKR pointer in KTCF is monotonically
increasing), but there is no definite relationship with the order of the
original tracks. The ordering described here is guaranteed for future releases
of the code, and may be relied on. Note also that some CTKR tracks, and all
FTKR tracks, have two parameterisations; the KTCF pointer is always to the
parameters closest to the vertex. The KTKR format also allows for more than one
parameterisation per track; this freedom is not currently used, but this may
change in future.
1.3 Track Extrapolation.
------------------------
Central and forward tracks are extrapolated to a common plane (specified by the
ZWALL1 steering parameter), in a common parameterisation (that of the FTKR
track banks, i.e. IPTYPE 2). The z coordinate is chosen to be just inside the
end wall of the CJC.
Central tracks are treated by the KTXTRC routine. They are only extrapolated
if they are pointing in the right direction (theta < 0.8 radians). An option is
also given (using the steering parameter NCMIN1) to reject any track with a
small number of hits. If a track has two parameterisations the second one is
used. The extrapolation and parameter transformation (from IPTYPE 1 to IPTYPE
2) are performed simultaneously by the KTFTCT routine; note that it is only
possible to transform between these two parameterisations for an intermediate
range of theta. Provided that the track extrapolates to within 140 cm of the z
axis, the track parameters are then filled (in double precision) into rows of
the KTCT bank. The CTKR track number and the packed number of hits (NHIT) are
also stored.
All forward tracks are extrapolated to the same z coordinate (using the
parameterisation nearest the vertex). The parameters are first transformed with
the KTROT routine; this allows for a misalignment between the forward and
central trackers, using calibration constants from the FTAL bank. For Monte
Carlo data this just gives a null transformation. The track parameters are then
converted into the internal parameterisation of the Kalman filter code, to
allow the use of its routines to extrapolate the track.
Multiple scattering is allowed for by increasing the extrapolated covariance
matrix, assuming material with radiation length RADLEN between planes at
z=ZWALL1 and ZWALL2 (all defined in the KTRP steering bank). This is somewhat
unsatisfactory for real data, as the actual material distribution in this
region is highly non-uniform due to cables, preamplifier cards etc. However,
the true material distribution is not know; also, to be useful, the transverse
(xy) position of the track would have to be known to an accuracy smaller than
the scale of variations in the material distribution. Finally, although the
multiple scattering "errors" are of the same order as the errors on the forward
track parameters, they are typically at least an order of magnitude smaller
than the errors on the central track parameters, and so do not strongly
influence the final chi-squared.
The tracks are then transformed back into the standard (IPTYPE 2)
parameterisation, and filled (in double precision) into rows of the KTFT bank.
Since all tracks are extrapolated the track number is implicit (KTFT is
parallel to FTPR). Two extra words are left (set to zero) to provide a pointer
to the KTKA bank (see below). This violates modularity slightly, but saves the
overhead of creating another bank parallel to KTFT.
1.4 Track Association.
----------------------
The KTASS routine is the heart of the linking procedure; it is responsible for
constructing a list of (possibly ambiguous) associations between forward and
central tracks. This is done by looping over all extrapolated central tracks,
and for each of these calculating a chi-squared with each forward track, using
the track parameters stored in the KTFT and KTCT banks.
The chi-squared is calculated by the KTCHI function. This provides four
different functions, according to the value of IFLAG passed to it. Possible
values are:
IFLAG = 0 Transverse separation squared (dx**2 + dy**2).
IFLAG = 1 "Diagonal" chi-squared on 1/r, x and y.
IFLAG = 2 "Diagonal" chi-squared on all parameters.
IFLAG = 3 Full chi-squared.
If the transverse separation is greater than the RMAX steering parameter a
value of 10**10 is returned, so the association will always be rejected. If the
sum of the two covariance matrices is not positive definite the IFLAG=2 value
is returned. A "diagonal" chi-squared is calculated using only diagonal errors,
ignoring correlations. The simpler versions are provided to reduce cpu time if
there is a large number of tracks, but in practice the time consumption in
KTREC is small compared with other H1REC modules, so for normal use the full
chi-squared is used. There are two steering parameters to control the function
used. ICHI1 specifies which value of IFLAG is used for the initial matching. If
ICHI2 differs from ICHI1 the chi-squared is re-calculated with IFLAG=ICHI2
before being stored in the KTKA bank (see below).
Which associations are accepted is controlled by the CHIFC1 and CHIFC2
parameters. Any association with chi-squared less than CHIFC1 is kept; if
there are no such associations for a given central track then the one with the
minimum chi-squared is taken, provided that this is less than CHIFC2. The
reason for this is to attempt to minimise the number of central tracks
associated with more than one forward track. If an association is accepted, the
chi-squared and a pointer to the relevant forward track are stored in a work
bank, with a second work bank holding the number of associations for each
central track (the relationship between the two being implicit).
If some associations are found, these relations are inverted to produce
the KTKA bank, which contains the chi-squared and a pointer to the central
(KTCT) track for each association; all associations for a given forward track
are consecutive. The two extra words in the KTFT bank mentioned above are
filled with the number of associations and a pointer to the first. The final
structure is thus:
D1T1 D1TM DMT1 D1T1
FTPR ----> KTFT ----> KTKA ----> KTCT ----> CTKR
The KTFT, KTKA and KTCT banks are described in detail at the end of this
document. They are not present in the DDL as their format is non-standard. (In
fact, KTKA is similar to the intermediate bank in a D1IM relationship between
KTFT and KTCT, except that the DDL does not allow parameters to be stored in
the intermediate bank. There is no "internal next" pointer in KTKA, so the
KTFT-KTKA relationship is not really D1TM as far as the DDL is concerned.)
1.5 Track Linking.
------------------
Ambiguities are resolved and links chosen by the KTFIT routine. In essence this
is done by looping over all forward tracks, and choosing the association with
the minimum chi-squared. After each link is made any other associations with
the same central track are deleted, so that the final list of links is
unambiguous.
However, this strategy is modified in two ways. Firstly, all forward tracks
with only one associated central track are linked first. Secondly, where there
are multiple associations, central tracks with a value of NHIT .GE. NCMIN2 are
preferred even if they have a larger chi-squared than an association with a
track with fewer hits. The default value for this parameter is 256, which means
that central tracks with z-chamber hits are preferred to those with only CJC
hits. This is because a track found only in the CJC has very poor z resolution;
consequently the errors on some parameters are large, which tends to make the
chi-squared small.
This algorithm can still result in the links which are made being dependent
on the order of the tracks in the bank, and does not necessarily find the
optimum solution. However, a full search to find the global optimum would
be very complex, and is probably not justified given the large errors on the
parameters of most central tracks. It is possible that in future the algorithm
will be changed to make the links in order of increasing chi-squared, but again
this may just mean that the central tracks with the largest errors are linked
first.
The links themselves are made by the KTLINK routine. This calls KTWM to take
the weighted mean of the two sets of track parameters (equivalent to a linear
least squares fit). Note that this can fail if the covariance matrices are
badly behaved (specifically, if the sum of the forward and central track
covariance matrices is not positive definite). In this case KTLINK returns with
an error, and the association is ignored. Otherwise, KTOUT is called to add the
track data to the output banks, after transforming the track parameters into
the central tracker (IPTYPE 1) format. Some monitoring histograms are also
filled in KTOUT, while others, together with some diagnostic histograms (if
requested), are filled in the KTDIFF routine (called from KTLINK).
2. Error Handling.
==================
Errors are reported in the standard way, using ERRLOG. The error message always
includes the name of the routine in which the error occurred. It is also
possible to get Kalman filter error messages, as some of its routines are also
used in KTREC. The error messages are generally self-explanatory. The only
messages which occur in normal use are "weighted mean failed" and
"tan(theta)>1", and these can be ignored provided that they do not occur too
often. Other messages indicate serious problems, either with the code or the
data, and if they occur with any frequency they should be reported to the
librarian.
3. Monitoring Histograms.
=========================
Some standard LOOK histograms are generated to give an idea of the quality of
the track linking. The general appearance of the histograms should be as
follows (in a fairly ideal world). Note that there will be some variation
depending on the event type, and there may also be a dependence on steering
parameters (e.g. the chi-squared/DOF distribution will depend on the
chi-squared cuts used).
Linked tracks/event: Narrow distribution, peaked at 0 or 1
Delta (1/p): Symmetrical about zero, width about 0.2 GeV**-1
Delta phi: Symmetrical about zero, width about 0.05
Delta theta: Symmetrical about zero, width about 0.05
Delta x: Symmetrical about zero, width about 1 cm
Delta y: Symmetrical about zero, width about 1 cm
LOG(FT error/CT error): Peaked about -1, width about 1
Chi-squared/DOF: Peaked at 1, some tail
Chi-squared probability: Flat (ish)
Phi: Flat
Theta: Peaked about 0.3, width about 0.05
Q/Momentum: Fairly flat; symmetrical about zero.
LOG(Momentum): Broad distribution, peaked between 0 and 1
Fractional error on 1/r: Fairly narrow, peaked below 0.1, some tail
Error on theta: Broad distribution, peaked at a few milliradians
Error on xy: Broad distribution, peaked at about 0.1 cm
4. Diagnostics.
===============
Diagnostics are mainly provided in the form of HBOOK histograms, controlled by
the IDIAG flag described below. Note that the default size of the /PAWC/ common
defined in the main program must be increased if these are to be used. All
HBOOK histograms are booked in subdirectories of //PAWC with names beginning
with "K", so the histogram numbers should not clash with others used elsewhere.
The current directory is reset to //PAWC at the end of the module. Some HBOOK
calls are made even if IDIAG is zero, although no histograms are filled, so
/PAWC/ must always exist and HLIMIT be called. HBOOK histograms can be written
to the stream specified by the LUNHB steering parameter, if non-zero; this is
done on ENDJOB.
Diagnostic code is concentrated into special subroutines, in patch
KT_KTDEBUG, where possible. However, there are calls to HBOOK routines and to
these internal diagnostic routines scattered throughout the code; unfortunately
it is not easy to segregate this code completely, as the diagnostics must be
produced at the time that the information is available.
Most of the diagnostics rely on having information about the true tracks, so
they are only useful for Monte Carlo data. Also, the default setting in H1SIM
is to have all secondary tracks given the same track number as their parent,
which makes the diagnostics somewhat unreliable. To use them properly requires
a dataset simulated with the secondary momentum cut (SKECUT) set to zero for
the central and forward trackers. This results in larger output, but allows
tracks to be identified unambiguously. It is also useful to produce
forward-tracker starting track (FS) banks, which are also not made by default.
Finally, the STR, SVX, FRPX and FRRX banks must not have been removed.
Requesting "true tracks found" with IDIAG (see below) results in the use of
the UTSTR routine to determine a true track (STR) number for each extrapolated
central and forward track. These are found in the KTXTRC and KTXTRF routines,
and stored in one-column banks KTCX and KTFX, parallel to KTCT and KTFT. This
makes it very easy to determine whether associations and links are correct.
In addition to the histograms, linking efficiency statistics can also be
produced; these are printed by KTREC on ENDRUN. These come in four groups;
the first relating to tracks extrapolated by KTXTRC and KTXTRF, the second
to associations found by KTASS, the third to links made by KTFIT and the fourth
to the angular range of primary central and forward tracks. Note that it is
possible to determine whether a central track enters the forward tracker by
looking for its true track number in the FS bank.
Central tracks: The total* number of CTKR tracks.
Central tracks extrapolated: The number of tracks in KTCT banks.
Central tracks entering FT: The number of KTCT tracks in the FS bank.
Forward tracks: The number of tracks in KTFT banks.
True links: The number of "true" KTFT-KTCT links.
True links (with CIZ): True links with CIZ hits on the central track.
* This counts the total number of rows in CTKR banks in events with both
central and forward tracks, so in general it will be different from the number
of central tracks derived from the KTCF banks.
Single associations: FT tracks with 1 associated CT track.
Correct single associations: The number of the above which are correct.
Multiple associations: FT tracks with >1 associated CT track.
Correct multiple associations: The number of the above which are correct.
Links found (single): FT links with 1 CT association.
Correct links (single): The number of the above which are correct.
Links found (multiple): FT links with >1 CT association.
Correct links (multiple): The number of the above which are correct.
Links found (with CIZ): FT links with CIZ hits on the CT track.
Correct links (with CIZ): The number of the above which are correct.
Minimum theta (CJC only): The minimum angle of primary CT tracks.
Minimum theta (CJC + CIZ): As above, with CIZ hits.
Maximum theta (CT tracks): The maximum angle for CT tracks in the FS bank.
Maximum theta (FT tracks): The maximum angle for primary FT tracks.
5. Steering Banks.
==================
The operation of KTREC is controlled by the steering banks KTRS and KTRP.
The function of the various parameters is as follows.
The first item in each steering bank is a "version number", based on the date
when the format of the bank (i.e. the number, order or meaning of the other
items) was last modified. KTTEXT checks that the bank it gets contains the
right version number, to avoid problems with old versions of steering banks
being retrieved from the database by mistake. If the wrong version number is
found an error message is generated, the internal defaults are taken and
execution continues.
KTRS: Main steering flags.
LUN The unit to which all printout is directed.
IDIAG Diagnostic flag; should normally be left at zero. Diagnostics include
various (HBOOK) histograms and statistics on linking efficiency. Most
diagnostics only work for Monte Carlo data, and need a dataset
simulated with SKECUT=0. Note that the default size of the /PAWC/
common will probably need to be increased in the main routine if these
histograms are used. In more detail, IDIAG is interpreted as a
five-digit decimal number, where each digit can be 0 or 1, with each 1
turning on a particular feature. From right to left, the digits
control:
True tracks found, linking efficiency statistics printed
Linking efficiency histograms
Extrapolation/association histograms (for chi-squared tuning)
Resolution and true chi-squared histograms
Forward/central alignment histograms
PMCUT Alignment histograms (selected with IDIAG) are only filled if the
momentum is .GT. PMCUT.
ICHI1 The "chi-squared" function used for the initial track matching:
0 = Square of transverse separation (dx**2 + dy**2)
1 = "Diagonal" chi-squared on 1/r, x and y
2 = "Diagonal" chi-squared on all parameters
3 = Full chi-squared
ICHI2 As for ICHI1, but used to choose the best of a set of ambiguous
associations.
LUNHB If this is non-zero it defines a stream to which any HBOOK plots
will be written (as an RZ file).
KTRP: Steering parameters.
CHIFC1 Maximum chi-squared for multiple CT->FT associations.
CHIFC2 Maximum chi-squared for single CT->FT associations.
RMAX Maximum transverse separation between associated tracks.
ZWALL1 z coordinate of the start of the CJC end wall.
ZWALL2 z coordinate of the end of the CJC end wall.
RADLEN Average radiation length of the material in the end wall.
NCMIN1 Minimum value of NHIT for a CT track to be linked.
NCMIN2 Preferred value of NHIT for multiple FT->CT associations.
6. Common blocks.
=================
The KTREC common blocks are as follows (note that no use is made of /H1WORK/):
/KTSTEE/ PMCUT * Momentum cut for alignment histograms
IDIAG * Diagnostic steering flag
LUN * Output stream for messages
ICHI1 * Initial "chi-squared" function
ICHI2 * Final "chi-squared" function
LUNHB * HBOOK output stream
LALIGN Logical flag for alignment histograms
LRESID Logical flag for residual histograms
LASSOC Logical flag for association histograms
LEFFIC Logical flag for efficiency histograms
LTRUTH Logical flag for true track information
/KTPAR/ ZWALL1 * z coordinate of the CJC side of the end wall
ZWALL2 * z coordinate of the FTD side of the end wall
RADLEN * Radiation length (cm) of the material in the end wall
CHIFC1 * Maximum chi-squared for single associations
CHIFC2 * Maximum chi-squared for multiple associations
RMAX2 Maximum transverse separation squared of tracks (cm**2)
NCMIN1 * Minimum value of NHIT for a CTKR track
NCMIN2 * Preferred value of NHIT for a CTKR track
/KTSCAL/ NCT Number of central tracks
NCTE Number of extrapolated central tracks
NCTF Number of central tracks entering the forward tracker
NFT Number of forward tracks
NNLINK Number of true links
NZLINK Number of true links with CIZ hits
NSIN Number of single associations found
NINSIN Number of correct single associations
NAMB Number of multiple associations
NINAMB Number of correct multiple associations
NFSIN Number of single links
NCSIN Number of correct single links
NFAMB Number of multiple links
NCAMB Number of correct multiple links
NFZ Number of links with CIZ hits
NCZ Number of correct links with CIZ hits
THMIN Minimum polar angle of primary CT tracks
THZMIN Minimum polar angle of primary CT tracks with CIZ hits
THCMAX Maximum polar angle of primary CT tracks entering the FT
THFMAX Maximum polar angle of primary FT tracks
/KTWBI/ INDCI Index of a temporary work bank
INDCA Index of a temporary work bank
INDRJX Index of the unpacked CRJX bank
INDCTP Index of the unpacked CTPR bank
INDTJX Index of the unpacked CTJX bank
In /KTSTEE/ and /KTPAR/, items marked * are taken directly from steering banks;
the others are derived from the steering parameters in KTTEXT. /KTSCAL/
contains counters for various conditions, as printed by KTREC at ENDRUN.
/KTWBI/ contains various work bank indices.
7. Space Usage.
===============
The total size of H1REC (3.01/06, as measured on a VAX) is about 10 Mb (where
1 Mb = 10**6 bytes). Of this, code only accounts for about 1.4 Mb, of which
about 20 kb is KTREC. Local variables and common blocks total about 4.2 Mb, of
which 14 kb is in KTREC. The remainder of the space is accounted for by the
three large common blocks /BCS/, /COMIC/ and /H1WORK/. KTREC makes no use of
the latter. Thus KTREC accounts for about 0.3% of the total size of the program
(34 kb).
8. Time Consumption.
====================
The total time per event on the DESY IBM is about 1.5 s, of which 8 ms is
consumed by KTREC (for an average of 0.5 linked tracks, 10 central tracks and 5
forward tracks per event). These figures are based on "typical" (LUND NC)
events.
The breakdown of the time within KTREC has been estimated using the PCA
utility on a VAX; the results are not necessarily exactly transferable to other
machines. About 61% of the time is spent in the call to MDB in KTROT (once per
forward track), getting access to the FTAL bank. Apart from this, about 16% of
the time is spent in extrapolating forward tracks, 7% in extrapolating central
tracks, 5% in constructing the list of associations and 5% in making the links.
The remaining time is spent in filling the unlinked tracks into the KTCF bank,
creating the final output banks, filling monitoring histograms and various
overheads. The time consumed is therefore approximately proportional to the
number of forward tracks; if MDB were faster or the call avoided the time would
be closer to being proportional to the sum of the numbers of forward and
central tracks.
A component of the time spent in KTASS is proportional to the product of
the number of forward tracks and the number of extrapolated central tracks.
However, if the RMAX steering parameter is used (the default is 3 cm) then any
pairs of tracks further apart than this are immediately rejected as candidates
for linking. Since the dominant time consumption here is in the calculation of
the chi-squared, this will only become significant if there is a large number
of tracks within RMAX of one another. In any case, it is evident that the time
consumption is not very significant; for comparison, BFSEQR takes about 20 ms
to read an event.
9. Output Size.
===============
The KTKR bank has 20 words per linked track (assuming that the track parameters
are only given at the vertex) and KTCF has 3 words plus 3 words per track, so
for a "typical" event with 1 linked track, 5 forward tracks and 10 central
tracks this amounts to less than 0.3 kb/event.
10. Bank Existence.
===================
As a general policy, it is assumed that banks should exist even if they have no
entries; this makes it possible to tell unambiguously whether a module has been
run. Thus the input banks (CTKR and FTKR) are required to exist, and an error
is generated if they do not. Likewise the KTKR bank is created (with length 2
and word 2 set to zero) if no links are found. KTCF always has at least one
row, as the first row is filled with three zeroes to cater for unlinked muons.
However, if a serious "external" error occurs (e.g. input banks not existing,
or running out of space in /BCS/) these banks are NOT created, as KTREC has not
successfully run in this case.
11. Banks Used.
===============
See the H1BANKS CMZ file for full descriptions of these banks. Banks marked *
are only used if diagnostics are requested.
Input banks: CTKR, CTPR*, CTJX*, CTYX*, CTZX*,
FTKR, FTPR*, FTPX*, FTRX*
"MC truth" banks: STR*, SVX*, FS*, FRPX*, FRRX*, CRJX*, CRYX*, CRZX*
Calibration banks: FTAL
Steering banks: KTRS, KTRP
Internal banks: KTFT, KTCT, KTKA, KTFX*, KTCX*
Output banks: KTCF, KTKR
12. Internal Bank Formats.
==========================
These banks are not described in the official DDL, as their format is
non-standard. Note that the track parameters and covariance matrices are in
double precision; also that only the covariance matrix elements above the
leading diagonal are used, but the full 5*5 matrix is stored for convenience.
! BANKname BANKtype !Comments
!
TABLE KTFT ! Kombined Track Forward Track
! parameters (at the end wall)
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 KAPPA1 I ! 1/r (NB: all of these are really
2 KAPPA2 I ! double precision floating)
3 PHI1 I ! phi
4 PHI2 I !
5 THETA1 I ! theta
6 THETA2 I !
7 X1 I ! x
8 X2 I !
9 Y1 I ! y
10 Y2 I !
11 C111 I ! (1/r,1/r) covariance
12 C112 I !
13 C211 I ! (phi,1/r) covariance
14 C212 I !
15 C311 I ! (theta,1/r) covariance
16 C312 I !
17 C411 I ! (x,1/r) covariance
18 C412 I !
19 C511 I ! (y,1/r) covariance
20 C512 I !
21 C121 I ! garbage
22 C122 I !
23 C221 I ! (phi,phi) covariance
24 C222 I !
25 C321 I ! (theta,phi) covariance
26 C322 I !
27 C421 I ! (x,phi) covariance
28 C422 I !
29 C521 I ! (y,phi) covariance
30 C522 I !
31 C131 I ! garbage
32 C132 I !
33 C231 I ! garbage
34 C232 I !
35 C331 I ! (theta,theta) covariance
36 C332 I !
37 C431 I ! (x,theta) covariance
38 C432 I !
39 C531 I ! (y,theta) covariance
40 C532 I !
41 C141 I ! garbage
42 C142 I !
43 C241 I ! garbage
44 C242 I !
45 C341 I ! garbage
46 C342 I !
47 C441 I ! (x,x) covariance
48 C442 I !
49 C541 I ! (y,x) covariance
50 C542 I !
51 C151 I ! garbage
52 C152 I !
53 C251 I ! garbage
54 C252 I !
55 C351 I ! garbage
56 C352 I !
57 C451 I ! garbage
58 C452 I !
59 C551 I ! (y,y) covariance
60 C552 I !
61 NFCA I ! # CT associations
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
62 KTKA D1T1 ! CT associations
!
! This bank is parallel to FTPR and semi-parallel to FTKR; a track
! at JTR in KTFT is at 2*JTR-1 and 2*JTR in FTKR.
!
! The relationship between KTFT and KTKA is really D1TM, except that instead
! of having an internal next pointer the associations are stored successively
! and the number is stored in word 61. This is like D1IM, except that you
! can't have attributes in the intermediate bank.
!
END TABLE
! BANKname BANKtype !Comments
!
TABLE KTFX ! Kombined Track Forward X-reference
!
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
0 KTFT D1T1 ! FT track parameters at end wall
1 STR D1T1 ! True track information
! Pointer can be zero or -ve in case of error
!
END TABLE
! BANKname BANKtype !Comments
!
TABLE KTCT ! Kombined Track Central Track
! parameters (at the end wall)
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 KAPPA1 I ! 1/r (NB: all of these are really
2 KAPPA2 I ! double precision floating)
3 PHI1 I ! phi
4 PHI2 I !
5 THETA1 I ! theta
6 THETA2 I !
7 X1 I ! x
8 X2 I !
9 Y1 I ! y
10 Y2 I !
11 C111 I ! (1/r,1/r) covariance
12 C112 I !
13 C211 I ! (phi,1/r) covariance
14 C212 I !
15 C311 I ! (theta,1/r) covariance
16 C312 I !
17 C411 I ! (x,1/r) covariance
18 C412 I !
19 C511 I ! (y,1/r) covariance
20 C512 I !
21 C121 I ! garbage
22 C122 I !
23 C221 I ! (phi,phi) covariance
24 C222 I !
25 C321 I ! (theta,phi) covariance
26 C322 I !
27 C421 I ! (x,phi) covariance
28 C422 I !
29 C521 I ! (y,phi) covariance
30 C522 I !
31 C131 I ! garbage
32 C132 I !
33 C231 I ! garbage
34 C232 I !
35 C331 I ! (theta,theta) covariance
36 C332 I !
37 C431 I ! (x,theta) covariance
38 C432 I !
39 C531 I ! (y,theta) covariance
40 C532 I !
41 C141 I ! garbage
42 C142 I !
43 C241 I ! garbage
44 C242 I !
45 C341 I ! garbage
46 C342 I !
47 C441 I ! (x,x) covariance
48 C442 I !
49 C541 I ! (y,x) covariance
50 C542 I !
51 C151 I ! garbage
52 C152 I !
53 C251 I ! garbage
54 C252 I !
55 C351 I ! garbage
56 C352 I !
57 C451 I ! garbage
58 C452 I !
59 C551 I ! (y,y) covariance
60 C552 I !
62 NHIT I ! packed # of CT hits
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
61 CTKR D1T1 ! CT patrec bank
END TABLE
! BANKname BANKtype !Comments
!
TABLE KTCX ! Kombined Track Central X-reference
!
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
0 KTCT D1T1 ! CT track parameters at end wall
1 STR D1T1 ! True track information
! Pointer can be zero or -ve in case of error
!
END TABLE
! BANKname BANKtype !Comments
!
TABLE KTKA ! Kombined Track Kombined Associations
!
! ATTributes:
! -----------
!COL ATT-name FMT Min Max !Comments
!
1 CHI2 F 0.0 INF ! "Chi 2" of association (as
! defined by KTCHI function)
!
! RELations:
! ----------
!COL REL.bank TYPE INT.bank !Comments
! (COL)
1 KTCT DMT1 ! CT track parameters at end wall
! Pointer can be zero
!
! Note that there is no "internal next"; the associations for one
! forward track are successive, and the number is stored in KTFT.
!
END TABLE
JVM 24/9/98