August 24, 1998

Tutorial for Evgen and MCFast

Most users of Evgen and MCFast will use the MCFast product version, which is distributed via the Fermilab ups system. The tutorial on this page is appropriate for these users. Some users, mostly those doing development work, will want to use the bphyslib version, click here to go to the tutorial for the bphyslib version. . The difference between the two tutorials reflects differences in directory structure between the product and bphyslib versions.

Step 0: Finding all the Documentation.

Step 1: Set up packages

Step 2: Creation of directories

(A) Create a new directory somewhere and go into it.

(B) In the new directory, create two subdirectories: "evgen" and "mcfast".

Step 3: Create event generator executable and run it

(A) Go into the new evgen area. Copy the following files into the area.

$MCFAST_DIR/example/evgen/b_psiks/GNUmakefile : Makefile
$MCFAST_DIR/example/evgen/b_psiks/bookhistos.F : Select B0 events
$MCFAST_DIR/example/evgen/b_psiks/usr_filter_preqq.F : Select B0 events
$MCFAST_DIR/example/evgen/b_psiks/usr_end_event.F : Make some histograms
$MCFAST_DIR/example/evgen/b_psiks/b_psiks.dec : Force B0 --> psi Ks
$MCFAST_DIR/example/evgen/b_psiks/pythia_psiks.pyt : Pythia input file

(B) If you are not comfortable with unix script languagues, skip to step (C), which continues the tutorial line by line.

If you are comfortable with unix script languages, you can also copy:
$MCFAST_DIR/example/evgen/b_psiks/Run_evgen
$MCFAST_DIR/example/evgen/b_psiks/Run_all
The first file compiles links and runs a single Evgen job. The second file uses the Run_evgen to run examples for all of pythia, isajet and herwig. To run the examples for all three event generators, type:
Run_all
Inspect Run_all to see how to run a single example.

(C) Check the definition of the QQ user decay file.

This is the file which forces the B0 to decay to psi K_s. There are two ways to specify this file. The first way, which only works for herwig and pythia, is to include a line to the control file ( pythia_psiks.pyt or herwig_psiks.hwg ):

qq_user_file b_psiks.dec !QQ user decay file

This is done in the example. The other method, which is the only method which works for isajet, is to type:

setenv QQ_USER_FILE b_psiks.dec

If you run interactively, you must do this every time you log in, before running evgen. See the evgen commentary for more details.

(D) Make one of the following executables. Any of them can be used.

gmake pythia_exam
gmake isajet_exam
gmake herwig_exam

(E) Run pythia_exam, using QQ to decay the B0 and other particles correctly. This is done by entering the following command on one line:

pythia_exam -f pythia_psiks.pyt -l pythia_psiks.lpt -o pythia_psiks.evt -hb pythia_psiks.hbook -qq

This will generate 200 events of the form B0 --> psi Ks --> mu+mu-pi+pi-. You may need to decrease this number on account of disk space limitations. You can do this by editing the file pythia_psiks.pyt and changing the maximum number of events to be generated - maxev 200. The command line options are: -f the name of file which controls evgen; -l the "printer" file which contains a copy of most messages sent to the screen, plus some additional status information; -o the output file containing the generated event; -hb the hbook file containing histograms made by the job.

You may also specify the QQ user decay file with the -qu flag.

pythia_exam -f pythia_psiks.pyt -l pythia_psiks.lpt -o pythia_psiks.evt -hb pythia_psiks.hbook -qq -qu b_psiks.dec

The histograms created by this job check to see if charge and 4-momentum are conserved by the final state particles. They are not always conserved! Check the Evgen commentary. They also look at multiplicities of different sorts of final state particles.

There are similar examples which generate D0-> K- pi+ events and minimum bias events. These are found in the directories:
$MCFAST_DIR/example/evgen/d_kpi
$MCFAST_DIR/example/evgen/min_bias

Step 4: Create MCFast executable and run it

(A) Go into your mcfast directory and copy these files in to that area:

$MCFAST_DIR/example/simulator/GNUmakefile
$MCFAST_DIR/example/simulator/cdf.cmd
$MCFAST_DIR/example/simulator/cdf.db
$MCFAST_DIR/example/simulator/psiks.fil
$MCFAST_DIR/example/simulator/usr_init.F
$MCFAST_DIR/example/simulator/usr_analysis.F
$MCFAST_DIR/example/simulator/Run_MCfast

If you are not familar with unix script languages, then skip this paragraph to continue with the line by line tutorial. If you are familiar with unix script languages you can compile link and run the example with the command,
Run_MCfast cdf
where the argument cdf tells the script to run the job described by the file cdf.cmd. There are also btev.cmd and d0.cmd which are run in a similar fashion.

Continue here for line by line tutorial:
Create a link to the directory with the geometry template files, after first removing any pre-existing links.

rm db
ln -s $MCFAST_DIR/db db

Edit the file psiks.fil. It should contain at least 1 line specifying the name of the pythia event file(s) you just created, i.e. pythia_psiks.evt in your evgen working directory.

(B) The other user routines which you may wish to modify can be found $MCFAST_DIR/simulator/user/src/usr*.F:

usr_analysis.F : Analysis steering routine
usr_before_trigger.F : Trace particles/ fill calorimeter
usr_command.F : Build user defined runtime command
usr_filter.F : Filter generator events
usr_generate_event.F : modify internal event generator
usr_hbinit.F : initialization for HBOOK
usr_hbsummary.F : close out HBOOK files
usr_hsinit.F : Initialization for Histoscope (an alternate histogramming package)
usr_init.F : user defined initialization
usr_mcfio_out.F : user defines output structures
usr_summary.F : User defined summary output

(C) Edit GNUmakefile

1. If you want to include user routines other than the two specified in (A), then you must add these to the USER_OBJ list found in GNUmakefile. For example

USER_OBJ = usr_analysis.o usr_init.o usr_summary.F

2. If you wish, you can make your own library of user routines; but do NOT call it libuser.a ( that is the library which contains the dummy versions the user routines ). Make sure your local user library appears before the line -luser in the makefile.

(D) Make the MCFast executable

gmake mcfast

See below for a discussion about spurious link-time error messages.

(E) Run MCFast, reading in the data created by Pythia.

mcfast -f cdf.cmd -l cdf.lpt -hb cdf.hbook

The user histograms created by this job show the mass plots of the reconstructed Psi, K0s and B. The meaning of the command line arguments is as for evgen, described above.

Several other detector configurations are available in the examples area. To see what is available type:
ls $MCFAST_DIR/example/simulator/README

Comments on Spurious Error Messages