*
* $Id: ggeom.doc,v 1.2 2009/02/16 06:00:48 schubert Exp $
*
* Revision 1.1.1.1  2002/06/16 15:18:38  hristov
* Separate distribution  of Geant3
*
* Revision 1.1.1.1  1999/05/18 15:55:17  fca
* AliRoot sources
*
* Revision 1.1.1.1  1995/10/24 10:20:47  cernlib
* Geant
*
*
#include "geant321/pilot.h"
#if defined(CERNLIB_DOC)
*CMZ :  3.21/02 29/03/94  15.41.28  by  S.Giani
*-- Author :
*
************************************************************************
*                                                                      *
*            Introduction to the Geometry package                      *
*            ------------------------------------                      *
*                                                                      *
*                                                                      *
* THE GEOMETRY PACKAGE                                                 *
*                                                                      *
*  The geometry package consists of subroutines which can be used in   *
* the initialisation phase  of the program to  describe the geometry   *
* of the  experimental set-up, and  of subroutines which  ensure the   *
* communication  with   the  tracking   package  during   the  event   *
* processing phase.                                                    *
*  The  following paragraphs  review  the concepts  of the  geometry   *
* package  and explain  how  the geometrical  information should  be   *
* provided by the user.                                                *
*  It  is important  to point  out that,  once the  set-up has  been   *
* initialized, the tracking of particles through the different media   *
* can proceed without  any other intervention from  the user [TRAK].   *
* The  connection  between the  geometry  and  tracking packages  is   *
* established  by the  subprograms  GMEDIA/GTMEDI, GNEXT/GTNEXT  and   *
* GINVOL which answer respecti- vely the questions :                   *
*                                                                      *
* - In which medium is a given point ?                                 *
* - What is the path length to the next medium ?                       *
* - Is a given point still in the current medium ?                     *
*                                                                      *
* (The routines GTMEDI  and GTNEXT are used in a  dynamic context at   *
* tracking  time,  where  information  about the  direction  of  the   *
* particle can be used to save time).                                  *
*                                                                      *
* THE VOLUME DEFINITION                                                *
*                                                                      *
*  Experimental set-ups,  as complex  as the detectors  prepared for   *
* LEP, can be described rather  accurately through the definition of   *
* a  set of  simple VOLUMES.   Each VOLUME  is given  a NAME  and is   *
* characterized by:                                                    *
*                                                                      *
* - a  SHAPE identifier,  specifying  one of  the basic  geometrical   *
*   shapes  available [GEOM010],  the shape  parameters, giving  the   *
*   dimensions of the volume,                                          *
* - a local  reference system,  whose origin and  axes are  the ones   *
*   defined for the given shape (cartesian, cylindrical or spherical   *
*   coord.),                                                           *
* - its physical  properties, given  by a set  of constants  for the   *
*   homogeneous MATERIAL which fills the volume [CONS],                *
* - additional  properties, known  as  'TRACKING MEDIUM'  constants,   *
*   which depend  on the characteristics  of the volume  itself (the   *
*   MATERIAL  identifier  is  one  of  the  constants)  and  on  its   *
*   geometrical   and  physical   environment  (properties   of  the   *
*   neighbour media, magnetic field, etc.) [CONS,TRAK],                *
* - a set of attributes, in  connection with the drawing package and   *
*   the detector response package [DRAW,HITS].                         *
*                                                                      *
*  As long as  it is not 'positioned' in a  given reference frame, a   *
* VOLUME is an entity which has no spatial relation with the set-up.   *
* By convention,  a unique  initial volume has  to be  defined which   *
* should match  (or surround) the  outside boundaries of  the entire   *
* set-up.  The reference frame attached to this volume is considered   *
* to be the master reference frame.                                    *
*                                                                      *
* VOLUMES WITH CONTENTS                                                *
*                                                                      *
*  A VOLUME can be declared to have 'contents' and become a 'mother'   *
* volume.   The contents  are  either predefined  volumes which  are   *
* explicitly positioned inside the mother,  or new volumes which are   *
* implicitly defined by a division  mechanism applied to the mother.   *
*  Positioning a  volume with  given shape  and dimensions  inside a   *
* mother  volume  is  achieved  by specifying  its  translation  and   *
* rotation with  respect to  the mother  reference frame.   The user   *
* should make  sure that  no volume overlaps  the boundaries  of its   *
* mother.  When a volume is positioned,  the user gives it a NUMBER.   *
* Multiple copies of a given  volume, with different numbers, can be   *
* positioned inside  a mother  or inside  different mothers  and the   *
* contents of the volume are reproduced implicitly in all copies.      *
*  Divisions can  be performed along  any of  the three axes  of the   *
* mother volume.   The definition of  the axes (X,Y,Z or  R..,.,Z or   *
* R,.,.) depends on  the shape.  The mother volume  can be partially   *
* or  totally divided.   The  division generates  a  cell, which  is   *
* considered as  a new volume with  (usually) the same shape  as the   *
* mother.   Its dimensions  are computed  according to  the declared   *
* division number and/or  step size.  This cell, as  any volume, can   *
* again  be divided  along any  of its  proper axes,  or have  other   *
* volumes positioned into it.  Volumes  positioned within a cell are   *
* reproduced implicitly in all cells.                                  *
*  These operations permit a physical  tree to be defined of volumes   *
* at deeper and deeper levels.                                         *
*  It  is  assumed that  the  'tracking  medium' properties  of  the   *
* contents replace  the ones of  the mother within the  space region   *
* they occupy.                                                         *
*  A  VOLUME  is  therefore  defined   not  only  by  its  intrinsic   *
* characteristics but  also by the definition  of its 'descendants',   *
* namely its contents, the contents of its contents, etc.              *
*                                                                      *
* OVERLAPPING VOLUMES                                                  *
*                                                                      *
*  The user  may define volumes  which have  nothing to do  with the   *
* real physical structure.   It is sometimes convenient  to make use   *
* of  such  volumes, to  artificially  delimit  regions with  simple   *
* shapes.  As a consequence, it may happen that volumes overlap each   *
* other.  (A volume  positioned  inside a  mother  is obviously  not   *
* regarded as overlapping the mother).                                 *
*  The handling  of overlapping  volumes has some  implications that   *
* the user should be aware of:                                         *
*  A flag  'ONLY/MANY' is attached  to each positioned  volume.  The   *
* 'MANY' option  indicates that a point  found to be in  this volume   *
* could also be in other volumes which are not direct descendants of   *
* it.  The user is free to declare one of the overlapping volumes as   *
* 'ONLY', in which  case the medium searching  subroutines will give   *
* priority to this volume.                                             *
*  If  a point  is inside  several  'MANY' volumes  and outside  all   *
* 'ONLY' ones, priority  will be given to the first  volume found at   *
* the  deepest  level  and,  in  order  to  avoid  ambiguities,  two   *
* overlapping 'MANY' volumes should in  general be assigned the same   *
* default tracking medium.                                             *
*                                                                      *
* THE PHYSICAL TREE                                                    *
*                                                                      *
*  The package accepts a maximum of 15 levels, which should be quite   *
* enough to represent even the fine details of a complex set-up.       *
*                                                                      *
* THE DATA STRUCTURE JVOLUM AND THE COMMON BLOCK /GCVOLU/              *
*                                                                      *
*  In practice, the  physical tree is represented by  a logical tree   *
* structure, the  JVOLUM data structure [GEOM  199], which describes   *
* the arrangement of  volumes in a compact and  recurrent way.  Each   *
* generic  volume  appears once,  and  once  only, and  carries  the   *
* information relevant to the volume  itself and to its contents, if   *
* any, by  reference to the  generic volumes corresponding  to those   *
* contents.                                                            *
*  In the situation  where division or multiple  copies occur, there   *
* is no longer a one-to-one correspondence between a given volume in   *
* the logical tree and a unique region in space.  Information has to   *
* be kept at tracking time to  identify which division cell or which   *
* copy was considered at each depth level along the path through the   *
* physical  tree.   This information  is  stored  by the  subroutine   *
* GTMEDI, for the current point of  the current track, in the COMMON   *
* /GCVOLU/.   It contains  the current  LEVEL and,  for each  level,   *
* starting   from   the   first  initial   reference   volume,   the   *
* identification of  the corresponding  volume, e.g.:  NAME, NUMBER,   *
* 'ONLY/MANY'  flag, translation  and rotation  with respect  to the   *
* master reference  frame.  The SHAPE  parameters and the  number of   *
* parameters  (initialy  stored  in  /GCVOLU/)  are  stored  in  the   *
* separate structure JGPAR.                                            *
*                                                                      *
* THE BASIC USER TOOLS                                                 *
*                                                                      *
*  The rules of the game being  established, it is easy to introduce   *
* the  set of  subroutines  which ensure  the  functionality of  the   *
* package.   The user  can define  a volume  through a  call to  the   *
* subroutine:                                                          *
*                                                                      *
* GSVOLU    Input arguments  specify the NAME, SHAPE  and parameters   *
*           of the volume.  An  output argument returns the position   *
*           of the volume inside the bank JVOLUM.                      *
*                                                                      *
* The user can position a volume through a call to either one of the   *
* following subroutines:                                               *
*                                                                      *
* GSPOS     Input arguments specify the NAME  and copy NUMBER of the   *
*           volume to  be positioned,  the NAME  of the  mother, the   *
*           translation and the rotation matrix, and the 'ONLY/MANY'   *
*           flag.                                                      *
* GSPOSP    In case  the user has to  position , inside a  mother, a   *
*           large  number  of  volumes   with  the  same  shape  but   *
*           different dimensions  (lead glass blocks,  BGO crystals,   *
*           etc.)  an  alternative  is proposed  which  consists  of   *
*           defining  the generic  volume once,  with the  number of   *
*           shape parameters  set to  zero, and  to call  GSPOSP for   *
*           each volume  in turn, with  the same arguments  as GSPOS   *
*           plus  the   shape  parameters.   The  volumes   will  be   *
*           identified  by their  NAME+NUMBER  as  for the  multiple   *
*           copies.                                                    *
*                                                                      *
* The user can divide  a volume through a call to  either one of the   *
* following subroutines:                                               *
*                                                                      *
* GSDVN     Input arguments specify the NAME of the cell volume, the   *
*           name  of  the  MOTHER   being  divided,  the  number  of   *
*           divisions NDIV and the axis  along which the division is   *
*           performed.   In  this  simple case,  the  cell  tracking   *
*           medium is assumed to be the same as for the mother.        *
* GSDVS     The division STEP is given  instead of NDIV and the cell   *
*           tracking medium is specified.                              *
* GSDVX     In addition  to both STEP and  NDIV , the origin  of the   *
*           first cell and the cell tracking medium are specified.     *
*                                                                      *
* THE OPTIMISATION TOOLS                                               *
*                                                                      *
*  When a  track enters a volume  with contents, the search  time to   *
* identify whether the  current point is in the mother  or in any of   *
* the contents  is very short  when the contents are  division cells   *
* (straightforward computation  along the relevant axis).   When the   *
* contents have been positioned, the search time can be quite large.   *
* In order  to save  time the  user can  make use  of either  of the   *
* following facilities:                                                *
*                                                                      *
* GSORD/GGORD                                                          *
*   From the  known position of  the contents inside a  given volume   *
*   the subroutine  GGORD computes  fictitious boundaries  along the   *
*   specified  coordinate, simulating  a division  with non  regular   *
*   step size.  A binary search technique is used to identify within   *
*   which pseudo-cell  the current  point is.   The slow  process of   *
*   computing whether the point is inside or outside the contents is   *
*   therefore limited  to the few  (if any) volumes sitting  in that   *
*   pseudo-cell.  The  coordinate selected  for the  pseudo division   *
*   can be any of X, Y, Z, Rxy, R, Phi or Theta.  GSORD is called by   *
*   the user to  flag which volume should have  its contents ordered   *
*   and along which axis.  GGORD is  called by GGCLOS.  The user can   *
*   select via the data record OPTIM to automatically call GSORD for   *
*   all the volumes with content.  In  this case the system will try   *
*   to choose  the best axis  along which  to order the  contents of   *
*   every mother in the tree.                                          *
*                                                                      *
* GSNEXT - GSNEAR                                                      *
*   When a particle enters a mother volume, the contents are scanned   *
*   initially in the  order they have been positioned,  and the user   *
*   should  take  care  over  the  best  sequence  of  GSPOS  calls.   *
*   However, when the particle comes back inside the mother from any   *
*   one of the contents, it is  usually possible to limit the search   *
*   to the neighbour contents.  The subroutines GSNEXT,GSNEAR permit   *
*   the user to  inject at initialisation time, for  each content in   *
*   turn, the  list of neighbours  to search  for.  A proper  use of   *
*   this facility can reduce the search time significantly.            *
*                                                                      *
* GSUNEA/GUNEAR                                                        *
*   To specify any user ordering for the contents of a given volume.   *
*                                                                      *
*       Labelled COMMON blocks related to section GEOM                 *
*       ----------------------------------------------                 *
*                                                                      *
*       COMMON /GCPOLY/ IZSEC, IPSEC                                   *
* C                                                                    *
* IZSEC     Z-section number                                           *
* IPSEC     Phi-sector number                                          *
*                                                                      *
*       COMMON/GCVOLU/NLEVEL,NAMES(15),NUMBER(15),                     *
*      +LVOLUM(15),LINDEX(15),INFROM,NLEVMX,NLDEV(15),LINMX(15),       *
*      +GTRAN(3,15),GRMAT(10,15),GONLY(15),GLX(3)                      *
* C                                                                    *
* NLEVEL    Level number at which the last medium search stopped.      *
* NAMES     Volume names at each level.                                *
* NUMBER    User volume numbers at each level.                         *
* LVOLUM    System volume numbers at each level.                       *
* LINDEX    Physical tree volume indices at each level.                *
* INFROM    Number of  the content  a particle  has just left,  when   *
*           relevant                                                   *
* NLEVMX    Maximum number of levels in given geometry tree            *
* NLDEV     Levels where local development take place, if non 0        *
* LINMX     numbers of contents (position) or cells (division)         *
* GTRAN     X,Y,Z    offsets    of   the    cumulative    coordinate   *
*           transformation from  the master system to  the system at   *
*           each level.                                                *
* GRMAT     Rotation    matrix   elements    for   the    cumulative   *
*           transformation from  the master system to  the system at   *
*           each level.  GRMAT(10,LEVEL) equal  to 0.0 indicates the   *
*           null rotation.                                             *
* GONLY     Uniqueness flags at each level.                            *
* GLS       Current point in the local coordinates of level NLEVEL.    *
*                                                                      *
*                     The System Shapes                                *
*                     -----------------                                *
*                                                                      *
*  The system shapes supported at  present are as follows:             *
*                                                                      *
* 'BOX ' is a  box.  It has 3  parameters, the half lengths  in x, y   *
*        and z.                                                        *
* 'TRD1' is a trapezoid  with only the x length varying  with z.  It   *
*        has  4 parameters,  the  half  length in  x  at  the low  z   *
*        surface, that at  the high z surface, the half  length in y   *
*        and in z.                                                     *
* 'TRD2' is a  trapezoid with both x  and y lengths varying  with z.   *
*        It has  5 parameters,  the half  length in x  at the  low z   *
*        surface, that at  the high z surface, the half  length in y   *
*        at the low z surface, that  at the high z surface, the half   *
*        length in z.                                                  *
* 'TRAP' is  a  general trapezoid,  i.e.  one  for which  the  faces   *
*        perpendicular to z  are trapezia and their  centres are not   *
*        at the same x, y.  It has 11 parameters: Dz the half length   *
*        in z, Th & Phi the polar angles from the centre of the face   *
*        at  z=-Dz to  that at  z=+Dz, H1  the half  length in  y at   *
*        z=-Dz, LB1  the half length in  x at z=-Dz and  y=low edge,   *
*        LH1 the half length in x at z=-Dz and y= high edge, Th1 the   *
*        angle w.r.t. the  y axis from the centre of  the low y edge   *
*        to the centre of the high y edge, and H2, LB2, LH2, Th2 the   *
*        corresponding quantities to the 1s but at z=+Dz.              *
* 'TUBE' is a  tube.  It  has 3 parameters,  the inside  radius, the   *
*        outside radius and the half length in z.                      *
* 'TUBS' is a phi segment of a  tube.  It has 5 parameters, the same   *
*        3 as 'TUBE' plus the phi limits.  The segment starts at the   *
*        first limit  and includes  increasing phi  value up  to the   *
*        second limit or that plus 360 degrees.                        *
* 'CONE' is a conical tube.  It has 5 parameters, the half length in   *
*        z, the  inside and  outside radii  at the  low z  limit and   *
*        those at the high z limit.                                    *
* 'CONS' is a phi  segment of a conical tube.  It  has 7 parameters,   *
*        the same 5 as 'CONE' plus the phi limits.                     *
* 'SPHE' is a  segment of a  spherical shell.  It has  6 parameters,   *
*        the inside radius, the outside radius, the theta limits and   *
*        the phi limits.   At present, for the  drawing package only   *
*        first  two parameters  are significant  (inside radius  and   *
*        outside radius) and such a shape  is always drawn as a full   *
*        sphere.                                                       *
* 'PARA' is a parallelpiped.   It has 6 parameters,  the half length   *
*        in x, the half length in y, the half length in z, the angle   *
*        w.r.t. the y axis from the centre  of the low y edge to the   *
*        centre of the  high y edge, and the theta  phi polar angles   *
*        from the centre of the low z face to the centre of the high   *
*        z face.                                                       *
* 'PGON' is a polygon.  It has at least 10 parameters, the lower phi   *
*        limit, the range  in phi, the number of  straight sides (of   *
*        equal length)  between those  phi limits,  the number  of z   *
*        planes (at least two) where the distances to the z axis are   *
*        changing,  z  coordinate  of   first  plane,  the  shortest   *
*        distances  RMIN  & RMAX  from  the  z  axis to  the  inside   *
*        straight edge and  the outside straight edge  for the first   *
*        plane, Z, RMIN, RMAX for the second plane, and so on.         *
* 'PCON' is a polycone.  It has at least 9 parameters, the lower phi   *
*        limit, the range  in phi, the number of z  planes (at least   *
*        two) where  the radius are  changing, the z  coordinate and   *
*        the minimum and maximum radius for each z boundary.           *
* 'ELTU' is a  cylinder with  an elliptical  section.  It  has three   *
*        parameters:  the  ellipse  semi-axis   in  X,  the  ellipse   *
*        semi-axis in Y  and the half length in Z.   The equation of   *
*        the conical curve is:                                         *
*             X**2/PAR(1)**2  +  Y**2/PAR(2)**2  =  1                  *
*        ELTU is not divisible.                                        *
* 'HYPE' is a hyperbolic  tube, ie the inner and  outer surfaces are   *
*        hyperboloids, as would be formed by a system of cylindrical   *
*        wires  which were  then  rotated  tangentially about  their   *
*        centres.  The 4  parameters are the inner  and outer radii,   *
*        the  half lenght  in z,  and  the "stereo  angle" theta  in   *
*        degrees,  such that  the hyperbolic  surfaces are  given by   *
*        r**2 = (z*tan(theta))**2 + (r at z=0)**2                      *
* 'CTUB' is a cut  tube with 11 parameters.  The  first 5 parameters   *
*        are the same  as for the TUBS.  The  remaining 6 parameters   *
*        are the director  cosines of the surfaces  cutting the tube   *
*        respectively at the low and high Z values.                    *
*                                                                      *
*                  Shapes BOX,TRD1,TRD2,TRAP                           *
*                  Shapes TUBE,TUBS,CONE,CONS                          *
*                  Shapes PARA,SPHE,PGON,PCON                          *
*                  Shapes ELTU,HYPE,CTUB                               *
*                                                                      *
*              The Volume data structure JVOLUM                        *
*              --------------------------------                        *
*                                                                      *
* ISHAPE    system shape number                                        *
* NIN       number of volumes imbedded in  the mother volume.  If it   *
*           is negative then the volume is divided into slices         *
* NMED      medium number for the volume                               *
* NPAR      number of shape parameters                                 *
* NATT      number of drawing attributes                               *
* PAR       array of shape parameters                                  *
* IAT       array of drawing attributes                                *
* IAXIS     defines the direction of the  slices (1,2,3) in the case   *
*           of slice division (NIN < 0):                               *
* IVO       system volume number                                       *
* NDIV      number of slices                                           *
* C0        minimum coordinate limit                                   *
* STEP      coordinate step from slice to slice                        *
* IVO       system volume number  in the case  of  object  insertion   *
*           (NIN > 0):                                                 *
* NR        user number                                                *
* IROT      rotation matrix  number defining the  orientation of the   *
*           volume                                                     *
* X,Y,Z     define the position of the volume                          *
* KONLY     indicates  whether  it is  sufficient  to  find a  point   *
*           within  this  volume  or   whether  there  may  be  some   *
*           ambiguity with other volumes at the same level             *
*                                                                      *
*  User bits  in the bank  status word  are used with  the following   *
* meaning (the least significant bit is number 1):                     *
*                                                                      *
*  Bit       Meaning when set                                          *
*                                                                      *
*    1       Content of the volume has been ordered by GSORD           *
*    2       Content of the volume has been developed by GGDVLP        *
*    3       Volume is convex                                          *
*    4       User routines GSNEAR or GSNEXT have been called           *
*    5       Bit used to exclude a volume from the search in the       *
*            geometrical tree.                                         *
*                                                                      *
*                                                                      *
*                           | JVOLUM                                   *
* NVOLUM   IVO   IVO        v                 NVOLUM                   *
*  .............................................        (*)            *
*  |      | |   | |        | |  Volume names   |-->nlevmx              *
*  .............................................                       *
*          |     |                                                     *
*          |     v JVO = LQ(JVOLUM-IVO)       {NIN < 0}                *
*          |  ...........................................   (**)       *
*          |  | | |ishape|nin|numed|npar|natt|pars|atts.|->dev         *
*          |  ...........................................              *
*          |   |                                                       *
*          |   v JDIV=LQ(JVO-1)                                        *
*          |  .................................                        *
*          |  | | IAXIS |IVO |NDIV| C0 | STEP |                        *
*          |  .................................                        *
*          |                                                           *
*          .....                                                       *
*              |                                                       *
*     NIN IN   v  JVO = LQ(JVOLUM-IVO)      {NIN>0}                    *
* ........................................................  (**)       *
* | | |  | |  | |ishape| nin |numed|npar|natt|pars.|atts.|->dev        *
* ........................................................             *
*  | |    |                                                            *
*  | |    v   JIN = LQ(JVO-IN)                                         *
*  | | .......................................................         *
*  | | | | |-| ivo | nr |irot| x | y | z |konly|npar| pars.. |         *
*  | | .......................................................         *
*  | |  |                                                              *
*  | |  v   JNUP = LQ(JIN-1)  option GSNEXT only                       *
*  | | .............................                                   *
*  | | | | nus | in(1) ... in(nus) |                                   *
*  | | .............................                                   *
*  | |                                                                 *
*  | v   JNDW = LQ(JVO-NIN-1)       JSB = LQ(JNDW)                     *
*  |............................   .............................       *
*  || | nin | in(1) .. in(nin) | --| |IAXIS | NSB | C1..       |       *
*  |............................   .............................       *
*  |                                       option GSORD only           *
*  |                                                                   *
*  | JSC0 = LQ(JVO-NIN-2)  option GSORD only                           *
*  ..............                                                      *
*               |                                                      *
*  NSB-1  IDIV  v                      NSB-1                           *
*   ......................................                             *
*   |    | |   | | NCONT1...             |                             *
*   ......................................                             *
*         |                                                            *
*         |  JSCV = LQ(JSC0-IDIV)                                      *
*         v                      NCONT                                 *
*        ............................                                  *
*        | |  IN1...                |                                  *
*        ............................                                  *
*                                                                      *
* (*)                                                                  *
* Next of same type of JVOLUM filled in by routine GGNLEV/GGCLOS       *
* (**)                                                                 *
* Next of same type of JVO, for local development, filled in by        *
*  GGDVLP/GGCLOS                                                       *
*                                                                      *
************************************************************************
#endif