[u/mrichter/AliRoot.git] / GEANT321 / ghits / ghits.doc

*
* $Id$
*
* $Log$
* Revision 1.1.1.1  1995/10/24 10:21:08  cernlib
* Geant
*
*
#include "geant321/pilot.h"
#if defined(CERNLIB_DOC)
*CMZ :  3.21/02 29/03/94  15.41.20  by  S.Giani
*-- Author :
*
************************************************************************
*                                                                      *
*           Introduction to the Detector Response package              *
*           ---------------------------------------------              *
*                                                                      *
*                                                                      *
* THE DETECTOR RESPONSE PACKAGE                                        *
*                                                                      *
* In the context of GEANT3:                                            *
*                                                                      *
* - a hit is  the user defined 'quantum of  information' recorded at   *
*   tracking  time to  keep  track of  the  interaction between  one   *
*   particle  and  a  given  sensitive  detector,  and  regarded  as   *
*   necessary to compute the digitisations later.                      *
*                                                                      *
* - a  digitisation is  the  user defined  'quantum of  information'   *
*   simulating  the  response of  a  given  detector element,  after   *
*   tracking  of a  complete event.                                    *
*                                                                      *
*  The detector response package consists  of tools to store in, and   *
* retrieve or print from, the  data structures JSET, JHITS and JDIGI   *
* the information  relevant to  the hits  and digitisations.   A few   *
* subroutines which  may help the  user to  solve some of  the usual   *
* problems of  digitisation in simple  detectors have been  added to   *
* the package,  e.g. the intersection of  a track with a  plane or a   *
* cylinder  and  the  digitisation  of conventional  drift  and  MWP   *
* chambers.                                                            *
*  For complex  set-ups with different  types of detectors  the user   *
* has normally  to define several  types of hits  and digitisations.   *
* In addition to the hits generated  by all particles of the current   *
* event,   computing  the   digitisations   requires  usually   some   *
* information about the intrinsic characteristics and performance of   *
* the detectors.                                                       *
*  The information to be recorded  for the hits and digitisations is   *
* highly  experiment dependent,  therefore only  a framework  can be   *
* proposed  to  store  it.   The solution  adopted  here  should  be   *
* satisfactory  for most  of  the applications.   Feedback from  the   *
* users is needed and will be welcome.                                 *
*  Two remarks can be made:                                            *
*                                                                      *
* - the stability of the information to be stored is usually reached   *
*   much earlier for the hits than for the digitisations.  Therefore   *
*   the user  may save computing  time by designing  an intermediate   *
*   event output at the hits level.                                    *
* - the scheme proposed for storing  the digitisations should in any   *
*   case be considered  as an intermediate stage,   a reshuffling of   *
*   the data  being necessary  if the  user wants  to simulate  more   *
*   closely the specific format of the real data acquisition system.   *
*                                                                      *
* SETS AND DETECTORS                                                   *
*                                                                      *
* The reader is assumed to be  familiar with the way the geometrical   *
* setup is described [GEOM 001],  in particular with the concepts of   *
* logical volume structure  and of physical path  through the volume   *
* tree.                                                                *
*  The  user  is  required  to  classify  into  sets  all  sensitive   *
* detectors for which  storing the hits in the  data structure JHITS   *
* is wanted.                                                           *
*  The 4-character names  which identify the sets  are user defined,   *
* and the list of sets which the  user wants to activate for a given   *
* run  can be  entered  through the  data card  SETS.   The user  is   *
* entirely  free to  group  together,  in one  or  in several  sets,   *
* detectors  of   the  same  type   or  of  different   types.   For   *
* convenience, it is  recommended to have at least one  set for each   *
* main   component  of   the   setup,   e.g.  hadron   calorimeters,   *
* electromagnetic calorimeters, vertex chamber, etc.                   *
*   A detector  can be  declared as  sensitive through  the tracking   *
* medium  parameter  ISVOL,  and  allocated to  a  set  through  the   *
* subroutine GSDET.   Currently, the active sets  and detectors have   *
* to be  redefined for every run.   Tools will be provided  later to   *
* read in part  or the whole of the information  from a previous run   *
* and  to  update the  relevant  structures  according to  the  user   *
* requirements.                                                        *
*   Each (logical) detector is identified by the 4-character name of   *
* the corresponding volume.  As a  given volume may describe several   *
* similar  detectors   of  the   physical  setup,   some  additional   *
* information is needed for associating  correctly the hits with the   *
* physical detectors.  The user has  to enter the (shortest) list of   *
* volume names,  the vector NAMESV, which  permits identification of   *
* the  path through  the  physical  tree, even  in  the presence  of   *
* multiple copies at  the volume level or at any  lower level in the   *
* tree.   The  identification  will  be  achieved  when  needed,  by   *
* specifying a list  of volume numbers, the vector NUMBV,  in one to   *
* one  correspondence with  the above  list of  volume names.   This   *
* list,  after  packing,  will  constitute  the  identifier  of  the   *
* physical detector.                                                   *
*                                                                      *
* THE BASIC USER TOOLS                                                 *
*                                                                      *
* The  data structure  JSET is  built through  calls to  the routine   *
* GSDET  which  allocates  detectors   to  sets  and  defines  their   *
* parameters,  and  to the  auxiliary  routines  GSDETH, GSDETD  and   *
* GSDETU which  store respectively in  the structure JSET,  for each   *
* logical detector separately:                                         *
*                                                                      *
* - the parameters required  for the storage of the  hit elements in   *
*   the  data  structure JHITS,  such  as  the packing  and  scaling   *
*   conventions.                                                       *
*                                                                      *
* - the parameters required for the  storage of the digitisations in   *
*   the structure JDIGI,  such as the packing  conventions. the user   *
*   parameters, which  may consist,  for instance, of  the intrinsic   *
*   detector characteristics needed for computing the digitisations.   *
*                                                                      *
*  To  permit storage  of more  than  one type  of hit  for a  given   *
* sensitive  detector, detector  'aliases'  can  be defined  through   *
* calls  to  the routine  GSDETA.   They  are  entered in  the  JSET   *
* structure  as  additional  detectors, with  the  same  geometrical   *
* characteristics  as the  original  one.  Then,  the  user has  the   *
* possibility to  call the  appropriate routines GSDETH,  GSDETD and   *
* GSDETU.                                                              *
*  During  the   tracking,  for  each  step   inside  the  sensitive   *
* detectors, under control of the subroutine GUSTEP, the hits can be   *
* stored in the data structure  JHITS with the subroutine GSAHIT (or   *
* GSCHIT,  more  appropriate for  calorimetry).   For  each hit  the   *
* information consists of:                                             *
*                                                                      *
* - the reference to the track in the structure JKINE,                 *
* - the packed identifier of the physical detector, and                *
* - the packed data for the different elements of the hit.             *
*                                                                      *
*  When  the tracking  has been  completed for  the whole  event the   *
* digitisations can be computed in  the user subroutine GUDIGI which   *
* may  extract the  hits with  the subroutine  GFHITS and  store the   *
* digitisations  in the  data structure  JDIGI, with  the subroutine   *
* GSDIGI.   For each  digitisation the  information should  at least   *
* consist of:                                                          *
*                                                                      *
* - the reference to the track(s),                                     *
* - the packed identifier of the physical detector, and                *
* - the packed data for the digitisation itself.                       *
*                                                                      *
* RETRIEVAL OF GEOMETRICAL INFORMATION                                 *
*                                                                      *
*  The packed  identifier of as  physical detector stored a  part of   *
* the hit  (or digitisation) information, is  returned (unpacked) by   *
* the routines GFHITS  or GFDIGI which extract  the information from   *
* the JHITS  or JDIGI structures,  and may  be used to  retrieve the   *
* identity and geometrical characteristics of the given detector.      *
*   At  the  moment this  is  automatized  through  the use  of  the   *
* routines GFPATH  (which assumes that the  sensitive detectors have   *
* been declared  through the routine  GSDETV, not GSDET)  and GLVOLU   *
* which fills the common /GCVOLU/.                                     *
*   GFPATH prepares the lists LNAM  and LNUM required by the routine   *
* GLVOLU [GEOM 001].                                                   *
*   Worth  is in  progress in  this area  and might  lead to  a more   *
* transparent approach.  Therefore, the  routines GSDETV, GGDETV and   *
* GFPATH  and  their action  on  the  structure  JSETS will  not  be   *
* documented in more detail now.                                       *
*                                                                      *
************************************************************************
#endif
Commit	Line	Data
fe4da5cc	1	*
	2	* $Id$
	3	*
	4	* $Log$
	5	* Revision 1.1.1.1 1995/10/24 10:21:08 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.20 by S.Giani
	12	*-- Author :
	13	*
	14	************************************************************************
	15	* *
	16	* Introduction to the Detector Response package *
	17	* --------------------------------------------- *
	18	* *
	19	* *
	20	* THE DETECTOR RESPONSE PACKAGE *
	21	* *
	22	* In the context of GEANT3: *
	23	* *
	24	* - a hit is the user defined 'quantum of information' recorded at *
	25	* tracking time to keep track of the interaction between one *
	26	* particle and a given sensitive detector, and regarded as *
	27	* necessary to compute the digitisations later. *
	28	* *
	29	* - a digitisation is the user defined 'quantum of information' *
	30	* simulating the response of a given detector element, after *
	31	* tracking of a complete event. *
	32	* *
	33	* The detector response package consists of tools to store in, and *
	34	* retrieve or print from, the data structures JSET, JHITS and JDIGI *
	35	* the information relevant to the hits and digitisations. A few *
	36	* subroutines which may help the user to solve some of the usual *
	37	* problems of digitisation in simple detectors have been added to *
	38	* the package, e.g. the intersection of a track with a plane or a *
	39	* cylinder and the digitisation of conventional drift and MWP *
	40	* chambers. *
	41	* For complex set-ups with different types of detectors the user *
	42	* has normally to define several types of hits and digitisations. *
	43	* In addition to the hits generated by all particles of the current *
	44	* event, computing the digitisations requires usually some *
	45	* information about the intrinsic characteristics and performance of *
	46	* the detectors. *
	47	* The information to be recorded for the hits and digitisations is *
	48	* highly experiment dependent, therefore only a framework can be *
	49	* proposed to store it. The solution adopted here should be *
	50	* satisfactory for most of the applications. Feedback from the *
	51	* users is needed and will be welcome. *
	52	* Two remarks can be made: *
	53	* *
	54	* - the stability of the information to be stored is usually reached *
	55	* much earlier for the hits than for the digitisations. Therefore *
	56	* the user may save computing time by designing an intermediate *
	57	* event output at the hits level. *
	58	* - the scheme proposed for storing the digitisations should in any *
	59	* case be considered as an intermediate stage, a reshuffling of *
	60	* the data being necessary if the user wants to simulate more *
	61	* closely the specific format of the real data acquisition system. *
	62	* *
	63	* SETS AND DETECTORS *
	64	* *
