L1TNTuple Analysis utilities
============================

Update:  Su Dong  Dec/23/00   First version   

Note: This is not a complete description of all routines in L1TAnal,
      but only some of the basic utilities. 

Basic utilities
---------------
 gettkpar.for --- Copy reco track parameters 
 getl3trk.for --- Copy L3 track parameters 
 beaminit.f   --- Beam energy/IP position control package including:
                  beaminit -- initilize beam parameters  
                  setbeam  -- set beam energy with e+e- system 4 vector
                  pepbeam  -- set beam energy with HER,LER beams separately.
                  getbeam  -- get beam energy parameters 
                  setippos -- set IP position 
                  getippos -- get IP position                             
 vuboost.for  --- Lorentz boost for 4 vectors   
 getpcm.for*  --- Lab->CM Track/cluster 4-vector transformation for reco/L3
 getdoca.for* --- Get track IPd0,IPz0 w.r.t IP. 
 evdump.f*    --- Event header/track/Emc bump/L3 quantity dump. 

**NOTE**: The routines with the '*' tag require the beaminit to be called 
          at begin job to activate the beam parameter common. It is 
          recommended to always do a 
             call beaminit.f77(0)     
          at kumac begin job phase, then the user analysis phase
             nt/loop 1 myevanal.f77  
          which can use anything in the beaminit package or the * routines.
**Caution**:  Always use .f or .f77 calls uniformly. Never use a mix of 
          e.g. call beaminit.f(0) then  nt/loop 1 myevanal.f77  
          since the .f and .f77 compilations will not share the same memory 
          for commons with same name so that the beam parameter access
          routines will not work. 

Event selection/TrigConfig utilities
------------------------------------
 trgconfig.inc --- L1/L3 trigger line definitions for various periods
 myevsel.f     --- A grand package with many different event selections
 evsel.inc     --- A simple include to get all routines needed by myevsel.
 bhastk1.f     --- 1-prong Bhabha track based selection 
 bhastk2.f     --- 2-prong Bhabha/mu track based selection 
 bhaseltn.f    --- 2-cluster pure EMC based Bhabha/GammaGamma selection 
 hadselnf.f    --- Emulating Nando's offline track based hadronic selection
 hadselemc.f   --- Simple EMC hadronic selection purifier (rej bhabhas)      
 selcosmic.f   --- Track based cosmic selection          

Note: Most event selections need to work in conjunction with beaminit. 
      The old bhaseltn.for is removed from the L1TAnal package to avoid 
      confusion. Other old L1TAnal routines to be phased out soon: 
      ***->    bhaseltk.for, hadseltk.for, gettkpcm.for 
        
MC truth utilities
------------------
 mcpart.include  -- Included in MCPTYPE to define common types of particles
 mcptype.for     -- Classify particle type (Unstable/Heavy/Strange/Stable) 
 mctrace.for     -- Trace MC particle origin class
 mcdlist.for     -- Gather a list of generator level stable decay daughters
                    for an input parent particle.  
 mcdmatch.for    -- Test for a matching specific decay mode in event
 mcdcyfid.for    -- MC generic fiducial event selection for a specified 
                    exclusive decay mode. 
 mcdump.f        -- Dump out the MC tree details 
 lupart.f        -- Extraction from JETSET to translate particle ID to name

Note: This is only guaranteed to work for the official 8.8.0g MC and 
      may not work properly for some older 8.6.5e ntp productions when 
      there was an MC tree gen/Geant consistency problem.  

GLT utilities
-------------  
 gltindct.for    -- unpack GLT input DAQ DCT/IFT data
 gltinemt.for    -- unpack GLT input DAQ EMT data 
 gltinifr.for    -- unpack IFR input DAQ IFT data only 
 gltdctcnts.for  -- unpack GLT DCT object counts (OR all ticks) 
 gltemtcnts.for  -- unpack GLT EMT object counts (OR all ticks) 
     
Note on trigger line definitions
--------------------------------
  In the L1TNtuples, we unfortunately cannot use the trig configuration 
tools so that all trigger line bit definitions in L1FCT,L1GLT,OepInLine,
OepOutLine, L3ScriptFlag etc., unfortunately have to come from a manual 
dictionary. Part of this information is tabulated in trgconfig.inc which
divied the data into many different configuration periods and used 
extensively by many of the utility routines. For your convenience, the 
following table contains the data period definitions for various official
samples: 
Data        L1 Iper1    L3 Iper3         MC    L1 Iper1   L3 Iper3
            --------    --------               --------   --------
10865-17029     2          10          8.6.5e      2         11 
17032           2          11          8.8.0g      3         12  
17036           2          11 
1710[5-7]       3          12