Processing GMINOS events in the RECO_MINOS Framework

The following document give instructions on how to run MINOS analysis code in the RECO_MINOS framework that is part of the LABYRINTH. It is assumed that the LABYRINTH is installed and configured for the site where the code is to be run and that the user has run the setup script (LABYRINTH/setup_labyrinth.csh) to define the necessary environment.

Components

For any study or analysis there are a number of necessary components:

Analysis code: This is the actual FORTRAN code that the user supplies to perform their particular analysis/study. By default the executable constructed from this is named theseus.exe.
FFREAD data card file: This text file contains the input data cards that are read by FFREAD and control the processing of the events.
Input data files: These are ADAMO GAF files that contain both the geometry and the event information.
GAF list: This text file is a list of the GAF files to be processed, with the possibility of restricting event numbers and ranges to process.

Each of these will be discussed in turn below. The user's analysis code will be converted to an executable to be run. As well as supplying each of the above, the user must also set some environment variables.

Environment variables

RECO_FFR: This must point at the FFREAD file. If unset the code defaults to using reco.ffr in the current directory.
RECO_GAF_LIST: This must point at a single GAF file or a text gaf list file (which must use the extension .gaf_list). If using a single GAF file, the whole file will be processed. If unset the code defaults to using the file reco_minos.gaf_list in the current directory.
RECO_HISTFILE: This may be set by the user to redirect the HBOOK output to a file other than the default reco_minos.hr.
RECO_OUTPUT_GAF: This is the name of the output GAF file (if any) and should be set by the user if their FFREAD card WRITEGAF is set TRUE.

These environment variables should be set (in csh-like shells with setenv VAR value) prior to running the executable. Any paths given should be absolute (i.e. start with a "/") or relative to the working directory when the executable is run.

Analysis code

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_init_usr`	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_usr`	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_usr`	called after reading a 'not event' record. Typically this will be a geometry (`GAFKey_Type='GEOM'`) record.
`reco_new_run_usr`	called every time a event is read in where the run number changes.
`reco_event_usr`	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_usr`	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_usr`	called at the conclusion of all GAF record processing. Typically one would print out any counters and write out histograms.
`reco_keep_usr`	called prior to `reco_event`; logical return argument allows early bypass of processing of events that fail user criteria. Used in conjunction with the FFREAD card `TESTKEEP`.
`reco_minos`	OPTIONAL The main program. Users can modify the size of the /PAWC/ common and define additional the `GAFKey_Type`s that trigger calls to `reco_event` or `reco_notevt`. Then a call is made to `reco_minos_loop` which handles everything else.

The user can supply any or all of these routines. For those that they don't supply, a dummy version is pulled from the link library.

Constructing an executable

The steps for building an executable are simple.

Create a project area:

       mkdir myproject
       cd    myproject

Copy the template Makefile:
```
       cp $THESEUS/Makefile .
```

Copy selected template user routines, e.g.:

       cp $RECOPATH/reco_hist_usr.F .
       cp $RECOPATH/reco_event_usr.F .

Add your own code to the hook routines.
Edit the Makefile.
1. Add to the line USRSRCS = any local files to be compiled and linked in (including both the edited reco_*_usr.F files and any you've written that are called from reco_*_usr files).
  If there are too many to fit on a single line end each line, except the last, with a backslash symbol ("\")
2. If you are going to be directly calling NEUGEN or LUND routines follow the instructions preceeding the USRPREOBJ = line.
3. If you wish to supply a modified version of the main routine (in order to increase the /PAWC/ common) then you must remove the text after MAINOBJ = and add the name of the file to the MAINSRC = line.
Optional If you want to run the muon fitting code you must take the following steps. By default this code is not linked into the standard routines because it greatly expands the size of the executable and the virtual space used when running.
1. Make links to, but don't modify, the standard routines:
```
       ln -s $RECOPATH/reco_init.F reco_init.F
       ln -s $RECOPATH/reco_notevt.F reco_notevt.F
       ln -s $RECOPATH/reco_event.F reco_event.F
   
```
2. Edit the Makefile and convert the line:
  USRDFLGS = -DNOMUON to USRDFLGS =
3. Add the three routines to the USRSRCS list, e.g.:
```
       USRSRCS = reco_hist_usr.F reco_event_usr.F my_routine.F  \
                 reco_init.F reco_notevt.F reco_event.F
   
```
Compile and link to make an executable:
```
    gmake theseus.exe
