Logo ROOT   6.13/01
Reference Guide
GSLMCIntegrator.h
Go to the documentation of this file.
1 // @(#)root/mathmore:$Id$
2 // Author: Magdalena Slawinska 08/2007
3 
4 /**********************************************************************
5  * *
6  * Copyright (c) 2007 ROOT Foundation, CERN/PH-SFT *
7  * *
8  * This library is free software; you can redistribute it and/or *
9  * modify it under the terms of the GNU General Public License *
10  * as published by the Free Software Foundation; either version 2 *
11  * of the License, or (at your option) any later version. *
12  * *
13  * This library is distributed in the hope that it will be useful, *
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
16  * General Public License for more details. *
17  * *
18  * You should have received a copy of the GNU General Public License *
19  * along with this library (see file COPYING); if not, write *
20  * to the Free Software Foundation, Inc., 59 Temple Place, Suite *
21  * 330, Boston, MA 02111-1307 USA, or contact the author. *
22  * *
23  **********************************************************************/
24 //
25 // Header file for class GSLMCIntegrator
26 //
27 //
28 
29 #ifndef ROOT_Math_GSLMCIntegrator
30 #define ROOT_Math_GSLMCIntegrator
31 
33 
34 #include "Math/IFunctionfwd.h"
35 
36 #include "Math/IFunction.h"
37 
38 
40 
41 
42 #include "Math/MCParameters.h"
43 
44 #include "Math/VirtualIntegrator.h"
45 
46 #include <iostream>
47 
48 
49 namespace ROOT {
50 namespace Math {
51 
52 
53 
54  class GSLMCIntegrationWorkspace;
55  class GSLMonteFunctionWrapper;
56  class GSLRandomEngine;
57  class GSLRngWrapper;
58 
59 
60  /**
61  @defgroup MCIntegration Numerical Monte Carlo Integration Classes
62  Classes implementing method for Monte Carlo Integration.
63  @ingroup Integration
64 
65  Class for performing numerical integration of a multidimensional function.
66  It uses the numerical integration algorithms of GSL, which reimplements the
67  algorithms used in the QUADPACK, a numerical integration package written in Fortran.
68 
69  Plain MC, MISER and VEGAS integration algorithms are supported for integration over finite (hypercubic) ranges.
70 
71  <A HREF="http://www.gnu.org/software/gsl/manual/gsl-ref_16.html#SEC248">GSL Manual</A>.
72 
73  It implements also the interface ROOT::Math::VirtualIntegratorMultiDim so it can be
74  instantiate using the plugin manager (plugin name is "GSLMCIntegrator")
75  */
76 
77 
79 
80  public:
81 
83 
84  // constructors
85 
86 
87 // /**
88 // constructor of GSL MCIntegrator using all the default options
89 // */
90 // GSLMCIntegrator( );
91 
92 
93  /** constructor of GSL MCIntegrator. VEGAS MC is set as default integration type
94 
95  @param type type of integration. The possible types are defined in the MCIntegration::Type enumeration
96  Default is VEGAS
97  @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)
98  @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)
99  @param calls maximum number of function calls
100 
101  NOTE: When the default values are used , the options are taken from teh static method of ROOT::Math::IntegratorMultiDimOptions
102  */
103  explicit
104  GSLMCIntegrator(MCIntegration::Type type = MCIntegration::kVEGAS, double absTol = -1, double relTol = -1, unsigned int calls = 0 );
105 
106  /** constructor of GSL MCIntegrator. VEGAS MC is set as default integration type
107 
108  @param type type of integration using a char * (required by plug-in manager)
109  @param absTol desired absolute Error
110  @param relTol desired relative Error
111  @param calls maximum number of function calls
112  */
113  GSLMCIntegrator(const char * type, double absTol, double relTol, unsigned int calls);
114 
115 
116  /**
117  destructor
118  */
119  virtual ~GSLMCIntegrator();
120 
121  // disable copy ctrs
122 
123 private:
124 
126 
128 
129 public:
130 
131 
132  // template methods for generic functors
133 
134  /**
135  method to set the a generic integration function
136 
137  @param f integration function. The function type must implement the assigment operator, <em> double operator() ( double x ) </em>
138 
139  */
140 
141 
142  void SetFunction(const IMultiGenFunction &f);
143 
144 
145  typedef double ( * GSLMonteFuncPointer ) ( double *, size_t, void *);
146 
147  void SetFunction( GSLMonteFuncPointer f, unsigned int dim, void * p = 0 );
148 
149  // methods using GSLMonteFuncPointer
150 
151  /**
152  evaluate the Integral of a function f over the defined hypercube (a,b)
153  @param f integration function. The function type must implement the mathlib::IGenFunction interface
154  @param a lower value of the integration interval
155  @param b upper value of the integration interval
156  */
157 
158  double Integral(const GSLMonteFuncPointer & f, unsigned int dim, double* a, double* b, void * p = 0);
159 
160 
161  /**
162  evaluate the integral using the previously defined function
163  */
164  double Integral(const double* a, const double* b);
165 
166 
167  // to be added later
168  //double Integral(const GSLMonteFuncPointer & f);
169 
170  //double Integral(GSLMonteFuncPointer f, void * p, double* a, double* b);
171 
172  /**
173  return the type of the integration used
174  */
175  //MCIntegration::Type MCType() const;
176 
177  /**
178  return the Result of the last Integral calculation
179  */
180  double Result() const;
181 
182  /**
183  return the estimate of the absolute Error of the last Integral calculation
184  */
185  double Error() const;
186 
187  /**
188  return the Error Status of the last Integral calculation
189  */
190  int Status() const;
191 
192 
193  /**
194  return number of function evaluations in calculating the integral
195  (This is an fixed by the user)
196  */
197  int NEval() const { return fCalls; }
198 
199 
200  // setter for control Parameters (getters are not needed so far )
201 
202  /**
203  set the desired relative Error
204  */
205  void SetRelTolerance(double relTolerance);
206 
207 
208  /**
209  set the desired absolute Error
210  */
211  void SetAbsTolerance(double absTolerance);
212 
213  /**
214  set the integration options
215  */
217 
218 
219  /**
220  set random number generator
221  */
222  void SetGenerator(GSLRandomEngine & r);
223 
224  /**
225  set integration method
226  */
227  void SetType(MCIntegration::Type type);
228 
229  /**
230  set integration method using a name instead of an enumeration
231  */
232  void SetTypeName(const char * typeName);
233 
234 
235  /**
236  set integration mode for VEGAS method
237  The possible MODE are :
238  MCIntegration::kIMPORTANCE (default) : VEGAS will use importance sampling
239  MCIntegration::kSTRATIFIED : VEGAS will use stratified sampling if certain condition are satisfied
240  MCIntegration::kIMPORTANCE_ONLY : VEGAS will always use importance smapling
241  */
242 
243  void SetMode(MCIntegration::Mode mode);
244 
245  /**
246  set default parameters for VEGAS method
247  */
248  void SetParameters(const VegasParameters &p);
249 
250 
251  /**
252  set default parameters for MISER method
253  */
254  void SetParameters(const MiserParameters &p);
255 
256  /**
257  set parameters for PLAIN method
258  */
259  //void SetPParameters(const PlainParameters &p);
260 
261  /**
262  returns the error sigma from the last iteration of the Vegas algorithm
263  */
264  double Sigma();
265 
266  /**
267  returns chi-squared per degree of freedom for the estimate of the integral in the Vegas algorithm
268  */
269  double ChiSqr();
270 
271  /**
272  return the type
273  (need to be called GetType to avois a conflict with typedef)
274  */
275  MCIntegration::Type GetType() const { return fType; }
276 
277  /**
278  return the name
279  */
280  const char * GetTypeName() const;
281 
282  /**
283  get the option used for the integration
284  */
286 
287  /**
288  get the specific options (for Vegas or Miser)
289  in term of string- name
290  */
292 
293 
294  protected:
295 
296  // internal method to check validity of GSL function pointer
297  bool CheckFunction();
298 
299  // set internally the type of integration method
300  void DoInitialize( );
301 
302 
303  private:
304  //type of intergation method
306 
308 
309  unsigned int fDim;
310  unsigned int fCalls;
311  double fAbsTol;
312  double fRelTol;
313 
314  // cache Error, Result and Status of integration
315 
316  double fResult;
317  double fError;
318  int fStatus;
319  bool fExtGen; // flag indicating if class uses an external generator provided by the user
320 
321 
324 
325  };
326 
327 
328 
329 
330 
331 } // namespace Math
332 } // namespace ROOT
333 
334 
335 #endif /* ROOT_Math_GSLMCIntegrator */
MCIntegration::Type GetType() const
return the type (need to be called GetType to avois a conflict with typedef)
GSLMCIntegrator(MCIntegration::Type type=MCIntegration::kVEGAS, double absTol=-1, double relTol=-1, unsigned int calls=0)
constructor of GSL MCIntegrator using all the default options
double(* GSLMonteFuncPointer)(double *, size_t, void *)
Namespace for new ROOT classes and functions.
Definition: TFoamSampler.h:19
GSLMonteFunctionWrapper * fFunction
double Integral(const GSLMonteFuncPointer &f, unsigned int dim, double *a, double *b, void *p=0)
evaluate the Integral of a function f over the defined hypercube (a,b)
Type
enumeration specifying the integration types.
int Status() const
return the Error Status of the last Integral calculation
MCIntegration::Type Type
structures collecting parameters for MISER multidimensional integration
Definition: MCParameters.h:76
void SetFunction(const IMultiGenFunction &f)
method to set the a generic integration function
structures collecting parameters for VEGAS multidimensional integration FOr implementation of default...
Definition: MCParameters.h:45
void SetRelTolerance(double relTolerance)
set the desired relative Error
double ChiSqr()
returns chi-squared per degree of freedom for the estimate of the integral in the Vegas algorithm ...
GSLRandomEngine Base class for all GSL random engines, normally user instantiate the derived classes ...
virtual ~GSLMCIntegrator()
destructor
GSLMCIntegrationWorkspace * fWorkspace
GSLRngWrapper class to wrap gsl_rng structure.
Definition: GSLRngWrapper.h:25
ROOT::Math::IntegratorMultiDimOptions Options() const
get the option used for the integration
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:62
Numerical multi dimensional integration options.
Interface (abstract) class for multi numerical integration It must be implemented by the concrete Int...
MCIntegration::Type fType
void SetParameters(const VegasParameters &p)
set default parameters for VEGAS method
void SetOptions(const ROOT::Math::IntegratorMultiDimOptions &opt)
set the integration options
ROOT::Math::IOptions * ExtraOptions() const
get the specific options (for Vegas or Miser) in term of string- name
void SetType(MCIntegration::Type type)
set integration method
double Result() const
return the type of the integration used
void SetTypeName(const char *typeName)
set integration method using a name instead of an enumeration
GSLMCIntegrator & operator=(const GSLMCIntegrator &)
void SetGenerator(GSLRandomEngine &r)
set random number generator
const char * GetTypeName() const
return the name
double Sigma()
set parameters for PLAIN method
Namespace for new Math classes and functions.
void SetMode(MCIntegration::Mode mode)
set integration mode for VEGAS method The possible MODE are : MCIntegration::kIMPORTANCE (default) : ...
Generic interface for defining configuration options of a numerical algorithm.
Definition: IOptions.h:30
wrapper to a multi-dim function withtout derivatives for Monte Carlo multi-dimensional integration al...
void SetAbsTolerance(double absTolerance)
set the desired absolute Error
you should not use this method at all Int_t Int_t Double_t Double_t Double_t Int_t Double_t Double_t Double_t Double_t b
Definition: TRolke.cxx:630
double Error() const
return the estimate of the absolute Error of the last Integral calculation
int NEval() const
return number of function evaluations in calculating the integral (This is an fixed by the user) ...