Logo ROOT   6.12/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 #include "Math/IFunctionfwd.h"
36 
37 
38 namespace ROOT {
39  namespace Math {
40 
41  /**
42  @defgroup GenFunc Generic Function Evaluation Interfaces
43  Interface classes for evaluation of function object classes in one or multi-dimensions.
44  @ingroup CppFunctions
45  */
46 
47 //___________________________________________________________________________________
48  /**
49  Documentation for the abstract class IBaseFunctionMultiDim.
50  Interface (abstract class) for generic functions objects of multi-dimension
51  Provides a method to evaluate the function given a vector of coordinate values,
52  by implementing operator() (const double *).
53  In addition it defines the interface for copying functions via the pure virtual method Clone()
54  and the interface for getting the function dimension via the NDim() method.
55  Derived classes must implement the pure private virtual method DoEval(const double *) for the
56  function evaluation in addition to NDim() and Clone().
57 
58  @ingroup GenFunc
59  */
60 
61  template<class T>
63 
64  public:
65 
66  typedef T BackendType;
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 IBaseFunctionMultiDimTempl<T> *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  T operator()(const T *x) const
93  {
94  return DoEval(x);
95  }
96 
97 #ifdef LATER
98  /**
99  Template method to eveluate the function using the begin of an iterator
100  User is responsible to provide correct size for the iterator
101  */
102  template <class Iterator>
103  T operator()(const Iterator it) const
104  {
105  return DoEval(&(*it));
106  }
107 #endif
108 
109 
110  private:
111 
112 
113  /**
114  Implementation of the evaluation function. Must be implemented by derived classes
115  */
116  virtual T DoEval(const T *x) const = 0;
117 
118 
119  };
120 
121 
122 //___________________________________________________________________________________
123  /**
124  Interface (abstract class) for generic functions objects of one-dimension
125  Provides a method to evaluate the function given a value (simple double)
126  by implementing operator() (const double ).
127  In addition it defines the interface for copying functions via the pure virtual method Clone().
128  Derived classes must implement the pure virtual private method DoEval(double ) for the
129  function evaluation in addition to Clone().
130  An interface for evaluating the function passing a vector (like for multidim functions) is also
131  provided
132 
133  @ingroup GenFunc
134  */
136 
137  public:
138 
140 
142 
143  /**
144  virtual destructor
145  */
146  virtual ~IBaseFunctionOneDim() {}
147 
148  /**
149  Clone a function.
150  Each derived class will implement their version of the provate DoClone method
151  */
152  virtual IBaseFunctionOneDim *Clone() const = 0;
153 
154  /**
155  Evaluate the function at a point x
156  Use the a pure virtual private method DoEval which must be implemented by sub-classes
157  */
158  double operator()(double x) const
159  {
160  return DoEval(x);
161  }
162 
163  /**
164  Evaluate the function at a point x[].
165  Compatible method with multi-dimensional functions
166  */
167  double operator()(const double *x) const
168  {
169  return DoEval(*x);
170  }
171 
172 
173 
174  private:
175 
176  // use private virtual inheritance
177 
178  /// implementation of the evaluation function. Must be implemented by derived classes
179  virtual double DoEval(double x) const = 0;
180 
181  };
182 
183 
184 //-------- GRAD functions---------------------------
185 
186 //___________________________________________________________________________________
187  /**
188  Gradient interface (abstract class) defining the signature for calculating the gradient of a
189  multi-dimensional function.
190  Three methods are provided:
191  - Gradient(const double *x, double * grad) evaluate the full gradient vector at the vector value x
192  - Derivative(const double * x, int icoord) evaluate the partial derivative for the icoord coordinate
193  - FdF(const double *x, double &f, double * g) evaluate at the same time gradient and function/
194 
195  Concrete classes should derive from ROOT::Math::IGradientFunctionMultiDim and not from this class.
196 
197  @ingroup GenFunc
198  */
199 
200  template <class T>
202 
203  public:
204 
205  /// virual destructor
207 
208  /**
209  Evaluate all the vector of function derivatives (gradient) at a point x.
210  Derived classes must re-implement if it is more efficient than evaluting one at a time
211  */
212  virtual void Gradient(const T *x, T *grad) const = 0;
213 
214  /**
215  Return the partial derivative with respect to the passed coordinate
216  */
217  T Derivative(const T *x, unsigned int icoord = 0) const { return DoDerivative(x, icoord); }
218 
219  /**
220  Optimized method to evaluate at the same time the function value and derivative at a point x.
221  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
222  Derived class should implement this method if performances play an important role and if it is faster to
223  evaluate value and derivative at the same time
224 
225  */
226  virtual void FdF(const T *x, T &f, T *df) const = 0;
227 
228  private:
229 
230 
231  /**
232  function to evaluate the derivative with respect each coordinate. To be implemented by the derived class
233  */
234  virtual T DoDerivative(const T *x, unsigned int icoord) const = 0;
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  {
260  return DoDerivative(x);
261  }
262 
263 
264  /**
265  Optimized method to evaluate at the same time the function value and derivative at a point x.
266  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
267  Derived class should implement this method if performances play an important role and if it is faster to
268  evaluate value and derivative at the same time
269 
270  */
271  virtual void FdF(double x, double &f, double &df) const = 0;
272 
273 
274  /**
275  Compatibility method with multi-dimensional interface for partial derivative
276  */
277  double Derivative(const double *x) const
278  {
279  return DoDerivative(*x);
280  }
281 
282  /**
283  Compatibility method with multi-dimensional interface for Gradient
284  */
285  void Gradient(const double *x, double *g) const
286  {
287  g[0] = DoDerivative(*x);
288  }
289 
290  /**
291  Compatibility method with multi-dimensional interface for Gradient and function evaluation
292  */
293  void FdF(const double *x, double &f, double *df) const
294  {
295  FdF(*x, f, *df);
296  }
297 
298 
299 
300  private:
301 
302 
303  /**
304  function to evaluate the derivative with respect each coordinate. To be implemented by the derived class
305  */
306  virtual double DoDerivative(double x) const = 0;
307 
308  };
309 
310 //___________________________________________________________________________________
311  /**
312  Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
313  It implements both the ROOT::Math::IBaseFunctionMultiDimTempl and
314  ROOT::Math::IGradientMultiDimTempl interfaces.
315  The method ROOT::Math::IFunction::Gradient calculates the full gradient vector,
316  ROOT::Math::IFunction::Derivative calculates the partial derivative for each coordinate and
317  ROOT::Math::Fdf calculates the gradient and the function value at the same time.
318  The pure private virtual method DoDerivative() must be implemented by the derived classes, while
319  Gradient and FdF are by default implemented using DoDerivative, butthey can be overloaded by the
320  derived classes to improve the efficiency in the derivative calculation.
321 
322  @ingroup GenFunc
323  */
324 
325  template <class T>
327  public IGradientMultiDimTempl<T> {
328 
329  public:
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 T *x, T *grad) const
343  {
344  unsigned int ndim = NDim();
345  for (unsigned int icoord = 0; icoord < ndim; ++icoord)
346  grad[icoord] = BaseGrad::Derivative(x, icoord);
347  }
348 
349  using BaseFunc::NDim;
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  virtual void FdF(const T *x, T &f, T *df) const
358  {
359  f = BaseFunc::operator()(x);
360  Gradient(x, df);
361  }
362 
363 
364  };
365 
366 //___________________________________________________________________________________
367  /**
368  Interface (abstract class) for one-dimensional functions providing a gradient calculation.
369  It implements both the ROOT::Math::IBaseFunctionOneDim and
370  ROOT::Math::IGradientOneDim interfaces.
371  The method ROOT::Math::IFunction::Derivative calculates the derivative and
372  ROOT::Math::Fdf calculates the derivative and the function values at the same time.
373  The pure private virtual method DoDerivative() must be implemented by the derived classes, while
374  FdF is by default implemented using DoDerivative, but it can be overloaded by the
375  derived classes to improve the efficiency in the derivative calculation.
376 
377 
378  @ingroup GenFunc
379  */
380  //template <>
382  virtual public IBaseFunctionOneDim ,
383  public IGradientOneDim {
384 
385 
386  public:
387 
390 
391 
392  /**
393  Virtual Destructor (no operations)
394  */
396 
397 
398  /**
399  Optimized method to evaluate at the same time the function value and derivative at a point x.
400  Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
401  Derived class should implement this method if performances play an important role and if it is faster to
402  evaluate value and derivative at the same time
403 
404  */
405  virtual void FdF(double x, double &f, double &df) const
406  {
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 */
virtual ~IGradientMultiDimTempl()
virual destructor
Definition: IFunction.h:206
Interface (abstract class) for generic functions objects of one-dimension Provides a method to evalua...
Definition: IFunction.h:135
Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
Definition: IFunction.h:326
Namespace for new ROOT classes and functions.
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:293
double T(double x)
Definition: ChebyshevPol.h:34
T Derivative(const T *x, unsigned int icoord=0) const
Return the partial derivative with respect to the passed coordinate.
Definition: IFunction.h:217
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:139
double Derivative(const double *x) const
Compatibility method with multi-dimensional interface for partial derivative.
Definition: IFunction.h:277
virtual IBaseFunctionMultiDimTempl< T > * Clone() const =0
Clone a function.
virtual void Gradient(const T *x, T *grad) const
Evaluate all the vector of function derivatives (gradient) at a point x.
Definition: IFunction.h:342
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:330
Interface (abstract class) for one-dimensional functions providing a gradient calculation.
Definition: IFunction.h:381
virtual ~IGradientFunctionMultiDimTempl()
Virtual Destructor (no operations)
Definition: IFunction.h:336
Specialized Gradient interface(abstract class) for one dimensional functions It provides a method to ...
Definition: IFunction.h:247
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:285
virtual ~IBaseFunctionMultiDimTempl()
virtual destructor
Definition: IFunction.h:75
Gradient interface (abstract class) defining the signature for calculating the gradient of a multi-di...
Definition: IFunction.h:201
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:62
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:405
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:388
double operator()(const double *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:167
virtual void FdF(const T *x, T &f, T *df) const
Optimized method to evaluate at the same time the function value and derivative at a point x...
Definition: IFunction.h:357
virtual ~IGradientOneDim()
virtual destructor
Definition: IFunction.h:252
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:67
IGradientMultiDimTempl< T > BaseGrad
Definition: IFunction.h:331
virtual T DoEval(const T *x) const =0
Implementation of the evaluation function.
Namespace for new Math classes and functions.
virtual ~IGradientFunctionOneDim()
Virtual Destructor (no operations)
Definition: IFunction.h:395
virtual ~IBaseFunctionOneDim()
virtual destructor
Definition: IFunction.h:146
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 unsigned int NDim() const =0
Retrieve the dimension of the function.
double operator()(double x) const
Evaluate the function at a point x Use the a pure virtual private method DoEval which must be impleme...
Definition: IFunction.h:158
T operator()(const T *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:92
static constexpr double g