root/Minuit2/FunctionMinimum.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_FunctionMinimum
0011 #define ROOT_Minuit2_FunctionMinimum
0012
0013 #include "Minuit2/MinimumSeed.h"
0014 #include "Minuit2/MinimumState.h"
0015 #include "Minuit2/MnUserParameterState.h"
0016 #include "Minuit2/MnUserTransformation.h"
0017
0018 #include <vector>
0019 #include <memory>
0020 #include <cmath>
0021
0022 #ifdef G__DICTIONARY
0023 typedef ROOT::Minuit2::MinimumState MinimumState;
0024 #endif
0025
0026 namespace ROOT {
0027
0028 namespace Minuit2 {
0029
0030 //______________________________________________________________________________________________
0031 /**
0032     class holding the full result of the minimization;
0033     both internal and external (MnUserParameterState) representation available
0034     for the parameters at the Minimum
0035  */
0036
0037 class FunctionMinimum {
0038
0039 public:
0040    enum Status {
0041       MnValid,
0042       MnReachedCallLimit,
0043       MnAboveMaxEdm,
0044    };
0045
0046 public:
0047    /// Constructor from only MinimumSeed. Minimum is only from seed result not the full minimization
0048    FunctionMinimum(const MinimumSeed &seed, double up)
0049       : FunctionMinimum(seed,
0050                         std::vector<MinimumState>(1, MinimumState(seed.Parameters(), seed.Error(), seed.Gradient(),
0051                                                                   seed.Parameters().Fval(), seed.NFcn())),
0052                         up)
0053    {
0054    }
0055
0056    /// Constructor at the end of a minimization from seed and vector of states
0057    FunctionMinimum(const MinimumSeed &seed, std::span<const MinimumState> states, double up, Status status = MnValid)
0058       : fPtr{new Data{seed, {states.begin(), states.end()}, up, status == MnAboveMaxEdm, status == MnReachedCallLimit, {}}}
0059    {
0060    }
0061
0062    /// add latest minimization state (for example add Hesse result after Migrad)
0063    void Add(const MinimumState &state, Status status = MnValid)
0064    {
0065       fPtr->fStates.push_back(state);
0066       // LM : update also the user state
0067       fPtr->fUserState = MnUserParameterState(State(), Up(), Seed().Trafo());
0068       // reset maxedm flag. If new state has edm over max other method must be used
0069       fPtr->fAboveMaxEdm = status == MnAboveMaxEdm;
0070       fPtr->fReachedCallLimit = status == MnReachedCallLimit;
0071    }
0072
0073    const MinimumSeed &Seed() const { return fPtr->fSeed; }
0074    const std::vector<MinimumState> &States() const { return fPtr->fStates; }
0075
0076    // user representation of state at Minimum
0077    const MnUserParameterState &UserState() const
0078    {
0079       if (!fPtr->fUserState.IsValid())
0080          fPtr->fUserState = MnUserParameterState(State(), Up(), Seed().Trafo());
0081       return fPtr->fUserState;
0082    }
0083    const MnUserParameters &UserParameters() const { return UserState().Parameters(); }
0084    const MnUserCovariance &UserCovariance() const { return UserState().Covariance(); }
0085
0086    // forward interface of last state
0087    const MinimumState &State() const { return States().back(); }
0088    const MinimumParameters &Parameters() const { return States().back().Parameters(); }
0089    const MinimumError &Error() const { return States().back().Error(); }
0090    const FunctionGradient &Grad() const { return States().back().Gradient(); }
0091    double Fval() const { return States().back().Fval(); }
0092    double Edm() const { return States().back().Edm(); }
0093    int NFcn() const { return States().back().NFcn(); }
0094
0095    double Up() const { return fPtr->fErrorDef; }
0096    bool IsValid() const { return State().IsValid() && !IsAboveMaxEdm() && !HasReachedCallLimit(); }
0097    bool HasValidParameters() const { return State().Parameters().IsValid(); }
0098    bool HasValidCovariance() const { return State().Error().IsValid(); }
0099    bool HasAccurateCovar() const { return State().Error().IsAccurate(); }
0100    bool HasPosDefCovar() const { return State().Error().IsPosDef(); }
0101    bool HasMadePosDefCovar() const { return State().Error().IsMadePosDef(); }
0102    bool HesseFailed() const { return State().Error().HesseFailed(); }
0103    bool HasCovariance() const { return State().Error().IsAvailable(); }
0104    bool IsAboveMaxEdm() const { return fPtr->fAboveMaxEdm || std::isnan(Edm()); }
0105    bool HasReachedCallLimit() const { return fPtr->fReachedCallLimit; }
0106
0107    void SetErrorDef(double up)
0108    {
0109       fPtr->fErrorDef = up;
0110       // update user state for new value of up (scaling of errors)
0111       fPtr->fUserState = MnUserParameterState(State(), up, Seed().Trafo());
0112    }
0113
0114 private:
0115    struct Data {
0116       MinimumSeed fSeed;
0117       std::vector<MinimumState> fStates;
0118       double fErrorDef;
0119       bool fAboveMaxEdm;
0120       bool fReachedCallLimit;
0121       mutable MnUserParameterState fUserState;
0122    };
0123
0124    std::shared_ptr<Data> fPtr;
0125 };
0126
0127 } // namespace Minuit2
0128
0129 } // namespace ROOT
0130
0131 #endif // ROOT_Minuit2_FunctionMinimum