FCNBase.h

Go to the documentation of this file.

// @(#)root/minuit2:$Id$
// Authors: M. Winkler, F. James, L. Moneta, A. Zsenei   2003-2005
 
/**********************************************************************
 *                                                                    *
 * Copyright (c) 2005 LCG ROOT Math team,  CERN/PH-SFT                *
 *                                                                    *
 **********************************************************************/
 
#ifndef ROOT_Minuit2_FCNBase
#define ROOT_Minuit2_FCNBase
 
#include "Minuit2/MnConfig.h"
 
#include <ROOT/RSpan.hxx>
 
#include <vector>
 
namespace ROOT::Minuit2 {
 
/// \defgroup Minuit Minuit2 Minimization Library
///
/// New Object-oriented implementation of the MINUIT minimization package.
/// More information is available at the home page of the \ref Minuit2Page "Minuit2" minimization package".
///
/// \ingroup Math
 
enum class GradientParameterSpace {
   External,
   Internal
};
 
/// Interface (abstract class) defining the function to be minimized, which has to be implemented by the user.
///
/// \ingroup Minuit
 
class FCNBase {
 
public:
   virtual ~FCNBase() = default;
 
   /// The meaning of the vector of parameters is of course defined by the user,
   /// who uses the values of those parameters to calculate their function Value.
   /// The order and the position of these parameters is strictly the one specified
   /// by the user when supplying the starting values for minimization. The starting
   /// values must be specified by the user, either via an std::vector<double> or the
   /// MnUserParameters supplied as input to the MINUIT minimizers such as
   /// VariableMetricMinimizer or MnMigrad. Later values are determined by MINUIT
   /// as it searches for the Minimum or performs whatever analysis is requested by
   /// the user.
   ///
   /// @param v function parameters as defined by the user.
   ///
   /// @return the Value of the function.
   ///
   /// @see MnUserParameters
   /// @see VariableMetricMinimizer
   /// @see MnMigrad
 
   virtual double operator()(std::vector<double> const &v) const = 0;
 
   /// Error definition of the function. MINUIT defines Parameter errors as the
   /// change in Parameter Value required to change the function Value by up. Normally,
   /// for chisquared fits it is 1, and for negative log likelihood, its Value is 0.5.
   /// If the user wants instead the 2-sigma errors for chisquared fits, it becomes 4,
   /// as Chi2(x+n*sigma) = Chi2(x) + n*n.
   ///
   /// Comment a little bit better with links!!!!!!!!!!!!!!!!!
 
   virtual double ErrorDef() const { return Up(); }
 
   /// Error definition of the function. MINUIT defines Parameter errors as the
   /// change in Parameter Value required to change the function Value by up. Normally,
   /// for chisquared fits it is 1, and for negative log likelihood, its Value is 0.5.
   /// If the user wants instead the 2-sigma errors for chisquared fits, it becomes 4,
   /// as Chi2(x+n*sigma) = Chi2(x) + n*n.
   ///
   /// \todo Comment a little bit better with links!!!!!!!!!!!!!!!!! Idem for ErrorDef()
 
   virtual double Up() const = 0;
 
   /// add interface to set dynamically a new error definition
   /// Re-implement this function if needed.
   virtual void SetErrorDef(double) {};
 
   virtual bool HasGradient() const { return false; }
 
   /// Return the gradient vector of the function at the given parameter point.
   ///
   /// By default, returns an empty vector (no analytic gradient provided).
   /// Override this method if an analytic gradient is available.
   ///
   /// @param v Parameter vector.
   /// @return Gradient vector with respect to the parameters.
   virtual std::vector<double> Gradient(std::vector<double> const &) const { return {}; }
 
   /// \warning Not meant to be overridden! This is a requirement for an
   /// internal optimization in RooFit that might go away with any refactoring.
   virtual std::vector<double> GradientWithPrevResult(std::vector<double> const &parameters, double * /*previous_grad*/,
                                                      double * /*previous_g2*/, double * /*previous_gstep*/) const
   {
      return Gradient(parameters);
   };
 
   /// Variant of GradientWithPrevResult() that additionally receives the
   /// already-known function value at \p parameters (e.g. from the line search
   /// that preceded the gradient request), so implementations can avoid
   /// re-evaluating the function at the central point.
   ///
   /// \warning Not meant to be overridden! This is a requirement for an
   /// internal optimization in RooFit that might go away with any refactoring.
   virtual std::vector<double> GradientWithPrevResult(std::vector<double> const &parameters, double *previous_grad,
                                                      double *previous_g2, double *previous_gstep,
                                                      double /*fValAtParameters*/) const
   {
      return GradientWithPrevResult(parameters, previous_grad, previous_g2, previous_gstep);
   };
 
   /// \warning Not meant to be overridden! This is a requirement for an
   /// internal optimization in RooFit that might go away with any refactoring.
   virtual GradientParameterSpace gradParameterSpace() const { return GradientParameterSpace::External; };
 
   /// Return the diagonal elements of the Hessian (second derivatives).
   ///
   /// By default, returns an empty vector. Override this method if analytic second derivatives
   /// (per-parameter curvature) are available.
   ///
   /// @param v Parameter vector.
   /// @return Vector of second derivatives with respect to each parameter.
   virtual std::vector<double> G2(std::vector<double> const &) const { return {}; }
 
   /// Return the full Hessian matrix of the function.
   ///
   /// By default, returns an empty vector. Override this method if the full analytic Hessian
   /// (matrix of second derivatives) is available.
   ///
   /// @param v Parameter vector.
   /// @return Flattened Hessian matrix.
   virtual std::vector<double> Hessian(std::vector<double> const &) const { return {}; }
 
   virtual bool HasHessian() const { return false; }
 
   virtual bool HasG2() const { return false; }
 
   /// Indicate whether the mixed second order derivative with respect to
   /// parameters i and j is identically zero, i.e. zero for *all* parameter
   /// values. This can help to avoid expensive function calls in numerical
   /// Hessian evaluations (see MnHesse).
   ///
   /// The contract for implementations:
   ///
   ///   * The indices refer to the FCN's own full (external) parameter
   ///     space, including any parameters that are fixed in the minimizer.
   ///     Callers that work with internal indices, like MnHesse, must
   ///     translate them via MnUserTransformation::ExtOfInt() before calling
   ///     this function.
   ///   * The result must be symmetric in i and j.
   ///   * Only return `true` if the second derivative vanishes for *any*
   ///     value of the parameters: the result may be cached and is used at
   ///     arbitrary points in parameter space.
   ///   * The diagonal (i == j) is never queried by Minuit2, so its return
   ///     value has no effect.
   virtual bool SecondDerivativeAlwaysVanishes(unsigned int /*i*/, unsigned int /*j*/) const { return false; }
};
 
} // namespace ROOT::Minuit2
 
#endif // ROOT_Minuit2_FCNBase