5 * Revision 1.1.1.1 1995/10/24 10:20:47 cernlib
9 #include "geant321/pilot.h"
10 #if defined(CERNLIB_DOC)
11 *CMZ : 3.21/02 29/03/94 15.41.28 by S.Giani
14 ************************************************************************
16 * Introduction to the Geometry package *
17 * ------------------------------------ *
20 * THE GEOMETRY PACKAGE *
22 * The geometry package consists of subroutines which can be used in *
23 * the initialisation phase of the program to describe the geometry *
24 * of the experimental set-up, and of subroutines which ensure the *
25 * communication with the tracking package during the event *
27 * The following paragraphs review the concepts of the geometry *
28 * package and explain how the geometrical information should be *
29 * provided by the user. *
30 * It is important to point out that, once the set-up has been *
31 * initialized, the tracking of particles through the different media *
32 * can proceed without any other intervention from the user [TRAK]. *
33 * The connection between the geometry and tracking packages is *
34 * established by the subprograms GMEDIA/GTMEDI, GNEXT/GTNEXT and *
35 * GINVOL which answer respecti- vely the questions : *
37 * - In which medium is a given point ? *
38 * - What is the path length to the next medium ? *
39 * - Is a given point still in the current medium ? *
41 * (The routines GTMEDI and GTNEXT are used in a dynamic context at *
42 * tracking time, where information about the direction of the *
43 * particle can be used to save time). *
45 * THE VOLUME DEFINITION *
47 * Experimental set-ups, as complex as the detectors prepared for *
48 * LEP, can be described rather accurately through the definition of *
49 * a set of simple VOLUMES. Each VOLUME is given a NAME and is *
52 * - a SHAPE identifier, specifying one of the basic geometrical *
53 * shapes available [GEOM010], the shape parameters, giving the *
54 * dimensions of the volume, *
55 * - a local reference system, whose origin and axes are the ones *
56 * defined for the given shape (cartesian, cylindrical or spherical *
58 * - its physical properties, given by a set of constants for the *
59 * homogeneous MATERIAL which fills the volume [CONS], *
60 * - additional properties, known as 'TRACKING MEDIUM' constants, *
61 * which depend on the characteristics of the volume itself (the *
62 * MATERIAL identifier is one of the constants) and on its *
63 * geometrical and physical environment (properties of the *
64 * neighbour media, magnetic field, etc.) [CONS,TRAK], *
65 * - a set of attributes, in connection with the drawing package and *
66 * the detector response package [DRAW,HITS]. *
68 * As long as it is not 'positioned' in a given reference frame, a *
69 * VOLUME is an entity which has no spatial relation with the set-up. *
70 * By convention, a unique initial volume has to be defined which *
71 * should match (or surround) the outside boundaries of the entire *
72 * set-up. The reference frame attached to this volume is considered *
73 * to be the master reference frame. *
75 * VOLUMES WITH CONTENTS *
77 * A VOLUME can be declared to have 'contents' and become a 'mother' *
78 * volume. The contents are either predefined volumes which are *
79 * explicitly positioned inside the mother, or new volumes which are *
80 * implicitly defined by a division mechanism applied to the mother. *
81 * Positioning a volume with given shape and dimensions inside a *
82 * mother volume is achieved by specifying its translation and *
83 * rotation with respect to the mother reference frame. The user *
84 * should make sure that no volume overlaps the boundaries of its *
85 * mother. When a volume is positioned, the user gives it a NUMBER. *
86 * Multiple copies of a given volume, with different numbers, can be *
87 * positioned inside a mother or inside different mothers and the *
88 * contents of the volume are reproduced implicitly in all copies. *
89 * Divisions can be performed along any of the three axes of the *
90 * mother volume. The definition of the axes (X,Y,Z or R..,.,Z or *
91 * R,.,.) depends on the shape. The mother volume can be partially *
92 * or totally divided. The division generates a cell, which is *
93 * considered as a new volume with (usually) the same shape as the *
94 * mother. Its dimensions are computed according to the declared *
95 * division number and/or step size. This cell, as any volume, can *
96 * again be divided along any of its proper axes, or have other *
97 * volumes positioned into it. Volumes positioned within a cell are *
98 * reproduced implicitly in all cells. *
99 * These operations permit a physical tree to be defined of volumes *
100 * at deeper and deeper levels. *
101 * It is assumed that the 'tracking medium' properties of the *
102 * contents replace the ones of the mother within the space region *
104 * A VOLUME is therefore defined not only by its intrinsic *
105 * characteristics but also by the definition of its 'descendants', *
106 * namely its contents, the contents of its contents, etc. *
108 * OVERLAPPING VOLUMES *
110 * The user may define volumes which have nothing to do with the *
111 * real physical structure. It is sometimes convenient to make use *
112 * of such volumes, to artificially delimit regions with simple *
113 * shapes. As a consequence, it may happen that volumes overlap each *
114 * other. (A volume positioned inside a mother is obviously not *
115 * regarded as overlapping the mother). *
116 * The handling of overlapping volumes has some implications that *
117 * the user should be aware of: *
118 * A flag 'ONLY/MANY' is attached to each positioned volume. The *
119 * 'MANY' option indicates that a point found to be in this volume *
120 * could also be in other volumes which are not direct descendants of *
121 * it. The user is free to declare one of the overlapping volumes as *
122 * 'ONLY', in which case the medium searching subroutines will give *
123 * priority to this volume. *
124 * If a point is inside several 'MANY' volumes and outside all *
125 * 'ONLY' ones, priority will be given to the first volume found at *
126 * the deepest level and, in order to avoid ambiguities, two *
127 * overlapping 'MANY' volumes should in general be assigned the same *
128 * default tracking medium. *
130 * THE PHYSICAL TREE *
132 * The package accepts a maximum of 15 levels, which should be quite *
133 * enough to represent even the fine details of a complex set-up. *
135 * THE DATA STRUCTURE JVOLUM AND THE COMMON BLOCK /GCVOLU/ *
137 * In practice, the physical tree is represented by a logical tree *
138 * structure, the JVOLUM data structure [GEOM 199], which describes *
139 * the arrangement of volumes in a compact and recurrent way. Each *
140 * generic volume appears once, and once only, and carries the *
141 * information relevant to the volume itself and to its contents, if *
142 * any, by reference to the generic volumes corresponding to those *
144 * In the situation where division or multiple copies occur, there *
145 * is no longer a one-to-one correspondence between a given volume in *
146 * the logical tree and a unique region in space. Information has to *
147 * be kept at tracking time to identify which division cell or which *
148 * copy was considered at each depth level along the path through the *
149 * physical tree. This information is stored by the subroutine *
150 * GTMEDI, for the current point of the current track, in the COMMON *
151 * /GCVOLU/. It contains the current LEVEL and, for each level, *
152 * starting from the first initial reference volume, the *
153 * identification of the corresponding volume, e.g.: NAME, NUMBER, *
154 * 'ONLY/MANY' flag, translation and rotation with respect to the *
155 * master reference frame. The SHAPE parameters and the number of *
156 * parameters (initialy stored in /GCVOLU/) are stored in the *
157 * separate structure JGPAR. *
159 * THE BASIC USER TOOLS *
161 * The rules of the game being established, it is easy to introduce *
162 * the set of subroutines which ensure the functionality of the *
163 * package. The user can define a volume through a call to the *
166 * GSVOLU Input arguments specify the NAME, SHAPE and parameters *
167 * of the volume. An output argument returns the position *
168 * of the volume inside the bank JVOLUM. *
170 * The user can position a volume through a call to either one of the *
171 * following subroutines: *
173 * GSPOS Input arguments specify the NAME and copy NUMBER of the *
174 * volume to be positioned, the NAME of the mother, the *
175 * translation and the rotation matrix, and the 'ONLY/MANY' *
177 * GSPOSP In case the user has to position , inside a mother, a *
178 * large number of volumes with the same shape but *
179 * different dimensions (lead glass blocks, BGO crystals, *
180 * etc.) an alternative is proposed which consists of *
181 * defining the generic volume once, with the number of *
182 * shape parameters set to zero, and to call GSPOSP for *
183 * each volume in turn, with the same arguments as GSPOS *
184 * plus the shape parameters. The volumes will be *
185 * identified by their NAME+NUMBER as for the multiple *
188 * The user can divide a volume through a call to either one of the *
189 * following subroutines: *
191 * GSDVN Input arguments specify the NAME of the cell volume, the *
192 * name of the MOTHER being divided, the number of *
193 * divisions NDIV and the axis along which the division is *
194 * performed. In this simple case, the cell tracking *
195 * medium is assumed to be the same as for the mother. *
196 * GSDVS The division STEP is given instead of NDIV and the cell *
197 * tracking medium is specified. *
198 * GSDVX In addition to both STEP and NDIV , the origin of the *
199 * first cell and the cell tracking medium are specified. *
201 * THE OPTIMISATION TOOLS *
203 * When a track enters a volume with contents, the search time to *
204 * identify whether the current point is in the mother or in any of *
205 * the contents is very short when the contents are division cells *
206 * (straightforward computation along the relevant axis). When the *
207 * contents have been positioned, the search time can be quite large. *
208 * In order to save time the user can make use of either of the *
209 * following facilities: *
212 * From the known position of the contents inside a given volume *
213 * the subroutine GGORD computes fictitious boundaries along the *
214 * specified coordinate, simulating a division with non regular *
215 * step size. A binary search technique is used to identify within *
216 * which pseudo-cell the current point is. The slow process of *
217 * computing whether the point is inside or outside the contents is *
218 * therefore limited to the few (if any) volumes sitting in that *
219 * pseudo-cell. The coordinate selected for the pseudo division *
220 * can be any of X, Y, Z, Rxy, R, Phi or Theta. GSORD is called by *
221 * the user to flag which volume should have its contents ordered *
222 * and along which axis. GGORD is called by GGCLOS. The user can *
223 * select via the data record OPTIM to automatically call GSORD for *
224 * all the volumes with content. In this case the system will try *
225 * to choose the best axis along which to order the contents of *
226 * every mother in the tree. *
229 * When a particle enters a mother volume, the contents are scanned *
230 * initially in the order they have been positioned, and the user *
231 * should take care over the best sequence of GSPOS calls. *
232 * However, when the particle comes back inside the mother from any *
233 * one of the contents, it is usually possible to limit the search *
234 * to the neighbour contents. The subroutines GSNEXT,GSNEAR permit *
235 * the user to inject at initialisation time, for each content in *
236 * turn, the list of neighbours to search for. A proper use of *
237 * this facility can reduce the search time significantly. *
240 * To specify any user ordering for the contents of a given volume. *
242 * Labelled COMMON blocks related to section GEOM *
243 * ---------------------------------------------- *
245 * COMMON /GCPOLY/ IZSEC, IPSEC *
247 * IZSEC Z-section number *
248 * IPSEC Phi-sector number *
250 * COMMON/GCVOLU/NLEVEL,NAMES(15),NUMBER(15), *
251 * +LVOLUM(15),LINDEX(15),INFROM,NLEVMX,NLDEV(15),LINMX(15), *
252 * +GTRAN(3,15),GRMAT(10,15),GONLY(15),GLX(3) *
254 * NLEVEL Level number at which the last medium search stopped. *
255 * NAMES Volume names at each level. *
256 * NUMBER User volume numbers at each level. *
257 * LVOLUM System volume numbers at each level. *
258 * LINDEX Physical tree volume indices at each level. *
259 * INFROM Number of the content a particle has just left, when *
261 * NLEVMX Maximum number of levels in given geometry tree *
262 * NLDEV Levels where local development take place, if non 0 *
263 * LINMX numbers of contents (position) or cells (division) *
264 * GTRAN X,Y,Z offsets of the cumulative coordinate *
265 * transformation from the master system to the system at *
267 * GRMAT Rotation matrix elements for the cumulative *
268 * transformation from the master system to the system at *
269 * each level. GRMAT(10,LEVEL) equal to 0.0 indicates the *
271 * GONLY Uniqueness flags at each level. *
272 * GLS Current point in the local coordinates of level NLEVEL. *
274 * The System Shapes *
275 * ----------------- *
277 * The system shapes supported at present are as follows: *
279 * 'BOX ' is a box. It has 3 parameters, the half lengths in x, y *
281 * 'TRD1' is a trapezoid with only the x length varying with z. It *
282 * has 4 parameters, the half length in x at the low z *
283 * surface, that at the high z surface, the half length in y *
285 * 'TRD2' is a trapezoid with both x and y lengths varying with z. *
286 * It has 5 parameters, the half length in x at the low z *
287 * surface, that at the high z surface, the half length in y *
288 * at the low z surface, that at the high z surface, the half *
290 * 'TRAP' is a general trapezoid, i.e. one for which the faces *
291 * perpendicular to z are trapezia and their centres are not *
292 * at the same x, y. It has 11 parameters: Dz the half length *
293 * in z, Th & Phi the polar angles from the centre of the face *
294 * at z=-Dz to that at z=+Dz, H1 the half length in y at *
295 * z=-Dz, LB1 the half length in x at z=-Dz and y=low edge, *
296 * LH1 the half length in x at z=-Dz and y= high edge, Th1 the *
297 * angle w.r.t. the y axis from the centre of the low y edge *
298 * to the centre of the high y edge, and H2, LB2, LH2, Th2 the *
299 * corresponding quantities to the 1s but at z=+Dz. *
300 * 'TUBE' is a tube. It has 3 parameters, the inside radius, the *
301 * outside radius and the half length in z. *
302 * 'TUBS' is a phi segment of a tube. It has 5 parameters, the same *
303 * 3 as 'TUBE' plus the phi limits. The segment starts at the *
304 * first limit and includes increasing phi value up to the *
305 * second limit or that plus 360 degrees. *
306 * 'CONE' is a conical tube. It has 5 parameters, the half length in *
307 * z, the inside and outside radii at the low z limit and *
308 * those at the high z limit. *
309 * 'CONS' is a phi segment of a conical tube. It has 7 parameters, *
310 * the same 5 as 'CONE' plus the phi limits. *
311 * 'SPHE' is a segment of a spherical shell. It has 6 parameters, *
312 * the inside radius, the outside radius, the theta limits and *
313 * the phi limits. At present, for the drawing package only *
314 * first two parameters are significant (inside radius and *
315 * outside radius) and such a shape is always drawn as a full *
317 * 'PARA' is a parallelpiped. It has 6 parameters, the half length *
318 * in x, the half length in y, the half length in z, the angle *
319 * w.r.t. the y axis from the centre of the low y edge to the *
320 * centre of the high y edge, and the theta phi polar angles *
321 * from the centre of the low z face to the centre of the high *
323 * 'PGON' is a polygon. It has at least 10 parameters, the lower phi *
324 * limit, the range in phi, the number of straight sides (of *
325 * equal length) between those phi limits, the number of z *
326 * planes (at least two) where the distances to the z axis are *
327 * changing, z coordinate of first plane, the shortest *
328 * distances RMIN & RMAX from the z axis to the inside *
329 * straight edge and the outside straight edge for the first *
330 * plane, Z, RMIN, RMAX for the second plane, and so on. *
331 * 'PCON' is a polycone. It has at least 9 parameters, the lower phi *
332 * limit, the range in phi, the number of z planes (at least *
333 * two) where the radius are changing, the z coordinate and *
334 * the minimum and maximum radius for each z boundary. *
335 * 'ELTU' is a cylinder with an elliptical section. It has three *
336 * parameters: the ellipse semi-axis in X, the ellipse *
337 * semi-axis in Y and the half length in Z. The equation of *
338 * the conical curve is: *
339 * X**2/PAR(1)**2 + Y**2/PAR(2)**2 = 1 *
340 * ELTU is not divisible. *
341 * 'HYPE' is a hyperbolic tube, ie the inner and outer surfaces are *
342 * hyperboloids, as would be formed by a system of cylindrical *
343 * wires which were then rotated tangentially about their *
344 * centres. The 4 parameters are the inner and outer radii, *
345 * the half lenght in z, and the "stereo angle" theta in *
346 * degrees, such that the hyperbolic surfaces are given by *
347 * r**2 = (z*tan(theta))**2 + (r at z=0)**2 *
348 * 'CTUB' is a cut tube with 11 parameters. The first 5 parameters *
349 * are the same as for the TUBS. The remaining 6 parameters *
350 * are the director cosines of the surfaces cutting the tube *
351 * respectively at the low and high Z values. *
353 * Shapes BOX,TRD1,TRD2,TRAP *
354 * Shapes TUBE,TUBS,CONE,CONS *
355 * Shapes PARA,SPHE,PGON,PCON *
356 * Shapes ELTU,HYPE,CTUB *
358 * The Volume data structure JVOLUM *
359 * -------------------------------- *
361 * ISHAPE system shape number *
362 * NIN number of volumes imbedded in the mother volume. If it *
363 * is negative then the volume is divided into slices *
364 * NMED medium number for the volume *
365 * NPAR number of shape parameters *
366 * NATT number of drawing attributes *
367 * PAR array of shape parameters *
368 * IAT array of drawing attributes *
369 * IAXIS defines the direction of the slices (1,2,3) in the case *
370 * of slice division (NIN < 0): *
371 * IVO system volume number *
372 * NDIV number of slices *
373 * C0 minimum coordinate limit *
374 * STEP coordinate step from slice to slice *
375 * IVO system volume number in the case of object insertion *
378 * IROT rotation matrix number defining the orientation of the *
380 * X,Y,Z define the position of the volume *
381 * KONLY indicates whether it is sufficient to find a point *
382 * within this volume or whether there may be some *
383 * ambiguity with other volumes at the same level *
385 * User bits in the bank status word are used with the following *
386 * meaning (the least significant bit is number 1): *
388 * Bit Meaning when set *
390 * 1 Content of the volume has been ordered by GSORD *
391 * 2 Content of the volume has been developed by GGDVLP *
392 * 3 Volume is convex *
393 * 4 User routines GSNEAR or GSNEXT have been called *
394 * 5 Bit used to exclude a volume from the search in the *
395 * geometrical tree. *
399 * NVOLUM IVO IVO v NVOLUM *
400 * ............................................. (*) *
401 * | | | | | | | Volume names |-->nlevmx *
402 * ............................................. *
404 * | v JVO = LQ(JVOLUM-IVO) {NIN < 0} *
405 * | ........................................... (**) *
406 * | | | |ishape|nin|numed|npar|natt|pars|atts.|->dev *
407 * | ........................................... *
409 * | v JDIV=LQ(JVO-1) *
410 * | ................................. *
411 * | | | IAXIS |IVO |NDIV| C0 | STEP | *
412 * | ................................. *
416 * NIN IN v JVO = LQ(JVOLUM-IVO) {NIN>0} *
417 * ........................................................ (**) *
418 * | | | | | | |ishape| nin |numed|npar|natt|pars.|atts.|->dev *
419 * ........................................................ *
421 * | | v JIN = LQ(JVO-IN) *
422 * | | ....................................................... *
423 * | | | | |-| ivo | nr |irot| x | y | z |konly|npar| pars.. | *
424 * | | ....................................................... *
426 * | | v JNUP = LQ(JIN-1) option GSNEXT only *
427 * | | ............................. *
428 * | | | | nus | in(1) ... in(nus) | *
429 * | | ............................. *
431 * | v JNDW = LQ(JVO-NIN-1) JSB = LQ(JNDW) *
432 * |............................ ............................. *
433 * || | nin | in(1) .. in(nin) | --| |IAXIS | NSB | C1.. | *
434 * |............................ ............................. *
435 * | option GSORD only *
437 * | JSC0 = LQ(JVO-NIN-2) option GSORD only *
440 * NSB-1 IDIV v NSB-1 *
441 * ...................................... *
442 * | | | | | NCONT1... | *
443 * ...................................... *
445 * | JSCV = LQ(JSC0-IDIV) *
447 * ............................ *
449 * ............................ *
452 * Next of same type of JVOLUM filled in by routine GGNLEV/GGCLOS *
454 * Next of same type of JVO, for local development, filled in by *
457 ************************************************************************
git://git.uio.no / u / mrichter / AliRoot.git / blob