Introduction to GEANT3

+-------------+                                               +----------##
| Geant 3.15  |               GEANT User's Guide              | BASE001  ##
+-------------+                                               +----------##
                                   

                                   

Author(s) : F.Bruyant                                  Submitted: 01.10.84
Origin    : GEANT3                                       Revised: 15.05.91
                                  

GEANT3 applications

The GEANT3 program describes the passage of elementary particles through the matter. Originally designed for the High Energy Physics experiments, it has today found applications also outside this domain in the areas of medical and biological sciencies, radioprotection and astronautics. The principal applications of GEANT3 n High Energy Physics are:

1. the tracking of particles through an experimental setup for simulation of detector response
2. the graphical representation of the setup and of the particle trajectories.

It is of course desirable and very instructive to combine the two interactively since the observation of what happens to a particle inside the detector makes the debugging easier and may underline the weaknesses of the setup (also sometimes of the program!).

In view of these applications, the GEANT3 system allows:

1. to describe an experimental setup in an efficient and simple way. The setup is represented by a structure of geometrical VOLUMEs. Each volume is given a MEDIUM number by the user. Different volumes may have the same medium number [GEOM]. A medium is defined by a set of parameters, the so-called TRACKING MEDIUM parameters, which include reference to the MATERIAL filling the volume [CONS],
2. to accept events simulated by standard Monte Carlo generators [KINE].
3. to simulate the transport of particles through the various regions of the setup, taking into account the geometrical volume boundaries and all physical effects due to the nature of the particles themselves, to their interactions with the matter and to the magnetic field [TRAK, PHYS],
4. to record elements of the particle trajectories and the response from the sensitive detectors [TRAK, HITS],
5. to visualize the detectors and the particle trajectories [DRAW, XINT].

The program contains dummy and default user subroutines called whenever application dependent actions are expected.

It is the responsibility of the user to assemble the appropriate program segments and utilities into an executable program, to code the relevant user subroutines, to provide the data describing the experimental environment and to compose the appropriate data cards which control the execution of the program. The section BASE of this User's Guide gives the information necessary to do the job.

Note:

As a general convention the names of the dummy or default user subroutines have GU or UG as first two letters and are printed in bold characters.

Event simulation framework

The framework offered by GEANT for event simulation is described in the following paragraphs, to familiarize the reader with the areas where user interventions are expected.

At the same time, the GEANT3 data structures are introduced. This point is important as the coding to be provided by the user most often consists of filling data structures, or extracting information from them, or saving them on output, making use of standard routines available in the system.

A main program has to be provided by the user [BASE 100] for batch type operation. The intefactive main program provided in the GEANX file (GXINT) can be used instead. The main program allocates the dynamic memory for ZEBRA and HBOOK and gives control to the three phases of the run:

1. Initialisation
2. Event processing
3. Termination.

   Initialisation

   The initialisation phase is under the control of the user [BASE 100]. It consists of the following steps, most of them performed through calls to standard GEANT3 subroutines:

   GINIT

   to initialize the GEANT3 common blocks with default options (see [BASE 030, 110]).

   GFFGO

   to read free format data cards with the possibility of overriding the default options [BASE 040, 110].

   GZINIT

   to initialize the dynamic core divisions, the link areas and the Run header bank JRUNG [BASE 110].

   GDINIT

   to initialize the drawing package [DRAW].

   GPART

   and auxiliaries, to generate the data structure JPART describing the standard particle properties [CONS].

   GMATE

   and auxiliaries, to generate the data structure JMATE describing the characteristics of the most commonly used MATERIALs [CONS].

   User code

   to define the geometry of the different components of the experimental setup [GEOM] and the tracking medium parameters [CONS,TRAK], and to generate the corresponding data structures JROTM, JVOLUM and JTMED. Also to specify which elements of the geometrical setup should be considered as sensitive detectors, giving a response when hit by a particle [HITS].

   GGCLOS

   to process all the geometrical information provided by the user and get ready for the tracking.

   GBHSTA

   to book standard GEANT3 histograms if required by the user with the data card HSTA [BASE 040, 110].

   GPHYSI

   to compute energy loss and cross section tables and to store them in the data structure JMATE [CONS,PHYS].

   Event processing

   The processing phase is triggered by a call to the subroutine GRUN which, for each event to be processed, gives control to the subroutines:

   GTRIGI

   to initialize event processing and to create the Event header bank JHEAD.

   GTRIG

   to process one event.

   GTRIGC

   to clean up the portion of dynamic core used by the event and checks that enough time is left for the next event [BASE 200].

   The main steps of GTRIG consist of calls to the following user routines:

   GUKINE

   generates the data structures JVERTX and JKINE describing the kinematics of the current event on input [KINE], or reads them [IOPA].

   GUTREV

   calls GTREVE which for each original vertec in turn, fills the temporary stack ISTAK with all original track attached to that vertex and controls the propagation of each particle though the setup by calling GUTRAK/GTRACK [TRAK]. In the (default) sequantial tracking mode, each particle is tracked in turn and when a sensitive detector is hit, the user may store any useful information in the data structure JHITS [HITS]. Before going to the next particle any secondary products generated by a given particle, and stored by the user in the temporary data structure JSTAK, are processed in the same way. Simultaneously, the data structure JXYZ, containing the coordinates of space points along the tracks for the whole event, can be filled by the user [TRAK].

   GUDIGI

   simulates the detector responses for the whole event, making use of the information previously recorded in the data structure JHITS, and stores the results in the data structure JDIGI [HITS].

   GUOUT

   outputs the relevant data structures for the current event [IOPA].

   Other routines called during the tracking phase triggered by GTREVE should be mentioned for completeness:

   1. The hadronic processes activated by default for the tracking of hadrons in GEANT3 have been adapted from the program GHEISHA [PHYS]. In the subroutines GUPHAD and GUHADR [TRAK] the user may select the hadronic shower generation program to be used, the standard for GEANT is the GHEISHA program.
   2. After each tracking step along a given track in a given medium, control is given to the subroutine GUSTEP. From the information available in labelled common blocks the user is able to take the appropriate action, such as storing a hit or transfering a secondary product either in the stack JSTAK (or in the event structure JVERTX/JKINE, or in both) through the subroutine GSKING. In the subroutine GSSTAK, called by GSKING, a user routine GUSKIP is called which permits to skip any unwanted track before entering it in the stack.
   3. The subroutine GUSWIM is called by various tracking routines to select the appropriate code for transport of the particle over the given tracking step.
   4. The magnetic field, unless constant with no X- or Y-component, has to be described in the subroutine GUFLD.

   Termination

   The termination phase is under the control of the user [BASE 300]. For trivial applications it may simply consist of a call to the subroutine GLAST which computes and prints some statistical information (time per event, use of dynamic memory, etc.).