GUIDE TO BRAHMS GEANT SETUP

Flemming Videbaek Physics department Brookhaven National Laboratory Upton,NY 11973

Latest update 12/30/97

This is a short guide which is meant to enable you to get started using GBRAHMS, the interactive version of GEANT setup for the BRAHMS magnetic spectrometer setup. In addition to this short guide you will definitely also need the manual or the HTML pages for GEANT3.21 (often called 3.16 in the CERN documentation) and the description of the commands for the interactive version. The setup of the BRAHMS geant has undergone many revisions so what used to work may not be appropriate any more.

Directory structure
Utility Directories
Examples

Directory structure

The GBRAHMS is now setup exclusively for the UNIX systems, essentially for the linux, though it has been working on many other systems. for On the rhic afs the directory structure follows the following layout. There are different roots but the lower paths are:


afs:
      /afs/rhic/brahms/BRAHMS_LIB/geant/[version]

	the version can be among the following
	[version]  VER_DEV
		   VER_1.4
		   VER_1.5

   geant --
	 |
	 |
	 -- bin -|- irix      ; sgi executable
	 |       |
	 |       |- aix       ; RS6000 only relevant for /afs tree
	 |       |
	 |       |- linux     ; For linux farm

	 |
	 |- lib -|- irix      ; sgi object library and objects
	 |       |	
	 |       |- aix	
	 |       |
	 |       |- linux     ; For linux farm
	 |       	
	 |- src -| - user     ; Brahms specific routines
	 |       | - gene     ; general geant routines
	 |       | - fms1     ; front part of forward spectrometer
	 |       | - fms2     ; back part of forward spectrometer
	 |       | - mids     ; mid-rapidity spectrometer
	 |       | - global   ; global detectors
	 | 
	 |- inc

The executable exists for Linux. The program will also compile for AIX, SGI but no machines exists as such for RCF.

The GBRAHMS executable defines a standard configuration of the spectrometer. Angles, magnetic fields etc are set-table by commands. In addition it is possible to change parameters of the basic detector configuration like the size of magnet gaps, width of detectors etc.

The following is an example which defines the two arms of the forward spectrometer but do not have the mid rapidity arm included.

   /afs/rhic/brahms/BRAHMS_LIB/geant/VER_DEV/bin/irix/gbrahms

   setup> set_tree fms1 o
   setup> set_tree fms2 o
   setup> set_tree mids o
   setup> geodef

At this point the standard setup is given , and the user can add more volumes interactively by commands. After this is done the setup is terminated by


   setup> geodef

and GEANT is now ready to accept the usual commands for selecting kinematics, triggering, display etc.


   GEANT>

example for mid rapidity arm

   setup> set_tree fms1 z
   setup> set_tree fms2 z
   setup> set_tree mids o
   setup> set_param m0 angle 34
   setup> set_param m0 distance 290
   setup> geodef
   .

This sets the angle to 34 deg and the center of M0 to 290 cm. The rest of the detectors in the mid-rapidity spectrometer is moved with the dipole. With the most recent setups there should be no reason to change the specific distance.

BRAHMS Utility directories

The directories on RCF are defined as prescribed above. In addition additional directories are made to keep kumac files which defines default setting for spectrometers, commonly used kumac and scripts (command files). The directories contain kumac files. The master version is on the AFS file system.

There is a common set of macro's in the globally accesible place /afs/rhic/brahms/BRAHMS_LIB/proj/macro

add_logo [x] [y] [size]
add the colorfull BRAHMS logo to a plot
topview [x] [z] [size]
from within geant execute a 'draw cave ..' with parameters corresponding to a topview on absolute position (x,z) given in cm.

Macros in /afs/rhic/brahms/BRAHMS_LIB/proj/setup

beam_def.kumac
Several macros for beam pipe setups; There is still an issue on what default set should be. As of now do not use these macro's; Stick to the default setup.

setup.kumac
spectrometer setup's entry: mrs angle=[value] ; setup MRS at given angle; entry: fs_may97 [parameters] (current setup)

field.kumac
spectrometer field configurations. execute exec field to see posibilities;

There is not a special need to copy these files, inside the Geant session they can be accessed directly using the search list feature of the KUIP commands e.g.

GEANT> macro/default '.,/afs/rhic/brahms/BRAHMS_LIB/proj/setup,/rhic_data/code/proj/macro'

Example for FS

As an example for a setup at 2 degrees with the full complement of the spectrometer which accepts momenta from 7-20 Gev/c execute the following macro.

GEANT>exec fms_setup#2deg-66-plus

Examples of How To

This section gives some examples how to perform various features within the BRAHMS GEANT. They are not complete examples, but by combining them you should be able to make your analysis.

Reading data from event generated files

One can read data from LUND and VENUS output files into GEANT. Since these files for RHIC events can be extremely large there are options so you can cut down on what is read into the program. Quit often the detector only covers a small solid angle and many particles are generated in parts of the phase space which is not interesting. One can define which part of the phase space is of interest.


KUIP commands for setting the input file.
      On VAX the following logical name must be defined.
      $ define tape1 hi0$event:[rhic_data]auau_lund.zdat

On SGI you must have made a logical link before entering the program.
      >ln -is /rhic_data/data/venus/auau_venus.dat tape1

      * open the event file
      CARDS UKIN 5 TAPE1
      * set the range of the kinematic region
      * to 1<&< p- 50  3 theta in 8 -15 - phi - 15
      KINE 1 1. 50. 3. 8. -15. 15. 8.
      *   read the first event
      TRIG 1

