MUC_GEANT-DATA DRIVEN GEANT for Ring Coolers

 

Rajendran Raja

 7/19/2002 3:36:18 PM

MUC_GEANT is a version of GEANT 3.21 that is data driven. The program contains no hard-coded geometry constants. The Geometry and Detectors systems are fed to the program using  RCP files that are structured text files. The main routine is called hanuman.F. The program works on SGI/UNIX and LINUX. The program is built using Makefiles. All fortran routines are in the style of CERNLIB (i.e. *.F). They can contain compile time switches and common blocks are introduced via the #include construction.

                  Geant Documentation

                  RCP files

                  RCPE files 

                  Declaring RCP and RCPE files to the program 

                  Fortran Coding Standards

                  Preparing your area

                  Building the needed libraries

                  Building and running the MUC_GEANT executable

                  Library Linking Order and the lddum routines

                  Analyzing and Playing Back events

 

GEANT Documentation

CERN program library provides GEANT 3.21 documentation in postscript and HTML forms. We will assume that the user is familiar with GEANT principles and has read the GEANT manual. We will attempt to give hyperlinks to the appropriate GEANT subroutine documentation when warranted.

RCP files

RCP files are inherited from the D0 experiment Run I code. These are structured ASCII files that can be used to input data to programs in an orderly form. Fortran programs can read in variables from RCP files from any subroutine without use of common blocks. The constants are kept in ZEBRA banks and are made available to the user by means of a fast binary search among the bank contents. RCP files can handle all common data types, Integer *4, Character ,Real*4 and Logicals. The general format of the file is a variable name (up to 32 characters long) followed by a value. Character values are enclosed in single quotes. Exclamation point (!) signifies that the remainder of the line is a comment. In addition to single characters, one can also specify arrays of variables by the declaration

\array real_nums
 0.7   3.9  5.5 ! This line contains an array of 3 real numbers
\end 

The primary RCP file controlling the program is called HANUMAN.RCP. Please browse through it by following the hyperlink.

This file has an array called

\ARRAY DETECTOR_SYSTEMS                                                   

'MOTHERS'              !media 0-99. rot matrices 0-999                  

'MUCOOL'               !media 0-99. rot matrices 0-999                  

'TARGET'               !target for internal target measurement          

'MAPS'                 !Will DO MAPS between any two points in the ring if this RCP file is specified.                                       

\END

This array specifies the list of detector systems used by MUC_GEANT. For each system xxx, the user is expected to supply a file called xxx.rcp which describes how the system is setup. In our example we have the systems MOTHERS,  MUCOOL, TARGET, MAPS which will require the provision of the RCP files MOTHERS.RCP,  MUCOOL.RCP, TARGET.RCP AND MAPS.RCP  . Each of these RCP files will have identical structures. So if one understands the structure of one system, all other systems can be understood as well. The RCP file MOTHERS.RCP sets up the mother volumes for MUC_GEANT and the materials and media. We then setup the individual systems. The magnetic field is supplied by a routine called GUFLD.

GEANT geometry is defined using shapes made up of tracking media and placed in the mother volumes using translations and rotations defined in terms of rotation matrices. The rotation matrices and media are known to GEANT using integer numbers. In order to avoid conflicts in media and rotation matrix definitions, we define numerical ranges for these for each detector system as illustrated in the comment fields in the above \ARRAY definition.

Structure of detector RCP files

Each detector RCP file must contain the following RCP file structures.

\ARRAY ROTATION_MATRICES      !Interrupt here to read more about this structure
\ARRAY MATERIAL_LIST          !Interrupt here to read more about this structure
\ARRAY MIXTURE_LIST           !Interrupt here to read more about this structure
\ARRAY MEDIA_LIST             !Interrupt here to read more about this structure
\ARRAY VOLUME_LIST            !Interrupt here to read more about this structure
\ARRAY DETECTOR_LIST          !Interrupt here to read more about this structure
\ARRAY CERENKOV_LIST          !Interrupt here to read more about this structure

These arrays define the rotation matrices, materials, mixtures, tracking media, geometrical volumes and detector sets belonging to the detector subsystem in question.

RCPE files

RCP files can become somewhat large. Very often one wants to keep most of the RCP file but may want to change a few of the variables as the running conditions of the program change. This is done using RCPE files (stands for RCP Edit). As an example, the RCP file hanuman.rcp can be edited by a file called hanuman.rcpe. The variables in hanuman.rcp will be unaffected if they are not over-ridden by their being declared in hanuman.rcpe.

 

Declaring RCP and RCPE files to the program

Both RCP files and RCPE files are declared to the program using the following link structure.

 

