root/Math/GSLMCIntegrator.h

0001 // @(#)root/mathmore:$Id$
0002 // Author: Magdalena Slawinska 08/2007
0003
0004 /**********************************************************************
0005  *                                                                    *
0006  * Copyright (c) 2007 ROOT Foundation,  CERN/PH-SFT                   *
0007  *                                                                    *
0008  * This library is free software; you can redistribute it and/or      *
0009  * modify it under the terms of the GNU General Public License        *
0010  * as published by the Free Software Foundation; either version 2     *
0011  * of the License, or (at your option) any later version.             *
0012  *                                                                    *
0013  * This library is distributed in the hope that it will be useful,    *
0014  * but WITHOUT ANY WARRANTY; without even the implied warranty of     *
0015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU   *
0016  * General Public License for more details.                           *
0017  *                                                                    *
0018  * You should have received a copy of the GNU General Public License  *
0019  * along with this library (see file COPYING); if not, write          *
0020  * to the Free Software Foundation, Inc., 59 Temple Place, Suite      *
0021  * 330, Boston, MA 02111-1307 USA, or contact the author.             *
0022  *                                                                    *
0023  **********************************************************************/
0024 //
0025 // Header file for class GSLMCIntegrator
0026 //
0027 //
0028
0029 #ifndef ROOT_Math_GSLMCIntegrator
0030 #define ROOT_Math_GSLMCIntegrator
0031
0032 #include "Math/MCIntegrationTypes.h"
0033
0034 #include "Math/IFunctionfwd.h"
0035
0036 #include "Math/IFunction.h"
0037
0038 #include "Math/MCParameters.h"
0039
0040 #include "Math/VirtualIntegrator.h"
0041
0042 #include <iostream>
0043
0044
0045 namespace ROOT {
0046 namespace Math {
0047
0048
0049
0050    class GSLMCIntegrationWorkspace;
0051    class GSLMonteFunctionWrapper;
0052    class GSLRandomEngine;
0053    class GSLRngWrapper;
0054
0055
0056    /**
0057       @defgroup MCIntegration Numerical Monte Carlo Integration Classes
0058       Classes implementing method for Monte Carlo Integration.
0059       @ingroup Integration
0060
0061     Class for performing numerical integration of a multidimensional function.
0062     It uses the numerical integration algorithms of GSL, which reimplements the
0063     algorithms used in the QUADPACK, a numerical integration package written in Fortran.
0064
0065     Plain MC, MISER and VEGAS integration algorithms are supported for integration over finite (hypercubic) ranges.
0066
0067     <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_16.html#SEC248">GSL Manual</A>.
0068
0069     It implements also the interface ROOT::Math::VirtualIntegratorMultiDim so it can be
0070     instantiate using the plugin manager (plugin name is "GSLMCIntegrator")
0071    */
0072
0073
0074    class GSLMCIntegrator : public VirtualIntegratorMultiDim {
0075
0076    public:
0077
0078       typedef MCIntegration::Type Type;
0079
0080       // constructors
0081
0082
0083 //       /**
0084 //           constructor of GSL MCIntegrator using all the default options
0085 //       */
0086 //       GSLMCIntegrator( );
0087
0088
0089        /** constructor of GSL MCIntegrator. VEGAS MC is set as default integration type
0090
0091       @param type type of integration. The possible types are defined in the MCIntegration::Type enumeration
0092                                         Default is VEGAS
0093       @param absTol desired absolute Error  (this parameter is actually not used and it can be ignored. The tolerance is fixed by the number of given calls)
0094       @param relTol desired relative Error  (this parameter is actually not used and it can be ignored. The tolerance is fixed by the number of given calls)
0095       @param calls maximum number of function calls
0096
0097       NOTE: When the default values are used , the options are taken from the static method of ROOT::Math::IntegratorMultiDimOptions
0098       */
0099       explicit
0100       GSLMCIntegrator(MCIntegration::Type type = MCIntegration::kVEGAS, double absTol = -1, double relTol = -1, unsigned int calls = 0 );
0101
0102       /** constructor of GSL MCIntegrator. VEGAS MC is set as default integration type
0103
0104       @param type type of integration using a char * (required by plug-in manager)
0105       @param absTol desired absolute Error
0106       @param relTol desired relative Error
0107       @param calls maximum number of function calls
0108       */
0109       GSLMCIntegrator(const char *  type, double absTol, double relTol, unsigned int calls);
0110
0111
0112       /**
0113           destructor
0114       */
0115       ~GSLMCIntegrator() override;
0116
0117       // disable copy ctrs
0118
0119 private:
0120
0121       GSLMCIntegrator(const GSLMCIntegrator &);
0122
0123       GSLMCIntegrator & operator=(const GSLMCIntegrator &);
0124
0125 public:
0126
0127
0128          // template methods for generic functors
0129
0130          /**
0131          method to set the a generic integration function
0132
0133           @param f integration function. The function type must implement the assignment operator, <em>  double  operator() (  double  x ) </em>
0134
0135           */
0136
0137
0138       void SetFunction(const IMultiGenFunction &f) override;
0139
0140
0141       typedef double ( * GSLMonteFuncPointer ) ( double *, size_t, void *);
0142
0143       void SetFunction( GSLMonteFuncPointer f, unsigned int dim, void * p = nullptr );
0144
0145       // methods using GSLMonteFuncPointer
0146
0147       /**
0148          evaluate the Integral of a function f over the defined hypercube (a,b)
0149        @param f integration function. The function type must implement the mathlib::IGenFunction interface
0150        @param dim the dimension
0151        @param a lower value of the integration interval
0152        @param b upper value of the integration interval
0153        @param p pointer to parameter array
0154        */
0155
0156       double Integral(const GSLMonteFuncPointer & f, unsigned int dim, double* a, double* b, void * p = nullptr);
0157
0158
0159       /**
0160          evaluate the integral using the previously defined function
0161        */
0162       double Integral(const double* a, const double* b) override;
0163
0164
0165       // to be added later
0166       //double Integral(const GSLMonteFuncPointer & f);
0167
0168      //double Integral(GSLMonteFuncPointer f, void * p, double* a, double* b);
0169
0170       /**
0171          return the type of the integration used
0172        */
0173       //MCIntegration::Type MCType() const;
0174
0175       /**
0176          return  the Result of the last Integral calculation
0177        */
0178       double Result() const override;
0179
0180       /**
0181          return the estimate of the absolute Error of the last Integral calculation
0182        */
0183       double Error() const override;
0184
0185       /**
0186          return the Error Status of the last Integral calculation
0187        */
0188       int Status() const override;
0189
0190
0191       /**
0192           return number of function evaluations in calculating the integral
0193           (This is an fixed by the user)
0194       */
0195       int NEval() const override { return fCalls; }
0196
0197
0198       // setter for control Parameters  (getters are not needed so far )
0199
0200       /**
0201          set the desired relative Error
0202        */
0203       void SetRelTolerance(double relTolerance) override;
0204
0205
0206       /**
0207          set the desired absolute Error
0208        */
0209       void SetAbsTolerance(double absTolerance) override;
0210
0211       /**
0212          set the integration options
0213        */
0214       void SetOptions(const ROOT::Math::IntegratorMultiDimOptions & opt) override;
0215
0216
0217       /**
0218        set random number generator
0219       */
0220       void SetGenerator(GSLRandomEngine & r);
0221
0222       /**
0223        set integration method
0224       */
0225       void SetType(MCIntegration::Type type);
0226
0227       /**
0228        set integration method using a name instead of an enumeration
0229       */
0230       void SetTypeName(const char * typeName);
0231
0232
0233       /**
0234        set integration mode for VEGAS method
0235          The possible MODE are :
0236          MCIntegration::kIMPORTANCE (default) : VEGAS will use importance sampling
0237          MCIntegration::kSTRATIFIED           : VEGAS will use stratified sampling  if certain condition are satisfied
0238          MCIntegration::kIMPORTANCE_ONLY      : VEGAS will always use importance sampling
0239       */
0240
0241       void SetMode(MCIntegration::Mode mode);
0242
0243       /**
0244        set default parameters for VEGAS method
0245       */
0246       void SetParameters(const VegasParameters &p);
0247
0248
0249       /**
0250        set default parameters for MISER method
0251       */
0252       void SetParameters(const MiserParameters &p);
0253
0254       /**
0255        set parameters for PLAIN method
0256       */
0257       //void SetParameters(const PlainParameters &p);
0258
0259       /**
0260        returns the error sigma from the last iteration of the Vegas algorithm
0261       */
0262       double Sigma();
0263
0264       /**
0265        returns chi-squared per degree of freedom for the estimate of the integral in the Vegas algorithm
0266       */
0267       double ChiSqr();
0268
0269       /**
0270           return the type
0271           (need to be called GetType to avoid a conflict with typedef)
0272       */
0273       MCIntegration::Type GetType() const { return fType; }
0274
0275       /**
0276           return the name
0277       */
0278       const char * GetTypeName() const;
0279
0280       /**
0281          get the option used for the integration
0282       */
0283       ROOT::Math::IntegratorMultiDimOptions Options() const override;
0284
0285       /**
0286          get the specific options (for Vegas or Miser)
0287          in term of string-  name. This is for querying existing options and
0288          return object is managed by the user
0289       */
0290       std::unique_ptr<ROOT::Math::IOptions> ExtraOptions() const;
0291
0292       /**
0293        * Set the extra options for Vegas and Miser.
0294       */
0295       void SetExtraOptions(const ROOT::Math::IOptions & opt);
0296
0297
0298    protected:
0299
0300       // internal method to check validity of GSL function pointer
0301       bool CheckFunction();
0302
0303       // set internally the type of integration method
0304       void DoInitialize( );
0305
0306
0307    private:
0308       //type of integration method
0309       MCIntegration::Type fType;
0310
0311       GSLRngWrapper * fRng;
0312
0313       unsigned int fDim;
0314       unsigned int fCalls;
0315       double fAbsTol;
0316       double fRelTol;
0317
0318       // cache Error, Result and Status of integration
0319
0320       double fResult;
0321       double fError;
0322       int fStatus;
0323       bool fExtGen;   // flag indicating if class uses an external generator provided by the user
0324
0325
0326       GSLMCIntegrationWorkspace * fWorkspace;
0327       GSLMonteFunctionWrapper * fFunction;
0328
0329    };
0330
0331
0332
0333
0334
0335 } // namespace Math
0336 } // namespace ROOT
0337
0338
0339 #endif /* ROOT_Math_GSLMCIntegrator */