RooFit/TestStatistics/LikelihoodWrapper.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_LikelihoodWrapper
0014 #define ROOT_ROOFIT_TESTSTATISTICS_LikelihoodWrapper
0015
0016 #include "RooFit/TestStatistics/SharedOffset.h"
0017
0018 #include "RooArgSet.h"
0019 #include "RooAbsArg.h" // enum ConstOpCode
0020
0021 #include <Fit/ParameterSettings.h>
0022 #include <Math/MinimizerOptions.h>
0023 #include <Math/Util.h>
0024
0025 #include <memory> // shared_ptr
0026 #include <string>
0027
0028 // forward declaration
0029 class RooMinimizer;
0030
0031 namespace RooFit {
0032 namespace TestStatistics {
0033
0034 // forward declaration
0035 class RooAbsL;
0036
0037 /// For communication with wrappers, an instance of this struct must be shared between them and MinuitFcnGrad. It keeps
0038 /// track of what has been evaluated for the current parameter set provided by Minuit.
0039 struct WrapperCalculationCleanFlags {
0040    // indicate whether that part has been calculated since the last parameter update
0041    bool likelihood = false;
0042    bool gradient = false;
0043
0044    void set_all(bool value)
0045    {
0046       likelihood = value;
0047       gradient = value;
0048    }
0049 };
0050
0051 enum class LikelihoodType { unbinned, binned, subsidiary, sum };
0052
0053 enum class LikelihoodMode { serial, multiprocess };
0054
0055 /// Previously, offsetting was only implemented for RooNLLVar components of a likelihood,
0056 /// not for RooConstraintSum terms. To emulate this behavior, use OffsettingMode::legacy. To
0057 /// also offset the RooSubsidiaryL component (equivalent of RooConstraintSum) of RooSumL
0058 /// likelihoods, use OffsettingMode::full.
0059 enum class OffsettingMode { legacy, full };
0060
0061 class LikelihoodWrapper {
0062 protected:
0063    LikelihoodWrapper(std::shared_ptr<RooAbsL> likelihood,
0064                      std::shared_ptr<WrapperCalculationCleanFlags> calculation_is_clean, SharedOffset offset);
0065
0066 public:
0067    virtual ~LikelihoodWrapper() = default;
0068    LikelihoodWrapper(const LikelihoodWrapper &) = delete;
0069    LikelihoodWrapper &operator=(const LikelihoodWrapper &) = delete;
0070
0071    static std::unique_ptr<LikelihoodWrapper> create(LikelihoodMode likelihoodMode, std::shared_ptr<RooAbsL> likelihood,
0072                                                     std::shared_ptr<WrapperCalculationCleanFlags> calculationIsClean,
0073                                                     SharedOffset offset);
0074
0075    /// \brief Triggers (possibly asynchronous) evaluation of the likelihood
0076    ///
0077    /// In parallel strategies, it may be advantageous to allow a calling process to continue on with other tasks while
0078    /// the calculation is offloaded to another process or device, like a GPU. For this reason, evaluate() does not
0079    /// return the result, this is done in getResult().
0080    virtual void evaluate() = 0;
0081    /// \brief Return the latest result of a likelihood evaluation.
0082    ///
0083    /// Returns the result that was stored after calling evaluate(). It is up to the implementer to make sure the stored
0084    /// value represents the most recent evaluation call, e.g. by using a mutex.
0085    virtual ROOT::Math::KahanSum<double> getResult() const = 0;
0086
0087    /// Synchronize minimizer settings with calculators in child classes
0088    virtual void synchronizeWithMinimizer(const ROOT::Math::MinimizerOptions &options);
0089    virtual void synchronizeParameterSettings(const std::vector<ROOT::Fit::ParameterSettings> &parameter_settings);
0090    /// Minuit passes in parameter values that may not conform to RooFit internal standards (like applying range
0091    /// clipping), but that the specific calculator does need. This function can be implemented to receive these
0092    /// Minuit-internal values:
0093    virtual void updateMinuitInternalParameterValues(const std::vector<double> &minuit_internal_x);
0094    virtual void updateMinuitExternalParameterValues(const std::vector<double> &minuit_external_x);
0095
0096    // The following functions are necessary from MinuitFcnGrad to reach likelihood properties:
0097    void constOptimizeTestStatistic(RooAbsArg::ConstOpCode opcode, bool doAlsoTrackingOpt);
0098    double defaultErrorLevel() const;
0099    virtual std::string GetName() const;
0100    virtual std::string GetTitle() const;
0101    inline virtual bool isOffsetting() const { return do_offset_; }
0102    virtual void enableOffsetting(bool flag);
0103    void setOffsettingMode(OffsettingMode mode);
0104    void setApplyWeightSquared(bool flag);
0105
0106 protected:
0107    std::shared_ptr<RooAbsL> likelihood_;
0108    LikelihoodType likelihood_type_;
0109    std::shared_ptr<WrapperCalculationCleanFlags> calculation_is_clean_;
0110
0111    bool do_offset_ = false;
0112    SharedOffset shared_offset_;
0113    void calculate_offsets();
0114    OffsettingMode offsetting_mode_ = OffsettingMode::legacy;
0115 };
0116
0117 } // namespace TestStatistics
0118 } // namespace RooFit
0119
0120 #endif // ROOT_ROOFIT_TESTSTATISTICS_LikelihoodWrapper