setenv BETA $cwd     

ln -sf  $BETA/hanuman.rcp     hanuman_rcp                                            

ln -sf  $BETA/hanuman_generate.rcpe     hanuman_rcpe 

 

The above declarations are done in setup.muc_geant.rel. The important thing is to note is that an RCP file XXX.rcp is read in by the system as XXX_RCP. This is an old D0 convention

 

Fortran Coding standards

  1. Every subroutine must have a header with the Author name, Date of Creation, Modification, Purpose of routine, Input and Output.
  2. All include files must be of the form #include ‘name.inc’
  3. All code must be properly indented. The editor xemacs has an automatic way of doing this. Select the area you want to indent, and type in ‘esc’ followed by ‘ctrl-\’. It will make your code readable.
  4. All code must be single operation per line. No Semi-colons.
  5. Comments are encouraged strongly. Comments may be added at the end of a line by !comment.
  6. All source code should be in upper case. Comments may be in lower case.
  7. There should be no hard-coded constants in routines. All constants should be read in from RCP files. The programmer should familiarize him/herself with the routines EZPICK, EZGET and EZRSET.
  8. The use of  IMPLICIT NONE is mandatory in all routines. This forces declaration of all variables as logical,real etc.
  9. The use of the construction 

---------------------

        logical first

        data first/.true.

        save first

----------------

        if(first)then

        first = .false.

        endif

 Is encouraged when wanting to initialize things in routines.

  1. The use of common blocks is discouraged. If one must have common blocks, they should come in as include files as described above. The three main places the include files are found are shown in the example below.

#include "inc/gcphys.inc"  !from $d0library/inc. Geant common blocks in $d0library/inc have variables type declared                     #include "listvol.inc"           !from current directory (in this case dd_geant).

      #include “geant321/gcdraw.inc” !from the directory $GEANT_DIR/src/geant321/geant321

             These paths are defined in the files Makefile and config.mk

  1. All released code should reside in the CVS library.

 

 

 

An example of the code is as below. Only part of the routine is shown to illustrate the main points.

      SUBROUTINE UGINIT

C----------------------------------------------------------------------

C     -

C     -   Purpose and Methods : Initialisation

C     -                         include standard GEANT3 init.;

C     -                         Reading and initialisation of Run-time switches

C     -                         Initialization and filling of ZEBSTP structure

C     -                         for each detector

C     -

C     -

C     -   Inputs  : None

C     -   Outputs : None

C     -

C     -   Created  27-APR-1998   Rajendran Raja 

C     -

C----------------------------------------------------------------------

      IMPLICIT NONE

C    

#include "inc/gcunit.inc"

#include "inc/gcphys.inc"

#include "listvol.inc"

#include "end_kick.inc"

#include "maps.inc"

C    

      LOGICAL FIRST

      DATA FIRST/.TRUE./

      SAVE FIRST

C----------------------------------------------------------------------

      IF(FIRST)THEN

     C     ALL EZPICK('HANUMAN_RCP')

         CALL EZGET('PRINT_MATERIALS',PRMAT,IER)

         CALL EZGET('DO_INTERACTION_LENGTHS',DLAM,IER)

         CALL EZRSET

      ENDIF  

C     only part of the routine shown.

 

C     CALL SVSWCH                       ! Save switches into RUNG bank; LQ(-1)

C     CALL FLD0RG(9,72,ENTRY)           ! Fill version numbers

C    

C    

C     ****  Print out various GEANT banks.

C    

      IF (PRMAT) THEN

         CALL GPMATE(0)

         CALL GPTMED(0)

         CALL GPVOLU(0)

         CALL GPROTM(0)

         CALL GPSETS('*','*')

      ENDIF

 999  RETURN

      END

 Preparing Your Area

All code is in a CVS library. In your .cshrc file, declare

setenv CVSROOT e907cvs@cdcvs.fnal.gov:/cvs/e907

setenv CVS_RSH /usr/krb5/bin/rsh #(path to kerberized rsh)

 

 

The code resides in 3 libraries. 

1.      mipp/simulation/trim_d0lib contains  the RCP system and other routines in a trimmed down version of the RUN I D0library.

2.      mipp/simulation/dd_geant contains the data-driven code that is experiment independent.

3.      mipp/simulation/muc_geant  contains the MUC_GEANT specific RCP files and magnetic field routines etc.

In order to fetch the modules from CVS, perform in your work area

cvs co mipp/simulation/trim_d0lib

cvs co mipp/simulation/dd_geant

cvs co mipp/simulation/muc_geant

These commands should fetch the modules belonging to the 3 libraries.

 

Building the Needed Libraries

To build trim_d0lib, perform

 

