The MINFAST User Guide v1.2

Introduction

This is a version of the MINOS event display program, adapted in part from the ALICE and ATLAS programs and renamed MINFAST.

Creating input to MINFAST

Rerootjob reads a gminos gaf file and writes out a root file from it. By default it processes only 10 events per input file.

To run it type:-

rerootjob The rerootjob executable has an optional argument "-n 1000", for example, to stop after 1000 events (per input file). The files reco_minos.gaf_list and reco_options must both be present in the directory from which rerootjob is run. Rerootjob reads the gaf data from the file(s) listed in the reco_minos.gaf_list file. It also consults the reco_options file which contains the names of REROOT Classes to be created. We had to introduce this file during debug to turn off processing of some classes that got bad ADAMO data at one time. Right now everything is turned on. We shall eliminate the reco_options file eventually when one we are more confident of the data. Rerootjob doesn't use X windows.

Running MINFAST

Minfastjob is a stand-alone program to read a root file generated by rerootjob and to display events using X-Windows. It can also be run in "batch" mode.

To run it type:-

minfastjob Minfastjob has an optional argument "-b", which causes it to be run in "batch" mode, without displaying the GUI or any windows. A batch job must specify a macro file or series of macro files on the command line. These are run in succession. The first macro must open a REROOT file for input, using, for example, the command: gMINFast->OpenRerootFile("${MINFPATH}/root_files/myfile.root"); Note that the file name must include the path. When running in batch mode, the "-q" option causes the job to terminate after executing the macro(s) on the command line. A typical invocation of minfastjob in batch mode is thus: minfastjob -b -q batchloop.C The sample macro batchloop.C is included in the macros subdirectory. In any minfastjob session, one can now change the input data file using the "Open" item in the pull-down "File" menu, or from the ROOT command line or from a macro, using, for example, the command: gMINFast->OpenRerootFile("${MINFPATH}/root_files/myfile.root");

Using the Event Display

ZOOM

The native ROOT GUI has ZOOM and PICK features and hooks for other extensions. In ZOOM mode one uses the left mouse button to define a ZOOM box. Successive ZOOM operations can be done.

UNZOOM

The UNZOOM button undoes previous ZOOMs in reverse order. Since each view has its own ZOOM history, UNZOOM only works on the "selected view." When MINFAST has a hard time deciding which view is "selected," UNZOOM does nothing. The user can manually "select" a view by clicking in the view pad with the middle mouse button, or with both buttons simultaneously on a two button mouse.

PICK

In PICK mode, selected information about the hit and track over which the cursor is positioned is shown in the "status box" along the bottom of the display window. If you PICK individual hits with the left mouse button, all hits from the same primary track are highlighted. Clicking the right mouse button brings up a "context menu" to INSPECT or DUMP hit or track information. Control of the "context menu" on the right mouse button is a general ROOT feature to give the user access to "methods" from any graphical object. Of particular interest is the "SetMarkerAttributes" item in the context menu. This button brings up a panel through which one can mark all hits from the same track that produced the hit clicked upon with a distinctive marker or color. The "Propagate" item extends the marker choice to hits from the same track in other subdetectors. One of the included ROOT format data files has an emulsion detector tacked on before the main MINOS detector. It has to be ZOOMed several times to see the emulsion layers. In the emulsion detector, direction vectors at track hits in each emulsion layer are displayed when PICKed with the left mouse button. This allows one to find tau decay kinks, using the particle ID information displayed in the status box along the bottom of the window.

Interacting with the Data

Three additional hooks allow the user to interact with the data. They also permit developers to try out new code in the ROOT interpreter without the overhead of makefiles, compilation and linking. Developers can then convert this code into compiled code in personal libraries, which are then linked dynamically into the ROOT system for reconstruction or analysis tasks.

The interactive ROOT interface is turned on so that one can type ROOT commands from the command line in the window from which the program was launched.
One can write a ROOT script and run it via the interpreter from either the command line or by clicking on the MACRO button on the event display window and OPENing the file from the file browser which comes up. ROOT is robust enough to recover from many errors in these files, which permits interactive debugging. If one types ".s" on the command line, the macro will be run in single step debug mode. Some sample macros have been placed in the "macros" subdirectory, for reference:
- qtestmacro.C -- A new macro which simplifies data navigation by using the "Q" classes of the TOOL_Classes subdirectory. These relieve the user from declaring TClonesArrays and from knowing about REROOT_Event and REROOT_Geom classes. They use iterators to loop through the data containers, rather than indices. They restore the ADAMO SORT and SELECT functionality by allowing the user to declare custom containers with selected subsets of the raw data, sorted with custom algorithms. The macros below will be rewritten using the style of qtestmacro. Qtestmacro is heavily commented.
- digitsmacro.C -- Makes a LEGO of digits weighted by pulse height.
- plotmacro.C -- Makes some plots and a text panel for current event
- loopmacro.C -- Loops over all events and makes some plots
- geteventmacro.C -- jumps to a desired event. Currently needs to be run from command line with:- for example
Users can create custom objects in the USER_Classes subdirectory. This code will be compiled and placed in the libuser.so dynamic library, which is linked by minfastjob.

