root/Minuit2/FCNBase.h

0001 // @(#)root/minuit2:$Id$
0002 // Authors: M. Winkler, F. James, L. Moneta, A. Zsenei   2003-2005
0003
0004 /**********************************************************************
0005  *                                                                    *
0006  * Copyright (c) 2005 LCG ROOT Math team,  CERN/PH-SFT                *
0007  *                                                                    *
0008  **********************************************************************/
0009
0010 #ifndef ROOT_Minuit2_FCNBase
0011 #define ROOT_Minuit2_FCNBase
0012
0013 #include "Minuit2/MnConfig.h"
0014
0015 #include <ROOT/RSpan.hxx>
0016
0017 #include <vector>
0018
0019 namespace ROOT {
0020
0021 namespace Minuit2 {
0022
0023 /**
0024
0025   \defgroup Minuit Minuit2 Minimization Library
0026
0027   New Object-oriented implementation of the MINUIT minimization package.
0028   More information is available at the home page of the \ref Minuit2Page "Minuit2" minimization package".
0029
0030   \ingroup Math
0031 */
0032
0033 enum class GradientParameterSpace {
0034   External, Internal
0035 };
0036
0037 //______________________________________________________________________________
0038 /**
0039
0040
0041 Interface (abstract class) defining the function to be minimized, which has to be implemented by the user.
0042
0043 @author Fred James and Matthias Winkler; modified by Andras Zsenei and Lorenzo Moneta
0044
0045 \ingroup Minuit
0046
0047  */
0048
0049 class FCNBase {
0050
0051 public:
0052
0053    virtual ~FCNBase() = default;
0054
0055    /**
0056
0057       The meaning of the vector of parameters is of course defined by the user,
0058       who uses the values of those parameters to calculate their function Value.
0059       The order and the position of these parameters is strictly the one specified
0060       by the user when supplying the starting values for minimization. The starting
0061       values must be specified by the user, either via an std::vector<double> or the
0062       MnUserParameters supplied as input to the MINUIT minimizers such as
0063       VariableMetricMinimizer or MnMigrad. Later values are determined by MINUIT
0064       as it searches for the Minimum or performs whatever analysis is requested by
0065       the user.
0066
0067       @param v function parameters as defined by the user.
0068
0069       @return the Value of the function.
0070
0071       @see MnUserParameters
0072       @see VariableMetricMinimizer
0073       @see MnMigrad
0074
0075    */
0076
0077    virtual double operator()(std::vector<double> const &v) const = 0;
0078
0079    /**
0080
0081       Error definition of the function. MINUIT defines Parameter errors as the
0082       change in Parameter Value required to change the function Value by up. Normally,
0083       for chisquared fits it is 1, and for negative log likelihood, its Value is 0.5.
0084       If the user wants instead the 2-sigma errors for chisquared fits, it becomes 4,
0085       as Chi2(x+n*sigma) = Chi2(x) + n*n.
0086
0087       Comment a little bit better with links!!!!!!!!!!!!!!!!!
0088
0089    */
0090
0091    virtual double ErrorDef() const { return Up(); }
0092
0093    /**
0094
0095       Error definition of the function. MINUIT defines Parameter errors as the
0096       change in Parameter Value required to change the function Value by up. Normally,
0097       for chisquared fits it is 1, and for negative log likelihood, its Value is 0.5.
0098       If the user wants instead the 2-sigma errors for chisquared fits, it becomes 4,
0099       as Chi2(x+n*sigma) = Chi2(x) + n*n.
0100
0101       \todo Comment a little bit better with links!!!!!!!!!!!!!!!!! Idem for ErrorDef()
0102
0103    */
0104
0105    virtual double Up() const = 0;
0106
0107    /**
0108        add interface to set dynamically a new error definition
0109        Re-implement this function if needed.
0110    */
0111    virtual void SetErrorDef(double){};
0112
0113    virtual bool HasGradient() const { return false; }
0114
0115    virtual std::vector<double> Gradient(std::vector<double> const&) const { return {}; }
0116    virtual std::vector<double> GradientWithPrevResult(std::vector<double> const& parameters, double * /*previous_grad*/,
0117                                                       double * /*previous_g2*/, double * /*previous_gstep*/) const
0118    {
0119       return Gradient(parameters);
0120    };
0121
0122    virtual GradientParameterSpace gradParameterSpace() const {
0123       return GradientParameterSpace::External;
0124    };
0125
0126    /// return second derivatives (diagonal of the Hessian matrix)
0127    virtual std::vector<double> G2(std::vector<double> const&) const { return {};}
0128
0129    /// return Hessian
0130    virtual std::vector<double> Hessian(std::vector<double> const&) const { return {};}
0131
0132    virtual bool HasHessian() const { return false; }
0133
0134    virtual bool HasG2() const { return false; }
0135 };
0136
0137 } // namespace Minuit2
0138
0139 } // namespace ROOT
0140
0141 #endif // ROOT_Minuit2_FCNBase