Geant4  10.01.p03
G4ITNavigator1.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 // $Id: G4ITNavigator1.hh 85244 2014-10-27 08:24:13Z gcosmo $
27 //
28 // Original author: Paul Kent, July 95/96
29 //
41 //
42 // Contact : Mathieu Karamitros (kara (AT) cenbg . in2p3 . fr)
43 //
44 // WARNING : This class is released as a prototype.
45 // It might strongly evolve or even disapear in the next releases.
46 //
47 // We would be very happy hearing from you, send us your feedback! :)
48 //
49 // History:
50 // - Created. Paul Kent, Jul 95/96
51 // - Zero step protections J.A. / G.C., Nov 2004
52 // - Added check mode G. Cosmo, Mar 2004
53 // - Made Navigator Abstract G. Cosmo, Nov 2003
54 // - G4ITNavigator1 created M.K., Nov 2012
55 // *********************************************************************
56 
57 #ifndef G4ITNAVIGATOR_HH
58 #define G4ITNAVIGATOR_HH
59 
60 #include "geomdefs.hh"
61 
62 #include "G4ThreeVector.hh"
63 #include "G4AffineTransform.hh"
64 #include "G4RotationMatrix.hh"
65 
66 #include "G4LogicalVolume.hh" // Used in inline methods
67 #include "G4GRSVolume.hh" // " "
68 #include "G4GRSSolid.hh" // " "
69 #include "G4TouchableHandle.hh" // " "
71 
72 #include "G4NavigationHistory.hh"
73 #include "G4NormalNavigation.hh"
74 #include "G4VoxelNavigation.hh"
76 #include "G4ReplicaNavigation.hh"
77 #include "G4RegularNavigation.hh"
78 
79 #include <iostream>
80 
81 class G4VPhysicalVolume;
82 
83 
85 {
87 protected:
89 };
90 
92 {
93 public:
94  static const G4int fMaxNav = 8; // rename to kMaxNoNav ??
95 
96  public: // with description
97 
98  friend std::ostream& operator << (std::ostream &os, const G4ITNavigator1 &n);
99 
100  G4ITNavigator1();
101  // Constructor - initialisers and setup.
102 
103  virtual ~G4ITNavigator1();
104  // Destructor. No actions.
105 
106  // !>
109  void NewNavigatorState();
110  // <!
111 
112  virtual G4double ComputeStep(const G4ThreeVector &pGlobalPoint,
113  const G4ThreeVector &pDirection,
114  const G4double pCurrentProposedStepLength,
115  G4double &pNewSafety);
116  // Calculate the distance to the next boundary intersected
117  // along the specified NORMALISED vector direction and
118  // from the specified point in the global coordinate
119  // system. LocateGlobalPointAndSetup or LocateGlobalPointWithinVolume
120  // must have been called with the same global point prior to this call.
121  // The isotropic distance to the nearest boundary is also
122  // calculated (usually an underestimate). The current
123  // proposed Step length is used to avoid intersection
124  // calculations: if it can be determined that the nearest
125  // boundary is >pCurrentProposedStepLength away, kInfinity
126  // is returned together with the computed isotropic safety
127  // distance. Geometry must be closed.
128 
129  G4double CheckNextStep(const G4ThreeVector &pGlobalPoint,
130  const G4ThreeVector &pDirection,
131  const G4double pCurrentProposedStepLength,
132  G4double &pNewSafety);
133  // Same as above, but do not disturb the state of the Navigator.
134 
135  virtual
137  const G4ThreeVector &direction,
138  const G4TouchableHistory &h);
139 
140  // Resets the geometrical hierarchy and search for the volumes deepest
141  // in the hierarchy containing the point in the global coordinate space.
142  // The direction is used to check if a volume is entered.
143  // The search begin is the geometrical hierarchy at the location of the
144  // last located point, or the endpoint of the previous Step if
145  // SetGeometricallyLimitedStep() has been called immediately before.
146  //
147  // Important Note: In order to call this the geometry MUST be closed.
148 
149  virtual
151  const G4ThreeVector* direction=0,
152  const G4bool pRelativeSearch=true,
153  const G4bool ignoreDirection=true);
154  // Search the geometrical hierarchy for the volumes deepest in the hierarchy
155  // containing the point in the global coordinate space. Two main cases are:
156  // i) If pRelativeSearch=false it makes use of no previous/state
157  // information. Returns the physical volume containing the point,
158  // with all previous mothers correctly set up.
159  // ii) If pRelativeSearch is set to true, the search begin is the
160  // geometrical hierarchy at the location of the last located point,
161  // or the endpoint of the previous Step if SetGeometricallyLimitedStep()
162  // has been called immediately before.
163  // The direction is used (to check if a volume is entered) if either
164  // - the argument ignoreDirection is false, or
165  // - the Navigator has determined that it is on an edge shared by two or
166  // more volumes. (This is state information.)
167  //
168  // Important Note: In order to call this the geometry MUST be closed.
169 
170  virtual
172  // Notify the Navigator that a track has moved to the new Global point
173  // 'position', that is known to be within the current safety.
174  // No check is performed to ensure that it is within the volume.
175  // This method can be called instead of LocateGlobalPointAndSetup ONLY if
176  // the caller is certain that the new global point (position) is inside the
177  // same volume as the previous position. Usually this can be guaranteed
178  // only if the point is within safety.
179 
181  const G4ThreeVector& position,
182  const G4ThreeVector& direction,
183  G4TouchableHandle& oldTouchableToUpdate,
184  const G4bool RelativeSearch = true);
185  // First, search the geometrical hierarchy like the above method
186  // LocateGlobalPointAndSetup(). Then use the volume found and its
187  // navigation history to update the touchable.
188 
190  const G4ThreeVector& position,
191  const G4ThreeVector& direction,
192  G4VTouchable* touchableToUpdate,
193  const G4bool RelativeSearch = true);
194  // First, search the geometrical hierarchy like the above method
195  // LocateGlobalPointAndSetup(). Then use the volume found and its
196  // navigation history to update the touchable.
197 
199  const G4ThreeVector& position,
200  G4VTouchable* touchableToUpdate,
201  const G4bool RelativeSearch = true);
202  // Same as the method above but missing direction.
203 
204  inline void SetGeometricallyLimitedStep();
205  // Inform the navigator that the previous Step calculated
206  // by the geometry was taken in its entirety.
207 
208  virtual G4double ComputeSafety(const G4ThreeVector &globalpoint,
209  const G4double pProposedMaxLength = DBL_MAX,
210  const G4bool keepState = true);
211  // Calculate the isotropic distance to the nearest boundary from the
212  // specified point in the global coordinate system.
213  // The globalpoint utilised must be within the current volume.
214  // The value returned is usually an underestimate.
215  // The proposed maximum length is used to avoid volume safety
216  // calculations. The geometry must be closed.
217  // To ensure minimum side effects from the call, keepState
218  // must be true.
219 
220  inline G4VPhysicalVolume* GetWorldVolume() const;
221  // Return the current world (`topmost') volume.
222 
223  inline void SetWorldVolume(G4VPhysicalVolume* pWorld);
224  // Set the world (`topmost') volume. This must be positioned at
225  // origin (0,0,0) and unrotated.
226 
227  inline G4GRSVolume* CreateGRSVolume() const;
228  inline G4GRSSolid* CreateGRSSolid() const;
231  // `Touchable' creation methods: caller has deletion responsibility.
232 
234  // Returns a reference counted handle to a touchable history.
235 
236  virtual G4ThreeVector GetLocalExitNormal(G4bool* valid);
238  G4bool* valid);
239  virtual G4ThreeVector GetGlobalExitNormal(const G4ThreeVector& point,
240  G4bool* valid);
241  // Return Exit Surface Normal and validity too.
242  // Can only be called if the Navigator's last Step has crossed a
243  // volume geometrical boundary.
244  // It returns the Normal to the surface pointing out of the volume that
245  // was left behind and/or into the volume that was entered.
246  // Convention:
247  // The *local* normal is in the coordinate system of the *final* volume.
248  // Restriction:
249  // Normals are not available for replica volumes (returns valid= false)
250  // These methods takes full care about how to calculate this normal,
251  // but if the surfaces are not convex it will return valid=false.
252 
253  inline G4int GetVerboseLevel() const;
254  inline void SetVerboseLevel(G4int level);
255  // Get/Set Verbose(ness) level.
256  // [if level>0 && G4VERBOSE, printout can occur]
257 
258  inline G4bool IsActive() const;
259  // Verify if the navigator is active.
260  inline void Activate(G4bool flag);
261  // Activate/inactivate the navigator.
262 
263  inline G4bool EnteredDaughterVolume() const;
264  // The purpose of this function is to inform the caller if the track is
265  // entering a daughter volume while exiting from the current volume.
266  // This method returns
267  // - True only in case 1) above, that is when the Step has caused
268  // the track to arrive at a boundary of a daughter.
269  // - False in cases 2), 3) and 4), i.e. in all other cases.
270  // This function is not guaranteed to work if SetGeometricallyLimitedStep()
271  // was not called when it should have been called.
272  inline G4bool ExitedMotherVolume() const;
273  // Verify if the step has exited the mother volume.
274 
275  inline void CheckMode(G4bool mode);
276  // Run navigation in "check-mode", therefore using additional
277  // verifications and more strict correctness conditions.
278  // Is effective only with G4VERBOSE set.
279  inline G4bool IsCheckModeActive() const;
280  inline void SetPushVerbosity(G4bool mode);
281  // Set/unset verbosity for pushed tracks (default is true).
282 
283  void PrintState() const;
284  // Print the internal state of the Navigator (for debugging).
285  // The level of detail is according to the verbosity.
286 
287  inline const G4AffineTransform& GetGlobalToLocalTransform() const;
288  inline const G4AffineTransform GetLocalToGlobalTransform() const;
289  // Obtain the transformations Global/Local (and inverse).
290  // Clients of these methods must copy the data if they need to keep it.
291 
293  G4int dReplicaNo,
294  EVolume dVolumeType );
295  // Obtain mother to daughter transformation
296 
297  inline void ResetStackAndState();
298  // Reset stack and minimum or navigator state machine necessary for reset
299  // as needed by LocalGlobalPointAndSetup.
300  // [Does not perform clears, resizes, or reset fLastLocatedPointLocal]
301 
302  inline G4int SeverityOfZeroStepping( G4int* noZeroSteps ) const;
303  // Report on severity of error and number of zero steps,
304  // in case Navigator is stuck and is returning zero steps.
305  // Values: 1 (small problem), 5 (correcting),
306  // 9 (ready to abandon), 10 (abandoned)
307 
308  void SetSavedState();
309  // ( fValidExitNormal, fExitNormal, fExiting, fEntering,
310  // fBlockedPhysicalVolume, fBlockedReplicaNo, fLastStepWasZero);
311  void RestoreSavedState();
312  // Copy aspects of the state, to enable a non-state changing
313  // call to ComputeStep
314 
316  // Return the local coordinate of the point in the reference system
317  // of its containing volume that was found by LocalGlobalPointAndSetup.
318  // The local coordinate of the last located track.
319 
320  inline G4ThreeVector NetTranslation() const;
321  inline G4RotationMatrix NetRotation() const;
322  // Compute+return the local->global translation/rotation of current volume.
323 
324  inline void EnableBestSafety( G4bool value= false );
325  // Enable best-possible evaluation of isotropic safety
326 
327  virtual void ResetState();
328  // Utility method to reset the navigator state machine.
329 
330  protected: // with description
331 
332  inline G4ThreeVector ComputeLocalPoint(const G4ThreeVector& rGlobPoint) const;
333  // Return position vector in local coordinate system, given a position
334  // vector in world coordinate system.
335 
336  inline G4ThreeVector ComputeLocalAxis(const G4ThreeVector& pVec) const;
337  // Return the local direction of the specified vector in the reference
338  // system of the volume that was found by LocalGlobalPointAndSetup.
339  // The Local Coordinates of point in world coordinate system.
340 
341  inline EVolume VolumeType(const G4VPhysicalVolume *pVol) const;
342  // Characterise `type' of volume - normal/replicated/parameterised.
343 
344  inline EVolume CharacteriseDaughters(const G4LogicalVolume *pLog) const;
345  // Characterise daughter of logical volume.
346 
347  inline G4int GetDaughtersRegularStructureId(const G4LogicalVolume *pLog) const;
348  // Get regular structure ID of first daughter
349 
350  virtual void SetupHierarchy();
351  // Renavigate & reset hierarchy described by current history
352  // o Reset volumes
353  // o Recompute transforms and/or solids of replicated/parameterised
354  // volumes.
355 
356  private:
357 
360  // Private copy-constructor and assignment operator.
361 
362  void ComputeStepLog(const G4ThreeVector& pGlobalpoint,
363  G4double moveLenSq) const;
364  // Log and checks for steps larger than the tolerance
365 
366  protected: // without description
367 
369  // Geometrical tolerance for surface thickness of shapes.
370 
371  //
372  // BEGIN State information
373  //
374 
376  // Transformation and history of the current path
377  // through the geometrical hierarchy.
378 
380  // A memory of whether in this Step a daughter volume is entered
381  // (set in Compute & Locate).
382  // After Compute: it expects to enter a daughter
383  // After Locate: it has entered a daughter
384 
386  // A similar memory whether the Step exited current "mother" volume
387  // completely, not entering daughter.
388 
390  // Set true if last Step was limited by geometry.
391 
393  // Endpoint of last ComputeStep
394  // can be used for optimisation (e.g. when computing safety).
396  // Position of the end-point of the last call to ComputeStep
397  // in last Local coordinates.
398 
400  // Verbose(ness) level [if > 0, printout can occur].
401 
402  private:
403 
405  // States if the navigator is activated or not.
406 
408  // Whether ComputeStep was called since the last call to a Locate method
409  // Uses: - distinguish parts of state which differ before/after calls
410  // to ComputeStep or one of the Locate methods;
411  // - avoid two consecutive calls to compute-step (illegal).
412 
414  // Entering/Exiting volumes blocking/setup
415  // o If exiting
416  // volume ptr & replica number (set & used by Locate..())
417  // used for blocking on redescent of geometry
418  // o If entering
419  // volume ptr & replica number (set by ComputeStep(),used by
420  // Locate..()) of volume for `automatic' entry
421 
424 
426  // Position of the last located point relative to its containing volume.
428  // Whether the last call to Locate methods left the world
429 
430  G4bool fValidExitNormal; // Set true if have leaving volume normal
431  G4ThreeVector fExitNormal; // Leaving volume normal, in the
432  // volume containing the exited
433  // volume's coordinate system
434  G4ThreeVector fGrandMotherExitNormal; // Leaving volume normal, in its
435  // own coordinate system
436  G4bool fChangedGrandMotherRefFrame; // Whether frame is changed
437 
438  G4ThreeVector fExitNormalGlobalFrame; // Leaving volume normal, in the
439  // global coordinate system
440  G4bool fCalculatedExitNormal; // Has it been computed since
441  // the last call to ComputeStep
442  // Covers both Global and GrandMother
443 
444  // Count zero steps - as one or two can occur due to changing momentum at
445  // a boundary or at an edge common between volumes
446  // - several are likely a problem in the geometry
447  // description or in the navigation
448  //
450  // Whether the last ComputeStep moved Zero. Used to check for edges.
451 
453  // Whether the Navigator has detected an edge
455  // Number of preceding moves that were Zero. Reset to 0 after finite step
457  // After this many failed/zero steps, act (push etc)
459  // After this many failed/zero steps, abandon track
460 
463  // Memory of last safety origin & value. Used in ComputeStep to ensure
464  // that origin of current Step is in the same volume as the point of the
465  // last relocation
466 
467  //
468  // END State information
469  //
470 
471  // Save key state information (NOT the navigation history stack)
472  //
474  {
483 
484  // !>
489  // <!
490 
491  // Potentially relevant
492  //
498  } ;
499 
501 
502 
503  // Tracking Invariants
504  //
506  // A link to the topmost physical volume in the detector.
507  // Must be positioned at the origin and unrotated.
508 
509  // Utility information
510  //
512  // Check-mode flag [if true, more strict checks are performed].
514  // Push flags [if true, means a stuck particle has been pushed].
515 
516  // Helpers/Utility classes
517  //
524 };
525 
526 #include "G4ITNavigator1.icc"
527 
528 #endif
529 
530 
531 // NOTES:
532 //
533 // The following methods provide detailed information when a Step has
534 // arrived at a geometrical boundary. They distinguish between the different
535 // causes that can result in the track leaving its current volume.
536 //
537 // Four cases are possible:
538 //
539 // 1) The particle has reached a boundary of a daughter of the current volume:
540 // (this could cause the relocation to enter the daughter itself
541 // or a potential granddaughter or further descendant)
542 //
543 // 2) The particle has reached a boundary of the current
544 // volume, exiting into a mother (regardless the level
545 // at which it is located in the tree):
546 //
547 // 3) The particle has reached a boundary of the current
548 // volume, exiting into a volume which is not in its
549 // parental hierarchy:
550 //
551 // 4) The particle is not on a boundary between volumes:
552 // the function returns an exception, and the caller is
553 // reccomended to compare the G4touchables associated
554 // to the preStepPoint and postStepPoint to handle this case.
555 //
556 // G4bool EnteredDaughterVolume()
557 // G4bool IsExitNormalValid()
558 // G4ThreeVector GetLocalExitNormal()
559 //
560 // The expected usefulness of these methods is to allow the caller to
561 // determine how to compute the surface normal at the volume boundary. The two
562 // possibilities are to obtain the normal from:
563 //
564 // i) the solid associated with the volume of the initial point of the Step.
565 // This is valid for cases 2 and 3.
566 // (Note that the initial point is generally the PreStepPoint of a Step).
567 // or
568 //
569 // ii) the solid of the final point, ie of the volume after the relocation.
570 // This is valid for case 1.
571 // (Note that the final point is generally the PreStepPoint of a Step).
572 //
573 // This way the caller can always get a valid normal, pointing outside
574 // the solid for which it is computed, that can be used at his own
575 // discretion.
G4ThreeVector NetTranslation() const
G4VPhysicalVolume * GetWorldVolume() const
static const G4int fMaxNav
G4int fActionThreshold_NoZeroSteps
friend std::ostream & operator<<(std::ostream &os, const G4ITNavigator1 &n)
virtual void ResetState()
virtual void LocateGlobalPointWithinVolume(const G4ThreeVector &position)
G4GRSSolid * CreateGRSSolid() const
G4ThreeVector GetCurrentLocalCoordinate() const
G4TouchableHistory * CreateTouchableHistory() const
G4VoxelNavigation fvoxelNav
G4bool fChangedGrandMotherRefFrame
void SetWorldVolume(G4VPhysicalVolume *pWorld)
G4SaveNavigatorState * fpSaveState
G4int GetDaughtersRegularStructureId(const G4LogicalVolume *pLog) const
CLHEP::Hep3Vector G4ThreeVector
CLHEP::HepRotation G4RotationMatrix
G4bool fLastTriedStepComputation
virtual G4VPhysicalVolume * LocateGlobalPointAndSetup(const G4ThreeVector &point, const G4ThreeVector *direction=0, const G4bool pRelativeSearch=true, const G4bool ignoreDirection=true)
G4ThreeVector fExitNormal
G4VoxelSafety * fpVoxelSafety
G4ThreeVector ComputeLocalPoint(const G4ThreeVector &rGlobPoint) const
EVolume VolumeType(const G4VPhysicalVolume *pVol) const
void SetGeometricallyLimitedStep()
void LocateGlobalPointAndUpdateTouchableHandle(const G4ThreeVector &position, const G4ThreeVector &direction, G4TouchableHandle &oldTouchableToUpdate, const G4bool RelativeSearch=true)
virtual G4ThreeVector GetLocalExitNormal(G4bool *valid)
G4double fPreviousSafety
G4ThreeVector fLastStepEndPointLocal
void SetVerboseLevel(G4int level)
G4ITNavigator1 & operator=(const G4ITNavigator1 &)
void RestoreSavedState()
void EnableBestSafety(G4bool value=false)
int G4int
Definition: G4Types.hh:78
G4NormalNavigation fnormalNav
void ResetStackAndState()
void CheckMode(G4bool mode)
virtual G4double ComputeStep(const G4ThreeVector &pGlobalPoint, const G4ThreeVector &pDirection, const G4double pCurrentProposedStepLength, G4double &pNewSafety)
G4bool IsActive() const
virtual void SetupHierarchy()
G4int GetVerboseLevel() const
void Activate(G4bool flag)
virtual G4VPhysicalVolume * ResetHierarchyAndLocate(const G4ThreeVector &point, const G4ThreeVector &direction, const G4TouchableHistory &h)
G4int fAbandonThreshold_NoZeroSteps
#define position
Definition: xmlparse.cc:605
G4ThreeVector ComputeLocalAxis(const G4ThreeVector &pVec) const
G4RegularNavigation fregularNav
G4RotationMatrix NetRotation() const
bool G4bool
Definition: G4Types.hh:79
const G4AffineTransform & GetGlobalToLocalTransform() const
G4ThreeVector fStepEndPoint
virtual G4ThreeVector GetLocalExitNormalAndCheck(const G4ThreeVector &point, G4bool *valid)
G4NavigationHistory fHistory
void ComputeStepLog(const G4ThreeVector &pGlobalpoint, G4double moveLenSq) const
G4ITNavigatorState_Lock1 * GetNavigatorState()
G4double CheckNextStep(const G4ThreeVector &pGlobalPoint, const G4ThreeVector &pDirection, const G4double pCurrentProposedStepLength, G4double &pNewSafety)
G4ThreeVector fPreviousSftOrigin
G4VPhysicalVolume * fTopPhysical
const G4int n
void SetNavigatorState(G4ITNavigatorState_Lock1 *)
G4int SeverityOfZeroStepping(G4int *noZeroSteps) const
G4ParameterisedNavigation fparamNav
G4bool fLocatedOutsideWorld
const G4AffineTransform GetLocalToGlobalTransform() const
G4bool IsCheckModeActive() const
G4ThreeVector fLastLocatedPointLocal
void SetPushVerbosity(G4bool mode)
EVolume CharacteriseDaughters(const G4LogicalVolume *pLog) const
G4bool fCalculatedExitNormal
void NewNavigatorState()
G4bool EnteredDaughterVolume() const
void LocateGlobalPointAndUpdateTouchable(const G4ThreeVector &position, const G4ThreeVector &direction, G4VTouchable *touchableToUpdate, const G4bool RelativeSearch=true)
G4bool ExitedMotherVolume() const
G4VPhysicalVolume * spBlockedPhysicalVolume
G4VPhysicalVolume * fBlockedPhysicalVolume
EVolume
Definition: geomdefs.hh:68
double G4double
Definition: G4Types.hh:76
G4GRSVolume * CreateGRSVolume() const
virtual G4ThreeVector GetGlobalExitNormal(const G4ThreeVector &point, G4bool *valid)
G4ReplicaNavigation freplicaNav
virtual G4double ComputeSafety(const G4ThreeVector &globalpoint, const G4double pProposedMaxLength=DBL_MAX, const G4bool keepState=true)
#define DBL_MAX
Definition: templates.hh:83
G4AffineTransform GetMotherToDaughterTransform(G4VPhysicalVolume *dVolume, G4int dReplicaNo, EVolume dVolumeType)
G4double kCarTolerance
G4ThreeVector fGrandMotherExitNormal
G4ThreeVector fExitNormalGlobalFrame
void PrintState() const
G4bool fWasLimitedByGeometry
virtual G4TouchableHistoryHandle CreateTouchableHistoryHandle() const
virtual ~G4ITNavigator1()