cd trim_d0lib                  #gets to the root directory of trim_d0library

source setup.trim_d0lib   # This sets up environment variables such as $d0library and $d0debug and $d0platform

                                      # edit setup.trim_d0lib--  setenv d0debug DEBUG for debug version,  setenv d0debug NODEBUG for nodebug version.

gmake -f Makefile clean                   #will clean out all *.o and *.a files

gmake -f Makefile lib                       #will build all the sublibraries such as calor_util, srcp_util as well as a master library called trim_d0lib.a

 

To build dd_geant, perform

 

cd dd_geant                   #gets to the root directory of dd_geant

source setup.dd_geant    #This sets up environment variables such as $d0library and $d0debug and $d0platform

                                      #edit setup.dd_geant -- setenv d0debug DEBUG for debug version,  setenv d0debug NODEBUG for nodebug version.

gmake -f Makefile clean                   #will clean out all *.o and *.a files

gmake -f Makefile lib                       #will build dd_geant.a

 

To build muc_geant, perform

cd muc_geant                     #gets to the root directory of muc_geant

source setup.muc_geant      #This sets up environment variables such as $d0library and $d0debug and $d0platform

                                      #edit setup.muc_geant -- setenv d0debug DEBUG for debug version,  setenv d0debug NODEBUG for nodebug version.

gmake -f Makefile clean                   #will clean out all *.o and *.a files

gmake -f Makefile lib                       #will build muc_geant.a

 

Building and running the Muc_geant executable

In order to build the muc_geant executable, in the muc_geant area perform

 

 gmake -f Makefile bin       #will build the executable muc_geant.x

 

Before one builds the executable, it is necessary to have executed the command “Source setup.muc_geant to setup the environment variables such as $d0library. Before executing muc_geant.x , it is necessary to setup the links to the RCP files etc. This is done by

 

source setup.muc_geant.rel   #This has to be done only once.

 

Further,

 

source setup.interactive.rel  #will run program in an interactive mode

source setup.generate.rel    #will run program in a batch mode to generate events and record them on fort.2

source setup.analyze.rel     #will run program in a playback mode to analyze generate events.

 

Library Linking Order and the lddum routines

The linking order of routines is 1)those in muc_geant.a 2)those in dd_geant.a 3)Those in geant321.a

There exist a number of routines that are present in dummy or duplicate form in all three or any two of the libraries.

In order to link things correctly the following technique is used with lddum routines.

The main routine hanuman.F  in /muc_geant is structured as follows.

 

     PROGRAM HANUMAN
C----------------------------------------------------------------------
C-
C-   Purpose and Methods : MAIN program for 
C-          "HADRON NUCLEUS MEASUREMENTS ARE NECESSARY EXPERIMENT"
C-
C-   Created  27-APR-1998   Rajendran Raja   
C-
C----------------------------------------------------------------------
      IMPLICIT NONE
      LOGICAL LNKINC
      DATA LNKINC/.TRUE./
C----------------------------------------------------------------------
C
      CALL HNMAIN   
C
C  The following call to lddum is a dummy call just to get geant routines
C  loaded that are only called from geant and reside in geant.olb.  
C  the call must never actually be executed.......
C
      IF(.NOT.LNKINC) CALL LDDUM_MUC_GEANT
C
C LDDUM_XXX is a subroutine that calls all the Muc_geant specific routines that are
C different version of routines in either dd_geant, trim_d0lib/d0geant or GEANT321.
C this technique ensures that the proper routines get loaded. 
C
      STOP
      END

The routine lddum_muc_geant is not ever called but contains calls to routines that are present in duplicate form in muc_geant and dd_geant.a or in geant321.a. It further calls the subroutine lddum which is a similar construct for the library dd_geant.a which ensures that duplicate routines in dd_geant.a are given precedence over those in geant321. Anytime the user modifies a routine in either dd_geant or geant321, he should insert a call to the routine in lddum_muc_geant to ensure that the modified version (now part of muc_geant) is loaded.

 

 

 

ANALYZING and Playing Back  Events

 One can analyze the generated events while they are being generated by setting the flag ANALYZE_EVENTS to TRUE in hanuman.rcp. In addition, one can playback recorded events by setting the flags PLAYBACK_EVENTS and ANALYZE_EVENTS to TRUE in hanuman.rcp. While generating events, MUC_GEANT will save the generated output to fort.2, if the flag WRITE_EVENTS_OUT is set to true in hanuman.rcp. The generated output stream can be played back as fort.1 in the playback mode. The philosophy is to save idealized hits in each detector during generation and add resolutions and noise during playback mode. One set of generated events can be played back with many resolutions.