include/root/TMinuitMinimizer.h

0001 // @(#)root/minuit:$Id$
0002 // Author: L. Moneta Wed Oct 25 16:28:55 2006
0003
0004 /**********************************************************************
0005  *                                                                    *
0006  * Copyright (c) 2006  LCG ROOT Math Team, CERN/PH-SFT                *
0007  *                                                                    *
0008  *                                                                    *
0009  **********************************************************************/
0010
0011 // Header file for class TMinuitMinimizer
0012
0013 #ifndef ROOT_TMinuitMinimizer
0014 #define ROOT_TMinuitMinimizer
0015
0016 #include "Math/Minimizer.h"
0017
0018 #include "Rtypes.h"
0019
0020 #include <vector>
0021 #include <string>
0022
0023 class TMinuit;
0024
0025 namespace ROOT {
0026
0027    namespace Minuit {
0028
0029
0030       // enumeration specifying the type of TMinuit minimizers
0031       enum EMinimizerType {
0032          kMigrad,
0033          kSimplex,
0034          kCombined,
0035          kMigradImproved,
0036          kScan,
0037          kSeek
0038       };
0039
0040    }
0041 }
0042
0043
0044
0045 /**
0046    TMinuitMinimizer class:
0047    ROOT::Math::Minimizer implementation based on TMinuit
0048
0049    @ingroup MinuitOld
0050 */
0051 class TMinuitMinimizer  : public ROOT::Math::Minimizer {
0052
0053 public:
0054
0055    /**
0056       Default constructor
0057    */
0058    TMinuitMinimizer ( ROOT::Minuit::EMinimizerType type = ROOT::Minuit::kMigrad, unsigned int ndim = 0);
0059
0060    /**
0061       Constructor from a char * (used by PM)
0062    */
0063    TMinuitMinimizer ( const char * type , unsigned int ndim = 0);
0064
0065    /**
0066       Destructor (no operations)
0067    */
0068    ~TMinuitMinimizer () override;
0069
0070 private:
0071    // usually copying is non trivial, so we make this unaccessible
0072
0073    /**
0074       Copy constructor
0075    */
0076    TMinuitMinimizer(const TMinuitMinimizer &);
0077
0078    /**
0079       Assignment operator
0080    */
0081    TMinuitMinimizer & operator = (const TMinuitMinimizer & rhs);
0082
0083 public:
0084
0085    /// set the function to minimize
0086    void SetFunction(const ROOT::Math::IMultiGenFunction & func) override;
0087
0088    /// set free variable
0089    bool SetVariable(unsigned int ivar, const std::string & name, double val, double step) override;
0090
0091    /// set upper/lower limited variable (override if minimizer supports them )
0092    bool SetLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double /* lower */, double /* upper */) override;
0093
0094    /// set lower limit variable  (override if minimizer supports them )
0095    bool SetLowerLimitedVariable(unsigned int  ivar , const std::string & name , double val , double step , double lower ) override;
0096
0097    /// set upper limit variable (override if minimizer supports them )
0098    bool SetUpperLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double upper ) override;
0099
0100    /// set fixed variable (override if minimizer supports them )
0101    bool SetFixedVariable(unsigned int /* ivar */, const std::string & /* name */, double /* val */) override;
0102
0103    /// set the value of an existing variable
0104    bool SetVariableValue(unsigned int , double ) override;
0105
0106    /// set the step size of an existing variable
0107    bool SetVariableStepSize(unsigned int , double ) override;
0108    /// set the lower-limit of an existing variable
0109    bool SetVariableLowerLimit(unsigned int , double ) override;
0110    /// set the upper-limit of an existing variable
0111    bool SetVariableUpperLimit(unsigned int , double ) override;
0112    /// set the limits of an existing variable
0113    bool SetVariableLimits(unsigned int ivar, double lower, double upper) override;
0114    /// fix an existing variable
0115    bool FixVariable(unsigned int) override;
0116    /// release an existing variable
0117    bool ReleaseVariable(unsigned int) override;
0118    /// query if an existing variable is fixed (i.e. considered constant in the minimization)
0119    /// note that by default all variables are not fixed
0120    bool IsFixedVariable(unsigned int) const override;
0121    /// get variable settings in a variable object (like ROOT::Fit::ParamsSettings)
0122    bool GetVariableSettings(unsigned int, ROOT::Fit::ParameterSettings & ) const override;
0123
0124
0125    /// method to perform the minimization
0126     bool Minimize() override;
0127
0128    /// return minimum function value
0129    double MinValue() const override;
0130
0131    /// return expected distance reached from the minimum
0132    double Edm() const override;
0133
0134    /// return  pointer to X values at the minimum
0135    const double *  X() const override { return &fParams.front(); }
0136
0137    /// return pointer to gradient values at the minimum
0138    const double *  MinGradient() const override { return nullptr; } // not available in Minuit2
0139
0140    /// number of function calls to reach the minimum
0141    unsigned int NCalls() const override;
0142
0143    /// this is <= Function().NDim() which is the total
0144    /// number of variables (free+ constrained ones)
0145    unsigned int NDim() const override { return fDim; }
0146
0147    /// number of free variables (real dimension of the problem)
0148    /// this is <= Function().NDim() which is the total
0149    unsigned int NFree() const override;
0150
0151    /// minimizer provides error and error matrix
0152    bool ProvidesError() const override { return true; }
0153
0154    /// return errors at the minimum
0155    const double * Errors() const override { return  &fErrors.front(); }
0156
0157    /** return covariance matrices elements
0158        if the variable is fixed the matrix is zero
0159        The ordering of the variables is the same as in errors
0160    */
0161    double CovMatrix(unsigned int i, unsigned int j) const override {
0162       return ( fCovar.size() > (i + fDim* j) ) ? fCovar[i + fDim* j] : 0;
0163    }
0164
0165    /**
0166        Fill the passed array with the  covariance matrix elements
0167        if the variable is fixed or const the value is zero.
0168        The array will be filled as cov[i *ndim + j]
0169        The ordering of the variables is the same as in errors and parameter value.
0170        This is different from the direct interface of Minuit2 or TMinuit where the
0171        values were obtained only to variable parameters
0172    */
0173    bool GetCovMatrix(double * cov) const override;
0174
0175    /**
0176        Fill the passed array with the Hessian matrix elements
0177        The Hessian matrix is the matrix of the second derivatives
0178        and is the inverse of the covariance matrix
0179        If the variable is fixed or const the values for that variables are zero.
0180        The array will be filled as h[i *ndim + j]
0181    */
0182    bool GetHessianMatrix(double * h) const override;
0183
0184    ///return status of covariance matrix
0185    int CovMatrixStatus() const override;
0186
0187    ///global correlation coefficient for variable i
0188    double GlobalCC(unsigned int ) const override;
0189
0190    /// minos error for variable i, return false if Minos failed
0191    bool GetMinosError(unsigned int i, double & errLow, double & errUp, int = 0) override;
0192
0193    /// minos status code of last Minos run
0194    /// minos status = -1   : Minos is not run
0195    ///              =  0   : last MINOS run was successful
0196    ///              >  0   : some problems encountered when running MINOS
0197    int MinosStatus() const override { return fMinosStatus; }
0198
0199    /**
0200       perform a full calculation of the Hessian matrix for error calculation
0201     */
0202    bool Hesse() override;
0203
0204    /**
0205       scan a parameter i around the minimum. A minimization must have been done before,
0206       return false if it is not the case
0207     */
0208    bool Scan(unsigned int i, unsigned int &nstep, double * x, double * y, double xmin = 0, double xmax = 0) override;
0209
0210    /**
0211       find the contour points (xi,xj) of the function for parameter i and j around the minimum
0212       The contour will be find for value of the function = Min + ErrorUp();
0213     */
0214    bool Contour(unsigned int i, unsigned int j, unsigned int & npoints, double *xi, double *xj) override;
0215
0216
0217    void PrintResults() override;
0218
0219    /// return reference to the objective function
0220    ///virtual const ROOT::Math::IGenFunction & Function() const;
0221
0222    /// get name of variables (override if minimizer support storing of variable names)
0223    std::string VariableName(unsigned int ivar) const override;
0224
0225    /// get index of variable given a variable given a name
0226    /// return always -1 . (It is Not implemented)
0227    int VariableIndex(const std::string & name) const override;
0228
0229    /// static function to switch on/off usage of static global TMinuit instance (gMinuit)
0230    /// By default it is used (i.e. is on). Method returns the previous state
0231    bool static UseStaticMinuit(bool on = true);
0232
0233    /// suppress the minuit warnings (if called with false will enable them)
0234    /// By default they are suppressed only when the printlevel is <= 0
0235    void SuppressMinuitWarnings(bool nowarn=true);
0236
0237    /// set debug mode. Return true if setting was successful
0238    bool SetDebug(bool on = true);
0239
0240 protected:
0241
0242    /// implementation of FCN for Minuit
0243    static void Fcn( int &, double * , double & f, double * , int);
0244    /// implementation of FCN for Minuit when user provided gradient is used
0245    static void FcnGrad( int &, double * g, double & f, double * , int);
0246
0247    /// initialize the TMinuit instance
0248    void InitTMinuit(int ndim);
0249
0250    /// reset
0251    void DoClear();
0252
0253    ///release a parameter that is fixed  when it is redefined
0254    void DoReleaseFixParameter( int ivar);
0255
0256    /// retrieve minimum parameters and errors from TMinuit
0257    void RetrieveParams();
0258
0259    /// retrieve error matrix from TMinuit
0260    void RetrieveErrorMatrix();
0261
0262    /// check TMinuit instance
0263    bool CheckMinuitInstance() const;
0264
0265    ///check parameter
0266    bool CheckVarIndex(unsigned int ivar) const;
0267
0268
0269 private:
0270
0271    bool fUsed;
0272    bool fMinosRun;
0273    unsigned int fDim;
0274    int fMinosStatus = -1;         // Minos status code
0275    std::vector<double> fParams;   // vector of output values
0276    std::vector<double> fErrors;   // vector of output errors
0277    std::vector<double> fCovar;    // vector storing the covariance matrix
0278
0279    ROOT::Minuit::EMinimizerType fType;
0280    TMinuit * fMinuit;
0281
0282    static TMinuit * fgMinuit;
0283
0284    static bool fgUsed;  // flag to control if static instance has done minimization
0285    static bool fgUseStaticMinuit; // flag to control if using global TMInuit instance (gMinuit)
0286
0287    ClassDef(TMinuitMinimizer,1)  //Implementation of Minimizer interface using TMinuit
0288
0289 };
0290
0291
0292
0293 #endif /* ROOT_TMinuitMinimizer */