65	* The reader is assumed to be familiar with the way the geometrical *
66	* setup is described [GEOM 001], in particular with the concepts of *
67	* logical volume structure and of physical path through the volume *
68	* tree. *
69	* The user is required to classify into sets all sensitive *
70	* detectors for which storing the hits in the data structure JHITS *
71	* is wanted. *
72	* The 4-character names which identify the sets are user defined, *
73	* and the list of sets which the user wants to activate for a given *
74	* run can be entered through the data card SETS. The user is *
75	* entirely free to group together, in one or in several sets, *
76	* detectors of the same type or of different types. For *
77	* convenience, it is recommended to have at least one set for each *
78	* main component of the setup, e.g. hadron calorimeters, *
79	* electromagnetic calorimeters, vertex chamber, etc. *
80	* A detector can be declared as sensitive through the tracking *
81	* medium parameter ISVOL, and allocated to a set through the *
82	* subroutine GSDET. Currently, the active sets and detectors have *
83	* to be redefined for every run. Tools will be provided later to *
84	* read in part or the whole of the information from a previous run *
85	* and to update the relevant structures according to the user *
86	* requirements. *
87	* Each (logical) detector is identified by the 4-character name of *
88	* the corresponding volume. As a given volume may describe several *
89	* similar detectors of the physical setup, some additional *
90	* information is needed for associating correctly the hits with the *
91	* physical detectors. The user has to enter the (shortest) list of *
92	* volume names, the vector NAMESV, which permits identification of *
93	* the path through the physical tree, even in the presence of *
94	* multiple copies at the volume level or at any lower level in the *
95	* tree. The identification will be achieved when needed, by *
96	* specifying a list of volume numbers, the vector NUMBV, in one to *
97	* one correspondence with the above list of volume names. This *
98	* list, after packing, will constitute the identifier of the *
99	* physical detector. *
100	* *
101	* THE BASIC USER TOOLS *
102	* *
103	* The data structure JSET is built through calls to the routine *
104	* GSDET which allocates detectors to sets and defines their *
105	* parameters, and to the auxiliary routines GSDETH, GSDETD and *
106	* GSDETU which store respectively in the structure JSET, for each *
107	* logical detector separately: *
108	* *
109	* - the parameters required for the storage of the hit elements in *
110	* the data structure JHITS, such as the packing and scaling *
111	* conventions. *
112	* *
113	* - the parameters required for the storage of the digitisations in *
114	* the structure JDIGI, such as the packing conventions. the user *
115	* parameters, which may consist, for instance, of the intrinsic *
116	* detector characteristics needed for computing the digitisations. *
117	* *
118	* To permit storage of more than one type of hit for a given *
119	* sensitive detector, detector 'aliases' can be defined through *
120	* calls to the routine GSDETA. They are entered in the JSET *
121	* structure as additional detectors, with the same geometrical *
122	* characteristics as the original one. Then, the user has the *
123	* possibility to call the appropriate routines GSDETH, GSDETD and *
124	* GSDETU. *
125	* During the tracking, for each step inside the sensitive *
126	* detectors, under control of the subroutine GUSTEP, the hits can be *
127	* stored in the data structure JHITS with the subroutine GSAHIT (or *
128	* GSCHIT, more appropriate for calorimetry). For each hit the *
129	* information consists of: *
130	* *
131	* - the reference to the track in the structure JKINE, *
132	* - the packed identifier of the physical detector, and *
133	* - the packed data for the different elements of the hit. *
134	* *
135	* When the tracking has been completed for the whole event the *
136	* digitisations can be computed in the user subroutine GUDIGI which *
137	* may extract the hits with the subroutine GFHITS and store the *
138	* digitisations in the data structure JDIGI, with the subroutine *
139	* GSDIGI. For each digitisation the information should at least *
140	* consist of: *
141	* *
142	* - the reference to the track(s), *
143	* - the packed identifier of the physical detector, and *
144	* - the packed data for the digitisation itself. *
145	* *
146	* RETRIEVAL OF GEOMETRICAL INFORMATION *
147	* *
148	* The packed identifier of as physical detector stored a part of *
149	* the hit (or digitisation) information, is returned (unpacked) by *
150	* the routines GFHITS or GFDIGI which extract the information from *
151	* the JHITS or JDIGI structures, and may be used to retrieve the *
152	* identity and geometrical characteristics of the given detector. *
153	* At the moment this is automatized through the use of the *
154	* routines GFPATH (which assumes that the sensitive detectors have *
155	* been declared through the routine GSDETV, not GSDET) and GLVOLU *
156	* which fills the common /GCVOLU/. *
157	* GFPATH prepares the lists LNAM and LNUM required by the routine *
158	* GLVOLU [GEOM 001]. *
159	* Worth is in progress in this area and might lead to a more *
160	* transparent approach. Therefore, the routines GSDETV, GGDETV and *
161	* GFPATH and their action on the structure JSETS will not be *
162	* documented in more detail now. *
163	* *
164	************************************************************************
165	#endif