```

FFREAD file

The RECO_MINOS framework has a standard set of FFREAD cards that can control its' behavour. Additionally one can set cards that control the digitization and smearing of the FLS (scintillator) active detector response; the details of those cards is a topic for a separate document. Users can define their own cards in the reco_init_usr routine as they wish, obeying the usual FFREAD restrictions.

card description default

OVERLAY
OVRn
OVRM
OVRW Controls whether a call is made to the reco_overlay routine. This allows for overlaying events in a time frame for pile up studies. See the note on Near Detector Simulation Notes for details on the usage of these cards. FALSE
8*'    '
-1.0  8*0.0
1000000.

REDIGIT Controls whether the active detector response is redigitized. FALSE

SMRFLS Controls whether the active detector response is smeared by the photodetector response FALSE

LSTDIGIT Controls whether the LST detector response, if any, is redigitized. FALSE

DEMUX Controls whether a call is made to the reco_demux routine (currently a dummy). FALSE

CORRATTN Perform the attenuation correction to fill the FLSDigit_CorrA, FLSDigit_CorrB, FLSDigit_CorrSum entries and the FLSDigiCell, FLSDigiPln and FLSDigiView tables. FALSE

FNDVTX Call the standard vertex finding routine.
Note: the supplied vertex finder relies on information generated during the attenuation correction algorithm, so this flag should normally imply the card CORRATTN TRUE as well. FALSE

RECOMUON Call the muon reconstruction routines. Note: by default these are not compiled/linked into the normal executable and turning on this card will thus not do anything. Instructions on how to build an executable that can call these routine are given above. FALSE

CALLMHPD Two values control whether to call the standard event displays for side views and face-on view. FALSE
FALSE

DROPHITS Controls whether delete the "hit" information (FLSHit and LSTHit) from the output stream. FALSE

WRITEGAF Controls whether write to the output GAF. FALSE

NEWFLOW Controls whether the output GAF uses the latest "dataflow" TRUE

TESTKEEP Activates user supplied test (reco_keep_usr) on whether to bypass event processing. FALSE

WGTBEAM
WGTBVER
WGTSCALE Used in resampling events from input file generated with the envelope flux in the far detector to particular beam profiles (ph2he, ph2me, ph2le). For details see note on Weighted events in GMINOS '    '
0
1.0

card	description	default
OVERLAY OVRn OVRM OVRW	Controls whether a call is made to the `reco_overlay` routine. This allows for overlaying events in a time frame for pile up studies. See the note on Near Detector Simulation Notes for details on the usage of these cards.	FALSE 8' ' -1.0 80.0 1000000.
REDIGIT	Controls whether the active detector response is redigitized.	FALSE
SMRFLS	Controls whether the active detector response is smeared by the photodetector response	FALSE
LSTDIGIT	Controls whether the LST detector response, if any, is redigitized.	FALSE
DEMUX	Controls whether a call is made to the `reco_demux` routine (currently a dummy).	FALSE
CORRATTN	Perform the attenuation correction to fill the `FLSDigit_CorrA`, `FLSDigit_CorrB`, `FLSDigit_CorrSum` entries and the `FLSDigiCell`, `FLSDigiPln` and `FLSDigiView` tables.	FALSE
FNDVTX	Call the standard vertex finding routine. Note: the supplied vertex finder relies on information generated during the attenuation correction algorithm, so this flag should normally imply the card `CORRATTN TRUE` as well.	FALSE
RECOMUON	Call the muon reconstruction routines. Note: by default these are not compiled/linked into the normal executable and turning on this card will thus not do anything. Instructions on how to build an executable that can call these routine are given above.	FALSE
CALLMHPD	Two values control whether to call the standard event displays for side views and face-on view.	FALSE FALSE
DROPHITS	Controls whether delete the "hit" information (`FLSHit` and `LSTHit`) from the output stream.	FALSE
WRITEGAF	Controls whether write to the output GAF.	FALSE
NEWFLOW	Controls whether the output GAF uses the latest "dataflow"	TRUE
TESTKEEP	Activates user supplied test (`reco_keep_usr`) on whether to bypass event processing.	FALSE
WGTBEAM WGTBVER WGTSCALE	Used in resampling events from input file generated with the envelope flux in the far detector to particular beam profiles (ph2he, ph2me, ph2le). For details see note on Weighted events in GMINOS	' ' 0 1.0

Input GAF files

These are files created by GMINOS. The generation of such files is a whole separate topic.

GAF 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, respectively. 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

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 (currently "GEOM" and "GEVT") 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.

Due to the existence of some code that stores away state information, rather than checking the geometry for each event, it is safest to only process multiple files that use the same geometry.

Contact: Robert Hatcher <rhatcher@slac.stanford.edu>