]> git.uio.no Git - u/mrichter/AliRoot.git/blame - GEANT321/ggeom/ggeom.doc
git://git.uio.no / u / mrichter / AliRoot.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Makefile added to PDF8
[u/mrichter/AliRoot.git] / GEANT321 / ggeom / ggeom.doc
CommitLineData
fe4da5cc 1*
2* $Id$
3*
4* $Log$
5* Revision 1.1.1.1 1995/10/24 10:20:47 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.28 by S.Giani
12*-- Author :
13*
14************************************************************************
15* *
16* Introduction to the Geometry package *
17* ------------------------------------ *
18* *
19* *
20* THE GEOMETRY PACKAGE *
21* *
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 *
26* processing phase. *
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 : *
36* *
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 ? *
40* *
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). *
44* *
45* THE VOLUME DEFINITION *
46* *
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 *
50* characterized by: *
51* *
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 *
57* coord.), *
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]. *
67* *
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. *
74* *
75* VOLUMES WITH CONTENTS *
76* *
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 *
103* they occupy. *
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. *
107* *
108* OVERLAPPING VOLUMES *
109* *
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. *
129* *
130* THE PHYSICAL TREE *
131* *
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. *
134* *
135* THE DATA STRUCTURE JVOLUM AND THE COMMON BLOCK /GCVOLU/ *
136* *
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 *
143* contents. *
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. *
158* *
159* THE BASIC USER TOOLS *
160* *
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 *
164* subroutine: *
165* *
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. *
169* *
170* The user can position a volume through a call to either one of the *
171* following subroutines: *
172* *
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' *
176* flag. *
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 *
186* copies. *
187* *
188* The user can divide a volume through a call to either one of the *
189* following subroutines: *
190* *
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. *
200* *
201* THE OPTIMISATION TOOLS *
202* *
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: *
210* *
211* GSORD/GGORD *
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. *
227* *
228* GSNEXT - GSNEAR *
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. *
238* *
239* GSUNEA/GUNEAR *
240* To specify any user ordering for the contents of a given volume. *
241* *
242* Labelled COMMON blocks related to section GEOM *
243* ---------------------------------------------- *
244* *
245* COMMON /GCPOLY/ IZSEC, IPSEC *
246* C *
247* IZSEC Z-section number *
248* IPSEC Phi-sector number *
249* *
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) *
253* C *
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 *
260* relevant *
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 *
266* each level. *
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 *
270* null rotation. *
271* GONLY Uniqueness flags at each level. *
272* GLS Current point in the local coordinates of level NLEVEL. *
273* *
274* The System Shapes *
275* ----------------- *
276* *
277* The system shapes supported at present are as follows: *
278* *
279* 'BOX ' is a box. It has 3 parameters, the half lengths in x, y *
280* and z. *
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 *
284* and in z. *
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 *
289* length in z. *
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 *
316* sphere. *
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 *
322* z face. *
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. *
352* *
353* Shapes BOX,TRD1,TRD2,TRAP *
354* Shapes TUBE,TUBS,CONE,CONS *
355* Shapes PARA,SPHE,PGON,PCON *
356* Shapes ELTU,HYPE,CTUB *
357* *
358* The Volume data structure JVOLUM *
359* -------------------------------- *
360* *
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 *
376* (NIN > 0): *
377* NR user number *
378* IROT rotation matrix number defining the orientation of the *
379* volume *
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 *
384* *
385* User bits in the bank status word are used with the following *
386* meaning (the least significant bit is number 1): *
387* *
388* Bit Meaning when set *
389* *
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. *
396* *
397* *
398* | JVOLUM *
399* NVOLUM IVO IVO v NVOLUM *
400* ............................................. (*) *
401* | | | | | | | Volume names |-->nlevmx *
402* ............................................. *
403* | | *
404* | v JVO = LQ(JVOLUM-IVO) {NIN < 0} *
405* | ........................................... (**) *
406* | | | |ishape|nin|numed|npar|natt|pars|atts.|->dev *
407* | ........................................... *
408* | | *
409* | v JDIV=LQ(JVO-1) *
410* | ................................. *
411* | | | IAXIS |IVO |NDIV| C0 | STEP | *
412* | ................................. *
413* | *
414* ..... *
415* | *
416* NIN IN v JVO = LQ(JVOLUM-IVO) {NIN>0} *
417* ........................................................ (**) *
418* | | | | | | |ishape| nin |numed|npar|natt|pars.|atts.|->dev *
419* ........................................................ *
420* | | | *
421* | | v JIN = LQ(JVO-IN) *
422* | | ....................................................... *
423* | | | | |-| ivo | nr |irot| x | y | z |konly|npar| pars.. | *
424* | | ....................................................... *
425* | | | *
426* | | v JNUP = LQ(JIN-1) option GSNEXT only *
427* | | ............................. *
428* | | | | nus | in(1) ... in(nus) | *
429* | | ............................. *
430* | | *
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 *
436* | *
437* | JSC0 = LQ(JVO-NIN-2) option GSORD only *
438* .............. *
439* | *
440* NSB-1 IDIV v NSB-1 *
441* ...................................... *
442* | | | | | NCONT1... | *
443* ...................................... *
444* | *
445* | JSCV = LQ(JSC0-IDIV) *
446* v NCONT *
447* ............................ *
448* | | IN1... | *
449* ............................ *
450* *
451* (*) *
452* Next of same type of JVOLUM filled in by routine GGNLEV/GGCLOS *
453* (**) *
454* Next of same type of JVO, for local development, filled in by *
455* GGDVLP/GGCLOS *
456* *
457************************************************************************
458#endif