CKM Geant Monte Carlo

The CKM Geant Monte Carlo, or CKMGEANT for short, is a full Geant simulation of the detector. The beamline simulation, also Geant based, is supported independently of the detector simulation. For support of the detector simulation, contact Jurgen Engelfried (jurgen@fnal.gov) or Erik Ramberg (ramberg@fnal.gov). For information on the beamline simulation, contact Rick Coleman (coleman@fnal.gov).

CKMGEANT is available for SGI platforms (IRIX6) and Linux, and has been tested on fsgi01 and fnppd as well as on San Luis Potosi computers. Other flavours and machines are possible too. Please contact Jurgen on how to install it. Some instructions on installation are given below.

An online HTML manual for GEANT can be found at the CERN site: here. Other CERNLIB documentation, such as a KUIP manual and a PAW manual, can be found here.

We use the CVS code development platform for concurrent development at different institutions. The use of CVS is discussed below. In brief, you can checkout the latest modifications to the code, modify it yourself, and then check it back in. Periodically a new official version is released when enough modifications have been made.

Usage of the Monte Carlo is possible on different levels of complexity, described in detail here. To go to a higher complexity, make sure to read and understand the lower complexity first.

1. Running CKMGEANT without changing the code

Include the following lines in your .bashrc file (if you use bash)

. ~ckm/etc/ckmrc.sh

setup ckmgeant

or in your .cshrc file if you use csh or tcsh:

source ~ckm/etc/ckmrc.csh

setup ckmgeant

At this point, all code for the current release can be accessed via the environment variable CKMGEANT_DIR. The fortran source files are in $CKMGEANT_DIR/src, the libraries are in $CKMGEANT_DIR/lib, and this file is in $CKMGEANT_DIR/doc. The common blocks which show the data structure are in include files in the subdirectory $CKMGEANT_DIR/include. Beam input files (on fsgi03/fnppd) can be found in the directory ~ckm/geant/beam_at_detector/.

To run ckmgeant, simply copy $CKMGEANT_DIR/examples/ckminit.kumac into your area, modify it if you wish (as discussed below), and type

ckm_mc

This will run the official release interactive version of ckmgeant, which is located in $CKMGEANT_DIR/bin/ckm_mc. A GEANT> prompt will show and you can type commands such as

exec $CKMGEANT_DIR/examples/drawckm

which will draw the detector, and

trig 10

exit

which will cause 10 events to be run and finish the program. If you look in your area now, you will see the files:

ckmgeant.out = ASCII output file giving hits in the sub-detectors

ckm.hbook = PAW file containing histograms that can be plotted

If you want to run ckmgeant in the background, you can make a batch.kumac file, an example of which can be found in $CKMGEANT_DIR/examples/batch.kumac, and then type

echo "exec batch.kumac" | ckm.int -n -b batch.kumac

This is not a true batch process, but will run the job in the background. (The file batch.kumac should only contain run information, like the number of events. All physics cuts and switches should be put in the file ckminit.kumac, since that is automatically called at an early stage in the program.) The Fermilab machine fsgi01 will not support an interactive process longer than 30 minutes, but fnppd will.

2. Changing a few routines, rebuilding the code, and running

If you want to modify some routines before running, then copy $CKMGEANT_DIR/bin/GNUmakefile and the routines you would like to change into your area. Usually the routines can be found in $CKMGEANT_DIR/src or $CKMGEANT_DIR/examples. Edit the routines as you see fit. Remember, changes you make in one routine may affect many others. For instance, to add new tracking media and geometry definitions, you would have to copy and change both ckm_media.inc and ckmgeom.kumac. To book and fill histograms, or print out information, you can use the routines uuinit, uustep, uukine, and uuout. Examples are in $CKMGEANT_DIR/examples. Once you feel you have written the appropriate code, then simply type gmake. A new executable, again called ckm_mc, will be built in your directory. You can run this executable as discussed in section 1 above. If you are responsible for some group of code, then you should consider using CVS to officially commit your changes as discussed in section 5 below.

3. Short description of commands which can be used in ckminit.kumac

