Geant4  9.6.p02
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
G4Navigator.hh
Go to the documentation of this file.
1 //
2 // ********************************************************************
3 // * License and Disclaimer *
4 // * *
5 // * The Geant4 software is copyright of the Copyright Holders of *
6 // * the Geant4 Collaboration. It is provided under the terms and *
7 // * conditions of the Geant4 Software License, included in the file *
8 // * LICENSE and available at http://cern.ch/geant4/license . These *
9 // * include a list of copyright holders. *
10 // * *
11 // * Neither the authors of this software system, nor their employing *
12 // * institutes,nor the agencies providing financial support for this *
13 // * work make any representation or warranty, express or implied, *
14 // * regarding this software system or assume any liability for its *
15 // * use. Please see the license in the file LICENSE and URL above *
16 // * for the full disclaimer and the limitation of liability. *
17 // * *
18 // * This code implementation is the result of the scientific and *
19 // * technical work of the GEANT4 collaboration. *
20 // * By using, copying, modifying or distributing the software (or *
21 // * any work based on the software) you agree to acknowledge its *
22 // * use in resulting scientific publications, and indicate your *
23 // * acceptance of all terms of the Geant4 Software license. *
24 // ********************************************************************
25 //
26 //
27 // $Id$
28 //
29 //
30 // class G4Navigator
31 //
32 // Class description:
33 //
34 // A class for use by the tracking management, able to obtain/calculate
35 // dynamic tracking time information such as the distance to the next volume,
36 // or to find the physical volume containing a given point in the world
37 // reference system. The navigator maintains a transformation history and
38 // other information to optimise the tracking time performance.
39 
40 // History:
41 // - Created. Paul Kent, Jul 95/96
42 // - Zero step protections J.A. / G.C., Nov 2004
43 // - Added check mode G. Cosmo, Mar 2004
44 // - Made Navigator Abstract G. Cosmo, Nov 2003
45 // *********************************************************************
46 
47 #ifndef G4NAVIGATOR_HH
48 #define G4NAVIGATOR_HH
49 
50 #include "geomdefs.hh"
51 
52 #include "G4ThreeVector.hh"
53 #include "G4AffineTransform.hh"
54 #include "G4RotationMatrix.hh"
55 
56 #include "G4LogicalVolume.hh" // Used in inline methods
57 #include "G4GRSVolume.hh" // " "
58 #include "G4GRSSolid.hh" // " "
59 #include "G4TouchableHandle.hh" // " "
61 
62 #include "G4NavigationHistory.hh"
63 #include "G4NormalNavigation.hh"
64 #include "G4VoxelNavigation.hh"
66 #include "G4ReplicaNavigation.hh"
67 #include "G4RegularNavigation.hh"
68 
69 #include <iostream>
70 
71 class G4VPhysicalVolume;
72 
74 {
75  public: // with description
76 
77  friend std::ostream& operator << (std::ostream &os, const G4Navigator &n);
78 
79  G4Navigator();
80  // Constructor - initialisers and setup.
81 
82  virtual ~G4Navigator();
83  // Destructor. No actions.
84 
85  virtual G4double ComputeStep(const G4ThreeVector &pGlobalPoint,
86  const G4ThreeVector &pDirection,
87  const G4double pCurrentProposedStepLength,
88  G4double &pNewSafety);
89  // Calculate the distance to the next boundary intersected
90  // along the specified NORMALISED vector direction and
91  // from the specified point in the global coordinate
92  // system. LocateGlobalPointAndSetup or LocateGlobalPointWithinVolume
93  // must have been called with the same global point prior to this call.
94  // The isotropic distance to the nearest boundary is also
95  // calculated (usually an underestimate). The current
96  // proposed Step length is used to avoid intersection
97  // calculations: if it can be determined that the nearest
98  // boundary is >pCurrentProposedStepLength away, kInfinity
99  // is returned together with the computed isotropic safety
100  // distance. Geometry must be closed.
101 
102  G4double CheckNextStep(const G4ThreeVector &pGlobalPoint,
103  const G4ThreeVector &pDirection,
104  const G4double pCurrentProposedStepLength,
105  G4double &pNewSafety);
106  // Same as above, but do not disturb the state of the Navigator.
107 
108  virtual
110  const G4ThreeVector &direction,
111  const G4TouchableHistory &h);
112 
113  // Resets the geometrical hierarchy and search for the volumes deepest
114  // in the hierarchy containing the point in the global coordinate space.
115  // The direction is used to check if a volume is entered.
116  // The search begin is the geometrical hierarchy at the location of the
117  // last located point, or the endpoint of the previous Step if
118  // SetGeometricallyLimitedStep() has been called immediately before.
119  //
120  // Important Note: In order to call this the geometry MUST be closed.
121 
122  virtual
124  const G4ThreeVector* direction=0,
125  const G4bool pRelativeSearch=true,
126  const G4bool ignoreDirection=true);
127  // Search the geometrical hierarchy for the volumes deepest in the hierarchy
128  // containing the point in the global coordinate space. Two main cases are:
129  // i) If pRelativeSearch=false it makes use of no previous/state
130  // information. Returns the physical volume containing the point,
131  // with all previous mothers correctly set up.
132  // ii) If pRelativeSearch is set to true, the search begin is the
133  // geometrical hierarchy at the location of the last located point,
134  // or the endpoint of the previous Step if SetGeometricallyLimitedStep()
135  // has been called immediately before.
136  // The direction is used (to check if a volume is entered) if either
137  // - the argument ignoreDirection is false, or
138  // - the Navigator has determined that it is on an edge shared by two or
139  // more volumes. (This is state information.)
140  //
141  // Important Note: In order to call this the geometry MUST be closed.
142 
143  virtual
145  // Notify the Navigator that a track has moved to the new Global point
146  // 'position', that is known to be within the current safety.
147  // No check is performed to ensure that it is within the volume.
148  // This method can be called instead of LocateGlobalPointAndSetup ONLY if
149  // the caller is certain that the new global point (position) is inside the
150  // same volume as the previous position. Usually this can be guaranteed
151  // only if the point is within safety.
152 
154  const G4ThreeVector& position,
155  const G4ThreeVector& direction,
156  G4TouchableHandle& oldTouchableToUpdate,
157  const G4bool RelativeSearch = true);
158  // First, search the geometrical hierarchy like the above method
159  // LocateGlobalPointAndSetup(). Then use the volume found and its
160  // navigation history to update the touchable.
161 
163  const G4ThreeVector& position,
164  const G4ThreeVector& direction,
165  G4VTouchable* touchableToUpdate,
166  const G4bool RelativeSearch = true);
167  // First, search the geometrical hierarchy like the above method
168  // LocateGlobalPointAndSetup(). Then use the volume found and its
169  // navigation history to update the touchable.
170 
172  const G4ThreeVector& position,
173  G4VTouchable* touchableToUpdate,
174  const G4bool RelativeSearch = true);
175  // Same as the method above but missing direction.
176 
177  inline void SetGeometricallyLimitedStep();
178  // Inform the navigator that the previous Step calculated
179  // by the geometry was taken in its entirety.
180 
181  virtual G4double ComputeSafety(const G4ThreeVector &globalpoint,
182  const G4double pProposedMaxLength = DBL_MAX,
183  const G4bool keepState = true);
184  // Calculate the isotropic distance to the nearest boundary from the
185  // specified point in the global coordinate system.
186  // The globalpoint utilised must be within the current volume.
187  // The value returned is usually an underestimate.
188  // The proposed maximum length is used to avoid volume safety
189  // calculations. The geometry must be closed.
190  // To ensure minimum side effects from the call, keepState
191  // must be true.
192 
193  inline G4VPhysicalVolume* GetWorldVolume() const;
194  // Return the current world (`topmost') volume.
195 
196  inline void SetWorldVolume(G4VPhysicalVolume* pWorld);
197  // Set the world (`topmost') volume. This must be positioned at
198  // origin (0,0,0) and unrotated.
199 
200  inline G4GRSVolume* CreateGRSVolume() const;
201  inline G4GRSSolid* CreateGRSSolid() const;
204  // `Touchable' creation methods: caller has deletion responsibility.
205 
207  // Returns a reference counted handle to a touchable history.
208 
209  virtual G4ThreeVector GetLocalExitNormal(G4bool* valid);
211  G4bool* valid);
212  virtual G4ThreeVector GetGlobalExitNormal(const G4ThreeVector& point,
213  G4bool* valid);
214  // Return Exit Surface Normal and validity too.
215  // Can only be called if the Navigator's last Step has crossed a
216  // volume geometrical boundary.
217  // It returns the Normal to the surface pointing out of the volume that
218  // was left behind and/or into the volume that was entered.
219  // Convention:
220  // The *local* normal is in the coordinate system of the *final* volume.
221  // Restriction:
222  // Normals are not available for replica volumes (returns valid= false)
223  // These methods takes full care about how to calculate this normal,
224  // but if the surfaces are not convex it will return valid=false.
225 
226  inline G4int GetVerboseLevel() const;
227  inline void SetVerboseLevel(G4int level);
228  // Get/Set Verbose(ness) level.
229  // [if level>0 && G4VERBOSE, printout can occur]
230 
231  inline G4bool IsActive() const;
232  // Verify if the navigator is active.
233  inline void Activate(G4bool flag);
234  // Activate/inactivate the navigator.
235 
236  inline G4bool EnteredDaughterVolume() const;
237  // The purpose of this function is to inform the caller if the track is
238  // entering a daughter volume while exiting from the current volume.
239  // This method returns
240  // - True only in case 1) above, that is when the Step has caused
241  // the track to arrive at a boundary of a daughter.
242  // - False in cases 2), 3) and 4), i.e. in all other cases.
243  // This function is not guaranteed to work if SetGeometricallyLimitedStep()
244  // was not called when it should have been called.
245  inline G4bool ExitedMotherVolume() const;
246  // Verify if the step has exited the mother volume.
247 
248  inline void CheckMode(G4bool mode);
249  // Run navigation in "check-mode", therefore using additional
250  // verifications and more strict correctness conditions.
251  // Is effective only with G4VERBOSE set.
252  inline G4bool IsCheckModeActive() const;
253  inline void SetPushVerbosity(G4bool mode);
254  // Set/unset verbosity for pushed tracks (default is true).
255 
256  void PrintState() const;
257  // Print the internal state of the Navigator (for debugging).
258  // The level of detail is according to the verbosity.
259 
260  inline const G4AffineTransform& GetGlobalToLocalTransform() const;
261  inline const G4AffineTransform GetLocalToGlobalTransform() const;
262  // Obtain the transformations Global/Local (and inverse).
263  // Clients of these methods must copy the data if they need to keep it.
264 
266  G4int dReplicaNo,
267  EVolume dVolumeType );
268  // Obtain mother to daughter transformation
269 
270  inline void ResetStackAndState();
271  // Reset stack and minimum or navigator state machine necessary for reset
272  // as needed by LocalGlobalPointAndSetup.
273  // [Does not perform clears, resizes, or reset fLastLocatedPointLocal]
274 
275  inline G4int SeverityOfZeroStepping( G4int* noZeroSteps ) const;
276  // Report on severity of error and number of zero steps,
277  // in case Navigator is stuck and is returning zero steps.
278  // Values: 1 (small problem), 5 (correcting),
279  // 9 (ready to abandon), 10 (abandoned)
280 
282  // Return the local coordinate of the point in the reference system
283  // of its containing volume that was found by LocalGlobalPointAndSetup.
284  // The local coordinate of the last located track.
285 
286  inline G4ThreeVector NetTranslation() const;
287  inline G4RotationMatrix NetRotation() const;
288  // Compute+return the local->global translation/rotation of current volume.
289 
290  inline void EnableBestSafety( G4bool value= false );
291  // Enable best-possible evaluation of isotropic safety
292 
293  protected: // with description
294 
295  void SetSavedState();
296  // ( fValidExitNormal, fExitNormal, fExiting, fEntering,
297  // fBlockedPhysicalVolume, fBlockedReplicaNo, fLastStepWasZero);
298  // Extended to include:
299  // ( fLastLocatedPointLocal, fLocatedOutsideWorld;
300  // fEnteredDaughter, fExitedMother
301  // fPreviousSftOrigin, sPreviousSafety) Safety Sphere.
302 
303  void RestoreSavedState();
304  // Copy aspects of the state, to enable a non-state changing
305  // call to ComputeStep().
306 
307  virtual void ResetState();
308  // Utility method to reset the navigator state machine.
309 
310  inline G4ThreeVector ComputeLocalPoint(const G4ThreeVector& rGlobPoint) const;
311  // Return position vector in local coordinate system, given a position
312  // vector in world coordinate system.
313 
314  inline G4ThreeVector ComputeLocalAxis(const G4ThreeVector& pVec) const;
315  // Return the local direction of the specified vector in the reference
316  // system of the volume that was found by LocalGlobalPointAndSetup.
317  // The Local Coordinates of point in world coordinate system.
318 
319  inline EVolume VolumeType(const G4VPhysicalVolume *pVol) const;
320  // Characterise `type' of volume - normal/replicated/parameterised.
321 
322  inline EVolume CharacteriseDaughters(const G4LogicalVolume *pLog) const;
323  // Characterise daughter of logical volume.
324 
325  inline G4int GetDaughtersRegularStructureId(const G4LogicalVolume *pLog) const;
326  // Get regular structure ID of first daughter
327 
328  virtual void SetupHierarchy();
329  // Renavigate & reset hierarchy described by current history
330  // o Reset volumes
331  // o Recompute transforms and/or solids of replicated/parameterised
332  // volumes.
333 
334  private:
335 
336  void ComputeStepLog(const G4ThreeVector& pGlobalpoint,
337  G4double moveLenSq) const;
338  // Log and checks for steps larger than the tolerance
339 
340  protected: // without description
341 
343  // Geometrical tolerance for surface thickness of shapes.
344 
345  //
346  // BEGIN State information
347  //
348 
350  // Transformation and history of the current path
351  // through the geometrical hierarchy.
352 
354  // A memory of whether in this Step a daughter volume is entered
355  // (set in Compute & Locate).
356  // After Compute: it expects to enter a daughter
357  // After Locate: it has entered a daughter
358 
360  // A similar memory whether the Step exited current "mother" volume
361  // completely, not entering daughter.
362 
364  // Set true if last Step was limited by geometry.
365 
367  // Endpoint of last ComputeStep
368  // can be used for optimisation (e.g. when computing safety).
370  // Position of the end-point of the last call to ComputeStep
371  // in last Local coordinates.
372 
374  // Verbose(ness) level [if > 0, printout can occur].
375 
376  private:
377 
378  G4bool fActive;
379  // States if the navigator is activated or not.
380 
381  G4bool fLastTriedStepComputation;
382  // Whether ComputeStep was called since the last call to a Locate method
383  // Uses: - distinguish parts of state which differ before/after calls
384  // to ComputeStep or one of the Locate methods;
385  // - avoid two consecutive calls to compute-step (illegal).
386 
387  G4bool fEntering,fExiting;
388  // Entering/Exiting volumes blocking/setup
389  // o If exiting
390  // volume ptr & replica number (set & used by Locate..())
391  // used for blocking on redescent of geometry
392  // o If entering
393  // volume ptr & replica number (set by ComputeStep(),used by
394  // Locate..()) of volume for `automatic' entry
395 
396  G4VPhysicalVolume *fBlockedPhysicalVolume;
397  G4int fBlockedReplicaNo;
398 
399  G4ThreeVector fLastLocatedPointLocal;
400  // Position of the last located point relative to its containing volume.
401  G4bool fLocatedOutsideWorld;
402  // Whether the last call to Locate methods left the world
403 
404  G4bool fValidExitNormal; // Set true if have leaving volume normal
405  G4ThreeVector fExitNormal; // Leaving volume normal, in the
406  // volume containing the exited
407  // volume's coordinate system
408  G4ThreeVector fGrandMotherExitNormal; // Leaving volume normal, in its
409  // own coordinate system
410  G4bool fChangedGrandMotherRefFrame; // Whether frame is changed
411 
412  G4ThreeVector fExitNormalGlobalFrame; // Leaving volume normal, in the
413  // global coordinate system
414  G4bool fCalculatedExitNormal; // Has it been computed since
415  // the last call to ComputeStep
416  // Covers both Global and GrandMother
417 
418  // Count zero steps - as one or two can occur due to changing momentum at
419  // a boundary or at an edge common between volumes
420  // - several are likely a problem in the geometry
421  // description or in the navigation
422  //
423  G4bool fLastStepWasZero;
424  // Whether the last ComputeStep moved Zero. Used to check for edges.
425 
426  G4bool fLocatedOnEdge;
427  // Whether the Navigator has detected an edge
428  G4int fNumberZeroSteps;
429  // Number of preceding moves that were Zero. Reset to 0 after finite step
430  G4int fActionThreshold_NoZeroSteps;
431  // After this many failed/zero steps, act (push etc)
432  G4int fAbandonThreshold_NoZeroSteps;
433  // After this many failed/zero steps, abandon track
434 
435  G4ThreeVector fPreviousSftOrigin;
436  G4double fPreviousSafety;
437  // Memory of last safety origin & value. Used in ComputeStep to ensure
438  // that origin of current Step is in the same volume as the point of the
439  // last relocation
440 
441  //
442  // END State information
443  //
444 
445  // Save key state information (NOT the navigation history stack)
446  //
447  struct G4SaveNavigatorState
448  {
449  G4ThreeVector sExitNormal;
450  G4bool sValidExitNormal;
451  G4bool sEntering, sExiting;
452  G4VPhysicalVolume* spBlockedPhysicalVolume;
453  G4int sBlockedReplicaNo;
454  G4int sLastStepWasZero;
455 
456  // Potentially relevant
457  //
458  G4bool sLocatedOutsideWorld;
459  G4ThreeVector sLastLocatedPointLocal;
460  G4bool sEnteredDaughter, sExitedMother;
461  G4ThreeVector sPreviousSftOrigin;
462  G4double sPreviousSafety;
463  } fSaveState;
464 
465  // Tracking Invariants
466  //
467  G4VPhysicalVolume *fTopPhysical;
468  // A link to the topmost physical volume in the detector.
469  // Must be positioned at the origin and unrotated.
470 
471  // Utility information
472  //
473  G4bool fCheck;
474  // Check-mode flag [if true, more strict checks are performed].
475  G4bool fPushed, fWarnPush;
476  // Push flags [if true, means a stuck particle has been pushed].
477 
478  // Helpers/Utility classes
479  //
480  G4NormalNavigation fnormalNav;
481  G4VoxelNavigation fvoxelNav;
482  G4ParameterisedNavigation fparamNav;
483  G4ReplicaNavigation freplicaNav;
484  G4RegularNavigation fregularNav;
485 };
486 
487 #include "G4Navigator.icc"
488 
489 #endif
490 
491 
492 // NOTES:
493 //
494 // The following methods provide detailed information when a Step has
495 // arrived at a geometrical boundary. They distinguish between the different
496 // causes that can result in the track leaving its current volume.
497 //
498 // Four cases are possible:
499 //
500 // 1) The particle has reached a boundary of a daughter of the current volume:
501 // (this could cause the relocation to enter the daughter itself
502 // or a potential granddaughter or further descendant)
503 //
504 // 2) The particle has reached a boundary of the current
505 // volume, exiting into a mother (regardless the level
506 // at which it is located in the tree):
507 //
508 // 3) The particle has reached a boundary of the current
509 // volume, exiting into a volume which is not in its
510 // parental hierarchy:
511 //
512 // 4) The particle is not on a boundary between volumes:
513 // the function returns an exception, and the caller is
514 // reccomended to compare the G4touchables associated
515 // to the preStepPoint and postStepPoint to handle this case.
516 //
517 // G4bool EnteredDaughterVolume()
518 // G4bool IsExitNormalValid()
519 // G4ThreeVector GetLocalExitNormal()
520 //
521 // The expected usefulness of these methods is to allow the caller to
522 // determine how to compute the surface normal at the volume boundary. The two
523 // possibilities are to obtain the normal from:
524 //
525 // i) the solid associated with the volume of the initial point of the Step.
526 // This is valid for cases 2 and 3.
527 // (Note that the initial point is generally the PreStepPoint of a Step).
528 // or
529 //
530 // ii) the solid of the final point, ie of the volume after the relocation.
531 // This is valid for case 1.
532 // (Note that the final point is generally the PreStepPoint of a Step).
533 //
534 // This way the caller can always get a valid normal, pointing outside
535 // the solid for which it is computed, that can be used at his own
536 // discretion.