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
38namespace 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 */
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 */
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 /// In some cases, the derivative algorithm will use information from the previous step, these can be passed
219 /// in with this overload. The previous_* arrays can also be used to return second derivative and step size
220 /// so that these can be passed forward again as well at the call site, if necessary.
221 T Derivative(const T *x, unsigned int icoord, T *previous_grad, T *previous_g2,
222 T *previous_gstep) const
223 {
224 return DoDerivativeWithPrevResult(x, icoord, previous_grad, previous_g2, previous_gstep);
225 }
226
227 /**
228 Optimized method to evaluate at the same time the function value and derivative at a point x.
229 Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
230 Derived class should implement this method if performances play an important role and if it is faster to
231 evaluate value and derivative at the same time
232
233 */
234 virtual void FdF(const T *x, T &f, T *df) const = 0;
235
236 private:
237
238
239 /**
240 function to evaluate the derivative with respect each coordinate. To be implemented by the derived class
241 */
242 virtual T DoDerivative(const T *x, unsigned int icoord) const = 0;
243 /// In some cases, the derivative algorithm will use information from the previous step, these can be passed
244 /// in with this overload. The previous_* arrays can also be used to return second derivative and step size
245 /// so that these can be passed forward again as well at the call site, if necessary.
246 virtual T DoDerivativeWithPrevResult(const T *x, unsigned int icoord, T * /*previous_grad*/,
247 T * /*previous_g2*/, T * /*previous_gstep*/) const
248 {
249 return DoDerivative(x, icoord);
250 };
251 };
252
253//___________________________________________________________________________________
254 /**
255 Specialized Gradient interface(abstract class) for one dimensional functions
256 It provides a method to evaluate the derivative of the function, Derivative and a
257 method to evaluate at the same time the function and the derivative FdF
258
259 Concrete classes should derive from ROOT::Math::IGradientFunctionOneDim and not from this class.
260
261 @ingroup GenFunc
262 */
264
265 public:
266
267 /// virtual destructor
269
270 /**
271 Return the derivative of the function at a point x
272 Use the private method DoDerivative
273 */
274 double Derivative(double x) const
275 {
276 return DoDerivative(x);
277 }
278
279
280 /**
281 Optimized method to evaluate at the same time the function value and derivative at a point x.
282 Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
283 Derived class should implement this method if performances play an important role and if it is faster to
284 evaluate value and derivative at the same time
285
286 */
287 virtual void FdF(double x, double &f, double &df) const = 0;
288
289
290 /**
291 Compatibility method with multi-dimensional interface for partial derivative
292 */
293 double Derivative(const double *x) const
294 {
295 return DoDerivative(*x);
296 }
297
298 /**
299 Compatibility method with multi-dimensional interface for Gradient
300 */
301 void Gradient(const double *x, double *g) const
302 {
303 g[0] = DoDerivative(*x);
304 }
305
306 /**
307 Compatibility method with multi-dimensional interface for Gradient and function evaluation
308 */
309 void FdF(const double *x, double &f, double *df) const
310 {
311 FdF(*x, f, *df);
312 }
313
314
315
316 private:
317
318
319 /**
320 function to evaluate the derivative with respect each coordinate. To be implemented by the derived class
321 */
322 virtual double DoDerivative(double x) const = 0;
323
324 };
325
326//___________________________________________________________________________________
327 /**
328 Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
329 It implements both the ROOT::Math::IBaseFunctionMultiDimTempl and
332 ROOT::Math::IFunction::Derivative calculates the partial derivative for each coordinate and
333 ROOT::Math::Fdf calculates the gradient and the function value at the same time.
334 The pure private virtual method DoDerivative() must be implemented by the derived classes, while
335 Gradient and FdF are by default implemented using DoDerivative, butthey can be overloaded by the
336 derived classes to improve the efficiency in the derivative calculation.
337
338 @ingroup GenFunc
339 */
340
341 template <class T>
344
345 public:
348
349 /**
350 Virtual Destructor (no operations)
351 */
353
354 /**
355 Evaluate all the vector of function derivatives (gradient) at a point x.
356 Derived classes must re-implement it if more efficient than evaluting one at a time
357 */
359 {
360 unsigned int ndim = NDim();
361 for (unsigned int icoord = 0; icoord < ndim; ++icoord)
363 }
364
365 /// In some cases, the gradient algorithm will use information from the previous step, these can be passed
366 /// in with this overload. The previous_* arrays can also be used to return second derivative and step size
367 /// so that these can be passed forward again as well at the call site, if necessary.
369 {
370 unsigned int ndim = NDim();
371 for (unsigned int icoord = 0; icoord < ndim; ++icoord)
373 }
374
375 using BaseFunc::NDim;
376
377 /**
378 Optimized method to evaluate at the same time the function value and derivative at a point x.
379 Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
380 Derived class should implement this method if performances play an important role and if it is faster to
381 evaluate value and derivative at the same time
382 */
383 virtual void FdF(const T *x, T &f, T *df) const
384 {
387 }
388
389 virtual bool returnsInMinuit2ParameterSpace() const { return false; }
390 };
391
392//___________________________________________________________________________________
393 /**
394 Interface (abstract class) for one-dimensional functions providing a gradient calculation.
395 It implements both the ROOT::Math::IBaseFunctionOneDim and
397 The method ROOT::Math::IFunction::Derivative calculates the derivative and
398 ROOT::Math::Fdf calculates the derivative and the function values at the same time.
399 The pure private virtual method DoDerivative() must be implemented by the derived classes, while
400 FdF is by default implemented using DoDerivative, but it can be overloaded by the
401 derived classes to improve the efficiency in the derivative calculation.
402
403
404 @ingroup GenFunc
405 */
406 //template <>
408 virtual public IBaseFunctionOneDim ,
410
411
412 public:
413
416
417
418 /**
419 Virtual Destructor (no operations)
420 */
422
423
424 /**
425 Optimized method to evaluate at the same time the function value and derivative at a point x.
426 Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
427 Derived class should implement this method if performances play an important role and if it is faster to
428 evaluate value and derivative at the same time
429
430 */
431 virtual void FdF(double x, double &f, double &df) const
432 {
433 f = operator()(x);
434 df = Derivative(x);
435 }
436
437
438
439 };
440
441
442
443 } // namespace Math
444} // namespace ROOT
445
446#endif /* ROOT_Math_IFunction */
#define f(i)
Definition: RSha256.hxx:104
#define g(i)
Definition: RSha256.hxx:105
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:62
virtual IBaseFunctionMultiDimTempl< T > * Clone() const =0
Clone a function.
T operator()(const T *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:92
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:67
virtual unsigned int NDim() const =0
Retrieve the dimension of the function.
virtual T DoEval(const T *x) const =0
Implementation of the evaluation function.
virtual ~IBaseFunctionMultiDimTempl()
virtual destructor
Definition: IFunction.h:75
Interface (abstract class) for generic functions objects of one-dimension Provides a method to evalua...
Definition: IFunction.h:135
virtual ~IBaseFunctionOneDim()
virtual destructor
Definition: IFunction.h:146
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:139
virtual double DoEval(double x) const =0
implementation of the evaluation function. Must be implemented by derived classes
double operator()(const double *x) const
Evaluate the function at a point x[].
Definition: IFunction.h:167
virtual IBaseFunctionOneDim * Clone() const =0
Clone a 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
Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
Definition: IFunction.h:343
Virtual Destructor (no operations)
Definition: IFunction.h:352
Definition: IFunction.h:347
Evaluate all the vector of function derivatives (gradient) at a point x.
Definition: IFunction.h:358
virtual unsigned int NDim() const=0
Retrieve the dimension of the function.
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:383
In some cases, the gradient algorithm will use information from the previous step,...
Definition: IFunction.h:368
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:346
virtual bool returnsInMinuit2ParameterSpace() const
Definition: IFunction.h:389
Interface (abstract class) for one-dimensional functions providing a gradient calculation.
Definition: IFunction.h:409
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:431
IBaseFunctionOneDim BaseFunc
Definition: IFunction.h:414
Virtual Destructor (no operations)
Definition: IFunction.h:421
Gradient interface (abstract class) defining the signature for calculating the gradient of a multi-di...
Definition: IFunction.h:201
virtual T DoDerivative(const T *x, unsigned int icoord) const =0
function to evaluate the derivative with respect each coordinate.
T Derivative(const T *x, unsigned int icoord=0) const
Return the partial derivative with respect to the passed coordinate.
Definition: IFunction.h:217
Evaluate all the vector of function derivatives (gradient) at a point x.
virtual T DoDerivativeWithPrevResult(const T *x, unsigned int icoord, T *, T *, T *) const
In some cases, the derivative algorithm will use information from the previous step,...
Definition: IFunction.h:246
virual destructor
Definition: IFunction.h:206
T Derivative(const T *x, unsigned int icoord, T *previous_grad, T *previous_g2, T *previous_gstep) const
In some cases, the derivative algorithm will use information from the previous step,...
Definition: IFunction.h:221
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.
Specialized Gradient interface(abstract class) for one dimensional functions It provides a method to ...
Definition: IFunction.h:263
double Derivative(double x) const
Return the derivative of the function at a point x Use the private method DoDerivative.
Definition: IFunction.h:274
virtual double DoDerivative(double x) const =0
function to evaluate the derivative with respect each coordinate.
void FdF(const double *x, double &f, double *df) const
Compatibility method with multi-dimensional interface for Gradient and function evaluation.
Definition: IFunction.h:309
double Derivative(const double *x) const
Compatibility method with multi-dimensional interface for partial derivative.
Definition: IFunction.h:293