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