MINOS event reconstruction: reco_minos

Okay, so you, the user, have a bunch of 'events' that came out of the gminos GEANT simulation of the MINOS detector, now what? Well, presumably you'll want to read those events in order to perform some event reconstruction and analysis. But who wants to write the code that worries about the gritty details of how one reads in events? Wouldn't you rather let someone else deal with that? Well, you can!

What would you pay for this amazing product? $500? Too much! What would you say if I said you could get it for amazingly low, low price of free? Read on.

User modified routines

The basic program provides a shell for handling the file input. The user is given many hooks from which to hang their own code.
reco_minos The main program. Users modify the size of the /PAWC/ common and define the GAFKey_Types that trigger calls to reco_event or reco_notevt. Then a call is made to reco_minos_loop which handles everything else.
reco_init called once before any GAF files have been read, but after zebra and hbook have been intialized. Book global histograms (run and file independent) here. Define FFREAD data cards in this routine.
reco_hist called once before any GAF files have been read, but after the FFREAD has been processed. Book histograms that depend of FFREAD data card input values; perform any other FFREAD dependent calculations.
reco_notevt called after reading a 'not event' record. Typically this will be a geometry (GAFKey_Type='GEOM') record.
reco_new_run called every time a event is read in where the run number changes.
reco_event called for every record classified as an 'event' that passes run/event cuts. Currently, only GAFKey_Type='GEVT' records contain event-like information.
reco_end_run called every time a 'run number' sequence would end (including last event) Do not use the GAFKey value (since it corresponds to the next run); the old run number is passed as an argument.
reco_finish called at the conclusion of all GAF record processing. Typically one would print out any counters and write out histograms.

minos_reco main program

The casual user will probably have little need to modify this routine to any great degree. There are two reasons one might do so: to adjust the size of the /PAWC/ common; or to add GAFKey_Types to the processing list.

Users can modify the name of the gaf file or gaf file list without recompiling and linking, by specifying the environmental variable RECO_GAF_LIST (UNIX only, sorry VMS). The default filename is reco_minos.gaf_list.

gaf file or gaf file list

If the filename passed to the main loop contains the extension .gaf_list then it is treated as an ascii text file containing a list of gaf files to process. Otherwise the string is assumed to contain a valid GAF file name. Filenames that with the extension .fz_gaf and .ie_gaf are assumed to contain GAFs written by the FZ or ASCII drivers. Other files will attempt to use the FZ driver.

The list is currently processed sequentially, each gaf file taken in turn. Future enhancements may include the ability to simultaneously use multiple input files (for mixing data samples (be sure that they use the same geometry though!)) and the ability to tag a file as endless (rewind upon EOF).

Lines from the list file are processed as follows. Everything from a ! onwards is treated as a comment and ignored. Blank lines (including those created by a ! in the first column) are ignored. The last line must have a trailing return or it may be ignored (operating systems vary in their treatment). Lead blanks are ignored; fields are separated by blanks (not tabs, yet). The first field is taken to be the filename. The existance of this file is checked using the FORTRAN inquire statement. Further processing of alleged files that don't exist is skipped.

Following the filename are six optional fields that affect the handling of events in that file. They must occur in this order, using * as a placeholder for the default ("huge" represents a very large integer).

variable default description
mx_nevt_tot huge limit on total # evt to processed (including previous files)
while processing this file
mx_nevt_file huge limit on # evt in this file to process
irunlo 0 accept no evt w/ run # lower than this
irunhi huge accept no evt w/ run # greater than this
ievtlo 0 accept no evt w/ event # lower than this
ievthi huge accept no evt w/ event # greater than this
You might wonder "why bother? I'll just check this in my reco_event routine." The answer is speed. If you set limits by this method then the file reader can quickly ignore events that do not match the last four conditions. The GAF input processing works in two stages. First it reads a header block that contains the record type (cf. GAFKey_Types) along with run and event numbers. The ADAMO user is then given the option to actually read the whole dataflow (ie. event in our case) or skip on to the next record (a fast operation). If you're going to be skipping a lot of events then you will want to take advantage of this option.

GAFKEY_Type

The type_evt and type_notevt lists created in the main routine contain the 4 character strings found in the GAFKey_Type attribute. These tag GAF records as to what they contain. Records that match a value in the type_evt list are treated as events and are subject to run/event limitations Successfully reading one of these that passes those cuts triggers a call to reco_event. Otherwise, if the record matches something in the type_notevt list then it is treated as an interesting not event and triggers a call to reco_notevt without regard to the stored run/event # or other record count limitations. Records that match nothing in either list are not read in!

Known types:
GAFKey_Typedescription
'GEOM'geometry information
'GEVT'geant event

Pitfalls

When processing a .gaf_list you must never have a file that exists but isn't a GAF followed by any other files. This causes the underlying FZ driver to barf with ZFATAL. If the non-gaf file is the last in the list then it is correctly handled.

Writing a new GAF file

Users can now use the reco_minos structure for writing out dataflows. An example of all that is necessary for simply copying the input flows to the output flows while dropping all the information from the hits tables can be found in the file strip_hits.F. A new not-event "GEOM" structure is used to signal that a new file has started (and a new output filename is generated); all not-event dataflows are written out to the new file unmodified. Subsequent event flows have the hit tables cleared and then the dataflow is also written out.

Where to get the code

Users at Fermilab

Fermilab users should check out the labyrinth and theseus scripts.

Getting your own copy of the source

The package can be retrieved from the CVS respository using the command: 
   cvs -d minos@bigbang.astro.indiana.edu:/usr/local/cvsroot checkout reco_minos
This creates a directory with the reco_minos code including example user routines. The linking process depends on being able to access the gminos and util libraries for the definitions of the ADAMO "objects" (ESets) and support routines. These need not be in your area (ie. every user does not have to have a private version of them) but can be shared by users at a common site. This can be achieved by properly defining the setenv environmental variables to point at the common library areas.
Robert Hatcher <hatcher@astro.indiana.edu>
Last modified: Tue Apr 15 17:17:05 1997