6 JRunMC user interface in more details

At present, the following MC models are included to RunMC: PYTHIA6.3 [5], HERWIG 6.5 [6], ARIADNE 4.12 [7], LEPTO 6.5 [8], AROMA 2.2 [9], CASCADE 1.2 [10], PHOJET 1.05 [11], RAPGAP 3.1 [12]. When JRunMC is used, one can choose one of these MC programs. The final state used in your calculation (or/and in the RUNMC output trees) can be: all stable particles, "partons", "charged particles", "all particles" (which is equivalent to the HEPEVT record) , "stable+all" (fill both stable particles and, in addition, complete HEPEVT record), and "user-defined". The option "stable+all" allows to reconstruct some quantity from the final state (PP or PJ vectors, see the definition of the ``heplist'' class), and at the same time one can preselect events using information on all generated particles (HP vector, which is a copy of HEPEVT event record). Obviously, this option is the slowest. The last option is used to fill the final state in the "proj" directory.

Select the number of events to be processed, type of initial particles, the nucleon structure function (PDF). You also can set kinematic cuts applied on the final state in the transverse momentum (PT) or pseudorapidity (Eta) of particles, if particles were selected, or on jets, if your choice was jet reconstruction. If, instead of the "particles" option, one selects "hadronic jets", all kinematic cuts will be applied on the jets, without any kinematic constrains on the particles used to form jets. For DIS, one can set up the event kinematics in Q2, Bjorken x, y, or W.

Then, you can select the histograms to be filled by clicking on the "Histogram" from the "Ouput" panel. You should see the window ``Variables''. Normally, left window is empty - this means that the user did not specify the variables in ``proj/user-name.txt'' file. Howver, one can still use some system variables by selecting the option "system variables" below the left pannel.

Use mouse double-click to set the variable. This will add a new histogram to the histogram window (on the right). Then one should set the minimum and maximum range of the histograms, as well as the number of bins. You can also select two-dimensional (2D) histograms using the option from the right side.

You can select up to 8 one-dimensional histograms at the same time (or 4 2D histograms), but in fact, the user can specify up to 500 1D histograms (or 250 2D histograms), but only 8 can be viewed during the run (see below). If you click on ``more histograms'', you will get a spreadsheet ``Histograms'', where you can define more than 8 histograms (use the ``Variable'' window to do this). This spreadsheet should allow you to delete, copy, paste selected histograms.

Then, by clicking on ``Options'', you can select the size Canvas size, update interval for histograms (the larger number, the less CPU consuming run), color scheme (for 1D or 2D histograms separately, use plain style to look scientific!), and a renice level. Note that the log-scale option at present works only if you set a single histogram for on-line viewing (of course, when histograms will created, one can use ROOT to set log scale). You can also specify whether you want to fill the histograms for events, or use different normalizations. One can normalize histograms to unity, but also one can calculate differential cross sections (in ``nb'' or ``pb'') after taking into account the bin size and the luminosity for this MC run. Note that the histogram-normalization option works only for 1D histograms for a moment.

Now you can select the output using ''Output" pannel. Three types of the output files are possible:

No any kinematic cut is applied for such output, i.e. you cannot set any cut on the final state from RunMC GUI. To keep the output file small, only particle ID, charge (times 3), mother, daughter and Px, Py, Pz, E of particles are filled. The size of the output file is by a factor 4 smaller than that for the complete HEPEVT record. Note that double precision values were replaced by float values, to keep output small.

Now specify the name of your project on the main window, and save it by clicking on "File - save MC". Another type of projects (which called "RMC", and has the same extension) will be explained latter. The option ``Save MC'' saves the current status of RunMC GUI into the file <project>.mc in the directory ''proj''. Note, that even if you will not name your project, RunMC will save the present project in the default "analmc.mc" file automatically.

If you do want to preselect events for your RunMC tree, you can do this using three methods:

  1. Set appropriate values in the subroutines which initialize the MC programs. All user files are in the ``proj'' directory (read about this below). FORTRAN subroutines which initialize Monte Carlo models are located in the ``proj/ini'' directory. For every MC model, there is a separate subroutine, in which new parameters can be specified. (You have to read MC manuals for this, and use FORTRAN style of coding, of course). Then do ``make'' from the ``proj'' directory. It will rebuild all MC binary files in the ``bin'' directory. If you do this, the original MC HEPEVT record will contain the preselected events you want. The event class of RUNMC will also contain only preselected events, since this class is derived from the HEPEVT. Read about the ``proj'' directory in more details below. Note that this option is not preferable, but should be used if nothing else can help. Instead, use the steering cards (see below).

  2. Another way to change MC parameters is to use the steering cards. Examples of the steering cards are located in the ``example/steer/'' directory. Copy necessary steering card to a directory were you execute JRunMC (i.e. where you type ``runmc''. The steering cards will be loaded automatically. Note than in the parameter settings, the functions in ``proj/ini'' directory are always the last one, i.e. parameters in steering cards can be overwritten by the settings in the ``proj/ini'' functions. The MC settings is the most complicated part, please carefully check the output log file.

  3. One can preselect specific events, while generating fully inclusive events. Again, go to the ``proj'' directory, and put your user calculations in ``user-select.cpp''. By default, the function returns ``0'', i. e. it takes the event. If this function will return any other number, the event will not be taken. Note that this only affects the RUNMC tree (i.e. file ``project_name.rtup''). The event selection done in the ``user-select.cpp'' file does not change events in the original HEPEVT record, as well as in the simplified HEPEVT tree (i.e. the file ``project_name.htup''), which is simply a copy of the FORTRAN HEPEVT common block. In addition, such selection has no affect on the event class used to make histograms on-line. The event class ``main/inc/heplist.h'' is described below. After a modification in ``proj/user-select.cpp'', type ``make'' to recompile the project. Read about the ``proj'' directory below.

Now select predefined histograms, and set minimum and maximum values and the number of bins. To start the run, click ``run'. This will check all your setting, as well as will display the output file options. After 1-5 seconds, you will see the ROOT canvas with histograms updated in real time. Note that for some models, like AROMA or CASCADE, this takes more time since these programs do some initial integrations before they start looping over events. You will see a blue progress bar indicating how many events were processed.

To verify log file generated by RunMC, go to the ''Control'' panel and click on ''view log''. This executes ``JRunMC Notepad'' - an editor with the log file (''.runmc.log''). The log file can also be found in your current directory, look at ``project_name.log'' file.

In addition to the log file, there a file with possible errors ``project_name.err''. If it is not empty, you will be notified by JRunMC.

You can stop the run at any time by clicking on ``Stop''. (You have to wait for 3-10 sec after this, since the program needs to finish all calculations. This however depends on type of calculations.). When run is finished, you will see a pop-up window with the run information.

After the run finished, you should see a new button ``View output'' (below ``More histograms'' button), which has light color. Click on this button: you should see ROOT Browser with the opened file <project>.root.

Then, using the ROOT built-in graphics editor, you can modify the canvas, i.e. change scale, put/remove labels etc. To exit, you should click on ``Exit''. It is advisable to quite the ROOT canvas fist, before you exit RUNMC. All files can be saved as a ROOT file, ``project_name.root''. If you do not want to look at the histograms latter using ``project_name.root file'', go to ``Select output'' to change this setting.

If something goes wrong, click on ``Cancel''. It kills all the runing programs associated with the RunMC program. Note: if you are running some RunMC executables in the background, they will also be killed without saving the results!).