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