Setting the magnetic fields.

The magnitude of the magnetic fields are set by the user command SET_FIELD. There are 5 fields that can be set. For the forward spectrometer they can be set as follows. At present only the effective edge is implemented. The field boundary is given by at half the gap before the core such that the total length is the length of the core plus the gap size. The field is constant over this entire range. The effective edge can also be set to be just inside the magnetic gap by means of the GAP representation of the field.

*     set D1 = -8 KG D2 = -8KG
set_FIELD D1 -8 edge
set_FIELD D2 -8 edge

set_field M0 6 GAP
...
*

The command FIELD .. is now obsolete and should be avoided.
Due to the internal representations of the magnetic properties these commands are only effective following the geodef command which defines the GEANT geometry and also calculated auxiliary parameters.

Analyze Large event

Another feature which is useful and needed is to be able to split an event into sub-events which are tracked independtly. In the analysis you must of cause know how this is done. There are two variables available for the user analysis program which can be used to find when a real event is beginning and ending, and not just the sub-event.

This feature is set by the command SPLIT 5. This e.g. means that at most 5 tracks are traced per GEANT run. Since the user must trigger GEANT for each sub-event there is a special command has been implemented which will trigger and call an analysis program for n real events. This can be done by issuing the command

      >ANALYZE gxant 100
      ie. read 100 complete events and call the routine gxant for each event
      and sub-event.

Ntuple analysis

Most analysis as well as the input to the tracking program SONATA is so far being done by saving the results from the GEANT runs in Ntuple form. Two examples of this can be found in geant/ana/anantp.f and m_anantp.f. These two COMIS functions are used to generate Ntuples which can be used in studies of backgrounds, resolution, etc of the detector systems. There are also a set of functions which can read the Ntuples thus generated and create an ASCII file as input for the SONATA tracking program.

	Example of usage:

	>call anantp.f
	>call nthst('geant_hit_ntp.hbk')
	>analyze ntana 100
	>call ntend

This will first book the Ntuple (id no 1) and then fill it for 100 Geant events. Remember that even if the events are split over several events the numbering scheme in the Ntuple keeps track with the real event number. In this same directory is also an example how to read the Ntuple in a paw session using the COMIS routine hits.f.

C stream files.

There is another comis function which can store the output from GEANT rtaher than in Ntuple in a C-stream file. Files created this way can be read by several other program, and should be considered the preferable way of doing analysis (10/10/97).

The following is how this is called and used

	Example of usage:

	>call gbr2c.f
	>call nthst('geant_out.cdat')
	>analyze ntana 100
	>call ntend

The output file can be read by several programs now. The only draw back is that the files are not transportable between architectures with little endian/ big endian internal storage. The following programs/utilities can read the files.

Sonata. Choose input mode stream.
gb2cwn. A hbook based program which creates a coulomn wise ntuple from the data. Code and makefile can be found in /geant/ana/gbr directory. The input to the program is gb2cwn [inoutfile] [ntuplefile]. The data are swapped if need be. The output is a Column Wise Ntuple. For the precise meaning of the parameters please consult the code.
gb2a. A C++ program which acts as an eventdump utility. Can be found in /geant/ana/gbr directory.
The gbr_getevt AMI for STAF. Can read file and generate tables of the kind ghits and gtrack.

gb2cwn

A hbook based program which creates a coulomn wise ntuple from the data. It is a fairly straight forward mapping of the gtrack and ghits data structures used in the c-stream files. There is duplicate information and the hits structures in the Ntuple common for hits do contain trackinformation, such that no search are needed to find e.g. pid information for a given hit.

The command to invoke the program is gb2cwn [inoutfile] [ntuplefile],
where [inoutfile] is the c-stream file and [ntuplefile] the name of the Ntuple file. The data are byte swapped if need be. The output is a Column Wise Ntuple.

Code and makefile can be found in /geant/ana/gbr directory. The program is in the gb2cwn.F (note the capital F) and the makefile is invoked by
make -f gb2cwn.mk

There are some severe problems with the CWN. Hbook does apperently not allow for more than 50,000 columns. This is a problem for the architecture chosen for the Ntuples. This will have to be reconsidered.

Replay of GEANT output

One can in a GEANT run track the particles, record the hits, and store this information in a FZ-files. This can then later be read back for additional analysis within a given geometry without the need for rerunning GEANT but only running the analysis program. Of cause on cannot change any of the geometry variables this way. The user should specify what information should be saved for each event and the file. During the input the full geometry and drawing tools are available to the user.


KUIP commands for generating a file ---
      * open the FZ output file
      USER/FZ/DATOUT O gout.fzd
      * specify to save track, vertex, hit and point information
      CARDS SAVE 4 KINE VERT HITS JXYZ
      * analyse 200 events
      TRIG 200
      *close the file
      USER/FZ/DATOUT C
      ...

KUIP commands for later analyzing these events
      * open the FZ file
      USER/FZ/DATIN O gout.fzd
      * speify what data structures to read
      CARDS CGET 3 KINE VERT HITS
      * call a comis routine for each event
      * 100 events will be read back
      REPLAY 100 MYANA.FOR
      ...

Additional information

Since it is not always easy to maintain the tex files and keep them up to date two other means of information is available. In the geant\doc directory a file geant_history.html exists. Whenever updates are made to the code this file should be updated and a copy transferred to the BRAHMS WWW pages on the RCF machines.