D0 global tracking user's guide: Analyzing and debugging

D. Adams
26sep01 1700

Printing chunk contents

The contents of the global and Monte Carlo track chunks (and any other chunk) may be printed using the package DumpPkg in io_packages.

The utility d0ev may be used to examine the raw data for any chunk but is of limited use for GTrack chunks because the data is not stored in the form of GTrack's.

Global track ntuple

The global track ntuple (built by GtrTuplePkg as described above) may be used to assess and study the track-finding performance for a run. Reconstructed and Monte Carlo tracks are propagated to a common surface where they are matched. Each entry includes the parameters of a matched reconstructed and Monte Carlo track pair or one of the two if unmatched.

The contents of tuple depend on the type of the final surface (specified via RCP parameters) and are described in the package which provides the code to fill the ntuple. These packages also provide PAW macros to aid in the analysis of the ntuple.

The ntuple for the DCA (distance of closest approach) is defined in trfdca.

The ntuple for a cylinder is defined in trfcyl.

Reco analyze ntuple

Similar branches can be added to the reco analyze ntuple using the package gtr_analyze. Package gtr_tree provides classes for reading these brances and for converting them into the format of the standard tuple described above.

PAW

PAW macros for analyzing the standard ntuple (tracks propagated to the DCA) may be found in the package gtr_lyze. These may be installed in directory dir with the command

> gtr_get_kumacs dir

The default for dir is the current directory.

This is now deprecated in favor of the root-based analysis described below.

ROOT

The hbook ntuple may be converted to a ROOT tree with the h2root command. The package gtr_root provides root scripts and executables for studying this tree.

GTrack-based analysis

The ntuples will not be sufficient for all analyses. For studies that require more, the complete track information may be obtained from the GTrack chunks. Package gtr_sys provides an example in its src directory.

PTrack ntuple

The PTrack ntuple is filled each time a track is extended to a surface and contains the track parameters and the number of attempts and successes to add new clusters or misses to this track. It is defined and described at trffind/doc/ptrack-tuple.html.

The PTrack tuple is enabled by setting a flag in the step RCP (bool ptrack_tuple = true).

Timing ntuple

A timer with data in an ntuple can be enabled at run time by assigning a name in the top-level tracking RCP (string package_timer = "mytimer") and then a name in the step RCP (timer_name = sname) for each step for which timing information is to be recorded. This timing information includes the following (where sname is the name assigned in the step RCP):

init - total intialization time
find - total TRF++ finding time
refit - total time spent refitting
write - total time spent writing our track chunks
sname - time spent on step sname

All these values are summed and stored separately for each event.

A step RCP flag (bool time_trf = true) can be used to pass the timer to the TRF++ track finder to record PTrack time information. See the description at trffind/doc/timing-tuple.html.

TRF++ times are only recorded for named paths. These names are assigned when the paths are defined in the OBS file (name="cftx1"). This field is optional.

Debugging output

An RCP parameter for GtrFindPkg can be used to enable debugging output. The output can be vary large but can provide clues about why tracks are not being found. It is most useful for single track events.

Advanced Debugging

There are sophisticated tools available for debugging gtr using Monte Carlo with cluster id. information. These include the "Monte Carlo Cluster Filter," which forces tracking to follow only valid tracks (or a particular track), and "reporters," which in most cases can quickly identify why a particular Monte Carlo track was not found. Instructions can be found here.

Profiling

Herb Greenlee has written some profiling instructions.

Using Monte Carlo information during reconstruction

Adding Monte Carlo information to trf clusters

MC information is not included in trf clusters by default, as adding this information exacts a significant time penalty. There are different methods for adding MC information to cft and smt clusters.

Adding MC information to CFT clusters:

Chunks SFTDigiChunk and SFTDigiMCChunk must be present.

Modify the cft detector filler rcp file, which is included from the top level GtrFindPkg rcp file. For example, GtrFindPkg_CT.rcp has the following inclusion:

RCP cft_detector = <cft_trf2D Cft_add2D_clusters_NC>

Modify the included rcp file to contain the following rcp parameter:

bool Write_McClusters = true

Adding MC information to SMT clusters:

If the input file contains chunk SmtDataChunk, but not chunk SMTMcIdDataChunk, add framework package <smt_hitmatch SMTRecoHitMcIdFiller> to your top level framework rcp file. This package should be added after smt clusters chunks are created and before gtr packages.

This package adds a new chunk to the event, SMTMcIdDataChunk, which can be saved. If you are processing data that already has SMTMcIdDataChunk's, then you can save some time by running package <smt_hitpackages SMTActivate3DClusters> instead. If the input file doesn't have SmtDataChunk, but it does have SMTMcIdDataChunk, then you must run package <smt_hitpackages SMTActivate3DClusters> to access cluster mcid information.

Using the Monte Carlo cluster filter

The Monte Carlo cluster filter selects clusters based on Monte Carlo hit information. It can be used to select hits from a particular Monte Carlo track, or all Monte Carlo tracks (while rejecting combinatoric fakes).

The class name of the Monte Carlo cluster filter is ClusterFilterMcId, which is released in library trffind.

To successfully use the Monte Carlo cluster filter, MC information must be added to the trf clusters, as described above.

Standard obs files should be modified as follows. Define the cluster filter in the init file for a particular tracking step (e.g. cft_CTaxial_init.obs, cft_CTstereo_init.obs, cft2D_init.obs). The obs syntax for this is as follows:

[ cfiltmc ClusterFilterMcId mcid=-1 enable=true ]

Setting parameter mcid to be a positive number to selects a particular MC track (for example, a track that is known to fail). Setting mcid=-1 selects all Monte Carlo tracks while rejecting combinatoric fakes (i.e. tracks are required to have hits with compatible, non-empty MC ids.). The enable parameter can be used to turn the MC filter function on or off. Note that if this cluster filter is used for more than one tracking step, then the object name (cfiltmc in the above example) should be unique for different tracking steps.

Then in the path definition obs files, install the defined cluster filter object as the first cluster filter for each path. For example:

[ xxxxxx Path ... cfilters=@( cfiltmc ... ) ... ]

The cluster filter should normally be installed on every path. If the cfilters parameter is missing, it should be added.

The complete set of obs files (init and path definition) for a particular tracking step are specified in the step rcp file, which is included in the top level GtrFindPkg rcp file.

dladams@fnal.gov, greenlee@fnal.gov