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