Andres Kruse
A.Kruse@nikhef.nl
NIKHEF Amsterdam
Ard van Sighem
A.vanSighem@nikhef.nl
NIKHEF Amsterdam
MUFFINCUP is a collection of FORTRAN subroutines that facilitates the use of the MUFFIN muon finder [1] from within an EAZE job. MUFFINCUP is a ``wrapper'' which means that it does not have a lot of intelligence, it merely takes over from a physicist the burden of working through the MUFFIN documentation in order to run it. The only intention of this note is to describe what has to be done to include the code in an already existing EAZE job. A more elaborate description of MUFFIN will soon be available [1].
The way MUFFINCUP works is as follows. It just calls MUFFIN to do all the work of finding a muon candidate. For every candidate MUFFIN then calls a routine with selection algorithms inside MUFFINCUP to decide whether a particular candidate is indeed a muon. MUFFINCUP uses the candidate parameters to form a decision. These parameters are for example the number of cells in the candidate and matching muon or inner tracks. Two other important quantities are the hitratio and the occupancy of the candidate which are defined as
number of cells with energy hit by the muon
hitratio = --------------------------------------------
number of cells with energy in the candidate
number of cells with energy hit by the muon
occupancy = -------------------------------------------
number of cells in the candidate
These two ratios should be close to 1 for a ``good'' muon candidate. If one of the selection algorithms decides that a particular candidate is a good muon MUFFIN stops.
The muon candidate selection in MUFFINCUP has been tuned for finding muons in charged current events. It can find very odd looking muon candidates but it might not at all be suited for other analyses. The best is to develop different muon candidate selection algorithms and give it to the authors of MUFFINCUP to include it in there. The second best alternative is to restrict the muon types identified by the selection algorithms inside MUFFINCUP.
To do this conveniently a file that contains a list of all allowed muon types can be passed to MUFFINCUP. It is to be read upon initialization. The file format is very simple, it just contains a list of muon type numbers and a short explanatory text (see appendix A for an example). To load the muon type file the steering card MUFFINCU-MUTYPEFN has to contain the file name. Different versions of this muon type file are accessible on the MUFFIN WWW site. The user should make sure that the muon type file version agrees with the version of MUFFIN he is using. Note: if the muon type file can not be read MUFFINCUP will assume that all muon types are allowed.
MUFFIN also uses a library that is called CONDENSOR [1]. This is a package to create condensates similar to standard CCRECON condensates but with more functionality. The CConSa table is not changed when creating these new condensates.
It should be noted that the current version of MUFFINCUP only runs on SUN SOLARIS and SGI IRIX operating systems.
On http://www.nikhef.nl/pub/experiments/zeus/muffin/muffin.html the most recent information on the status of MUFFIN, MUFFINCUP and CONDENSOR can be found. It also contains many pictures of muons tagged by MUFFIN and a description of the different muon types recognized by the package.
MUFFINCUP is interfaced to by a call to two subroutines, one for initialization and one that has to be executed once per event:
call MUFFININI()
This sets up the communication between all the packages involved, reads in the steering cards and causes a printout of some information in the log file.
Integer BestMuonType
call MUFFINRUN( BestMuonType )
This will execute the muon finder. BestMuonType contains a value greater than zero if a muon has been found, zero if no muon was found and a negative value if an error occurred. For a positive value BestMuonType contains the type of the ``best'' muon found. The smaller the value the ``better'' the muon type. A muon is ``good'' if it has muon tracks and a high occupancy and hitratio. The worse the hitratio the ``worse'' the muon is. The precise meaning of these BestMuonType values can be found in the list of muon types on the WWW site.
An example that shows how MUFFINCUP can be called from within an EAZE job is accessible on the web site. It is called runmuffin. The code contains many comments and also makes use of the NTUPLE output option of MUFFINCUP (see section 5).
The two libraries MUFFINCUP uses, MUFFIN and CONDENSOR, have to be included during linking of the EAZE job. To link the code together with an EAZE job on the ZARAH machines at DESY the user has to add the following lines to his shell script (usually called something like EAZE-RUN):
ln -s /zeus/private/sighem/libmuffin_muffin_version.a libmuffin.a ln -s /zeus/private/sighem/libcondens_condensor_version.a libcondens.a LIBS="-L./ -lmuffin -lcondens"
The above will locate the CONDENSOR and MUFFIN library files and create a symbolic link to them. The user should replace condensor_version and muffin_version by the version numbers of the code that should be linked.
The call to zmake in the shell script should look like this:
zmake LIBS="$LIBS" PROGRAM="$PROGRAM" ...
An example of a shell script can also be found on the WWW site.
To include MUFFIN in an EAZE job in a ZSMSM environment the user has to add the following lines to the Makefile.preamble file
CONDENSDIR = /zeus/private/sighem CONDLIB = $(CONDENSDIR)/libcondens_condensor_version.a MUFFINDIR = /zeus/private/sighem MUFLIB = $(MUFFINDIR)/libmuffin_muffin_version.a LIBS += $(MUFLIB) LIBS += $(CONDLIB)
An example of such a Makefile.preamble file can be found in appendix B.
The following code versions should always be accessible:
Due to the structure of the program new code versions at the lower levels should be compatible with old versions at higher levels. The levels are
The calling structure is always downwards, so a routine will only call routines that are in the same level or lower. This means that RUNMUFFIN may call all three other packages. MUFFINCUP will only call routines in MUFFIN or CONDENSOR. MUFFIN will only call routines inside MUFFIN or CONDENSOR, where the only exception is the muon candidate selection, that is provided by MUFFINCUP. CONDENSOR will only call routines inside itself.
Since every new version will still provide the same features as the old one the compatibility between old and new versions can be ensured as follows: the version for CONDENSOR may be more recent than MUFFIN which in turn may be more recent than MUFFINCUP which in turn may be more recent than RUNMUFFIN or the user's EAZE job.
The currently available versions are 1.0 (pro) and 2.0-beta (new). More information about these two versions is available on the WWW site.
Different configurations for the NTUPLE output are possible:
MUFFINCUP can add the condensates found by CONDENSOR to the NTUPLE. The default setting is that MUFFINCUP will not add this information. With the steering card MUFFINCU-GETCOND the user can change this.
Note that CONDENSOR is used in such a way that the calorimeter cell path length correction is undone. Only this way MUFFIN can calculate the speed for candidates correctly. The result of this is though that for particles originating from a true collision at the nominal interaction point the average condensate time is not zero. If MUFFINCUP is instructed to output the condensates it recalculates the condensate time using the proper path length correction.
MUFFINCUP can also create a VRML file for every event. Such a VRML file will display the entire event in a 3D view and can be viewed with a package like VRWeb or WebSpace. With the steering card MUFFINCU-EVTDRAW the user can switch on this VRML mode. It is also possible to draw the event only if there was no muon found (MUFFINCU-EVTDRNOM) or if no candidate was found (MUFFINCU-EVTDRNOC). If the card MUFFINCU-EVTDRAWC is set a VRML file that shows all the condensates in the event will be created.
The following steering cards are used by MUFFINCUP. Cards marked with an asterisk are only available in version 2.0-beta. The steering cards for MUFFIN and CONDENSOR can be found on the MUFFIN WWW site and in [1].
Steering cards of type LOGICAL and INTEGER:
| Card name | Type | Default | Contents |
|---|---|---|---|
| MKTMPL | L | .FALSE. | make template steering cards file? |
| CCGEOM | L | .TRUE. | call CCGEOM for a new run? |
| MKNOISE | L | .FALSE. | make noise: print out lots of messages about the algorithm? |
| EVTDRAW | L | .FALSE. | create VRML file for each event? |
| EVTDRAWC | L | .FALSE. | create VRML file containing the condensates for each event? |
| EVTDRNOC* | L | .FALSE. | create VRML file if no candidate is found? |
| EVTDRNOM* | L | .FALSE. | create VRML file if no muon is found? |
| GETCOND | L | .FALSE. | get condensates into NUTPLE? |
| NTUPLEID | I | 0 | ntuple identifier that holds the candidates (0=no ntuple). |
| NTUPLEAP | L | .TRUE. | append data to an existing NTUPLE? |
Steering cards of type STRING:
| Card name | Type | Default | Contents |
|---|---|---|---|
| NTUPLED | S | . | HBOOK directory that will contain NTUPLES and histograms produced by MUFFIN. |
| MUTYPEFN | S | muffintypes.list | name of the ASCII file that contains the list of muon types that should be recognized. |
MUFFIN contains all the pattern recognition logic and access to sub detector data to find muon candidates. A candidate is the collection of condensates and tracks which together form the signal the muon left behind in the detector. MUFFIN does not decide whether a candidate is indeed a muon. This is done by an external routine provided by MUFFINCUP. The routine is very simple, it simply checks a couple of variables for that candidate to form a decision (here one could also imagine a neural network). In the current MUFFINCUP implementation this routine is called CUP_ClassifyCandidate() which in turn calls CUP_FindMuon(). Reason for this is that CUP_FindMuon is written in such a way that it can immediately be used inside PAW. In PAW it operates on the NTUPLE produced by RUNMUFFIN to find events with a muon.
The current versions of the code contain selection algorithms that are tuned for finding muons in events with high missing transverse momentum like for a charged current analysis. This might make the selection algorithms less appropriate for other analyses and this is the reason why additional tuning is required. It is very easy and also instructive to go through such tuning cycles, it requires
A short description was given on how the MUFFIN muon finder can be run from within an EAZE job. A release of MUFFINCUP is available on SGI and SUN for immediate use. A wider use of MUFFIN inside ZEUS requires some more tuning but a framework for such work exists.
c c filename: muontypes.list c c contents: muon types supported by muffincup.car c c the file format: c - a "c" or "!" or "#" as first character in a line c indicates a comment and will be discarded. c - a "H" is also a comment but it will be included in c the HTML file that can be generated from this file. c - if a line begins with a number it contains a new c muon type, in that case the comment starting at c character position should describe the muon type. c c a muon type should not occur twice. c c ------------------------------------------------------------ c H <HR> H muons found by algorithm 1 (combined muon tracks) H or algorithm 2 (single muon tracks) c 1 very good, occupancy and hitratio very high 2 <A HREF="http:#1">type 1</A> + shower in wls 3 <A HREF="http:#1">type 1</A> + shower 4 <A HREF="http:#1">type 1</A> + particles bent away 5 <A HREF="http:#1">type 1</A> + particles bent away and shower 11 good, muon traverses entire cal 12 <A HREF="http:#11">type 11</A> + shower in wls 13 <A HREF="http:#11">type 11</A> + shower 14 <A HREF="http:#11">type 11</A> + particles bent away 15 <A HREF="http:#11">type 11</A> + particles bent away and shower c c ------------------------------------------------------------ c H <HR> H muons found by the condensate based finder c H halo muons: c 1001 halo muon, very nice 1002 <A HREF="http:#1001">type 1001</A> + shower in WLS 1003 <A HREF="http:#1001">type 1001</A> + shower 1004 <A HREF="http:#1001">type 1001</A> + a few cells missed, but neighbors hit c H <HR> H other muons, using the inner tracks: c 1011 good muon, with aligned track 1012 <A HREF="http:#1011">type 1011</A> + shower in WLS 1013 <A HREF="http:#1011">type 1011</A> + shower 1014 <A HREF="http:#1011">type 1011</A> + a few cells missed, but neighbors hit c c ------------------------------------------------------------ c H <HR> H muons found by condensate timing based finder, speed H compatible with c c 3001 occupancy good, hitratio not so good 3002 like <A HREF="http:#3001">type 3001</A> + matching (muon) tracks 3003 muon goes all way through CAL 3004 good occupancy, very good hitratio, matching muon track
#___________________________________________________________________________ # # Definitions for FPP #___________________________________________________________________________ # CONDITIONAL_FLAGS = # CONDITIONAL_FLAGS_OFF = # #___________________________________________________________________________ # # Definitions for FPP #___________________________________________________________________________ # # For running the Debugger, one must use the debug Linker flag: DEBUG_LIBRARY=ON #____________________________________________________________________ # CONDENSDIR = /zeus/private/sighem CONDLIB = $(CONDENSDIR)/libcondens_pro.a MUFFINDIR = /zeus/private/sighem MUFLIB = $(MUFFINDIR)/libmuffin_pro.a # LIBS += $(MUFLIB) LIBS += $(CONDLIB)