ROOT   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
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  */
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
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
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>
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  */
343  {
344  unsigned int ndim = NDim();
345  for (unsigned int icoord = 0; icoord < ndim; ++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  {
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
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 ,
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 T DoDerivative(const T *x, unsigned int icoord) const =0
function to evaluate the derivative with respect each coordinate.
ROOT::Math::IBaseFunctionMultiDimTempl::BaseFunc
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:67
virual destructor
Definition: IFunction.h:206
f
#define f(i)
Definition: RSha256.hxx:122
Virtual Destructor (no operations)
Definition: IFunction.h:395
double Derivative(const double *x) const
Compatibility method with multi-dimensional interface for partial derivative.
Definition: IFunction.h:277
ROOT::Math::IBaseFunctionOneDim::BaseFunc
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:139
ROOT::Math::IBaseFunctionOneDim::operator()
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
ROOT::Math::IBaseFunctionMultiDimTempl::operator()
T operator()(const T *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:92
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
T Derivative(const T *x, unsigned int icoord=0) const
Return the partial derivative with respect to the passed coordinate.
Definition: IFunction.h:217
IFunctionfwd.h
Definition: IFunction.h:389
ROOT::Math::IBaseFunctionMultiDimTempl::NDim
virtual unsigned int NDim() const =0
Retrieve the dimension of the function.
ROOT::Math::IBaseFunctionMultiDimTempl::Clone
virtual IBaseFunctionMultiDimTempl< T > * Clone() const =0
Clone a function.
x
Double_t x[n]
Definition: legend1.C:17
Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
Definition: IFunction.h:326
Virtual Destructor (no operations)
Definition: IFunction.h:336
void Gradient(const double *x, double *g) const
Compatibility method with multi-dimensional interface for Gradient.
Definition: IFunction.h:285
Definition: IFunction.h:331
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
virtual void FdF(double x, double &f, double &df) const =0
Optimized method to evaluate at the same time the function value and derivative at a point x.
ROOT::Math::IBaseFunctionOneDim::IBaseFunctionOneDim
IBaseFunctionOneDim()
Definition: IFunction.h:141
double Derivative(double x) const
Return the derivative of the function at a point x Use the private method DoDerivative.
Definition: IFunction.h:258
Interface (abstract class) for one-dimensional functions providing a gradient calculation.
Definition: IFunction.h:381
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:330
Evaluate all the vector of function derivatives (gradient) at a point x.
Definition: IFunction.h:342
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 double DoDerivative(double x) const =0
function to evaluate the derivative with respect each coordinate.
ROOT::Math::IBaseFunctionMultiDimTempl::IBaseFunctionMultiDimTempl
IBaseFunctionMultiDimTempl()
Definition: IFunction.h:70
ROOT::Math::IBaseFunctionOneDim::~IBaseFunctionOneDim
virtual ~IBaseFunctionOneDim()
virtual destructor
Definition: IFunction.h:146
ROOT::Math::IBaseFunctionOneDim::operator()
double operator()(const double *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:167
ROOT::Math::IBaseFunctionOneDim::Clone
virtual IBaseFunctionOneDim * Clone() const =0
Clone a function.
ROOT::Math::IBaseFunctionOneDim
Interface (abstract class) for generic functions objects of one-dimension Provides a method to evalua...
Definition: IFunction.h:135
ROOT::Math::IBaseFunctionMultiDimTempl::~IBaseFunctionMultiDimTempl
virtual ~IBaseFunctionMultiDimTempl()
virtual destructor
Definition: IFunction.h:75
ROOT::Math::IBaseFunctionMultiDimTempl::DoEval
virtual T DoEval(const T *x) const =0
Implementation of the evaluation function.
Gradient interface (abstract class) defining the signature for calculating the gradient of a multi-di...
Definition: IFunction.h:201
virtual void FdF(const T *x, T &f, T *df) const =0
Optimized method to evaluate at the same time the function value and derivative at a point x.
ROOT::Math::IBaseFunctionOneDim::DoEval
virtual double DoEval(double x) const =0
implementation of the evaluation function. Must be implemented by derived classes
Specialized Gradient interface(abstract class) for one dimensional functions It provides a method to ...
Definition: IFunction.h:247
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:388
ROOT::Math::Chebyshev::T
double T(double x)
Definition: ChebyshevPol.h:52
ROOT::Math::IBaseFunctionMultiDimTempl
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:62
ROOT::Math::IBaseFunctionMultiDimTempl::BackendType
T BackendType
Definition: IFunction.h:66
ROOT
VSD Structures.
Definition: StringConv.hxx:21
Math