Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
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#include "Math/IFunctionfwd.h"
35
36
37namespace ROOT {
38 namespace Math {
39
40 /**
41 @defgroup GenFunc Generic Function Evaluation Interfaces
42 Interface classes for evaluation of function object classes in one or multi-dimensions.
43 @ingroup CppFunctions
44 */
45
46//___________________________________________________________________________________
47 /**
48 Documentation for the abstract class IBaseFunctionMultiDim.
49 Interface (abstract class) for generic functions objects of multi-dimension
50 Provides a method to evaluate the function given a vector of coordinate values,
51 by implementing operator() (const double *).
52 In addition it defines the interface for copying functions via the pure virtual method Clone()
53 and the interface for getting the function dimension via the NDim() method.
54 Derived classes must implement the pure private virtual method DoEval(const double *) for the
55 function evaluation in addition to NDim() and Clone().
56
57 @note ROOT::Math::Functor is the recommended way to use one's own function with the fitting framework.
58
59 @ingroup GenFunc
60 */
61
62 template<class T>
64
65 public:
66
67 typedef T BackendType;
69
70 virtual ~IBaseFunctionMultiDimTempl() = default;
71
72 /// Clone a function.
73 /// Each derived class must implement their version of the Clone method.
75
76 /// Retrieve the dimension of the function.
77 virtual unsigned int NDim() const = 0;
78
79 /// Evaluate the function at a point x[].
80 /// Use the pure virtual private method DoEval which must be implemented by the sub-classes.
81 T operator()(const T *x) const { return DoEval(x); }
82
83#ifdef LATER
84 /// Template method to evaluate the function using the begin of an iterator.
85 /// User is responsible to provide correct size for the iterator.
86 template <class Iterator>
87 T operator()(const Iterator it) const { return DoEval(&(*it)); }
88#endif
89
90 // Indicate whether this class supports gradient calculations, i.e.,
91 // if it inherits from ROOT::Math::IGradientFunctionMultiDim.
92 virtual bool HasGradient() const { return false; }
93
94 private:
95
96 /// Implementation of the evaluation function. Must be implemented by derived classes.
97 virtual T DoEval(const T *x) const = 0;
98 };
99
100
101//___________________________________________________________________________________
102 /**
103 Interface (abstract class) for generic functions objects of one-dimension
104 Provides a method to evaluate the function given a value (simple double)
105 by implementing operator() (const double ).
106 In addition it defines the interface for copying functions via the pure virtual method Clone().
107 Derived classes must implement the pure virtual private method DoEval(double ) for the
108 function evaluation in addition to Clone().
109 An interface for evaluating the function passing a vector (like for multidim functions) is also
110 provided
111
112 @ingroup GenFunc
113 */
115
116 public:
117
119
120 virtual ~IBaseFunctionOneDim() = default;
121
122 /// Clone a function.
123 /// Each derived class will implement their version of the private DoClone method.
124 virtual IBaseFunctionOneDim *Clone() const = 0;
125
126 /// Evaluate the function at a point x.
127 /// Use the a pure virtual private method DoEval which must be implemented by sub-classes.
128 double operator()(double x) const { return DoEval(x); }
129
130 /// Evaluate the function at a point x[].
131 /// Compatible method with multi-dimensional functions.
132 double operator()(const double *x) const { return DoEval(*x); }
133
134 // Indicate whether this class supports gradient calculations, i.e.,
135 // if it inherits from ROOT::Math::IGradientFunctionOneDim.
136 virtual bool HasGradient() const { return false; }
137
138 private:
139
140 /// implementation of the evaluation function. Must be implemented by derived classes
141 virtual double DoEval(double x) const = 0;
142 };
143
144
145//-------- GRAD functions---------------------------
146
147
148
149//___________________________________________________________________________________
150 /**
151 Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
152 The method ROOT::Math::IFunction::Gradient calculates the full gradient vector,
153 ROOT::Math::IFunction::Derivative calculates the partial derivative for each coordinate and
154 ROOT::Math::Fdf calculates the gradient and the function value at the same time.
155 The pure private virtual method DoDerivative() must be implemented by the derived classes, while
156 Gradient and FdF are by default implemented using DoDerivative, butthey can be overloaded by the
157 derived classes to improve the efficiency in the derivative calculation.
158
159 Gradient interface (abstract class) defining the signature for calculating the gradient of a
160 multi-dimensional function.
161 Three methods are provided:
162 - Gradient(const double *x, double * grad) evaluate the full gradient vector at the vector value x
163 - Derivative(const double * x, int icoord) evaluate the partial derivative for the icoord coordinate
164 - FdF(const double *x, double &f, double * g) evaluate at the same time gradient and function/
165
166 @ingroup GenFunc
167 */
168
169 template <class T>
171
172 public:
175
176
177 /// Evaluate all the vector of function derivatives (gradient) at a point x.
178 /// Derived classes must re-implement it if more efficient than evaluating one at a time
179 virtual void Gradient(const T *x, T *grad) const
180 {
181 unsigned int ndim = NDim();
182 for (unsigned int icoord = 0; icoord < ndim; ++icoord) {
183 grad[icoord] = Derivative(x, icoord);
184 }
185 }
186
187 /// In some cases, the gradient algorithm will use information from the previous step, these can be passed
188 /// in with this overload. The `previous_*` arrays can also be used to return second derivative and step size
189 /// so that these can be passed forward again as well at the call site, if necessary.
190 virtual void GradientWithPrevResult(const T *x, T *grad, T *previous_grad, T *previous_g2, T *previous_gstep) const
191 {
192 unsigned int ndim = NDim();
193 for (unsigned int icoord = 0; icoord < ndim; ++icoord) {
195 }
196 }
197
198 using BaseFunc::NDim;
199
200 /// Optimized method to evaluate at the same time the function value and derivative at a point x.
201 /// Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
202 /// Derived class should implement this method if performances play an important role and if it is faster to
203 /// evaluate value and derivative at the same time
204 virtual void FdF(const T *x, T &f, T *df) const
205 {
207 Gradient(x, df);
208 }
209
210 /// Return the partial derivative with respect to the passed coordinate.
211 T Derivative(const T *x, unsigned int icoord = 0) const { return DoDerivative(x, icoord); }
212
213 /// In some cases, the derivative algorithm will use information from the previous step, these can be passed
214 /// in with this overload. The `previous_*` arrays can also be used to return second derivative and step size
215 /// so that these can be passed forward again as well at the call site, if necessary.
216 T Derivative(const T *x, unsigned int icoord, T *previous_grad, T *previous_g2,
217 T *previous_gstep) const
218 {
220 }
221
222 bool HasGradient() const { return true; }
223
224 virtual bool returnsInMinuit2ParameterSpace() const { return false; }
225
226 private:
227 /// Function to evaluate the derivative with respect each coordinate. To be implemented by the derived class.
228 virtual T DoDerivative(const T *x, unsigned int icoord) const = 0;
229
230 /// In some cases, the derivative algorithm will use information from the previous step, these can be passed
231 /// in with this overload. The `previous_*` arrays can also be used to return second derivative and step size
232 /// so that these can be passed forward again as well at the call site, if necessary.
233 virtual T DoDerivativeWithPrevResult(const T *x, unsigned int icoord, T * /*previous_grad*/,
234 T * /*previous_g2*/, T * /*previous_gstep*/) const
235 {
236 return DoDerivative(x, icoord);
237 }
238 };
239
240
241//___________________________________________________________________________________
242 /**
243 Interface (abstract class) for one-dimensional functions providing a gradient calculation.
244 The method ROOT::Math::IFunction::Derivative calculates the derivative and
245 ROOT::Math::Fdf calculates the derivative and the function values at the same time.
246 The pure private virtual method DoDerivative() must be implemented by the derived classes, while
247 FdF is by default implemented using DoDerivative, but it can be overloaded by the
248 derived classes to improve the efficiency in the derivative calculation.
249
250 Specialized Gradient interface(abstract class) for one dimensional functions
251 It provides a method to evaluate the derivative of the function, Derivative and a
252 method to evaluate at the same time the function and the derivative FdF
253
254 @ingroup GenFunc
255 */
257
258 public:
259
262
263 /// Return the derivative of the function at a point x
264 /// Use the private method DoDerivative
265 double Derivative(double x) const { return DoDerivative(x); }
266
267 /// Compatibility method with multi-dimensional interface for partial derivative.
268 double Derivative(const double *x) const { return DoDerivative(*x); }
269
270 /// Compatibility method with multi-dimensional interface for Gradient.
271 void Gradient(const double *x, double *g) const { g[0] = DoDerivative(*x); }
272
273 /// Optimized method to evaluate at the same time the function value and derivative at a point x.
274 /// Often both value and derivatives are needed and it is often more efficient to compute them at the same time.
275 /// Derived class should implement this method if performances play an important role and if it is faster to
276 /// evaluate value and derivative at the same time.
277 virtual void FdF(double x, double &f, double &df) const
278 {
279 f = operator()(x);
280 df = Derivative(x);
281 }
282
283 /// Compatibility method with multi-dimensional interface for Gradient and function evaluation.
284 void FdF(const double *x, double &f, double *df) const { FdF(*x, f, *df); }
285
286 bool HasGradient() const override { return true; }
287
288 private:
289
290 /// Function to evaluate the derivative with respect each coordinate. To be implemented by the derived class.
291 virtual double DoDerivative(double x) const = 0;
292 };
293
294
295
296 } // namespace Math
297} // namespace ROOT
298
299#endif /* ROOT_Math_IFunction */
#define f(i)
Definition RSha256.hxx:104
#define g(i)
Definition RSha256.hxx:105
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.
Documentation for the abstract class IBaseFunctionMultiDim.
Definition IFunction.h:63
virtual IBaseFunctionMultiDimTempl< T > * Clone() const =0
Clone a function.
virtual ~IBaseFunctionMultiDimTempl()=default
T operator()(const T *x) const
Evaluate the function at a point x[].
Definition IFunction.h:81
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition IFunction.h:68
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. Must be implemented by derived classes.
Interface (abstract class) for generic functions objects of one-dimension Provides a method to evalua...
Definition IFunction.h:114
virtual bool HasGradient() const
Definition IFunction.h:136
virtual ~IBaseFunctionOneDim()=default
IBaseFunctionOneDim BaseFunc
Definition IFunction.h:118
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:132
virtual IBaseFunctionOneDim * Clone() const =0
Clone a function.
double operator()(double x) const
Evaluate the function at a point x.
Definition IFunction.h:128
Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
Definition IFunction.h:170
IGradientFunctionMultiDimTempl< T > BaseGrad
Definition IFunction.h:174
virtual void Gradient(const T *x, T *grad) const
Evaluate all the vector of function derivatives (gradient) at a point x.
Definition IFunction.h:179
T Derivative(const T *x, unsigned int icoord=0) const
Return the partial derivative with respect to the passed coordinate.
Definition IFunction.h:211
virtual unsigned int NDim() const=0
Retrieve the dimension of the function.
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:216
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:204
virtual void GradientWithPrevResult(const T *x, T *grad, T *previous_grad, T *previous_g2, T *previous_gstep) const
In some cases, the gradient algorithm will use information from the previous step,...
Definition IFunction.h:190
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:233
virtual T DoDerivative(const T *x, unsigned int icoord) const =0
Function to evaluate the derivative with respect each coordinate. To be implemented by the derived cl...
IBaseFunctionMultiDimTempl< T > BaseFunc
Definition IFunction.h:173
virtual bool returnsInMinuit2ParameterSpace() const
Definition IFunction.h:224
Interface (abstract class) for one-dimensional functions providing a gradient calculation.
Definition IFunction.h:256
double Derivative(const double *x) const
Compatibility method with multi-dimensional interface for partial derivative.
Definition IFunction.h:268
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:277
void FdF(const double *x, double &f, double *df) const
Compatibility method with multi-dimensional interface for Gradient and function evaluation.
Definition IFunction.h:284
IGradientFunctionOneDim BaseGrad
Definition IFunction.h:261
void Gradient(const double *x, double *g) const
Compatibility method with multi-dimensional interface for Gradient.
Definition IFunction.h:271
double Derivative(double x) const
Return the derivative of the function at a point x Use the private method DoDerivative.
Definition IFunction.h:265
virtual double DoDerivative(double x) const =0
Function to evaluate the derivative with respect each coordinate. To be implemented by the derived cl...
bool HasGradient() const override
Definition IFunction.h:286
Double_t x[n]
Definition legend1.C:17
Namespace for new Math classes and functions.
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...