1 | |
---|
2 | OLAP |
---|
3 | |
---|
4 | Debugging Tool for Ovelapping Geometries |
---|
5 | ---------------------------------------- |
---|
6 | (Martin.Liendl@cern.ch) |
---|
7 | |
---|
8 | 1 Abbreviations |
---|
9 | 2 Introduction |
---|
10 | 3 Instrumenting the example with a user-geometry |
---|
11 | 4 Reference of command line commands |
---|
12 | 5 Known Problems |
---|
13 | |
---|
14 | |
---|
15 | 1 Abbreviations |
---|
16 | =============== |
---|
17 | |
---|
18 | LV ... instance of G4LogicalVolume |
---|
19 | |
---|
20 | PV ... instance of G4VPhysicalVolume (Placement, Replica or Parameterised) |
---|
21 | |
---|
22 | MV ... mother volume, also referred as NewMother |
---|
23 | |
---|
24 | DV ... daughter volume |
---|
25 | |
---|
26 | NewWorld ... a geometry consisting of one MV and several DVs. The world |
---|
27 | volume is a enlarged bounding box into which the MV is put. Optionally the |
---|
28 | MV can be rotated according to user given parameters inside the NewWorld. |
---|
29 | |
---|
30 | |
---|
31 | 2 Introduction |
---|
32 | ============== |
---|
33 | |
---|
34 | Intersecting DVs inside the same MV or a DV protruding from its MV |
---|
35 | are said to be overlapping. Thus a complete geometry is correct, if |
---|
36 | all direct DVs of any given MV are not intersecting mutually or whith |
---|
37 | their MV. To be noticed that the tool described here cannot do this in |
---|
38 | a perfect way, strictly speaking, but allows to identify most defects in |
---|
39 | the geometry if any. If the check fails, the error is located and can be |
---|
40 | fixed easily. Checking means, that a geantino is shot from a given point |
---|
41 | A to another point B and viceversa from B to A. |
---|
42 | At each step of the geantino's track a boundary crossing has occurred |
---|
43 | (only geometry limits the geantino's steps!). If the set of boundary |
---|
44 | crossings from A to B is different from the set going from B to A |
---|
45 | (within a given Geant4 tolerance), some volumes must be overlapping |
---|
46 | along the line connecting A and B. To locate the overlaps more easily, |
---|
47 | the full geometry (which can be very complex in 'depth' in a hierarchical |
---|
48 | sense) is not used but only a subset consisting of a user selectable |
---|
49 | MV and all contained DVs. Then a user defined 'grid' of geantinos |
---|
50 | is shot through this simple geometry and possible overlaps are detected |
---|
51 | and reported. Checking all MVs in this way is then equivalent to checking |
---|
52 | the full geometry and has the advantage of identifying the cause of |
---|
53 | overlap directly. |
---|
54 | |
---|
55 | |
---|
56 | 3 Instrumenting the example with a user-geometry |
---|
57 | ================================================ |
---|
58 | |
---|
59 | A very tiny geometry (RandomDetector.hh,.cc) is provided within the example. |
---|
60 | It is instantiated in the file olapex.cc. |
---|
61 | |
---|
62 | |
---|
63 | 3.1 Configuring the user-geometry |
---|
64 | --------------------------------- |
---|
65 | |
---|
66 | The geometry debugging tools can be used for any Geant4 geometry. The |
---|
67 | geometry which one wants to debug must be available as subclass of |
---|
68 | G4VUserDetectorConstruction and must be used to construct the OlapDetConstr. |
---|
69 | Just read the code in olapex.cc and see how any geometry |
---|
70 | has to be prepared for debugging. The only thing to do is to use the provided |
---|
71 | Olap-UserActions in the main() of the Geant4 program: |
---|
72 | |
---|
73 | G4RunManager * runManager = new G4RunManager; |
---|
74 | |
---|
75 | // special primary generator for geantino shooting (in a grid) |
---|
76 | |
---|
77 | runManager->SetUserAction(new OlapGenerator); |
---|
78 | |
---|
79 | // the full geometry (which will be debugged) |
---|
80 | |
---|
81 | G4VUserDetectorConstruction * origGeom = new RandomDetector; |
---|
82 | |
---|
83 | // wrap full geometry into Olap-Geometry class |
---|
84 | |
---|
85 | OlapDetConstr * olapGeom = new OlapDetConstr(origGeom); |
---|
86 | |
---|
87 | // set wrapped geometry for Geant4 to use |
---|
88 | |
---|
89 | runManager->SetUserInitialization(olapGeom); |
---|
90 | |
---|
91 | // special physics list (nothing but transportation) |
---|
92 | |
---|
93 | runManager->SetUserInitialization(new OlapPhysicsList); |
---|
94 | |
---|
95 | // now create all UserActions ... |
---|
96 | |
---|
97 | OlapRunAction * olapRunAction = new OlapRunAction; |
---|
98 | |
---|
99 | OlapEventAction * olapEventAction = new OlapEventAction(olapRunAction); |
---|
100 | |
---|
101 | OlapSteppingAction * olapSteppingAction = |
---|
102 | |
---|
103 | new OlapSteppingAction(olapEventAction); |
---|
104 | |
---|
105 | runManager->SetUserAction(olapRunAction); |
---|
106 | |
---|
107 | runManager->SetUserAction(olapEventAction); |
---|
108 | |
---|
109 | runManager->SetUserAction(olapSteppingAction); |
---|
110 | |
---|
111 | |
---|
112 | 3.2 Navigating the geometry from command line |
---|
113 | ---------------------------------------------- |
---|
114 | |
---|
115 | Unix like navigation of the logical volume hierarchy is provided by |
---|
116 | the /olap/cd command. The root of the logical volume tree can be accessed |
---|
117 | by the character '/'. Any node in the volume tree can be accessed by a '/' |
---|
118 | separated string of regular expressions. If '/' is at the beginning of the string, |
---|
119 | the tree hierarchy is transversed from the root otherwise from the |
---|
120 | currently chosen logical volume. Further the command /olap/goto <regexp> |
---|
121 | can be used to jump to the first LogicalVolume matching the <regexp>. |
---|
122 | |
---|
123 | Every succesful navigational command (/olap/cd, olap/goto) results |
---|
124 | in the construction of a NewWorld, the MV beeing the argument of the |
---|
125 | navigational command and the DVs beeing the direct daughters of the MV. |
---|
126 | |
---|
127 | /olap/pwd always shows where in the full geometrical hierarchy the |
---|
128 | current NewWorld and MV is located. |
---|
129 | |
---|
130 | |
---|
131 | 3.3 Detecting Overlaps |
---|
132 | ---------------------- |
---|
133 | |
---|
134 | First determine the density of the grid of geantinos using |
---|
135 | |
---|
136 | /olap/grid 7 7 7 |
---|
137 | |
---|
138 | which returns the number of events (= pairs of geantinos) which will |
---|
139 | be shot through the NewWorld geometry (in this case 147 geantino pairs). |
---|
140 | |
---|
141 | To start overlap detection type |
---|
142 | |
---|
143 | /olap/trigger |
---|
144 | |
---|
145 | After all 147 events are processed, a summary of detected overlaps |
---|
146 | is given. Multiple detected overlaps are only reported once |
---|
147 | |
---|
148 | Error reports are written to G4cerr and to a log file if this is chosen |
---|
149 | (see section on output). The output looks like this: |
---|
150 | |
---|
151 | ===== collected overlaps of run [1] (ol=2) |
---|
152 | |
---|
153 | --[1]-------------------------- |
---|
154 | |
---|
155 | delta=51 |
---|
156 | |
---|
157 | vol 1: point=(-23,0,-40.02) vol 2: point=(-74,0,-40.02) axis=0 |
---|
158 | |
---|
159 | A -> B: |
---|
160 | [0]: ins=[i] PVName=[NewWorld:0] Type=[N] P=(-0,-0,-0) R=[0,90,90,90,0,0] |
---|
161 | G4Box: x/2=1234.23 y/2=1234.23 z/2=60.06 |
---|
162 | [1]: ins=[o] PVName=[SiliconPatchPanel:0] Type=[N] P=(-0,-0,-0) R=[0,90,90,90,0,0] |
---|
163 | G4Tubs: z/2=60 rIn=74 rOut=1233 startPhi=0 deltaPhi=6.28319 |
---|
164 | [2]: ins=[s] PVName=[SiliconPatchPanel1:1] Type=[N] P=(-0,-0,-40) R=[0,90,90,90,0,0] |
---|
165 | G4Tubs: z/2=20 rIn=23 rOut=1135 startPhi=0 deltaPhi=6.28319 |
---|
166 | |
---|
167 | B -> A: |
---|
168 | [0]: ins=[i] PVName=[NewWorld:0] Type=[N] P=(-0,-0,-0) R=[0,90,90,90,0,0] |
---|
169 | G4Box: x/2=1234.23 y/2=1234.23 z/2=60.06 |
---|
170 | |
---|
171 | 'delta' denotes the detected overlap distance. Two volumes are overlapping |
---|
172 | at least this distance. The following coordinates of points are points |
---|
173 | on the boundary of the overlapping volumes. In case of no overlap |
---|
174 | they should be the same points. The first point was found when tracking |
---|
175 | from A to B, while the second point was found when tracking from B |
---|
176 | to A. Using the command |
---|
177 | /olap/delta <DELTA> <unit> |
---|
178 | the accuracy for detecting an overlap can be set. Overlaps will only |
---|
179 | be reported if two volumes overlap at least DELTA*unit on one of the |
---|
180 | genantino tracks scanning the volumes. |
---|
181 | The default value is 1 nm, which is quite tight. |
---|
182 | |
---|
183 | To identify the overlapping volumes, |
---|
184 | the NavigationHistories of the two points are also shown in the output. |
---|
185 | The format of these histories is as follows: |
---|
186 | |
---|
187 | [A]: ins=[B] PVName=[C] Type=[D] P=(E) R=[F] G |
---|
188 | |
---|
189 | A --> Level in G4Navigationhistory |
---|
190 | |
---|
191 | B --> Stepping point is 'inside' vol [2], 'on surface' [1] or 'outside' |
---|
192 | [0] (mostly biased by numerical limits) |
---|
193 | |
---|
194 | C --> PhysicalVolume-name:copy-no |
---|
195 | |
---|
196 | D --> [N]..placement, [R]..repicated, [P]..parameterized |
---|
197 | |
---|
198 | E --> Position(intern.units) |
---|
199 | |
---|
200 | F --> Rotation(in deg:phiX,thetaX,phiY,..) |
---|
201 | |
---|
202 | G --> Solidtype: specification |
---|
203 | |
---|
204 | In the sample output given above, one can deduce that 'SiliconPatchPanel1' |
---|
205 | with copy-no 1 is overlapping its mother 'SiliconPatchPanel'. |
---|
206 | A schematic sketch of this situation is below: |
---|
207 | |
---|
208 | (x=0) (x=-1234*mm) |
---|
209 | (B) <----------------------------------------------------> (A) |
---|
210 | |
---|
211 | ------------------------------------------------------- |
---|
212 | |NewWorld | |
---|
213 | | ------------------------------------------- | |
---|
214 | | |SiliconPatchPanel | | |
---|
215 | | | | | |
---|
216 | | ----------------------------------- | | |
---|
217 | | |SiliconPatchPanel1 | | | |
---|
218 | | | | | | |
---|
219 | |....x...*.............................|...........|..| |
---|
220 | | | | | | |
---|
221 | | ----------------------------------- | | |
---|
222 | | | | | |
---|
223 | | ------------------------------------------- | |
---|
224 | | | |
---|
225 | ------------------------------------------------------- |
---|
226 | |
---|
227 | ... = geantino rays from (A) to (B) and from (B) to (A) |
---|
228 | x = point found when tracking from (A) to (B) |
---|
229 | * = point found wehn tracking from (B) to (A) |
---|
230 | |
---|
231 | 'x' and '*' should be on the same position in case of no |
---|
232 | overlaps. But they are not, because 'SiliconPatchPanel1' is |
---|
233 | protruding its mother volume 'SiliconPatchPanel'. |
---|
234 | The output report always assigns a point to the volume which |
---|
235 | is left behind the current direction of the geantino ray. |
---|
236 | In the example 'x' is assigned to 'SiliconPatchPanel1', because |
---|
237 | the tracking direction was (A) to (B). On the other hand side, |
---|
238 | '*' is assigned to 'NewWorld', because the tracking direction |
---|
239 | was (B) to (A). |
---|
240 | |
---|
241 | 3.4 Handling the output |
---|
242 | ----------------------- |
---|
243 | |
---|
244 | The output from the overlap detection can be written to file. The program |
---|
245 | provides two possibilities: 'Global logging', which creates one file, |
---|
246 | or 'logging by volume' where each logical volume puts its overlapping |
---|
247 | error into a file. |
---|
248 | |
---|
249 | To instantiate global logging type: |
---|
250 | |
---|
251 | /olap/log <path/filename> |
---|
252 | |
---|
253 | where path/filename is omittable, and the default is olap.log which |
---|
254 | will be created in the current directory. Alternatively one can type |
---|
255 | the path (must end with /), or only the filename. To stop the logging, |
---|
256 | type |
---|
257 | |
---|
258 | /olap/log false |
---|
259 | |
---|
260 | (or exit the program) |
---|
261 | |
---|
262 | The logging by volume command is |
---|
263 | |
---|
264 | /olap/logByVolume <path/> |
---|
265 | |
---|
266 | where the path is once again omittable. If the path is specified, it |
---|
267 | is important that it ends with / . Each log file will then be called |
---|
268 | NameOfLogicalVolume.log, for example SiliconPatchPanel.log. Again |
---|
269 | the logging can be stopped by typing |
---|
270 | |
---|
271 | /olap/logByVolume false |
---|
272 | |
---|
273 | Logging can be done from batch mode with a macro file, or when running |
---|
274 | the program. If the path is specified, it has to exist. The logging |
---|
275 | files are using the append format. |
---|
276 | |
---|
277 | |
---|
278 | 4 Reference of command line commands |
---|
279 | ==================================== |
---|
280 | |
---|
281 | 4.1 Terminology |
---|
282 | --------------- |
---|
283 | |
---|
284 | NewWorld: NewWorld is the world volume of the chosen subset of the |
---|
285 | detector where overlap detection takes place. Its solid is a box slightly |
---|
286 | larger than the bounding box of the NewMother solid. |
---|
287 | |
---|
288 | NewMother(MV): The user chosen mother volume where overlap detection takes |
---|
289 | place. It is positioned into origin of the NewWorld. Only |
---|
290 | the first level of daughter volumes is then placed inside the NewMother. |
---|
291 | |
---|
292 | |
---|
293 | 4.2 Commands for geometry navigation |
---|
294 | ------------------------------------ |
---|
295 | |
---|
296 | All command line commands are available in the Geant4 command directory |
---|
297 | /olap. For a short help inside Geant4 type help and choose the olap |
---|
298 | command directory. |
---|
299 | |
---|
300 | Commands for navigating the geometry always navigate the full logical |
---|
301 | hierarchy and set the current logical volume to the NewMother. |
---|
302 | Overlaps are detected only between the volumes of the first layer of |
---|
303 | daughters of NewMother and between the daughters and their mother |
---|
304 | volume. |
---|
305 | |
---|
306 | /olap/ls: list all logical daughters of the current NewMother |
---|
307 | |
---|
308 | /olap/pwd: prints the position of the current NewMother within the |
---|
309 | logical hierarchy of the full geometry. |
---|
310 | |
---|
311 | /olap/rotate <theta> <phi> <alpha> <angle-unit>: Defines the rotation |
---|
312 | of the NewMother inside the NewWorld. The rotation will be applied only |
---|
313 | in subsequent navigational commands such as /olap/goto or /olap/cd. |
---|
314 | The rotation axis is defined by the angles <theta> and <phi>, the rotation |
---|
315 | angle around this axis by the angle <alpha>. |
---|
316 | Rotating the NewMother can be particulary helpfull in cases where |
---|
317 | boundaries of the NewMother or of the daugher volumes are parallel |
---|
318 | to the bounderies of the NewWorld-box. Parallesl boundaries often cause |
---|
319 | numierical ambiguities during tracking time resulting in fake overlap |
---|
320 | detections. |
---|
321 | |
---|
322 | /olap/goto <regexp>: Sets the current NewMother to the logical Volume |
---|
323 | which name matches <regexp>. Search order is always descending construction |
---|
324 | order of volumes. If more than one volume matches the <regexp> the |
---|
325 | first match is chosen. |
---|
326 | |
---|
327 | /olap/cd <regexp-1>/<regexp-2>...: Unix-like changing of the current |
---|
328 | NewMother. The argument /olap/cd / sets the topmost logical volume |
---|
329 | of the full geometry to NewMother. olap/cd /Tracker sets the first |
---|
330 | logical daughter of the topmost logical volume which name matches |
---|
331 | Tracker to NewMother. olap/cd .. moves up one step in the logical |
---|
332 | hierarchy and sets the corresponding logical volume to NewMother. |
---|
333 | Combinations are possible, e.g.: /olap/cd Abc.*xy/../../cdef |
---|
334 | |
---|
335 | /olap/list <regexp>: Lists all logical volumes whose name matches <regexp> |
---|
336 | without changing the NewMother. |
---|
337 | |
---|
338 | |
---|
339 | 4.2 Commands for overlap detection |
---|
340 | ---------------------------------- |
---|
341 | |
---|
342 | /olap/grid a b c: Sets a grid for geantino pairs flying through the |
---|
343 | NewWorld. There will be a*b geantino pairs flying parallel to the |
---|
344 | z-axis in a regular grid, b*c parallel to the x-axis and a*c parallel |
---|
345 | to the y-axis. |
---|
346 | |
---|
347 | /olap/delta value unit: Sets boundary tolerance for overlaps in units |
---|
348 | of length. |
---|
349 | |
---|
350 | /olap/trigger: Start geantino shooting in the current NewWorld according |
---|
351 | to the defined grid. |
---|
352 | |
---|
353 | /olap/triggerFull n: Starting from the current NewWorld, the trigger-command |
---|
354 | is applied n times, each time changing the NewWorld by traversing |
---|
355 | the logical volume subtree. If -1 is given as argument (or n > number |
---|
356 | of subtree nodes), the whole subtree is checked. |
---|
357 | |
---|
358 | |
---|
359 | 4.3 Commands for logging |
---|
360 | ------------------------ |
---|
361 | |
---|
362 | /olap/log <path/filename>: Puts the output into one global file. |
---|
363 | Default-filename is olap.log. |
---|
364 | |
---|
365 | /olap/logByVolume <path/>: Each logical volume makes its own file called |
---|
366 | NameOfLogicalVolume.log where overlap errors for that specific volume |
---|
367 | are put. |
---|
368 | |
---|
369 | |
---|
370 | 5. Known Problem |
---|
371 | ================ |
---|
372 | |
---|
373 | . Overlaps of the same two volumes are sometimes reported more the one |
---|
374 | time at the end of a run |
---|
375 | |
---|
376 | . Fake overlaps are reported sometimes when many boundaries of volumes |
---|
377 | are parallel to the axis of 'NewWorld'. In this case, try to |
---|
378 | use /olap/rotate to rotate the volumes inside 'NewWorld', set the |
---|
379 | 'NewWorld' again and redo the overlap scan. |
---|
380 | |
---|
381 | . Fake overlaps can be reported when the Geant4 tracking algorithm |
---|
382 | gets 'caught' between volume boundaries (many small steps ...) |
---|
383 | |
---|
384 | . Visualization of overlaps is not yet correctly supported. |
---|
385 | |
---|
386 | |
---|
387 | ---------------------------------------------------------------------------- |
---|
388 | END OF README |
---|
389 | please don't read stuff below ... |
---|
390 | ---------------------------------------------------------------------------- |
---|
391 | |
---|
392 | [[********************************** experimental *********************** |
---|
393 | 3.3 |
---|
394 | If visualization |
---|
395 | was enabled, the detected overlaps are visualized with green markers |
---|
396 | as shown in Fig. [fig:olap]. In this figure the NewMother is visualized |
---|
397 | in blue and her daughters in red. |
---|
398 | ]]************************************************************************ |
---|
399 | |
---|
400 | [[*** The following is experimental *************************************** |
---|
401 | Visualization can also be enabled from the command line. Simply type |
---|
402 | /olap/syncVis 1 |
---|
403 | where the argument is a boolean and '0' turns the visualization off. |
---|
404 | If turned on every change of NewMother should also trigger a redraw |
---|
405 | of the chosen visualization driver. If the viewer is not updated, |
---|
406 | a flush can be triggered by /vis/viewer/update. Using VRML2FILE as |
---|
407 | visualization output, ECalBarrelAlveola_2 can be viewed in an appropriate |
---|
408 | VRML viewer:([fig] <fig:alv>Example of a NewWorld with a NewMother |
---|
409 | in red and her daughters in blue (Alveola structure and contained |
---|
410 | crystals of the CMS Ecal). ) |
---|
411 | |
---|
412 | ]]******************************************************************** |
---|
413 | |
---|
414 | |
---|
415 | [[************************************** experimental ********************** |
---|
416 | 4.4 Commands for visulization |
---|
417 | ----------------------------- |
---|
418 | |
---|
419 | /olap/syncVis 1/0: Enables visualization. Every change of NewMother |
---|
420 | should trigger a redraw. The argument is a boolean where '1' turns |
---|
421 | it on and '0' off. |
---|
422 | |
---|
423 | /olap/saveVis <filename>: Saves the current color scheme to an ASCII |
---|
424 | file. (The visualisation attributes can also be modified in this file |
---|
425 | externally.) |
---|
426 | |
---|
427 | /olap/saveVis <filename>: Loads a color scheme from an ASCII file. |
---|
428 | The color scheme must be compatible with the active Geant4 geometry |
---|
429 | in memory. |
---|
430 | ]]*************************************************************************** |
---|