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