The "root_files" subdirectory contains pointers to root format data files in an external directory, downloaded from the repository or constructed by the user. There are pointers to two root data files included in the "root_files" subdirectory:

far_mu-tau_v5.root -- has 100 numu events and 100 nutau events in the back-end 2 supermodules. The U(X) and V(Y) plane digitizations can be viewed by running the digitsmacro.C. This plot should be improved and integrated into the main GUI.
emu_tauCC.root -- has 200 nutau events forced to begin in the emulsion layers. The PICK vector feature allows one to find the tau decay kinks in the emulsion.

Many longer REROOT data files are available at: /afs/fnal.gov/files/data/minos/d12/root_files

Future Improvements

The next improvements to the display will be to correct the following:

The ability of the data INSPECTOR to inspect arrays in our data structures and to follow indices, which we often use instead of pointer links, is somewhat limited. We can introduce mechanisms which make the data more browsable.
Display of digitizations with pulse height information is currently done via a macro-in-progress called digitsmacro.C, which can be run via the MACRO button. It is slow and inelegant, although the plotting and display characteristics can be altered with the SetDrawOption item of the menu produced from the right mouse button in PICK mode. Digitization views should be integrated into the main display frame, along with other useful 2D views.
One needs to be able to select from a set of color schemes to make the display visible on a variety of black and white and color terminals, hard copy and transparency displays. A temporary kludge for this problem is to type, for example, at the root prompt: gMINFast->Display()->SetBackColor(28); to get a brownish background.
It takes several ZOOMs to get into the emulsion detector, where the scale is a few cm. It would be nice to speed this up.
Sometimes UNZOOM can't decide which view to UNZOOM. To "select" a view for this purpose click on the view pad with the middle mouse button.
Commands from the interactive ROOT command line or from user MACROs can cause problems if they conflict with the state of the main display program. For example, looping over events from a macro can confuse the display, which is looking at a selected event. The loopmacro.C and the batchloop.C examples show how to do this safely.
The GUI has NEXT and PREVIOUS buttons to display a new event. A macro called geteventmacro(Int_t nevt) allows one to jump to the nevt'th event in the file. You call it from the command line by typing: .x geteventmacro.C(28) for example, to get event 28 This capability needs to be added to the GUI itself.
The histogram tree is not implemented for MINFAST yet, so there are no ready-made histograms to look at.
The naming conventions are inconsistent between parts of the program.
The MACRO button needs a way to take arguments, so that geteventmacro need not be run from the command line, for example.
There are requests for an event vertex marker, a way to force 1:1 aspect ratio, a 3 dimensional distance scale, XYZ axis arrows, a way to measure angles, etc. Please keep these requests coming.
The file browser starts in the wrong directory. To move down in the directory structure, one should double-click on the desired directory, rather than clicking on "OPEN" in the file browser. Use "OPEN" to select the target root data file after locating it in the browser.
One needs a model for writing out one's own data to a data file.

Installation Notes

The following environment variables need to be pre-defined. A script, setup.source, can be used to set these variables, if executed with "source setup.source". The file setup.source should be set locally as a soft link with: ln -s setup_scripts/setup.source.[site] setup.source where setup.source.[site] can be constructed for new sites from the sample versions provided. New versions created by users can be added to the distribution.

Needed for minfastjob and rerootjob

ROOTSYS = path to ROOT system
MINFPATH = path to top level MINFAST directory (this directory).
LD_LIBRARY_PATH = default path to dynamic link libraries

Needed for rerootjob, not minfastjob

CERNLIBS = ${CERNPATH}/pro/lib

LABYRINTH = path to gminos labyrinth
LABYRINTH_RELEASE = probably "test" until release no. is implemented
LABYRINTHBIN = ${LABYRINTH}/bin/${arch}/${LABYRINTH_RELEASE}
LABYRINTHINC = ${LABYRINTH}/inc/${arch}/${LABYRINTH_RELEASE}
LABYRINTHLIB = ${LABYRINTH}/lib/${arch}/${LABYRINTH_RELEASE}

There are two executables which one can build:

rerootjob.
minfastjob.

To build them type "gmake"

Rerootjob will only be built if environment variable LABYRINTH is defined with the correct path. If LABYRINTH is set to nothing, gmake will not attempt to build rerootjob. The way to do this is to execute:

setenv LABYRINTH

The present version has been installed on Sun Solaris(CC), Linux(egcs), SGI(CC), IBM AIX(xlC), and DEC OSF/1(cxx and egcs) where the C++ compiler is indicated. It should also work on HP with an updated OS. One may need to edit the appropriate platform dependent sections in file Make.include to bring up other machines. ROOT version 2.22 or later is needed. GMINOS data files must have been produced with GMINOS Release 5 or later. The FLSDigit HitBits word is filled starting with GMINOS Release 5.4.

This release is tagged as MINFAST_v1.2.

Go Back to the The OO Companion Top Page

If you have any comments about this page please send them to Nick West