include/Geant4/G4VFSALIntegrationStepper.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 // G4VFSALIntegrationStepper
0027 //
0028 // Class description:
0029 //
0030 // Class similar to G4VMagIntegratorStepper, for steppers which
0031 // estimate the value of the derivative at the projected endpoint
0032 // of integration - at each successful step.
0033 // This ability is known as 'First Same As Last' (FSAL). It
0034 // reduces the number of required calls to the equation's
0035 // RightHandSide method, and, as such the number of calls to the
0036 // (potentially expensive) field evaluation methods.
0037 //
0038 // Based on G4VMagIntegratorStepper
0039
0040 // Author: Somnath Banerjee (CERN, Google Summer of Code 2015), 26.05.2016
0041 // Supervision: John Apostolakis (CERN)
0042 // --------------------------------------------------------------------
0043 #ifndef G4VFSALINTEGRATOR_STEPPER_HH
0044 #define G4VFSALINTEGRATOR_STEPPER_HH
0045
0046 #include "G4Types.hh"
0047 #include "G4EquationOfMotion.hh"
0048
0049 /**
0050  * @brief G4VFSALIntegrationStepper is a class similar to
0051  * G4VMagIntegratorStepper, but for steppers which estimate the value of
0052  * the derivative at the projected endpoint of integration, at each successful
0053  * step. This ability is known as 'First Same As Last' (FSAL).
0054  * It reduces the number of required calls to the equation's RightHandSide
0055  * method, and, as such the number of calls to the (potentially expensive)
0056  * field evaluation methods.
0057  */
0058
0059 class G4VFSALIntegrationStepper
0060 {
0061   public:
0062
0063     /**
0064      * Constructor for G4VFSALIntegrationStepper.
0065      *  @param[in] Equation Pointer to the provided equation of motion.
0066      *  @param[in] numStateVariables The number of state variables.
0067      */
0068     G4VFSALIntegrationStepper (G4EquationOfMotion* Equation,
0069                                G4int numIntegrationVariables,
0070                                G4int numStateVariables = 12);
0071
0072     /**
0073      * Default Destructor.
0074      */
0075     virtual ~G4VFSALIntegrationStepper() = default;
0076
0077     /**
0078      * Copy constructor and assignment operator not allowed.
0079      */
0080     G4VFSALIntegrationStepper(const G4VFSALIntegrationStepper&) = delete;
0081     G4VFSALIntegrationStepper& operator=(const G4VFSALIntegrationStepper&) = delete;
0082
0083     /**
0084      * The stepper for the Runge Kutta integration.
0085      * The stepsize is fixed, with the step size given by 'h'.
0086      * Integrates ODE starting values yInput[0 to 6].
0087      * Outputs yout[] and its estimated error yerr[].
0088      *  @param[in] y Starting values array of integration variables.
0089      *  @param[in] dydx Derivatives array.
0090      *  @param[in] h The given step size.
0091      *  @param[out] yout Integration output.
0092      *  @param[out] yerr The estimated error.
0093      *  @param[out] lastDydx Last derivative.
0094      */
0095     virtual void Stepper( const G4double y[],
0096                           const G4double dydx[],
0097                                 G4double h,
0098                                 G4double yout[],
0099                                 G4double yerr[],
0100                                 G4double lastDydx[]) = 0;
0101
0102     /**
0103      * Returns an estimate of the maximum distance of a chord from the
0104      * true path over the segment last integrated.
0105      */
0106     virtual G4double DistChord() const = 0;
0107
0108     /**
0109      * Simple utility function to (re)normalise 'unit velocity' vector.
0110      */
0111     inline void NormaliseTangentVector( G4double vec[6] );
0112
0113     /**
0114      * Simple utility function to (re)normalise 'unit spin' vector.
0115      */
0116     inline void NormalisePolarizationVector( G4double vec[12] );
0117
0118     /**
0119      * Utility method to supply the standard Evaluation of the
0120      * Right Hand side of the associated equation.
0121      */
0122     void RightHandSide( const double y[], double dydx[] );
0123
0124     /**
0125      * Returns the number of variables that the stepper will integrate over.
0126      */
0127     inline G4int GetNumberOfVariables() const;
0128
0129     /**
0130      * Returns the number of variables of state variables (>= above, integration)
0131      */
0132     inline G4int GetNumberOfStateVariables() const;
0133
0134     /**
0135      * Returns the order of the integrator, i.e. its error behaviour
0136      * is of the order O(h^order).
0137      */
0138     virtual G4int IntegratorOrder() const = 0;
0139
0140     /**
0141      * Returns a pointer to the equation of motion.
0142      * As some steppers (e.g. RKG3) require other methods of Eq_Rhs,
0143      * this function allows for access to them.
0144      */
0145     inline G4EquationOfMotion* GetEquationOfMotion();
0146
0147     /**
0148      * Setter for the equation of motion.
0149      */
0150     inline void SetEquationOfMotion(G4EquationOfMotion* newEquation);
0151
0152     /**
0153      * Methods for debug use.
0154      */
0155     inline G4int GetfNoRHSCalls() { return fNoRHSCalls; }
0156     void increasefNORHSCalls();
0157     inline void ResetfNORHSCalls() { fNoRHSCalls = 0; }
0158
0159   private:
0160
0161     G4EquationOfMotion* fEquation_Rhs = nullptr;
0162
0163     /** Variables in integration. */
0164     const G4int fNoIntegrationVariables = 0;
0165
0166     /** Number required for FieldTrack. */
0167     const G4int fNoStateVariables = 0;
0168
0169     /** Used for debug. */
0170     G4int fNoRHSCalls = 0;
0171 };
0172
0173 #include "G4VFSALIntegrationStepper.icc"
0174
0175 #endif