Logo ROOT  
Reference Guide
GSLMultiRootFinder.h
Go to the documentation of this file.
1// @(#)root/mathmore:$Id$
2// Author: L. Moneta 03/2011
3
4 /**********************************************************************
5 * *
6 * Copyright (c) 2004 ROOT Foundation, CERN/PH-SFT *
7 * *
8 * This library is free software; you can redistribute it and/or *
9 * modify it under the terms of the GNU General Public License *
10 * as published by the Free Software Foundation; either version 2 *
11 * of the License, or (at your option) any later version. *
12 * *
13 * This library is distributed in the hope that it will be useful, *
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
16 * General Public License for more details. *
17 * *
18 * You should have received a copy of the GNU General Public License *
19 * along with this library (see file COPYING); if not, write *
20 * to the Free Software Foundation, Inc., 59 Temple Place, Suite *
21 * 330, Boston, MA 02111-1307 USA, or contact the author. *
22 * *
23 **********************************************************************/
24
25// Header file for class GSLMultiRootFinder
26//
27
28#ifndef ROOT_Math_GSLMultiRootFinder
29#define ROOT_Math_GSLMultiRootFinder
30
31
32
33#include "Math/IFunction.h"
34
36
37#include <vector>
38#include <utility>
39#include <iostream>
40
41namespace ROOT {
42namespace Math {
43
44
45 class GSLMultiRootBaseSolver;
46
47 /** @defgroup MultiRoot Multidimensional ROOT finding
48 Classes for finding the roots of a multi-dimensional system.
49 @ingroup NumAlgo
50 */
51
52 /**
53 Class for Multidimensional root finding algorithms bassed on GSL. This class is used to solve a
54 non-linear system of equations:
55
56 f1(x1,....xn) = 0
57 f2(x1,....xn) = 0
58 ..................
59 fn(x1,....xn) = 0
60
61 See the GSL <A HREF="http://www.gnu.org/software/gsl/manual/html_node/Multidimensional-Root_002dFinding.html"> online manual</A> for
62 information on the GSL MultiRoot finding algorithms
63
64 The available GSL algorithms require the derivatives of the supplied functions or not (they are
65 computed internally by GSL). In the first case the user needs to provide a list of multidimensional functions implementing the
66 gradient interface (ROOT::Math::IMultiGradFunction) while in the second case it is enough to supply a list of
67 functions impelmenting the ROOT::Math::IMultiGenFunction interface.
68 The available algorithms requiring derivatives (see also the GSL
69 <A HREF="http://www.gnu.org/software/gsl/manual/html_node/Algorithms-using-Derivatives.html">documentation</A> )
70 are the followings:
71 <ul>
72 <li><tt>ROOT::Math::GSLMultiRootFinder::kHybridSJ</tt> with name <i>"HybridSJ"</i>: modified Powell's hybrid
73 method as implemented in HYBRJ in MINPACK
74 <li><tt>ROOT::Math::GSLMultiRootFinder::kHybridJ</tt> with name <i>"HybridJ"</i>: unscaled version of the
75 previous algorithm</li>
76 <li><tt>ROOT::Math::GSLMultiRootFinder::kNewton</tt> with name <i>"Newton"</i>: Newton method </li>
77 <li><tt>ROOT::Math::GSLMultiRootFinder::kGNewton</tt> with name <i>"GNewton"</i>: modified Newton method </li>
78 </ul>
79 The algorithms without derivatives (see also the GSL
80 <A HREF="http://www.gnu.org/software/gsl/manual/html_node/Algorithms-without-Derivatives.html">documentation</A> )
81 are the followings:
82 <ul>
83 <li><tt>ROOT::Math::GSLMultiRootFinder::kHybridS</tt> with name <i>"HybridS"</i>: same as HybridSJ but using
84 finate difference approximation for the derivatives</li>
85 <li><tt>ROOT::Math::GSLMultiRootFinder::kHybrid</tt> with name <i>"Hybrid"</i>: unscaled version of the
86 previous algorithm</li>
87 <li><tt>ROOT::Math::GSLMultiRootFinder::kDNewton</tt> with name <i>"DNewton"</i>: discrete Newton algorithm </li>
88 <li><tt>ROOT::Math::GSLMultiRootFinder::kBroyden</tt> with name <i>"Broyden"</i>: Broyden algorithm </li>
89 </ul>
90
91 @ingroup MultiRoot
92 */
93
94
96
97 public:
98
99 /**
100 enumeration specifying the types of GSL multi root finders
101 requiring the derivatives
102
103 */
109 };
110 /**
111 enumeration specifying the types of GSL multi root finders
112 which do not require the derivatives
113
114 */
115 enum EType {
120 };
121
122
123
124 /// create a multi-root finder based on an algorithm not requiring function derivative
126
127 /// create a multi-root finder based on an algorithm requiring function derivative
129
130 /*
131 create a multi-root finder using a string.
132 The names are those defined in the GSL manuals
133 after having remived the GSL prefix (gsl_multiroot_fsolver).
134 Default algorithm is "hybrids" (without derivative).
135 */
136 GSLMultiRootFinder(const char * name = 0);
137
138 /// destructor
139 virtual ~GSLMultiRootFinder();
140
141 private:
142 // usually copying is non trivial, so we make this unaccessible
145
146 public:
147
148 /// set the type for an algorithm without derivatives
150 fType = type; fUseDerivAlgo = false;
151 }
152
153 /// set the type of algorithm using derivatives
155 fType = type; fUseDerivAlgo = true;
156 }
157
158 /// set the type using a string
159 void SetType(const char * name);
160
161 /*
162 add the list of functions f1(x1,..xn),...fn(x1,...xn). The list must contain pointers of
163 ROOT::Math::IMultiGenFunctions. The method requires the
164 the begin and end of the list iterator.
165 The list can be any stl container or a simple array of ROOT::Math::IMultiGenFunctions* or
166 whatever implementing an iterator.
167 If using a derivative type algorithm the function pointers must implement the
168 ROOT::Math::IMultiGradFunction interface
169 */
170 template<class FuncIterator>
171 bool SetFunctionList( FuncIterator begin, FuncIterator end) {
172 bool ret = true;
173 for (FuncIterator itr = begin; itr != end; ++itr) {
174 const ROOT::Math::IMultiGenFunction * f = *itr;
175 // Using bitwise operator &= require the operand to be a bool
176 // to have the intended effect here.
177 ret &= (AddFunction( *f) != 0);
178 }
179 return ret;
180 }
181
182 /*
183 add (set) a single function fi(x1,...xn) which is part of the system of
184 specifying the begin and end of the iterator.
185 If using a derivative type algorithm the function must implement the
186 ROOT::Math::IMultiGradFunction interface
187 Return the current number of function in the list and 0 if failed to add the function
188 */
190
191 /// same method as before but using any function implementing
192 /// the operator(), so can be wrapped in a IMultiGenFunction interface
193 template <class Function>
194 int AddFunction( Function & f, int ndim) {
195 // no need to care about lifetime of wfunc. It will be cloned inside AddFunction
197 return AddFunction(wfunc);
198 }
199
200 /**
201 return the number of sunctions set in the class.
202 The number must be equal to the dimension of the functions
203 */
204 unsigned int Dim() const { return fFunctions.size(); }
205
206 /// clear list of functions
207 void Clear();
208
209 /// return the root X values solving the system
210 const double * X() const;
211
212 /// return the function values f(X) solving the system
213 /// i.e. they must be close to zero at the solution
214 const double * FVal() const;
215
216 /// return the last step size
217 const double * Dx() const;
218
219
220 /**
221 Find the root starting from the point X;
222 Use the number of iteration and tolerance if given otherwise use
223 default parameter values which can be defined by
224 the static method SetDefault...
225 */
226 bool Solve(const double * x, int maxIter = 0, double absTol = 0, double relTol = 0);
227
228 /// Return number of iterations
229 int Iterations() const {
230 return fIter;
231 }
232
233 /// Return the status of last root finding
234 int Status() const { return fStatus; }
235
236 /// Return the algorithm name used for solving
237 /// Note the name is available only after having called solved
238 /// Otherwise an empyty string is returned
239 const char * Name() const;
240
241 /*
242 set print level
243 level = 0 quiet (no messages print)
244 = 1 print only the result
245 = 3 max debug. Print result at each iteration
246 */
247 void SetPrintLevel(int level) { fPrintLevel = level; }
248
249 /// return the print level
250 int PrintLevel() const { return fPrintLevel; }
251
252
253 //-- static methods to set configurations
254
255 /// set tolerance (absolute and relative)
256 /// relative tolerance is only use to verify the convergence
257 /// do it is a minor parameter
258 static void SetDefaultTolerance(double abstol, double reltol = 0 );
259
260 /// set maximum number of iterations
261 static void SetDefaultMaxIterations(int maxiter);
262
263 /// print iteration state
264 void PrintState(std::ostream & os = std::cout);
265
266
267 protected:
268
269 // return type given a name
270 std::pair<bool,int> GetType(const char * name);
271 // clear list of functions
272 void ClearFunctions();
273
274
275 private:
276
277 int fIter; // current numer of iterations
278 int fStatus; // current status
279 int fPrintLevel; // print level
280
281 // int fMaxIter; // max number of iterations
282 // double fAbsTolerance; // absolute tolerance
283 // double fRelTolerance; // relative tolerance
284 int fType; // type of algorithm
285 bool fUseDerivAlgo; // algorithm using derivative
286
288 std::vector<ROOT::Math::IMultiGenFunction *> fFunctions; //! transient Vector of the functions
289
290
291 };
292
293 // use typedef for most sensible name
295
296} // namespace Math
297} // namespace ROOT
298
299
300#endif /* ROOT_Math_GSLMultiRootFinder */
#define f(i)
Definition: RSha256.hxx:104
char name[80]
Definition: TGX11.cxx:110
int type
Definition: TGX11.cxx:121
Double_t(* Function)(Double_t)
Definition: Functor.C:4
GSLMultiRootBaseSolver, internal class for implementing GSL multi-root finders This is the base class...
Class for Multidimensional root finding algorithms bassed on GSL.
GSLMultiRootFinder & operator=(const GSLMultiRootFinder &)
unsigned int Dim() const
return the number of sunctions set in the class.
const double * Dx() const
return the last step size
virtual ~GSLMultiRootFinder()
destructor
const double * FVal() const
return the function values f(X) solving the system i.e.
void SetType(EDerivType type)
set the type of algorithm using derivatives
void SetType(EType type)
set the type for an algorithm without derivatives
std::vector< ROOT::Math::IMultiGenFunction * > fFunctions
bool Solve(const double *x, int maxIter=0, double absTol=0, double relTol=0)
Find the root starting from the point X; Use the number of iteration and tolerance if given otherwise...
EType
enumeration specifying the types of GSL multi root finders which do not require the derivatives
std::pair< bool, int > GetType(const char *name)
bool SetFunctionList(FuncIterator begin, FuncIterator end)
const char * Name() const
Return the algorithm name used for solving Note the name is available only after having called solved...
void PrintState(std::ostream &os=std::cout)
print iteration state
int PrintLevel() const
return the print level
GSLMultiRootBaseSolver * fSolver
int Status() const
Return the status of last root finding.
EDerivType
enumeration specifying the types of GSL multi root finders requiring the derivatives
GSLMultiRootFinder(EType type)
create a multi-root finder based on an algorithm not requiring function derivative
int AddFunction(Function &f, int ndim)
same method as before but using any function implementing the operator(), so can be wrapped in a IMul...
void Clear()
clear list of functions
static void SetDefaultTolerance(double abstol, double reltol=0)
set tolerance (absolute and relative) relative tolerance is only use to verify the convergence do it ...
int AddFunction(const ROOT::Math::IMultiGenFunction &func)
const double * X() const
return the root X values solving the system
static void SetDefaultMaxIterations(int maxiter)
set maximum number of iterations
int Iterations() const
Return number of iterations.
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:62
Template class to wrap any C++ callable object implementing operator() (const double * x) in a multi-...
Double_t x[n]
Definition: legend1.C:17
Namespace for new Math classes and functions.
GSLMultiRootFinder MultiRootFinder
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...