Logo ROOT   6.18/05
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
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 {
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 */
#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:327
virtual ~IGradientFunctionMultiDimTempl()
Virtual Destructor (no operations)
Definition: IFunction.h:336
IGradientMultiDimTempl< T > BaseGrad
Definition: IFunction.h:331
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
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:357
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition: IFunction.h:330
Interface (abstract class) for one-dimensional functions providing a gradient calculation.
Definition: IFunction.h:383
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
virtual ~IGradientFunctionOneDim()
Virtual Destructor (no operations)
Definition: IFunction.h:395
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
virtual void Gradient(const T *x, T *grad) const =0
Evaluate all the vector of function derivatives (gradient) at a point x.
virtual ~IGradientMultiDimTempl()
virual destructor
Definition: IFunction.h:206
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:247
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 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:293
double Derivative(const double *x) const
Compatibility method with multi-dimensional interface for partial derivative.
Definition: IFunction.h:277
virtual ~IGradientOneDim()
virtual destructor
Definition: IFunction.h:252
void Gradient(const double *x, double *g) const
Compatibility method with multi-dimensional interface for Gradient.
Definition: IFunction.h:285
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.
Double_t x[n]
Definition: legend1.C:17
Namespace for new Math classes and functions.
double T(double x)
Definition: ChebyshevPol.h:34
Namespace for new ROOT classes and functions.
Definition: StringConv.hxx:21