RooFit/TestStatistics/LikelihoodGradientWrapper.h

0001 /*
0002  * Project: RooFit
0003  * Authors:
0004  *   PB, Patrick Bos, Netherlands eScience Center, p.bos@esciencecenter.nl
0005  *
0006  * Copyright (c) 2021, CERN
0007  *
0008  * Redistribution and use in source and binary forms,
0009  * with or without modification, are permitted according to the terms
0010  * listed in LICENSE (http://roofit.sourceforge.net/license.txt)
0011  */
0012
0013 #ifndef ROOT_ROOFIT_TESTSTATISTICS_LikelihoodGradientWrapper
0014 #define ROOT_ROOFIT_TESTSTATISTICS_LikelihoodGradientWrapper
0015
0016 #include "RooFit/TestStatistics/SharedOffset.h"
0017
0018 #include <Fit/ParameterSettings.h>
0019 #include <Math/IFunctionfwd.h>
0020 #include "Math/MinimizerOptions.h"
0021 #include "Math/Util.h"
0022
0023 #include <vector>
0024 #include <memory> // shared_ptr
0025
0026 // forward declaration
0027 class RooMinimizer;
0028
0029 namespace RooFit {
0030 namespace TestStatistics {
0031
0032 // forward declaration
0033 class RooAbsL;
0034 struct WrapperCalculationCleanFlags;
0035
0036 enum class LikelihoodGradientMode { multiprocess };
0037
0038 class LikelihoodGradientWrapper {
0039 protected:
0040    LikelihoodGradientWrapper(std::shared_ptr<RooAbsL> likelihood,
0041                              std::shared_ptr<WrapperCalculationCleanFlags> calculation_is_clean, std::size_t N_dim,
0042                              RooMinimizer *minimizer, SharedOffset offset);
0043
0044 public:
0045    virtual ~LikelihoodGradientWrapper() = default;
0046    LikelihoodGradientWrapper(const LikelihoodGradientWrapper &) = delete;
0047    LikelihoodGradientWrapper &operator=(const LikelihoodGradientWrapper &) = delete;
0048
0049    static std::unique_ptr<LikelihoodGradientWrapper>
0050    create(LikelihoodGradientMode likelihoodGradientMode, std::shared_ptr<RooAbsL> likelihood,
0051           std::shared_ptr<WrapperCalculationCleanFlags> calculationIsClean, std::size_t nDim, RooMinimizer *minimizer,
0052           SharedOffset offset);
0053
0054    virtual void fillGradient(double *grad) = 0;
0055    virtual void
0056    fillGradientWithPrevResult(double *grad, double *previous_grad, double *previous_g2, double *previous_gstep) = 0;
0057
0058    /// Synchronize minimizer settings with calculators in child classes.
0059    virtual void synchronizeWithMinimizer(const ROOT::Math::MinimizerOptions &options);
0060    virtual void synchronizeParameterSettings(const std::vector<ROOT::Fit::ParameterSettings> &parameter_settings);
0061    virtual void synchronizeParameterSettings(ROOT::Math::IMultiGenFunction *function,
0062                                              const std::vector<ROOT::Fit::ParameterSettings> &parameter_settings) = 0;
0063    /// Minuit passes in parameter values that may not conform to RooFit internal standards (like applying range
0064    /// clipping), but that the specific calculator does need. This function can be implemented to receive these
0065    /// Minuit-internal values.
0066    virtual void updateMinuitInternalParameterValues(const std::vector<double> &minuit_internal_x);
0067    virtual void updateMinuitExternalParameterValues(const std::vector<double> &minuit_external_x);
0068
0069    /// \brief Implement usesMinuitInternalValues to return true when you want Minuit to send this class Minuit-internal
0070    /// values, or return false when you want "regular" Minuit-external values.
0071    ///
0072    /// Minuit internally uses a transformed parameter space to graciously handle externally mandated parameter range
0073    /// boundaries. Transformation from Minuit-internal to external (i.e. "regular") parameters is done using
0074    /// trigonometric functions that in some cases can cause a few bits of precision loss with respect to the original
0075    /// parameter values. To circumvent this, Minuit also allows external gradient providers (like
0076    /// LikelihoodGradientWrapper) to take the Minuit-internal parameter values directly, without transformation. This
0077    /// way, the gradient provider (e.g. the implementation of this class) can handle transformation manually, possibly
0078    /// with higher precision.
0079    virtual bool usesMinuitInternalValues() = 0;
0080
0081    /// Reports whether or not the gradient is currently being calculated.
0082    ///
0083    /// This is used in MinuitFcnGrad to switch between LikelihoodWrapper implementations
0084    /// inside and outside of a LikelihoodGradientJob calculation when the LikelihoodWrapper
0085    /// used is LikelihoodJob. This is to prevent Jobs from being started within Jobs.
0086    virtual bool isCalculating() = 0;
0087
0088 protected:
0089    std::shared_ptr<RooAbsL> likelihood_;
0090    RooMinimizer *minimizer_;
0091    std::shared_ptr<WrapperCalculationCleanFlags> calculation_is_clean_;
0092    SharedOffset shared_offset_;
0093 };
0094
0095 } // namespace TestStatistics
0096 } // namespace RooFit
0097
0098 #endif // ROOT_ROOFIT_TESTSTATISTICS_LikelihoodGradientWrapper