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