[807] | 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 | ]]*************************************************************************** |
---|