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::Minuit2 {
0020
0021 /// \defgroup Minuit Minuit2 Minimization Library
0022 ///
0023 /// New Object-oriented implementation of the MINUIT minimization package.
0024 /// More information is available at the home page of the \ref Minuit2Page "Minuit2" minimization package".
0025 ///
0026 /// \ingroup Math
0027
0028 enum class GradientParameterSpace {
0029    External,
0030    Internal
0031 };
0032
0033 /// Interface (abstract class) defining the function to be minimized, which has to be implemented by the user.
0034 ///
0035 /// \ingroup Minuit
0036
0037 class FCNBase {
0038
0039 public:
0040    virtual ~FCNBase() = default;
0041
0042    /// The meaning of the vector of parameters is of course defined by the user,
0043    /// who uses the values of those parameters to calculate their function Value.
0044    /// The order and the position of these parameters is strictly the one specified
0045    /// by the user when supplying the starting values for minimization. The starting
0046    /// values must be specified by the user, either via an std::vector<double> or the
0047    /// MnUserParameters supplied as input to the MINUIT minimizers such as
0048    /// VariableMetricMinimizer or MnMigrad. Later values are determined by MINUIT
0049    /// as it searches for the Minimum or performs whatever analysis is requested by
0050    /// the user.
0051    ///
0052    /// @param v function parameters as defined by the user.
0053    ///
0054    /// @return the Value of the function.
0055    ///
0056    /// @see MnUserParameters
0057    /// @see VariableMetricMinimizer
0058    /// @see MnMigrad
0059
0060    virtual double operator()(std::vector<double> const &v) const = 0;
0061
0062    /// Error definition of the function. MINUIT defines Parameter errors as the
0063    /// change in Parameter Value required to change the function Value by up. Normally,
0064    /// for chisquared fits it is 1, and for negative log likelihood, its Value is 0.5.
0065    /// If the user wants instead the 2-sigma errors for chisquared fits, it becomes 4,
0066    /// as Chi2(x+n*sigma) = Chi2(x) + n*n.
0067    ///
0068    /// Comment a little bit better with links!!!!!!!!!!!!!!!!!
0069
0070    virtual double ErrorDef() const { return Up(); }
0071
0072    /// Error definition of the function. MINUIT defines Parameter errors as the
0073    /// change in Parameter Value required to change the function Value by up. Normally,
0074    /// for chisquared fits it is 1, and for negative log likelihood, its Value is 0.5.
0075    /// If the user wants instead the 2-sigma errors for chisquared fits, it becomes 4,
0076    /// as Chi2(x+n*sigma) = Chi2(x) + n*n.
0077    ///
0078    /// \todo Comment a little bit better with links!!!!!!!!!!!!!!!!! Idem for ErrorDef()
0079
0080    virtual double Up() const = 0;
0081
0082    /// add interface to set dynamically a new error definition
0083    /// Re-implement this function if needed.
0084    virtual void SetErrorDef(double) {};
0085
0086    virtual bool HasGradient() const { return false; }
0087
0088    /// Return the gradient vector of the function at the given parameter point.
0089    ///
0090    /// By default, returns an empty vector (no analytic gradient provided).
0091    /// Override this method if an analytic gradient is available.
0092    ///
0093    /// @param v Parameter vector.
0094    /// @return Gradient vector with respect to the parameters.
0095    virtual std::vector<double> Gradient(std::vector<double> const &) const { return {}; }
0096
0097    /// \warning Not meant to be overridden! This is a requirement for an
0098    /// internal optimization in RooFit that might go away with any refactoring.
0099    virtual std::vector<double> GradientWithPrevResult(std::vector<double> const &parameters, double * /*previous_grad*/,
0100                                                       double * /*previous_g2*/, double * /*previous_gstep*/) const
0101    {
0102       return Gradient(parameters);
0103    };
0104
0105    /// \warning Not meant to be overridden! This is a requirement for an
0106    /// internal optimization in RooFit that might go away with any refactoring.
0107    virtual GradientParameterSpace gradParameterSpace() const { return GradientParameterSpace::External; };
0108
0109    /// Return the diagonal elements of the Hessian (second derivatives).
0110    ///
0111    /// By default, returns an empty vector. Override this method if analytic second derivatives
0112    /// (per-parameter curvature) are available.
0113    ///
0114    /// @param v Parameter vector.
0115    /// @return Vector of second derivatives with respect to each parameter.
0116    virtual std::vector<double> G2(std::vector<double> const &) const { return {}; }
0117
0118    /// Return the full Hessian matrix of the function.
0119    ///
0120    /// By default, returns an empty vector. Override this method if the full analytic Hessian
0121    /// (matrix of second derivatives) is available.
0122    ///
0123    /// @param v Parameter vector.
0124    /// @return Flattened Hessian matrix.
0125    virtual std::vector<double> Hessian(std::vector<double> const &) const { return {}; }
0126
0127    virtual bool HasHessian() const { return false; }
0128
0129    virtual bool HasG2() const { return false; }
0130 };
0131
0132 } // namespace ROOT::Minuit2
0133
0134 #endif // ROOT_Minuit2_FCNBase