include/Geant4/G4PathFinder.hh

0001 //
0002 // ********************************************************************
0003 // * License and Disclaimer                                           *
0004 // *                                                                  *
0005 // * The  Geant4 software  is  copyright of the Copyright Holders  of *
0006 // * the Geant4 Collaboration.  It is provided  under  the terms  and *
0007 // * conditions of the Geant4 Software License,  included in the file *
0008 // * LICENSE and available at  http://cern.ch/geant4/license .  These *
0009 // * include a list of copyright holders.                             *
0010 // *                                                                  *
0011 // * Neither the authors of this software system, nor their employing *
0012 // * institutes,nor the agencies providing financial support for this *
0013 // * work  make  any representation or  warranty, express or implied, *
0014 // * regarding  this  software system or assume any liability for its *
0015 // * use.  Please see the license in the file  LICENSE  and URL above *
0016 // * for the full disclaimer and the limitation of liability.         *
0017 // *                                                                  *
0018 // * This  code  implementation is the result of  the  scientific and *
0019 // * technical work of the GEANT4 collaboration.                      *
0020 // * By using,  copying,  modifying or  distributing the software (or *
0021 // * any work based  on the software)  you  agree  to acknowledge its *
0022 // * use  in  resulting  scientific  publications,  and indicate your *
0023 // * acceptance of all terms of the Geant4 Software license.          *
0024 // ********************************************************************
0025 //
0026 // G4PathFinder
0027 //
0028 // Class description:
0029 //
0030 // This class directs the lock-stepped propagation of a track in the
0031 // 'mass' and other parallel geometries. It ensures that tracking
0032 // in a magnetic field sees these parallel geometries at each trial step,
0033 // and that the earliest boundary limits the step.
0034 //
0035 // In field, it relies on the class G4PropagatorInField.
0036
0037 // Author: John Apostolakis (CERN), 7 October 2005
0038 // ---------------------------------------------------------------------
0039 #ifndef G4PATHFINDER_HH
0040 #define G4PATHFINDER_HH  1
0041
0042 #include <vector>
0043
0044 #include "G4Types.hh"
0045 #include "G4FieldTrack.hh"
0046 #include "G4MultiNavigator.hh"
0047 #include "G4TouchableHandle.hh"
0048
0049 class G4TransportationManager;
0050 class G4Navigator;
0051 class G4PropagatorInField;
0052
0053 /**
0054  * @brief G4PathFinder directs the lock-stepped propagation of a track in the
0055  * 'mass' and other parallel geometries. It ensures that tracking in a magnetic
0056  * field sees these parallel geometries at each trial step and that the earliest
0057  * boundary limits the step.
0058  */
0059
0060 class G4PathFinder
0061 {
0062   public:
0063
0064     /**
0065      * Retrieves singleton instance and creates it if not existing.
0066      */
0067     static G4PathFinder* GetInstance();
0068
0069     /**
0070      * Retrieve singleton instance pointer.
0071      */
0072     static G4PathFinder* GetInstanceIfExist();
0073
0074     /**
0075      * Destructor, called only by G4RunManagerKernel.
0076      */
0077     ~G4PathFinder();
0078
0079     /**
0080      * Computes the next geometric Step, curved or linear.
0081      * If it is called with a larger 'stepNo' it will execute a new step;
0082      * if 'stepNo' is same as last call, then the results for the geometry
0083      * with Id number 'navigatorId' will be returned.
0084      *  @param[in,out] pFieldTrack Field track to be filled.
0085      *  @param[in] pCurrentProposedStepLength Current proposed step length.
0086      *  @param[in] navigatorId Identifier of the geometry.
0087      *  @param[in] stepNo Step number; see next step/check.
0088      *  @param[in, out] pNewSafety New safety for this geometry.
0089      *  @param[in, out] limitedStep Step characterisation to be returned.
0090      *  @param[in, out] EndState Field track end state.
0091      *  @param[in] currentVolume Pointer to the current volume.
0092      *  @returns Step length.
0093      */
0094     G4double ComputeStep( const G4FieldTrack& pFieldTrack,
0095                           G4double  pCurrentProposedStepLength,
0096                           G4int     navigatorId, // Identifies the geometry
0097                           G4int     stepNo,      // See next step/check
0098                           G4double& pNewSafety,  // Only for this geometry
0099                           ELimited& limitedStep,
0100                           G4FieldTrack& EndState,
0101                           G4VPhysicalVolume* currentVolume );
0102
0103     /**
0104      * Makes primary relocation of the global point in all navigators,
0105      * and updates them.
0106      *  @param[in] position Point in global coordinates system.
0107      *  @param[in] direction Global direction vector.
0108      *  @param[in] relativeSearch If set to true (default), the search begins
0109      *             is the geometrical hierarchy at the location of the last
0110      *             located point.
0111      */
0112     void Locate( const G4ThreeVector& position,
0113                  const G4ThreeVector& direction,
0114                        G4bool relativeSearch = true);
0115
0116     /**
0117      * Makes secondary relocation of the global point (within safety only)
0118      * in all navigators, and updates them.
0119      *  @param[in] position Point in global coordinates system.
0120      */
0121     void ReLocate( const G4ThreeVector& position );
0122
0123     /**
0124      * Checks and caches the set of active navigators.
0125      *  @param[in] position Point in global coordinates system.
0126      *  @param[in] direction Global direction vector.
0127      *  @param[in] massStartVol Pointer to the mass geometry world.
0128      */
0129     void PrepareNewTrack( const G4ThreeVector& position,
0130                           const G4ThreeVector& direction,
0131                                 G4VPhysicalVolume* massStartVol = nullptr);
0132
0133     /**
0134      * Signals the end of tracking of the current track. Resets internal state
0135      * and informs G4TransportationManager to use 'ordinary' Navigator.
0136      */
0137     void EndTrack();
0138
0139     /**
0140      * Creates a touchable handle for the specified navigator.
0141      *  @param[in] navId The navigator identifier.
0142      *  @returns A touchable handle of the geometry.
0143      */
0144     G4TouchableHandle CreateTouchableHandle( G4int navId ) const;
0145
0146     /**
0147      * Returns the located volume for the specified navigator.
0148      *  @param[in] navId The navigator identifier.
0149      *  @returns A pointer to the located volume in the geometry.
0150      */
0151     inline G4VPhysicalVolume* GetLocatedVolume( G4int navId ) const;
0152
0153     // -----------------------------------------------------------------
0154
0155     /**
0156      * Returns the minimum value of safety after last ComputeStep().
0157      */
0158     inline G4double GetCurrentSafety() const;
0159
0160     /**
0161      * Gets the minimum step size from the last ComputeStep() call.
0162      *  @note In case full step is taken, this is kInfinity.
0163      */
0164     inline G4double GetMinimumStep() const;
0165
0166     /**
0167      * Returns the number of all geometries limiting the step.
0168      */
0169     inline unsigned int GetNumberGeometriesLimitingStep() const;
0170
0171     /**
0172      * Recomputes the safety for the relevant point, i.e. the endpoint of the
0173      * last step. Maintains a vector of individual safety values (used by next
0174      * method below).
0175      *  @param[in] globalPoint Point in global coordinates system.
0176      *  @returns The safety value for the specified point in the geometry.
0177      */
0178     G4double ComputeSafety( const G4ThreeVector& globalPoint);
0179
0180     /**
0181      * Obtains the safety for the specified navigator/geometry for last point
0182      * 'computed' (i.e., the last point for which ComputeSafety() was called).
0183      *  @param[in] navId The navigator identifier.
0184      *  @param[in,out] globalCenterPoint The point (center) for which this
0185      *                 safety is valid.
0186      *  @returns The safety value in the specified geometry.
0187      */
0188     inline G4double ObtainSafety(G4int navId, G4ThreeVector& globalCenterPoint);
0189
0190     /**
0191      * To enable parallel navigation. Must call it to ensure that G4PathFinder
0192      * is prepared, especially for curved tracks.
0193      * If true it switches G4PropagatorInField to use G4MultiNavigator.
0194      * Must call it with false to undo (i.e. G4PropagatorInField uses classic
0195      * G4Navigator for tracking in such case).
0196      *  @param[in] enableChoice Flag to enable/disable parallel navigation.
0197      */
0198     void EnableParallelNavigation( G4bool enableChoice = true );
0199
0200     /**
0201      * To control the level of verbosity. Default is no verbosity.
0202      */
0203     inline G4int SetVerboseLevel(G4int lev = -1);
0204
0205     /**
0206      * To get/set the maximum for the number of steps that a (looping)
0207      * particle can take.
0208      */
0209     inline G4int GetMaxLoopCount() const;
0210     inline void  SetMaxLoopCount( G4int new_max );
0211
0212     /**
0213      * Signals that the point location will be moved.
0214      *  @note Internal use primarily.
0215      */
0216     inline void MovePoint();
0217
0218     // To provide best compatibility between Coupled and normal Transportation
0219     // the next two methods are provided...
0220
0221     /**
0222      * Obtains the last safety needed in ComputeStep() for the specified
0223      * geometry 'navId' (i.e. the last point at which ComputeStep() has
0224      * recalculated the safety). Returns the point (center) for which this
0225      * safety is valid and also the minimum safety over all navigators.
0226      *  @param[in] navId The navigator identifier.
0227      *  @param[in,out] globCenterPoint The point (center) for which this
0228      *                 safety is valid.
0229      *  @param[in,out] minSafety The minimum safety over all navigators.
0230      *  @returns The safety value in the specified geometry.
0231      */
0232     inline G4double LastPreSafety( G4int navId, G4ThreeVector& globCenterPoint,
0233                                    G4double& minSafety );
0234
0235     /**
0236      * Tells G4PathFinder to copy PostStep Safety to PreSafety
0237      * for use at the next step.
0238      */
0239     void PushPostSafetyToPreSafety();
0240
0241     /**
0242      * Utility to convert ELimited specification to a string.
0243      */
0244     G4String& LimitedString( ELimited lim );
0245
0246   private:
0247
0248     /**
0249      * Private singleton constructor.
0250      */
0251     G4PathFinder();
0252
0253     /**
0254      * Returns pointer to the specified navigator.
0255      */
0256     inline G4Navigator* GetNavigator(G4int n) const;
0257
0258     /**
0259      * Performs a linear step.
0260      *  @param[in,out] FieldTrack Field track to be filled.
0261      *  @param[in] proposedStepLength Current proposed step length.
0262      *  @returns The minimum linear step to undertake.
0263      */
0264     G4double DoNextLinearStep( const G4FieldTrack& FieldTrack,
0265                                      G4double proposedStepLength);
0266
0267     /**
0268      * Performs a curved step.
0269      *  @param[in,out] FieldTrack Field track to be filled.
0270      *  @param[in] proposedStepLength Current proposed step length.
0271      *  @param[in] pCurrentPhysVolume Pointer to the current volume of interest.
0272      *  @returns The minimum step to undertake.
0273      */
0274     G4double DoNextCurvedStep( const G4FieldTrack& FieldTrack,
0275                                      G4double proposedStepLength,
0276                                      G4VPhysicalVolume* pCurrentPhysVolume);
0277
0278     /**
0279      * Prints key details out for debugging.
0280      */
0281     void WhichLimited();
0282     void PrintLimited();
0283
0284     /**
0285      * Helper method to report movement (likely of initial point).
0286      */
0287     void ReportMove( const G4ThreeVector& OldV,
0288                      const G4ThreeVector& NewV,
0289                      const G4String& Quantity ) const;
0290
0291   private:
0292
0293     // ----------------------------------------------------------------------
0294     //  DATA Members
0295     // ----------------------------------------------------------------------
0296
0297     /** Object that enables G4PropagatorInField to see many geometries. */
0298     G4MultiNavigator* fpMultiNavigator;
0299
0300     G4int fNoActiveNavigators = 0;
0301     G4bool fNewTrack = false; // Flag a new track (ensure first step)
0302
0303     static const G4int fMaxNav = 16;
0304
0305     // Global state (retained during stepping for one track)
0306
0307     G4Navigator*  fpNavigator[fMaxNav];
0308
0309     // ---- State changed in a step computation
0310     //
0311     ELimited fLimitedStep[fMaxNav];
0312     G4bool fLimitTruth[fMaxNav];
0313     G4double fCurrentStepSize[fMaxNav];
0314     G4int fNoGeometriesLimiting = 0;  // How many processes contribute to limit
0315
0316     /** Last initial position for which safety evaluated. */
0317     G4ThreeVector fPreSafetyLocation;
0318     /* Corresponding value of full safety. */
0319     G4double fPreSafetyMinValue = -1.0;
0320
0321     /** Safeties for the above point. */
0322     G4double fPreSafetyValues[ fMaxNav ];
0323
0324     // This part of the state can be retained for several calls --> CARE
0325
0326     /** Point where last ComputeStep() called. */
0327     G4ThreeVector fPreStepLocation;
0328     /** Corresponding value of full safety. */
0329     G4double fMinSafety_PreStepPt = -1.0;
0330
0331     /** Safeties for the above point.
0332       * @note This changes at each step, so it can differ when steps
0333       *       inside min-safety are made. */
0334     G4double fCurrentPreStepSafety[ fMaxNav ];
0335
0336     /** Whether PreSafety coincides with PreStep point. */
0337     G4bool fPreStepCenterRenewed = false;
0338
0339     G4double fMinStep = -1.0;  // As reported by Navigators -- can be kInfinity
0340     G4double fTrueMinStep = -1.0;  // Corrected in case >= proposed
0341
0342     // ---- State after calling 'locate'
0343     //
0344     G4VPhysicalVolume* fLocatedVolume[fMaxNav];
0345     G4ThreeVector      fLastLocatedPosition;
0346
0347     // ---- State after calling 'ComputeStep'
0348     //      (other member variables will be affected)
0349     //
0350     G4FieldTrack fEndState;  // Point, velocity, ... at proposed step end
0351     G4bool fFieldExertedForce = false; // In current proposed step
0352
0353     G4bool fRelocatedPoint = false; // Signals that point was or is being moved
0354                                     // from the position of the last location or
0355                                     // the endpoint resulting from ComputeStep()
0356                                     // -- invalidates fEndState
0357
0358     // ---- State for 'ComputeSafety' and related methods
0359     //
0360     /** Point where ComputeSafety() is called. */
0361     G4ThreeVector fSafetyLocation;
0362     /** Corresponding value of safety. */
0363     G4double      fMinSafety_atSafLocation = -1.0;
0364     /** Safeties for last ComputeSafety(). */
0365     G4double      fNewSafetyComputed[ fMaxNav ];
0366
0367     // ---- State for Step numbers
0368     //
0369     G4int fLastStepNo = -1, fCurrentStepNo = -1;
0370
0371     G4int fVerboseLevel = 0;  // For debugging purposes
0372
0373     G4TransportationManager* fpTransportManager; // Cache for frequent use
0374     G4PropagatorInField* fpFieldPropagator;
0375
0376     G4double kCarTolerance;
0377
0378     static G4ThreadLocal G4PathFinder* fpPathFinder;
0379 };
0380
0381 // ********************************************************************
0382 // Inline methods.
0383 // ********************************************************************
0384
0385 #include "G4PathFinder.icc"
0386
0387 #endif