ROOT  6.06/09
Reference Guide
Minuit2Minimizer.h
Go to the documentation of this file.
1 // @(#)root/minuit2:$Id$
2 // Author: L. Moneta Wed Oct 18 11:48:00 2006
3 
4 /**********************************************************************
5  * *
6  * Copyright (c) 2006 LCG ROOT Math Team, CERN/PH-SFT *
7  * *
8  * *
9  **********************************************************************/
10 
11 // Header file for class Minuit2Minimizer
12 
13 #ifndef ROOT_Minuit2_Minuit2Minimizer
14 #define ROOT_Minuit2_Minuit2Minimizer
15 
16 #ifndef ROOT_Math_Minimizer
17 #include "Math/Minimizer.h"
18 #endif
19 
20 #ifndef ROOT_Minuit2_MnUserParameterState
22 #endif
23 
24 #ifndef ROOT_Math_IFunctionfwd
25 #include "Math/IFunctionfwd.h"
26 #endif
27 
28 
29 
30 namespace ROOT {
31 
32  namespace Minuit2 {
33 
34  class ModularFunctionMinimizer;
35  class FCNBase;
36  class FunctionMinimum;
37  class MnTraceObject;
38 
39  // enumeration specifying the type of Minuit2 minimizers
46  };
47 
48  }
49 
50  namespace Minuit2 {
51 //_____________________________________________________________________________________________________
52 /**
53  Minuit2Minimizer class implementing the ROOT::Math::Minimizer interface for
54  Minuit2 minimization algorithm.
55  In ROOT it can be instantiated using the plug-in manager (plug-in "Minuit2")
56  Using a string (used by the plugin manager) or via an enumeration
57  an one can set all the possible minimization algorithms (Migrad, Simplex, Combined, Scan and Fumili).
58 
59  @ingroup Minuit
60 */
62 
63 public:
64 
65  /**
66  Default constructor
67  */
69 
70  /**
71  Constructor with a char (used by PM)
72  */
73  Minuit2Minimizer (const char * type);
74 
75  /**
76  Destructor (no operations)
77  */
78  virtual ~Minuit2Minimizer ();
79 
80 private:
81  // usually copying is non trivial, so we make this unaccessible
82 
83  /**
84  Copy constructor
85  */
87 
88  /**
89  Assignment operator
90  */
92 
93 public:
94 
95  // clear resources (parameters) for consecutives minimizations
96  virtual void Clear();
97 
98  /// set the function to minimize
99  virtual void SetFunction(const ROOT::Math::IMultiGenFunction & func);
100 
101  /// set gradient the function to minimize
102  virtual void SetFunction(const ROOT::Math::IMultiGradFunction & func);
103 
104  /// set free variable
105  virtual bool SetVariable(unsigned int ivar, const std::string & name, double val, double step);
106 
107  /// set lower limit variable (override if minimizer supports them )
108  virtual bool SetLowerLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double lower );
109  /// set upper limit variable (override if minimizer supports them )
110  virtual bool SetUpperLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double upper );
111  /// set upper/lower limited variable (override if minimizer supports them )
112  virtual bool SetLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double /* lower */, double /* upper */);
113  /// set fixed variable (override if minimizer supports them )
114  virtual bool SetFixedVariable(unsigned int /* ivar */, const std::string & /* name */, double /* val */);
115  /// set variable
116  virtual bool SetVariableValue(unsigned int ivar, double val);
117  // set variable values
118  virtual bool SetVariableValues(const double * val);
119  /// set the step size of an already existing variable
120  virtual bool SetVariableStepSize(unsigned int ivar, double step );
121  /// set the lower-limit of an already existing variable
122  virtual bool SetVariableLowerLimit(unsigned int ivar, double lower);
123  /// set the upper-limit of an already existing variable
124  virtual bool SetVariableUpperLimit(unsigned int ivar, double upper);
125  /// set the limits of an already existing variable
126  virtual bool SetVariableLimits(unsigned int ivar, double lower, double upper);
127  /// fix an existing variable
128  virtual bool FixVariable(unsigned int ivar);
129  /// release an existing variable
130  virtual bool ReleaseVariable(unsigned int ivar);
131  /// query if an existing variable is fixed (i.e. considered constant in the minimization)
132  /// note that by default all variables are not fixed
133  virtual bool IsFixedVariable(unsigned int ivar) const;
134  /// get variable settings in a variable object (like ROOT::Fit::ParamsSettings)
135  virtual bool GetVariableSettings(unsigned int ivar, ROOT::Fit::ParameterSettings & varObj) const;
136  /// get name of variables (override if minimizer support storing of variable names)
137  virtual std::string VariableName(unsigned int ivar) const;
138  /// get index of variable given a variable given a name
139  /// return -1 if variable is not found
140  virtual int VariableIndex(const std::string & name) const;
141 
142  /**
143  method to perform the minimization.
144  Return false in case the minimization did not converge. In this case a
145  status code different than zero is set
146  (retrieved by the derived method Minimizer::Status() )"
147 
148  status = 1 : Covariance was made pos defined
149  status = 2 : Hesse is invalid
150  status = 3 : Edm is above max
151  status = 4 : Reached call limit
152  status = 5 : Any other failure
153  */
154  virtual bool Minimize();
155 
156  /// return minimum function value
157  virtual double MinValue() const { return fState.Fval(); }
158 
159  /// return expected distance reached from the minimum
160  virtual double Edm() const { return fState.Edm(); }
161 
162  /// return pointer to X values at the minimum
163  virtual const double * X() const;
164 
165  /// return pointer to gradient values at the minimum
166  virtual const double * MinGradient() const { return 0; } // not available in Minuit2
167 
168  /// number of function calls to reach the minimum
169  virtual unsigned int NCalls() const { return fState.NFcn(); }
170 
171  /// this is <= Function().NDim() which is the total
172  /// number of variables (free+ constrained ones)
173  virtual unsigned int NDim() const { return fDim; }
174 
175  /// number of free variables (real dimension of the problem)
176  /// this is <= Function().NDim() which is the total
177  virtual unsigned int NFree() const { return fState.VariableParameters(); }
178 
179  /// minimizer provides error and error matrix
180  virtual bool ProvidesError() const { return true; }
181 
182  /// return errors at the minimum
183  virtual const double * Errors() const;
184 
185  /**
186  return covariance matrix elements
187  if the variable is fixed or const the value is zero
188  The ordering of the variables is the same as in errors and parameter value.
189  This is different from the direct interface of Minuit2 or TMinuit where the
190  values were obtained only to variable parameters
191  */
192  virtual double CovMatrix(unsigned int i, unsigned int j) const;
193 
194 
195  /**
196  Fill the passed array with the covariance matrix elements
197  if the variable is fixed or const the value is zero.
198  The array will be filled as cov[i *ndim + j]
199  The ordering of the variables is the same as in errors and parameter value.
200  This is different from the direct interface of Minuit2 or TMinuit where the
201  values were obtained only to variable parameters
202  */
203  virtual bool GetCovMatrix(double * cov) const;
204 
205  /**
206  Fill the passed array with the Hessian matrix elements
207  The Hessian matrix is the matrix of the second derivatives
208  and is the inverse of the covariance matrix
209  If the variable is fixed or const the values for that variables are zero.
210  The array will be filled as h[i *ndim + j]
211  */
212  virtual bool GetHessianMatrix(double * h) const;
213 
214 
215  /**
216  return the status of the covariance matrix
217  status = -1 : not available (inversion failed or Hesse failed)
218  status = 0 : available but not positive defined
219  status = 1 : covariance only approximate
220  status = 2 : full matrix but forced pos def
221  status = 3 : full accurate matrix
222 
223  */
224  virtual int CovMatrixStatus() const;
225  /**
226  return correlation coefficient between variable i and j.
227  If the variable is fixed or const the return value is zero
228  */
229  virtual double Correlation(unsigned int i, unsigned int j ) const;
230 
231  /**
232  get global correlation coefficient for the variable i. This is a number between zero and one which gives
233  the correlation between the i-th variable and that linear combination of all other variables which
234  is most strongly correlated with i.
235  If the variable is fixed or const the return value is zero
236  */
237  virtual double GlobalCC(unsigned int i) const;
238 
239  /**
240  get the minos error for parameter i, return false if Minos failed
241  A minimizaiton must be performed befre, return false if no minimization has been done
242  In case of Minos failed the status error is updated as following
243  status += 10 * minosStatus where the minos status is:
244  status = 1 : maximum number of function calls exceeded when running for lower error
245  status = 2 : maximum number of function calls exceeded when running for upper error
246  status = 3 : new minimum found when running for lower error
247  status = 4 : new minimum found when running for upper error
248  status = 5 : any other failure
249 
250  */
251  virtual bool GetMinosError(unsigned int i, double & errLow, double & errUp, int = 0);
252 
253  /**
254  scan a parameter i around the minimum. A minimization must have been done before,
255  return false if it is not the case
256  */
257  virtual bool Scan(unsigned int i, unsigned int & nstep, double * x, double * y, double xmin = 0, double xmax = 0);
258 
259  /**
260  find the contour points (xi,xj) of the function for parameter i and j around the minimum
261  The contour will be find for value of the function = Min + ErrorUp();
262  */
263  virtual bool Contour(unsigned int i, unsigned int j, unsigned int & npoints, double *xi, double *xj);
264 
265 
266  /**
267  perform a full calculation of the Hessian matrix for error calculation
268  If a valid minimum exists the calculation is done on the minimum point otherwise is performed
269  in the current set values of parameters
270  Status code of minimizer is updated according to the following convention (in case Hesse failed)
271  status += 100*hesseStatus where hesse status is:
272  status = 1 : hesse failed
273  status = 2 : matrix inversion failed
274  status = 3 : matrix is not pos defined
275  */
276  virtual bool Hesse();
277 
278 
279  /// return reference to the objective function
280  ///virtual const ROOT::Math::IGenFunction & Function() const;
281 
282  /// print result of minimization
283  virtual void PrintResults();
284 
285  /// set an object to trace operation for each iteration
286  /// The object muust implement operator() (unsigned int, MinimumState & state)
288 
289  /// set storage level = 1 : store all iteration states (default)
290  /// = 0 : store only first and last state to save memory
291  void SetStorageLevel(int level);
292 
293  /// return the minimizer state (containing values, step size , etc..)
295 
296 protected:
297 
298  // protected function for accessing the internal Minuit2 object. Needed for derived classes
299 
301 
303 
305 
306  virtual const ROOT::Minuit2::FCNBase * GetFCN() const { return fMinuitFCN; }
307 
308  /// examine the minimum result
310 
311 private:
312 
313  unsigned int fDim; // dimension of the function to be minimized
315 
317  // std::vector<ROOT::Minuit2::MinosError> fMinosErrors;
321  mutable std::vector<double> fValues;
322  mutable std::vector<double> fErrors;
323 
324 };
325 
326  } // end namespace Fit
327 
328 } // end namespace ROOT
329 
330 
331 
332 #endif /* ROOT_Minuit2_Minuit2Minimizer */
virtual bool Scan(unsigned int i, unsigned int &nstep, double *x, double *y, double xmin=0, double xmax=0)
scan a parameter i around the minimum.
Minuit2Minimizer & operator=(const Minuit2Minimizer &rhs)
Assignment operator.
Interface (abstract class) for multi-dimensional functions providing a gradient calculation.
Definition: IFunction.h:322
virtual unsigned int NCalls() const
number of function calls to reach the minimum
virtual bool SetUpperLimitedVariable(unsigned int ivar, const std::string &name, double val, double step, double upper)
set upper limit variable (override if minimizer supports them )
float xmin
Definition: THbookFile.cxx:93
static Vc_ALWAYS_INLINE int_v min(const int_v &x, const int_v &y)
Definition: vector.h:433
virtual bool GetCovMatrix(double *cov) const
Fill the passed array with the covariance matrix elements if the variable is fixed or const the value...
Namespace for new ROOT classes and functions.
Definition: ROOT.py:1
virtual unsigned int NDim() const
this is <= Function().NDim() which is the total number of variables (free+ constrained ones) ...
virtual bool SetVariableLimits(unsigned int ivar, double lower, double upper)
set the limits of an already existing variable
Class, describing value, limits and step size of the parameters Provides functionality also to set/re...
ROOT::Minuit2::FunctionMinimum * fMinimum
virtual const double * X() const
return pointer to X values at the minimum
virtual bool SetLimitedVariable(unsigned int ivar, const std::string &name, double val, double step, double, double)
set upper/lower limited variable (override if minimizer supports them )
TH1 * h
Definition: legend2.C:5
virtual int CovMatrixStatus() const
return the status of the covariance matrix status = -1 : not available (inversion failed or Hesse fai...
virtual bool Contour(unsigned int i, unsigned int j, unsigned int &npoints, double *xi, double *xj)
find the contour points (xi,xj) of the function for parameter i and j around the minimum The contour ...
virtual void SetMinimizer(ROOT::Minuit2::ModularFunctionMinimizer *m)
static const float upper
Definition: main.cpp:49
virtual bool SetVariableValue(unsigned int ivar, double val)
set variable
Double_t x[n]
Definition: legend1.C:17
virtual bool ProvidesError() const
minimizer provides error and error matrix
virtual int VariableIndex(const std::string &name) const
get index of variable given a variable given a name return -1 if variable is not found ...
ROOT::Minuit2::MnUserParameterState fState
Abstract Minimizer class, defining the interface for the various minimizer (like Minuit2, Minuit, GSL, etc..) Plug-in's exist in ROOT to be able to instantiate the derived classes like ROOT::Math::GSLMinimizer or ROOT::Math::Minuit2Minimizer via the plug-in manager.
Definition: Minimizer.h:86
class holding the full result of the minimization; both internal and external (MnUserParameterState) ...
virtual double GlobalCC(unsigned int i) const
get global correlation coefficient for the variable i.
virtual double Correlation(unsigned int i, unsigned int j) const
return correlation coefficient between variable i and j.
virtual bool ReleaseVariable(unsigned int ivar)
release an existing variable
Interface (abstract class) defining the function to be minimized, which has to be implemented by the ...
Definition: FCNBase.h:47
virtual ~Minuit2Minimizer()
Destructor (no operations)
virtual bool FixVariable(unsigned int ivar)
fix an existing variable
virtual double Edm() const
return expected distance reached from the minimum
virtual bool GetHessianMatrix(double *h) const
Fill the passed array with the Hessian matrix elements The Hessian matrix is the matrix of the second...
virtual bool SetLowerLimitedVariable(unsigned int ivar, const std::string &name, double val, double step, double lower)
set lower limit variable (override if minimizer supports them )
virtual bool GetVariableSettings(unsigned int ivar, ROOT::Fit::ParameterSettings &varObj) const
get variable settings in a variable object (like ROOT::Fit::ParamsSettings)
TMarker * m
Definition: textangle.C:8
class which holds the external user and/or internal Minuit representation of the parameters and error...
virtual bool SetFixedVariable(unsigned int, const std::string &, double)
set fixed variable (override if minimizer supports them )
virtual bool SetVariableValues(const double *val)
set the values of all existing variables (array must be dimensioned to the size of the existing param...
virtual void PrintResults()
return reference to the objective function virtual const ROOT::Math::IGenFunction & Function() const;...
virtual const ROOT::Minuit2::ModularFunctionMinimizer * GetMinimizer() const
float xmax
Definition: THbookFile.cxx:93
virtual double CovMatrix(unsigned int i, unsigned int j) const
return covariance matrix elements if the variable is fixed or const the value is zero The ordering of...
Minuit2Minimizer class implementing the ROOT::Math::Minimizer interface for Minuit2 minimization algo...
int type
Definition: TGX11.cxx:120
virtual bool SetVariableLowerLimit(unsigned int ivar, double lower)
set the lower-limit of an already existing variable
Double_t y[n]
Definition: legend1.C:17
double func(double *x, double *p)
Definition: stressTF1.cxx:213
virtual void Clear()
reset for consecutive minimizations - implement if needed
void SetMinimizerType(ROOT::Minuit2::EMinimizerType type)
#define name(a, b)
Definition: linkTestLib0.cpp:5
Minuit2Minimizer(ROOT::Minuit2::EMinimizerType type=ROOT::Minuit2::kMigrad)
Default constructor.
virtual bool SetVariable(unsigned int ivar, const std::string &name, double val, double step)
set free variable
ROOT::Minuit2::ModularFunctionMinimizer * fMinimizer
void SetTraceObject(MnTraceObject &obj)
set an object to trace operation for each iteration The object muust implement operator() (unsigned i...
virtual bool Minimize()
method to perform the minimization.
bool ExamineMinimum(const ROOT::Minuit2::FunctionMinimum &min)
examine the minimum result
virtual double MinValue() const
return minimum function value
void SetStorageLevel(int level)
set storage level = 1 : store all iteration states (default) = 0 : store only first and last state to...
ROOT::Minuit2::FCNBase * fMinuitFCN
virtual const ROOT::Minuit2::FCNBase * GetFCN() const
virtual bool Hesse()
perform a full calculation of the Hessian matrix for error calculation If a valid minimum exists the ...
virtual std::string VariableName(unsigned int ivar) const
get name of variables (override if minimizer support storing of variable names)
const ROOT::Minuit2::MnUserParameterState & State()
return the minimizer state (containing values, step size , etc..)
virtual bool GetMinosError(unsigned int i, double &errLow, double &errUp, int=0)
get the minos error for parameter i, return false if Minos failed A minimizaiton must be performed be...
virtual bool IsFixedVariable(unsigned int ivar) const
query if an existing variable is fixed (i.e.
Documentation for the abstract class IBaseFunctionMultiDim.
Definition: IFunction.h:63
TObject * obj
Base common class providing the API for all the minimizer Various Minimize methods are provided varyi...
virtual const double * Errors() const
return errors at the minimum
virtual const double * MinGradient() const
return pointer to gradient values at the minimum
virtual void SetFunction(const ROOT::Math::IMultiGenFunction &func)
set the function to minimize
virtual bool SetVariableUpperLimit(unsigned int ivar, double upper)
set the upper-limit of an already existing variable
static const float lower
Definition: main.cpp:48
virtual bool SetVariableStepSize(unsigned int ivar, double step)
set the step size of an already existing variable
virtual unsigned int NFree() const
number of free variables (real dimension of the problem) this is <= Function().NDim() which is the to...