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    /// set the function to minimize
0071    void SetFunction(const ROOT::Math::IMultiGenFunction & func) override;
0072
0073    /// set free variable
0074    bool SetVariable(unsigned int ivar, const std::string & name, double val, double step) override;
0075
0076    /// set upper/lower limited variable (override if minimizer supports them )
0077    bool SetLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double /* lower */, double /* upper */) override;
0078
0079    /// set lower limit variable  (override if minimizer supports them )
0080    bool SetLowerLimitedVariable(unsigned int  ivar , const std::string & name , double val , double step , double lower ) override;
0081
0082    /// set upper limit variable (override if minimizer supports them )
0083    bool SetUpperLimitedVariable(unsigned int ivar , const std::string & name , double val , double step , double upper ) override;
0084
0085    /// set fixed variable (override if minimizer supports them )
0086    bool SetFixedVariable(unsigned int /* ivar */, const std::string & /* name */, double /* val */) override;
0087
0088    /// set the value of an existing variable
0089    bool SetVariableValue(unsigned int , double ) override;
0090
0091    /// set the step size of an existing variable
0092    bool SetVariableStepSize(unsigned int , double ) override;
0093    /// set the lower-limit of an existing variable
0094    bool SetVariableLowerLimit(unsigned int , double ) override;
0095    /// set the upper-limit of an existing variable
0096    bool SetVariableUpperLimit(unsigned int , double ) override;
0097    /// set the limits of an existing variable
0098    bool SetVariableLimits(unsigned int ivar, double lower, double upper) override;
0099    /// fix an existing variable
0100    bool FixVariable(unsigned int) override;
0101    /// release an existing variable
0102    bool ReleaseVariable(unsigned int) override;
0103    /// query if an existing variable is fixed (i.e. considered constant in the minimization)
0104    /// note that by default all variables are not fixed
0105    bool IsFixedVariable(unsigned int) const override;
0106    /// get variable settings in a variable object (like ROOT::Fit::ParamsSettings)
0107    bool GetVariableSettings(unsigned int, ROOT::Fit::ParameterSettings & ) const override;
0108
0109
0110    /// method to perform the minimization
0111     bool Minimize() override;
0112
0113    /// return minimum function value
0114    double MinValue() const override;
0115
0116    /// return expected distance reached from the minimum
0117    double Edm() const override;
0118
0119    /// return  pointer to X values at the minimum
0120    const double *  X() const override { return &fParams.front(); }
0121
0122    /// return pointer to gradient values at the minimum
0123    const double *  MinGradient() const override { return nullptr; } // not available in Minuit2
0124
0125    /// number of function calls to reach the minimum
0126    unsigned int NCalls() const override;
0127
0128    /// this is <= Function().NDim() which is the total
0129    /// number of variables (free+ constrained ones)
0130    unsigned int NDim() const override { return fDim; }
0131
0132    /// number of free variables (real dimension of the problem)
0133    /// this is <= Function().NDim() which is the total
0134    unsigned int NFree() const override;
0135
0136    /// minimizer provides error and error matrix
0137    bool ProvidesError() const override { return true; }
0138
0139    /// return errors at the minimum
0140    const double * Errors() const override { return  &fErrors.front(); }
0141
0142    /** return covariance matrices elements
0143        if the variable is fixed the matrix is zero
0144        The ordering of the variables is the same as in errors
0145    */
0146    double CovMatrix(unsigned int i, unsigned int j) const override {
0147       return ( fCovar.size() > (i + fDim* j) ) ? fCovar[i + fDim* j] : 0;
0148    }
0149
0150    /**
0151        Fill the passed array with the  covariance matrix elements
0152        if the variable is fixed or const the value is zero.
0153        The array will be filled as cov[i *ndim + j]
0154        The ordering of the variables is the same as in errors and parameter value.
0155        This is different from the direct interface of Minuit2 or TMinuit where the
0156        values were obtained only to variable parameters
0157    */
0158    bool GetCovMatrix(double * cov) const override;
0159
0160    /**
0161        Fill the passed array with the Hessian matrix elements
0162        The Hessian matrix is the matrix of the second derivatives
0163        and is the inverse of the covariance matrix
0164        If the variable is fixed or const the values for that variables are zero.
0165        The array will be filled as h[i *ndim + j]
0166    */
0167    bool GetHessianMatrix(double * h) const override;
0168
0169    ///return status of covariance matrix
0170    int CovMatrixStatus() const override;
0171
0172    ///global correlation coefficient for variable i
0173    double GlobalCC(unsigned int ) const override;
0174
0175    /// minos error for variable i, return false if Minos failed
0176    bool GetMinosError(unsigned int i, double & errLow, double & errUp, int = 0) override;
0177
0178    /// minos status code of last Minos run
0179    /// minos status = -1   : Minos is not run
0180    ///              =  0   : last MINOS run was successful
0181    ///              >  0   : some problems encountered when running MINOS
0182    int MinosStatus() const override { return fMinosStatus; }
0183
0184    /**
0185       perform a full calculation of the Hessian matrix for error calculation
0186     */
0187    bool Hesse() override;
0188
0189    /**
0190       scan a parameter i around the minimum. A minimization must have been done before,
0191       return false if it is not the case
0192     */
0193    bool Scan(unsigned int i, unsigned int &nstep, double * x, double * y, double xmin = 0, double xmax = 0) override;
0194
0195    /**
0196       find the contour points (xi,xj) of the function for parameter i and j around the minimum
0197       The contour will be find for value of the function = Min + ErrorUp();
0198     */
0199    bool Contour(unsigned int i, unsigned int j, unsigned int & npoints, double *xi, double *xj) override;
0200
0201
0202    void PrintResults() override;
0203
0204    /// return reference to the objective function
0205    ///virtual const ROOT::Math::IGenFunction & Function() const;
0206
0207    /// get name of variables (override if minimizer support storing of variable names)
0208    std::string VariableName(unsigned int ivar) const override;
0209
0210    /// get index of variable given a variable given a name
0211    /// return always -1 . (It is Not implemented)
0212    int VariableIndex(const std::string & name) const override;
0213
0214    /// static function to switch on/off usage of static global TMinuit instance (gMinuit)
0215    /// By default it is used (i.e. is on). Method returns the previous state
0216    bool static UseStaticMinuit(bool on = true);
0217
0218    /// suppress the minuit warnings (if called with false will enable them)
0219    /// By default they are suppressed only when the printlevel is <= 0
0220    void SuppressMinuitWarnings(bool nowarn=true);
0221
0222    /// set debug mode. Return true if setting was successful
0223    bool SetDebug(bool on = true);
0224
0225 protected:
0226
0227    /// implementation of FCN for Minuit
0228    static void Fcn( int &, double * , double & f, double * , int);
0229    /// implementation of FCN for Minuit when user provided gradient is used
0230    static void FcnGrad( int &, double * g, double & f, double * , int);
0231
0232    /// initialize the TMinuit instance
0233    void InitTMinuit(int ndim);
0234
0235    /// reset
0236    void DoClear();
0237
0238    ///release a parameter that is fixed  when it is redefined
0239    void DoReleaseFixParameter( int ivar);
0240
0241    /// retrieve minimum parameters and errors from TMinuit
0242    void RetrieveParams();
0243
0244    /// retrieve error matrix from TMinuit
0245    void RetrieveErrorMatrix();
0246
0247    /// check TMinuit instance
0248    bool CheckMinuitInstance() const;
0249
0250    ///check parameter
0251    bool CheckVarIndex(unsigned int ivar) const;
0252
0253
0254 private:
0255
0256    bool fUsed;
0257    bool fMinosRun;
0258    unsigned int fDim;
0259    int fMinosStatus = -1;         // Minos status code
0260    std::vector<double> fParams;   // vector of output values
0261    std::vector<double> fErrors;   // vector of output errors
0262    std::vector<double> fCovar;    // vector storing the covariance matrix
0263
0264    ROOT::Minuit::EMinimizerType fType;
0265    TMinuit * fMinuit;
0266
0267    static TMinuit * fgMinuit;
0268
0269    static bool fgUsed;  // flag to control if static instance has done minimization
0270    static bool fgUseStaticMinuit; // flag to control if using global TMInuit instance (gMinuit)
0271
0272    ClassDef(TMinuitMinimizer,1)  //Implementation of Minimizer interface using TMinuit
0273
0274 };
0275
0276
0277
0278 #endif /* ROOT_TMinuitMinimizer */