GEANT321/gtrak/gtrak.doc

   1 *
   2 * $Id$
   3 *
   4 * $Log$
   5 * Revision 1.1.1.1  1995/10/24 10:21:40  cernlib
   6 * Geant
   7 *
   8 *
   9 #include "geant321/pilot.h"
  10 #if defined(CERNLIB_DOC)
  11 *CMZ :  3.21/02 29/03/94  15.41.23  by  S.Giani
  12 *-- Author :
  13 *
  14 ************************************************************************
  15 *                                                                      *
  16 *                Introduction to the Tracking package                  *
  17 *                ------------------------------------                  *
  18 *                                                                      *
  19 *                                                                      *
  20 *  THE TRACKING PACKAGE                                                *
  21 *                                                                      *
  22 *  In  the context  of  simulation programs,  'tracking' a  particle   *
  23 * through matter consists of predicting the spatial coordinates of a   *
  24 * set of  points which  define the trajectory  and of  computing the   *
  25 * components  of  the  momentum  at each  point.   This  is  usually   *
  26 * achieved by integrating the  'equations of motion' over successive   *
  27 * steps and applying  corrections when necessary to  account for the   *
  28 * perturbations introduced by the interactions with matter.            *
  29 *  The tracking package contains mainly a subprogram which controls,   *
  30 * and effectively  performs, the transport  of all particles  in the   *
  31 * current  event and  of  the secondary  products  which they  might   *
  32 * possibly generate,  plus some  tools for  storing the  space point   *
  33 * coordinates computed along the corresponding trajectories.           *
  34 *                                                                      *
  35 * THE STEP SIZE                                                        *
  36 *                                                                      *
  37 *  When tracking particles through a complex medium structure one of   *
  38 * the critical tasks is the estimation  'a priori' of the step size.   *
  39 * This is performed automatically by the program.                      *
  40 *  For a particle with given  energy the step size depends primarily   *
  41 * on the properties  of the particle (mass,  charge, lifetime, etc.)   *
  42 * and of  the current medium in  which the particle is  moving.  The   *
  43 * dependence may come either  from (quasi)continuous processes which   *
  44 * usually  impose a  limit to  the interval  of integration  (energy   *
  45 * loss, multiple scattering or bending  in magnetic field) or to the   *
  46 * occurence of  a discrete process which  introduces a discontinuity   *
  47 * in   the   trajectory    (decay,   electromagnetic   or   hadronic   *
  48 * interaction).   In addition  to these  physical effects  there are   *
  49 * constraints of a geometrical nature, the step being limited by the   *
  50 * path length to the medium boundary.                                  *
  51 *  In  practice,  the step  size  depends  ultimately  on a  set  of   *
  52 * tolerances and cuts which should be  optimized by the user for the   *
  53 * given application, such as:                                          *
  54 *                                                                      *
  55 * - the maximum bending angle due to magnetic field permitted in one   *
  56 *   step,                                                              *
  57 * - the maximum fractional energy loss in one step,                    *
  58 * - the  maximum  step size  permitted  by  the multiple  scattering   *
  59 *   theory used                                                        *
  60 * - the accuracy for crossing medium boundaries and                    *
  61 * - the absolute maximum step allowed                                  *
  62 *                                                                      *
  63 *  The limitations imposed  by the first three  processes could lead   *
  64 * to extremely small steps for low energy particles.  To avoid this,   *
  65 * in  GEANT has  been introduced  a minimum  step due  to continuous   *
  66 * processes.   This represent  a lower  bound for  the maximum  step   *
  67 * which is very important for keeping  the time taken to develop and   *
  68 * follow a shower within reasonable limits.                            *
  69 *                                                                      *
  70 *  These  quantities are  part of  the so  called 'tracking  medium'   *
  71 * parameters.  They  are usually calculated automatically  by GEANT,   *
  72 * but may be provided by the user to be stored in the data structure   *
  73 * JTMED, through the  routine GSTMED [CONS].  Usually,  this is done   *
  74 * together with the initialisation  of the geometrical setup.  Users   *
  75 * are  suggested   to  begin  their  simulations   with  the  values   *
  76 * calculated by GEANT.   The optimisation is by no  means trivial as   *
  77 * the economy of  computing time should not lead  to an unacceptable   *
  78 * loss of accuracy.                                                    *
  79 *  Other  general information  required for  the computation  of the   *
  80 * step size is expected to be available in the data structures JPART   *
  81 * and  JMATE,  for  the  properties  of the  particles  and  of  the   *
  82 * materials,  and in  the  data structure  JVOLUM,  for the  current   *
  83 * medium and its geometrical  boundaries.  The communication between   *
  84 * the tracking package and the  structure JVOLUM is achieved through   *
  85 * the  basic subroutines  of the  geometry package  GMEDIA (GTMEDI),   *
  86 * GNEXT (GTNEXT) and GINVOL [GEOM,GTRAK]                               *
  87 *  Some additional information is computed  at tracking time such as   *
  88 * the probability  of occurence of an  interaction.  For convenience   *
  89 * every particle is assigned a 'tracking  type', 1 for the gammas, 2   *
  90 * for the  electrons and positrons,  3 for the neutral  hadrons (and   *
  91 * neutrinos!), 4 for the charged hadrons and 5 for the muons.  Which   *
  92 * physics processes  have potentially to  be considered for  a given   *
  93 * particle depends on its tracking type.  For the hadrons it depends   *
  94 * also, through  the subroutine GUPHAD, on  which hadronic processes   *
  95 * have been selected (GHEISHA is the default) [PHYS 001].              *
  96 *                                                                      *
  97 * THE SUBROUTINES GTREVE and  GTRACK                                   *
  98 *                                                                      *
  99 *  At  event level  the  tracking is  controlled  by the  subroutine   *
 100 * GTREVE called by  the subroutine GUTREV where the user  is free to   *
 101 * take any other action.  GTREVE  loops over all vertices and stores   *
 102 * all tracks  from the current vertex  in the stack JSTAK,  then for   *
 103 * each  one  in  turn,  calls  GLTRAC to  prepare  the  commons  for   *
 104 * tracking,  and starts  tracking through  a call  to GUTRAK,  which   *
 105 * calls GTRACK.                                                        *
 106 *  The subroutine GTRACK  tracks the particle up to the  end : stop,   *
 107 * decay, interaction  or escape.   During this  phase it  may happen   *
 108 * that secondary products  are generated and stored by  the user, as   *
 109 * explained  below, in  the stack, and if  wanted, in  the permanent   *
 110 * structure JKINE.                                                     *
 111 *  The subroutine GTRACK loops over  all geometrical volumes seen by   *
 112 * the  current  track,  first identifying,  through  the  subroutine   *
 113 * GTMEDI, the new volume which  the particle has reached and storing   *
 114 * the corresponding  material and  tracking medium constants  in the   *
 115 * common blocks /GCMATE/ and /GCTMED/; the tracking is controlled by   *
 116 * the  type-dependent  routines  GTELEC,GTGAMA,GTHADR,GTMUON,GTNEUT.   *
 117 * These compute  the physical step  size according to  the activated   *
 118 * physics processes, and compute the geometrical limit for the step,   *
 119 * only when  necessary, through  GTNEXT, and propagate  the particle   *
 120 * over the computed step.                                              *
 121 *                                                                      *
 122 * MAGNETIC FIELD ROUTINES                                              *
 123 *                                                                      *
 124 *  As mentioned before,  the effective propagation of the particles is *
 125 * controlled by the routines GTGAMA, GTELEC, etc., which call GUSWIM.  *
 126 * Depending on the  value chosen by the user for  the tracking medium  *
 127 * parameter IFIELD the routine GUSWIM calls either                     *
 128 *                                                                      *
 129 * GRKUTA    for inhomogeneous fields, IFIELD=1                         *
 130 * GHELIX    for quasi-homogeneous fields tilted w.r.t. the reference   *
 131 *           frame, IFIELD=2, or                                        *
 132 * GHELX3    for one-component fields along the z axis, IFIELD=3        *
 133 *                                                                      *
 134 *  GRKUTA and  GHELIX call the  default user subroutine  GUFLD where   *
 135 * the  components of  the field  at  the given  point are  computed.   *
 136 * GHELX3  takes  the value  of  the  field  in the  tracking  medium   *
 137 * parameter FIELDM.                                                    *
 138 *                                                                      *
 139 * INFORMATION AVAILABLE AT TRACKING TIME, AND THE SUBROUTINE GUSTEP    *
 140 *                                                                      *
 141 *  At any  moment the  current track parameters  are available  in the *
 142 * common block  /GCTRAK/ as well  as all  variables which have  to be  *
 143 * preserved by  the tracking  routines for  the control  of the  step  *
 144 * size.  In  addition a  few flags  and variables  are stored  in the  *
 145 * common block /GCTRAK/ to record the history of the current step:     *
 146 *                                                                      *
 147 * INWVOL    is initialized  to 1 when  entering a new volume,  it is   *
 148 *           set to  0 for all steps  inside the volume, to  2 if the   *
 149 *           particle has reached  the volume boundary and  to 3 when   *
 150 *           the particle is leaving the experimental setup.            *
 151 * ISTOP     is initialized to 0 and set  to 1 if the particle looses   *
 152 *           its identity or to 2 if it stops.                          *
 153 *                                                                      *
 154 *  The effect  which is responsible  for the limitation of  the step   *
 155 * size as well as the corrective  effects which have been applied at   *
 156 * the end of the step, if any,  are recorded in the first NMEC words   *
 157 * of the mechanism vector LMEC and this is most useful to understand   *
 158 * and debug the program.                                               *
 159 *  The  total energy  loss for  the current  step is  stored in  the   *
 160 * variable DESTEP, and the continuous energy loss in DESTEL.           *
 161 *  This information  is necessary  for the user  to take  the proper   *
 162 * actions in the subroutine GUSTEP which  is called by GTRACK at the   *
 163 * end of every step.                                                   *
 164 *  In addition, the  number NGKINE of secondary  products which have   *
 165 * possibly been  generated and  their characteristics are  stored in   *
 166 * the common  block /GCKING/ together with  an identification (array   *
 167 * LMEC)  of   which  process  is  responsible.    Depending  on  the   *
 168 * application  and on  the particle  type,  the user  may decide  in   *
 169 * GUSTEP through the routine GSKING,                                   *
 170 *                                                                      *
 171 * - to discard the newly produced secondaries                          *
 172 * - to  enter them  in  the  temporary JSTAK  data  structure to  be   *
 173 *   tracked                                                            *
 174 * - to  store them  in  the  permanent JKINE  data  structure to  be   *
 175 *   tracked                                                            *
 176 *                                                                      *
 177 * CONNECTION WITH THE DETECTOR RESPONSE PACKAGE                        *
 178 *                                                                      *
 179 *  The loop over the volumes in  GTRACK makes the interface with the   *
 180 * detector response  package simple [HITS].  By  construction of the   *
 181 * geometrical setup  there is  a correspondance between  the volumes   *
 182 * seen by  the particle and  the components of the  detectors.  When   *
 183 * entering a new volume (in GTRACK) the subroutine GFINDS is called.   *
 184 * If  the volume  has  been  declared by  the  user  as a  sensitive   *
 185 * detector   through  appropriate   calls  to   GSDET  and   if  the   *
 186 * corresponding tracking  medium constant ISVOL is  non zero, GFINDS   *
 187 * returns in the  common block /GCSETS/ the  information to identify   *
 188 * uniquely the detector component.  This  enables the user in GUSTEP   *
 189 * to  record the  hits  properly  as well  as  the energy  deposited   *
 190 * [HITS].                                                              *
 191 *                                                                      *
 192 * CONNECTION WITH THE DRAWING PACKAGE                                  *
 193 *                                                                      *
 194 *  The coordinates of the space points generated during the tracking   *
 195 * are  available at  each step  in  the common  block /GCTRAK/.   In   *
 196 * GUSTEP the user can store them in the structure JXYZ with the help   *
 197 * of the subroutine  GSXYZ.  This information can be  used later for   *
 198 * debug (subroutine  GPCXYZ) or for the  graphical representation of   *
 199 * the trajectories [DRAW].                                             *
 200 *                                                                      *
 201 ************************************************************************
 202 #endif