Geant has a large number of interactive commands available; for a description see the Geant manual. For CKM usage, we have created additional commands. HELP is available for all commands at the geant prompt, and also from a help menu. The commands basically turn switches on and off, or allow you to communicate some kind of information to the program, such as the limits of the decay region, or the number of events to run. You should put all commands into a single kumac file - ckminit.kumac. As discussed above, if you want to run in the background, you can have an additional batch.kumac which communicates the number of events to run. Here are descriptions of some commands:

Command                  Description of parameters 
-------                  ------------------------- 
KINE itype ipart      Describes how initial particle is generated

                     itype=-2: start given particle at given location with
                               given momentum and smear initial angle  (must
                               give additional 8 parameters as follows:
                                KINE -2 99 -24.5 0 -1450. 0 0 22.0 .001 .001
                               where the parameters are 3 vertex numbers, 3
                               momentum values and the last two numbers are 
                               the smear angles in mrad)
                           -1: same as -2, but no angle smearing (must give 
                               additional 6 parameters)
                            0: can use arbitrary input file; the structure of the
                               input file is # of input particles, followed by
                               that number of lines, each line containing:
                                  IPART XVTX YVTX ZVTX PX PY PZ
                            1: use beamfile as input (if ipart=0, use particle 
                               type in file, otherwise use the given particle
                               type)
                            2: use randomly generated beam with given particle 
                                type

DECAY_POS lowz hiz    Gives limits on decay position.  Will loop inside program
                           and force the decay within these limits.

SWIT num value        Switches performance level, track drawing, debugging:

                      SWIT 1 0 - maximum performance 
                      SWIT 1 1 - secondaries' kinematics are saved, particle 
                            trajectories are memorized; both can be viewed then 
                            with CONTROL/KINE and DXYZ commands correspondingly. 
                      SWIT 1 2 - the same as previous + trajectories are drawn in
                            a graphics window. 
                      SWIT 2 n - use to dump RICH internals at different levels. (use
                            SWIT 2 100 if you want drawing of RICH photons+lots of output)
                      SWIT 3 1 - events are dumped interactively 
        
BEAMFILE filename     Determines what beamfile to use, if you have KINE 1

OUTPUTFILE filename   Determines what output file to write.
 
