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