include/Geant4/G4FSALIntegrationDriver.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 // G4FSALIntegrationDriver
0027 //
0028 // Class description:
0029 //
0030 // Driver class which controls the integration error of a Runge-Kutta stepper
0031
0032 // Author: Dmitry Sorokin (CERN, Google Summer of Code 2017), 20.10.2017
0033 // --------------------------------------------------------------------
0034 #ifndef G4FSALINTEGRATIONDRIVER_HH
0035 #define G4FSALINTEGRATIONDRIVER_HH
0036
0037 #include "G4RKIntegrationDriver.hh"
0038 #include "G4ChordFinderDelegate.hh"
0039
0040 /**
0041  * @brief G4FSALIntegrationDriver is a templated driver class which controls
0042  * the integration error of a Runge-Kutta stepper.
0043  */
0044
0045 template <class T>
0046 class G4FSALIntegrationDriver : public G4RKIntegrationDriver<T>,
0047                                 public G4ChordFinderDelegate<G4FSALIntegrationDriver<T>>
0048 {
0049   public:
0050
0051     /**
0052      * Constructor for G4FSALIntegrationDriver.
0053      *  @param[in] hminimum Minimum allowed step.
0054      *  @param[in] stepper Pointer to the stepper algorithm.
0055      *  @param[in] numberOfComponents The number of integration variables,
0056      *             if not matching stepper's number of variables, issue exception.
0057      *  @param[in] statisticsVerbosity Verbosity level.
0058      */
0059     inline G4FSALIntegrationDriver(G4double hminimum,
0060                                    T* stepper,
0061                                    G4int numberOfComponents = 6,
0062                                    G4int statisticsVerbosity = 1);
0063
0064     /**
0065      * Destructor. Provides statistics if verbosity level is greater than zero.
0066      */
0067     inline ~G4FSALIntegrationDriver() override;
0068
0069     /**
0070      * Copy constructor and assignment operator not allowed.
0071      */
0072     G4FSALIntegrationDriver(const G4FSALIntegrationDriver&) = delete;
0073     G4FSALIntegrationDriver& operator=(const G4FSALIntegrationDriver&) = delete;
0074
0075     /**
0076      * Computes the step to take, based on chord limits.
0077      *  @param[in,out] track The current track in field.
0078      *  @param[in] hstep Proposed step length.
0079      *  @param[in] eps Requested accuracy, y_err/hstep.
0080      *  @param[in] chordDistance Maximum sagitta distance.
0081      *  @returns The length of step taken.
0082      */
0083     inline G4double AdvanceChordLimited(G4FieldTrack& track,
0084                                         G4double hstep,
0085                                         G4double eps,
0086                                         G4double chordDistance) override;
0087
0088     /**
0089      * Dispatch interface method for initialisation/reset of driver.
0090      */
0091     inline void OnStartTracking() override;
0092
0093     /**
0094      * Dispatch interface method for computing step. Does nothing here.
0095      */
0096     inline void OnComputeStep(const G4FieldTrack* /*track*/ = nullptr) override;
0097
0098     /**
0099      * The driver does implement re-integration. Returns true.
0100      */
0101     inline G4bool DoesReIntegrate() const override;
0102
0103     /**
0104      * Advances integration accurately by relative accuracy better than 'eps'.
0105      * On output the track is replaced by the value at the end of interval.
0106      *  @param[in,out] track The current track in field.
0107      *  @param[in] hstep Proposed step length.
0108      *  @param[in] eps Requested accuracy, y_err/hstep.
0109      *  @param[in] hinitial Initial minimum integration step.
0110      *  @returns true if integration succeeds.
0111      */
0112     inline G4bool AccurateAdvance(G4FieldTrack& track,
0113                                   G4double hstep,
0114                                   G4double eps, // Requested y_err/hstep
0115                                   G4double hinitial = 0.0) override;
0116
0117     /**
0118      * Attempts one integration step, and returns estimated error 'dyerr'.
0119      * It does not ensure accuracy.
0120      *  @param[in,out] fieldTrack The current track in field.
0121      *  @param[in] dydx dydx array.
0122      *  @param[in] hstep Proposed step length.
0123      *  @param[out] dchord_step Estimated sagitta distance.
0124      *  @param[out] dyerr Estimated error.
0125      *  @returns true if integration succeeds.
0126      */
0127     inline G4bool QuickAdvance(G4FieldTrack& fieldTrack,
0128                                const G4double dydx[],
0129                                G4double hstep,
0130                                G4double& dchord_step,
0131                                G4double& dyerr) override;
0132
0133     /**
0134      * Takes one Step that is as large as possible while satisfying the
0135      * accuracy criterion.
0136      *  @param[in,out] y The current track state, y.
0137      *  @param[in] dydx dydx array.
0138      *  @param[in,out] curveLength Step start, x.
0139      *  @param[in] htry Step to attempt.
0140      *  @param[in] eps The relative accuracy.
0141      *  @param[out] hdid Step achieved.
0142      *  @param[out] hnext Proposed next step.
0143      */
0144     inline void OneGoodStep(G4double y[],  // InOut
0145                             G4double dydx[],
0146                             G4double& curveLength,
0147                             G4double htry,
0148                             G4double eps,
0149                             G4double& hdid,
0150                             G4double& hnext);
0151
0152     /**
0153      * Setter and getter for verbosity.
0154      */
0155     inline void SetVerboseLevel(G4int newLevel) override;
0156     inline G4int GetVerboseLevel() const override;
0157
0158     /**
0159      * Writes out to stream the parameters/state of the driver.
0160      */
0161     inline void StreamInfo( std::ostream& os ) const override;
0162
0163     /**
0164      * Getter and Setter for minimum allowed step.
0165      */
0166     inline G4double GetMinimumStep() const;
0167     inline void SetMinimumStep(G4double newval);
0168
0169     /**
0170      * Getter and Setter for smallest fraction.
0171      */
0172     inline G4double GetSmallestFraction() const;
0173     inline void SetSmallestFraction(G4double val);
0174
0175   protected:
0176
0177     /**
0178      * Increments the counter for the number of calls to QuickAdvance().
0179      */
0180     inline void IncrementQuickAdvanceCalls();
0181
0182   private:
0183
0184     /**
0185      * Checks accuracy of step distance on the end point.
0186      */
0187     inline void CheckStep(const G4ThreeVector& posIn,
0188                           const G4ThreeVector& posOut, G4double hdid);
0189
0190   private:
0191
0192     /** Minimum Step allowed in a Step (in absolute units). */
0193     G4double fMinimumStep;
0194
0195     /** Smallest fraction of (existing) curve length in relative units.
0196      *  Below this fraction the current step will be the last.
0197      *  The expected range: smaller than 0.1 * epsilon and bigger than 5e-13
0198      *  (range not enforced). */
0199     G4double fSmallestFraction{1e-12};
0200
0201     /** Verbosity level for printing (debug, etc..)
0202      *  Could be varied during tracking to help identifying issues. */
0203     G4int fVerboseLevel;
0204
0205     G4int fNoQuickAvanceCalls{0};
0206     G4int fNoAccurateAdvanceCalls{0};
0207     G4int fNoAccurateAdvanceBadSteps{0};
0208     G4int fNoAccurateAdvanceGoodSteps{0};
0209
0210     using Base = G4RKIntegrationDriver<T>;
0211     using ChordFinderDelegate = G4ChordFinderDelegate<G4FSALIntegrationDriver<T>>;
0212 };
0213
0214 #include "G4FSALIntegrationDriver.icc"
0215
0216 #endif