OUTPUT_MODE mode(4)   Determines what output gets written (if 0, don't write out).  This
                      switch has the following format:
*                      n:   1   2   3   4   5   6   7   8   9  10  11
*               detector:  ALL GEN UMS KRC KEA BIV VVS STR PRC FVS MVS
             OUTPUT_MODE    1   0   0   0   0   0   0   0   0   0   0

                   
KRCH_GAS              Selects the Kaon RICH gas
                      Parameters: 
                          Gas'Kaon RICH Gas' C D=CF4 R=CF4,N2 
        
KRCH_PRES             Change the value of pressure of Kaon Rich Gas (atm) 
                      Parameters: 
                          KPRESSURE'Radiator pressure' R D=0.68 R=0.:3. 
        
PRCH_PRES             Change the value of pressure of Pion Rich Gas (atm) 
                      Parameters: 
                          PPRESSURE'Radiator pressure' R D=1. R=0.:3.

4. Modifying the matrix element in the decay

5. Reading the output file and analyzing the data

Once you have run either the standard version of CKMGEANT, you can read the output hit file ckmgeant.out with a set of released code. This code is available in the subdirectory $CKMGEANT_DIR/read. Copy the GNUmakefile in this area to your own working directory, as well as the routines CKM_read_init.F and CKM_read_user.F. Edit these files to book histograms and to fill them, respectively. Then type

gmake ckm_read

to create the executable ckm_read. Run this routine by typing

  
        ckm_read input_file 120             # process 120 events from input_file
        cat input_file | ckm_read           # process all events from input_file
        zcat file1.gz file2.gz | ckm_read   # process all events from 2 gzipped files

It will read events in the file you indicate, and create the histogram file ckm_read.hbook. A perusal of the routine CKM_read_user.F should indicate how to access the data, which is stored in the common blocks found in $CKMGEANT_DIR/include/*data.inc. We are currently working on tracking and ring fitting routines that fit the hit data.

6. Making changed code generally available - or using cvs

This should be done when you think that what you changed/added to the code is good and should be used generally. The cvs repository lives on ckm00.fnal.gov. To access it, you need to have cvs and ssh installed on your computer (at Fermilab, type setup cvs), and you have to add the following line to your .bashrc

export CVSROOT=cvsckm@ckm00.fnal.gov:/home/cvsckm/cvsroot

export CVS_RSH=$CKMGEANT_DIR/bin/ckmsshcvs
or .cshrc

setenv CVSROOT cvsckm@ckm00.fnal.gov:/home/cvsckm/cvsroot

setenv CVS_RSH $CKMGEANT_DIR/bin/ckmsshcvs
The definition of CVS_RSH is also performed when you setup ckmgeant devel. (SELEX members be carefull! When developing for SELEX and CKM you have to toggle this environment variable between the two locations!)
To be allowed to access the repository, you have to be in the authorized user lists file of the cvsckm account on ckm00. Send mail to jurgen or pcooper to add your name, indicating where we can pick up your public ssh key. The ssh key is generated via ssh-keygen -t rsa or ssh-keygen -t dsa and is called id_rsa.pub or id_dsa.pub in your ~/.ssh/ directory. The public keys can be send via email. We also need the name of the machine(s) you will be accessing the repository.

You can either checkout the whole package (with cvs checkout ckmgeant) or sub-packages only; at this time we have "driver" (general code) "bin" (contains the general makefiles), "examples" (contains ckminit.kumac and batch.kumac, some kumacs to plot, and uu-routines) "rich" (kaon rich and pion rich codes), "vvs" (everything about the vacuum veto system), "straw" (obvious), "fvs" (forward veto), "keat" (obvious) "mvs" (muon veto), "ums" (upstream magnetic spectrometer), "bivs" (beam interaction veto), "btsm" (beam time stamp module), "cvp" (conversion veto plan), "driver" (general init and steering routines), "etp" (exit time plane), "hvs" (hole veto), "utility" (general utility routines) "scripts" (contains scripts to build a new version) and "ups" (used by the setup command). For analysing the output, we have the "read" sub-packages, which is not fully supported anymore. "unpack" reads and digitizes the output to real data format, and "digi" is the trigger and analysis sub-packages. "display" is an older version of the display routines. To add a new package, you need to be an expert. The checkout command should only be used once for the whole package or for every sub-package. If you do not like to use a sub-package (or even the whole package) you should type cvs release -d package_name

You should edit the routines (or add new ones) in the directories the checkout command generates. To check if your routines compile, go to a different directory (for example where you "played" with the previous chapter) and make a symbolic link (with ln -s) to your changed routine and add it to the GNUmakefile. Compiling the code in the a different directory will help you keep the cvs directories clean.
After you are sure that your changes are correct and without bugs, you can commit this code. A good sequence of commands to do this would be:

cvs -n update (to see which routines changed). A "U" in front of the routine name indicated that somebody commited a new version to cvs, a "M" that you changed it, and a "C" that both happened.
cvs update routine_name in case "U" and "C" from above (in "C" cvs will merge your changes)
cvs diff -w routine_name which will show what you changed since the last version. This shows what you changed. Please make sure to comment out all debug statements like "write(*,*)".
cvs add routine_name will add your routine if it is new to the package.
cvs commit routine_name which will actually commit your changes. If your environment variable EDITOR is set (you can check this with echo $EDITOR) your favorate editor will pop up and allow you to enter some comments to what you changed.

There are reasonable man pages for cvs available, and there exists a short primer, and more info (including a 100 page document) can be found here. Another good bet is cvs -H which gives a short summary of the usage.

7. Installing the libraries on your own computer

The libaries are installed at this moment on fsgi03/fnppd (afs space) and at San Luis Potosi. Installing them somewhere else is strait forward. The code runs on IRIX5.x, IRIX6.x, and LINUX2.0, LINUX2.2, LINUX2.4.

Since version v2.1, to install it on any computer, tar files are available. They are located on fnppd/fsgi03 in ~ckm/ckmgeant/ with obvious names. To compile and link, you need also cern and geant installed on your computer.

If you like to be able to follow easily new version, a installation script via cvs is provided. For the first installation, cvs checkout scripts and edit make_ckmgeant_versions to add information. execute this script and you will have the libraries installed on your computer. After this you have either to declare the version to ups (if you use setup) or set the environment variable CKMGEANT_DIR and source setup.sh.

last change June 27, 2003 by Jurgen Engelfried (jurgen@fnal.gov) and Erik Ramberg (ramberg@fnal.gov)