Logo ROOT   6.08/07
Reference Guide
IFunction.h
Go to the documentation of this file.
1 // @(#)root/mathcore:$Id$
2 // Authors: L. Moneta 11/2006
3 
4 /**********************************************************************
5  * *
6  * Copyright (c) 2006 , LCG ROOT MathLib Team *
7  * *
8  * *
9  **********************************************************************/
10 
11 // Header file for function interfaces
12 //
13 // Generic Interfaces for one or multi-dimensional functions
14 //
15 // Created by: Lorenzo Moneta : Wed Nov 13 2006
16 //
17 //
18 #ifndef ROOT_Math_IFunction
19 #define ROOT_Math_IFunction
20 
21 /**
22 @defgroup CppFunctions Function Classes and Interfaces
23 
24  Interfaces (abstract classes) and Base classes used in MathCore and MathMore numerical methods
25  for describing function classes. They define function and gradient evaluation and as well the
26  functionality for dealing with parameters in the case of parametric functions which are used for
27  fitting and data modeling.
28  Included are also adapter classes, such as functors, to wrap generic callable C++ objects
29  in the desired interface.
30 
31 @ingroup MathCore
32 */
33 
34 //typedefs and tags definitions
35 #ifndef ROOT_Math_IFunctionfwd
36 #include "Math/IFunctionfwd.h"
37 #endif
38 
39 
40 namespace ROOT {
41 namespace Math {
42 
43 /**
44  @defgroup GenFunc Generic Function Evaluation Interfaces
45  Interface classes for evaluation of function object classes in one or multi-dimensions.
46  @ingroup CppFunctions
47 */
48 
49 //___________________________________________________________________________________
50  /**
51  Documentation for the abstract class IBaseFunctionMultiDim.
52  Interface (abstract class) for generic functions objects of multi-dimension
53  Provides a method to evaluate the function given a vector of coordinate values,
54  by implementing operator() (const double *).
55  In addition it defines the interface for copying functions via the pure virtual method Clone()
56  and the interface for getting the function dimension via the NDim() method.
57  Derived classes must implement the pure private virtual method DoEval(const double *) for the
58  function evaluation in addition to NDim() and Clone().
59 
60  @ingroup GenFunc
61  */
62 
64 
65  public:
66 
68 
69 
71 
72  /**
73  virtual destructor
74  */
76 
77  /**
78  Clone a function.
79  Each derived class must implement their version of the Clone method
80  */
81  virtual IBaseFunctionMultiDim * Clone() const = 0;
82 
83  /**
84  Retrieve the dimension of the function
85  */
86  virtual unsigned int NDim() const = 0;
87 
88  /**
89  Evaluate the function at a point x[].
90  Use the pure virtual private method DoEval which must be implemented by the sub-classes
91  */
92  double operator() (const double* x) const {
93  return DoEval(x);
94  }
95 
96 #ifdef LATER
97  /**
98  Template method to eveluate the function using the begin of an iterator
99  User is responsible to provide correct size for the iterator
100  */
101  template <class Iterator>
102  double operator() (const Iterator it ) const {
103  return DoEval( &(*it) );
104  }
105 #endif
106 
107 
108  private:
109 
110 
111  /**
112  Implementation of the evaluation function. Must be implemented by derived classes
113  */
114  virtual double DoEval(const double * x) const = 0;
115 
116 
117  };
118 
119 
120 //___________________________________________________________________________________
121  /**
122  Interface (abstract class) for generic functions objects of one-dimension
123  Provides a method to evaluate the function given a value (simple double)
124  by implementing operator() (const double ).
125  In addition it defines the interface for copying functions via the pure virtual method Clone().
126  Derived classes must implement the pure virtual private method DoEval(double ) for the
127  function evaluation in addition to Clone().
128  An interface for evaluating the function passing a vector (like for multidim functions) is also
129  provided
130 
131  @ingroup GenFunc
132  */
134 
135  public:
136 
138 
140 
141  /**
142  virtual destructor
143  */
144  virtual ~IBaseFunctionOneDim() {}
145 
146  /**
147  Clone a function.
148  Each derived class will implement their version of the provate DoClone method
149  */
150  virtual IBaseFunctionOneDim * Clone() const = 0;
151 
152  /**
153  Evaluate the function at a point x
154  Use the a pure virtual private method DoEval which must be implemented by sub-classes
155  */
156  double operator() (double x) const {
157  return DoEval(x);
158  }
159 
160  /**
161  Evaluate the function at a point x[].
162  Compatible method with multi-dimensional functions
163  */
164  double operator() (const double * x) const {
165  return DoEval(*x);
166  }
167 
168 
169 
170  private:
171 
172  // use private virtual inheritance
173 
174  /// implementation of the evaluation function. Must be implemented by derived classes
175  virtual double DoEval(double x) const = 0;
176 
177  };
178 
179 
180 //-------- GRAD functions---------------------------
181 
182 //___________________________________________________________________________________
183  /**
184  Gradient interface (abstract class) defining the signature for calculating the gradient of a
185  multi-dimensional function.
186  Three methods are provided:
187  - Gradient(const double *x, double * grad) evaluate the full gradient vector at the vector value x
188  - Derivative(const double * x, int icoord) evaluate the partial derivative for the icoord coordinate
189  - FdF(const double *x, double &f, double * g) evaluate at the same time gradient and function/
190 
191  Concrete classes should derive from ROOT::Math::IGradientFunctionMultiDim and not from this class.
192 
193  @ingroup GenFunc
194  */
195 
197 
198  public:
199 
200  /// virual destructor
201  virtual ~IGradientMultiDim() {}
202 
203  /**
204  Evaluate all the vector of function derivatives (gradient) at a point x.
205  Derived classes must re-implement if it is more efficient than evaluting one at a time
206  */
207  virtual void Gradient(const double *x, double * grad) const = 0;
208 
209  /**
210  Return the partial derivative with respect to the passed coordinate
211  */
212  double Derivative(const double * x, unsigned int icoord = 0) const {
213  return DoDerivative(x, icoord);
214  }
215 
216 
217  /**
218  Optimized method to evaluate at the same time the function value and derivative at a point x.
219  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
220  Derived class should implement this method if performances play an important role and if it is faster to
221  evaluate value and derivative at the same time
222 
223  */
224  virtual void FdF (const double * x, double & f, double * df) const = 0;
225 
226 
227  private:
228 
229 
230  /**
231  function to evaluate the derivative with respect each coordinate. To be implemented by the derived class
232  */
233  virtual double DoDerivative(const double * x, unsigned int icoord ) const = 0;
234 
235  };
236 
237 //___________________________________________________________________________________
238  /**
239  Specialized Gradient interface(abstract class) for one dimensional functions
240  It provides a method to evaluate the derivative of the function, Derivative and a
241  method to evaluate at the same time the function and the derivative FdF
242 
243  Concrete classes should derive from ROOT::Math::IGradientFunctionOneDim and not from this class.
244 
245  @ingroup GenFunc
246  */
248 
249  public:
250 
251  /// virtual destructor
252  virtual ~IGradientOneDim() {}
253 
254  /**
255  Return the derivative of the function at a point x
256  Use the private method DoDerivative
257  */
258  double Derivative(double x ) const {
259  return DoDerivative(x );
260  }
261 
262 
263  /**
264  Optimized method to evaluate at the same time the function value and derivative at a point x.
265  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
266  Derived class should implement this method if performances play an important role and if it is faster to
267  evaluate value and derivative at the same time
268 
269  */
270  virtual void FdF (double x, double & f, double & df) const = 0;
271 
272 
273  /**
274  Compatibility method with multi-dimensional interface for partial derivative
275  */
276  double Derivative(const double * x) const {
277  return DoDerivative( *x);
278  }
279 
280  /**
281  Compatibility method with multi-dimensional interface for Gradient
282  */
283  void Gradient(const double * x, double *g) const {
284  g[0] = DoDerivative( *x);
285  }
286 
287  /**
288  Compatibility method with multi-dimensional interface for Gradient and function evaluation
289  */
290  void FdF(const double * x, double & f, double * df) const {
291  FdF(*x, f, *df);
292  }
293 
294 
295 
296  private:
297 
298 
299  /**
300  function to evaluate the derivative with respect each coordinate. To be implemented by the derived class
301  */
302  virtual double DoDerivative(double x ) const = 0;
303 
304  };
305 
306 //___________________________________________________________________________________
307 /**
308  Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
309  It implements both the ROOT::Math::IBaseFunctionMultiDim and
310  ROOT::Math::IGradientMultiDim interfaces.
311  The method ROOT::Math::IFunction::Gradient calculates the full gradient vector,
312  ROOT::Math::IFunction::Derivative calculates the partial derivative for each coordinate and
313  ROOT::Math::Fdf calculates the gradient and the function value at the same time.
314  The pure private virtual method DoDerivative() must be implemented by the derived classes, while
315  Gradient and FdF are by default implemented using DoDerivative, butthey can be overloaded by the
316  derived classes to improve the efficiency in the derivative calculation.
317 
318  @ingroup GenFunc
319 */
320 
321 
323  virtual public IBaseFunctionMultiDim ,
324  public IGradientMultiDim {
325 
326 
327  public:
328 
331 
332 
333  /**
334  Virtual Destructor (no operations)
335  */
337 
338  /**
339  Evaluate all the vector of function derivatives (gradient) at a point x.
340  Derived classes must re-implement it if more efficient than evaluting one at a time
341  */
342  virtual void Gradient(const double *x, double * grad) const {
343  unsigned int ndim = NDim();
344  for (unsigned int icoord = 0; icoord < ndim; ++icoord)
345  grad[icoord] = BaseGrad::Derivative(x,icoord);
346  }
347 
348  using BaseFunc::NDim;
349 
350 
351  /**
352  Optimized method to evaluate at the same time the function value and derivative at a point x.
353  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
354  Derived class should implement this method if performances play an important role and if it is faster to
355  evaluate value and derivative at the same time
356 
357  */
358  virtual void FdF (const double * x, double & f, double * df) const {
359  f = BaseFunc::operator()(x);
360  Gradient(x,df);
361  }
362 
363 
364  };
365 
366 
367 //___________________________________________________________________________________
368 /**
369  Interface (abstract class) for one-dimensional functions providing a gradient calculation.
370  It implements both the ROOT::Math::IBaseFunctionOneDim and
371  ROOT::Math::IGradientOneDim interfaces.
372  The method ROOT::Math::IFunction::Derivative calculates the derivative and
373  ROOT::Math::Fdf calculates the derivative and the function values at the same time.
374  The pure private virtual method DoDerivative() must be implemented by the derived classes, while
375  FdF is by default implemented using DoDerivative, but it can be overloaded by the
376  derived classes to improve the efficiency in the derivative calculation.
377 
378 
379  @ingroup GenFunc
380 */
381  //template <>
383  virtual public IBaseFunctionOneDim ,
384  public IGradientOneDim {
385 
386 
387  public:
388 
391 
392 
393  /**
394  Virtual Destructor (no operations)
395  */
397 
398 
399  /**
400  Optimized method to evaluate at the same time the function value and derivative at a point x.
401  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
402  Derived class should implement this method if performances play an important role and if it is faster to
403  evaluate value and derivative at the same time
404 
405  */
406  virtual void FdF (double x, double & f, double & df) const {
407  f = operator()(x);
408  df = Derivative(x);
409  }
410 
411 
412 
413  };
414 
415 
416 
417 } // namespace Math
418 } // namespace ROOT
419 
420 #endif /* ROOT_Math_IFunction */
Gradient interface (abstract class) defining the signature for calculating the gradient of a multi-di...
Definition: IFunction.h:196
Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
Definition: IFunction.h:322
Interface (abstract class) for generic functions objects of one-dimension Provides a method to evalua...
Definition: IFunction.h:133
virtual ~IBaseFunctionMultiDim()
virtual destructor
Definition: IFunction.h:75
This namespace contains pre-defined functions to be used in conjuction with TExecutor::Map and TExecu...
Definition: StringConv.hxx:21
void FdF(const double *x, double &f, double *df) const
Compatibility method with multi-dimensional interface for Gradient and function evaluation.
Definition: IFunction.h:290
double operator()(const double *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:92
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:137
double Derivative(const double *x) const
Compatibility method with multi-dimensional interface for partial derivative.
Definition: IFunction.h:276
virtual void Gradient(const double *x, double *grad) const
Evaluate all the vector of function derivatives (gradient) at a point x.
Definition: IFunction.h:342
IBaseFunctionMultiDim BaseFunc
Definition: IFunction.h:67
Interface (abstract class) for one-dimensional functions providing a gradient calculation.
Definition: IFunction.h:382
Specialized Gradient interface(abstract class) for one dimensional functions It provides a method to ...
Definition: IFunction.h:247
IBaseFunctionMultiDim BaseFunc
Definition: IFunction.h:329
Double_t x[n]
Definition: legend1.C:17
void Gradient(const double *x, double *g) const
Compatibility method with multi-dimensional interface for Gradient.
Definition: IFunction.h:283
virtual void FdF(double x, double &f, double &df) const
Optimized method to evaluate at the same time the function value and derivative at a point x...
Definition: IFunction.h:406
virtual ~IGradientFunctionMultiDim()
Virtual Destructor (no operations)
Definition: IFunction.h:336
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:389
virtual unsigned int NDim() const =0
Retrieve the dimension of the function.
double Derivative(const double *x, unsigned int icoord=0) const
Return the partial derivative with respect to the passed coordinate.
Definition: IFunction.h:212
virtual ~IGradientOneDim()
virtual destructor
Definition: IFunction.h:252
double f(double x)
virtual void FdF(const double *x, double &f, double *df) const
Optimized method to evaluate at the same time the function value and derivative at a point x...
Definition: IFunction.h:358
Namespace for new Math classes and functions.
virtual ~IGradientFunctionOneDim()
Virtual Destructor (no operations)
Definition: IFunction.h:396
virtual ~IBaseFunctionOneDim()
virtual destructor
Definition: IFunction.h:144
virtual ~IGradientMultiDim()
virual destructor
Definition: IFunction.h:201
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:63
double Derivative(double x) const
Return the derivative of the function at a point x Use the private method DoDerivative.
Definition: IFunction.h:258
virtual double DoEval(const double *x) const =0
Implementation of the evaluation function.
virtual IBaseFunctionMultiDim * Clone() const =0
Clone a function.