include/root/TUnuranContDist.h

0001 // @(#)root/unuran:$Id$
0002 // Authors: L. Moneta, J. Leydold Wed Feb 28 2007
0003
0004 /**********************************************************************
0005  *                                                                    *
0006  * Copyright (c) 2006  LCG ROOT Math Team, CERN/PH-SFT                *
0007  *                                                                    *
0008  *                                                                    *
0009  **********************************************************************/
0010
0011 // Header file for class TUnuranContDist
0012
0013
0014 #ifndef ROOT_Math_TUnuranContDist
0015 #define ROOT_Math_TUnuranContDist
0016
0017 #include "TUnuranBaseDist.h"
0018
0019 #include "Math/IFunctionfwd.h"
0020
0021 class TF1;
0022
0023
0024
0025
0026 /**
0027    \class TUnuranContDist
0028    \ingroup Unuran
0029
0030    TUnuranContDist class describing one dimensional continuous distribution.
0031    It is used by TUnuran to generate random numbers according to this distribution via
0032    TUnuran::Sample()
0033
0034    The class can be constructed from a function (TF1) representing the probability density
0035    function of the distribution. Optionally the derivative of the pdf can also be passed.
0036
0037    It provides a method to set the domain of the distribution ( SetDomain ) which will correspond to the range
0038    of the generated random numbers. By default the domain is (-inf, + inf), independently of the
0039    range set in the TF1 class used to construct the distribution.
0040
0041    In addition, some UNURAN methods requires extra information (cdf function, distribution mode,
0042    area of pdf, etc...). This information can as well be set.
0043    Some methods require instead of the pdf the log of the pdf.
0044    This can also be controlled by setting a flag when constructing this class.
0045 */
0046
0047
0048 class TUnuranContDist : public TUnuranBaseDist {
0049
0050 public:
0051
0052
0053    /**
0054       Constructor from a TF1 objects specifying the pdf and optionally from another function
0055       representing the derivative of the pdf. The flag isLogPdf can be used to pass instead of the pdf
0056       (and its derivative) the log (and the derivative of the log) of the pdf.
0057       By default the distribution has not domain set (it is defined between [-inf,+inf], no mode, no pdf area and no
0058       cdf explicitly defined. UnuRan, if needed, can compute some of this quantities, but the user if they know them can
0059       set them in order to speed up the algorithm. For example in case of the Cdf, if the user has not set it, a numerical
0060       integration algorithm is used to estimate the Cdf from the Pdf.
0061    */
0062    explicit TUnuranContDist (TF1 * pdf = nullptr, TF1 * deriv = nullptr, bool isLogPdf = false );
0063    /**
0064       Constructor as above but with the possibility to pass also the Cdf.
0065        In case an algorithm requiring only the Cdf (no Pdf), one can use this constructor passing nullptr for Pdf and derivative of
0066        the Pdf
0067    */
0068    TUnuranContDist (TF1 * pdf, TF1 * deriv, TF1 * cdf, bool isLogPdf = false );
0069    /**
0070       Constructor as before but from a generic function object interface for one-dim functions
0071    */
0072    explicit TUnuranContDist (const ROOT::Math::IGenFunction & pdf, const ROOT::Math::IGenFunction * dpdf = nullptr, bool isLogPdf = false, bool copyFunc = false);
0073    /**
0074       Constructor as before from pointers to generic function object interface for one-dim functions
0075       which can be use for all algorithms including those requiring only the Cdf
0076     */
0077    TUnuranContDist (const ROOT::Math::IGenFunction * pdf, const ROOT::Math::IGenFunction * dpdf,
0078    const ROOT::Math::IGenFunction * cdf, bool isLogPdf = false, bool copyFunc = false );
0079
0080    /**
0081       Destructor
0082    */
0083    ~TUnuranContDist () override;
0084
0085
0086    /**
0087       Copy constructor
0088    */
0089    TUnuranContDist(const TUnuranContDist &);
0090
0091    /**
0092       Assignment operator
0093    */
0094    TUnuranContDist & operator = (const TUnuranContDist & rhs);
0095
0096    /**
0097       Clone (required by base class)
0098     */
0099    TUnuranContDist * Clone() const override { return new TUnuranContDist(*this); }
0100
0101
0102    /**
0103       set cdf distribution. If a method requires it
0104       and is not set it is then estimated using numerical
0105       integration from the pdf
0106    */
0107    void SetCdf(TF1 *  cdf);
0108
0109    /**
0110       set cdf distribution using a generic function interface
0111    */
0112    void SetCdf(const ROOT::Math::IGenFunction & cdf);
0113
0114    /**
0115       Set the distribution domain. If min < max a domain is defined otherwise is undefined
0116     */
0117    void SetDomain(double xmin, double xmax)  {
0118       fXmin = xmin;
0119       fXmax = xmax;
0120       if (fXmin < fXmax)
0121          fHasDomain = true;
0122       else
0123          fHasDomain = false;
0124    }
0125
0126    /**
0127       set the distribution mode (x position of its maximum)
0128    */
0129    void SetMode(double mode) { fMode = mode; fHasMode=true;}
0130
0131    /**
0132       set the area below the pdf
0133     */
0134    void SetPdfArea(double area) { fArea = area; fHasArea=true;}
0135
0136    /**
0137       check if distribution has a defined domain and return in case its domain
0138    */
0139    bool GetDomain(double & xmin, double & xmax) const {
0140       xmin = fXmin;
0141       xmax = fXmax;
0142       return fHasDomain;
0143    }
0144
0145    /**
0146       check if a cdf function is provided for the distribution
0147     */
0148    bool HasCdf() const { return fCdf != nullptr; }
0149
0150    /**
0151       check if distribution has a pre-computed mode
0152     */
0153    bool HasMode() const { return fHasMode; }
0154
0155
0156    /**
0157       check if distribution has a pre-computed area below the Pdf
0158     */
0159    bool HasPdfArea() const { return fHasArea; }
0160
0161    /**
0162       return the mode   (x location of  maximum of the pdf)
0163    */
0164    double Mode() const { return fMode; }
0165
0166    /**
0167       return area below the pdf
0168    */
0169    double PdfArea() const { return fArea; }
0170
0171
0172    /**
0173       flag to control if given function represent the log of a pdf
0174    */
0175    bool IsLogPdf() const {  return fIsLogPdf; }
0176
0177    /**
0178       evaluate the Probability Density function. Used by the UnuRan algorithms
0179    */
0180    double Pdf ( double x) const;
0181
0182    /**
0183       evaluate the derivative of the pdf. Used by  UnuRan
0184    */
0185    double DPdf( double x) const;
0186
0187    /**
0188       evaluate the integral (cdf)  on the domain. Used by Unuran algorithm
0189    */
0190    double Cdf(double x) const;
0191
0192
0193 protected:
0194
0195
0196 private:
0197
0198
0199    const ROOT::Math::IGenFunction * fPdf;       ///< pointer to the pdf
0200    const ROOT::Math::IGenFunction * fDPdf;      ///< pointer to the derivative of the pdf
0201    const ROOT::Math::IGenFunction * fCdf;       ///< pointer to the cdf (cumulative dist.)
0202
0203    double fXmin;            ///< lower value of the domain
0204    double fXmax;            ///< upper value of the domain
0205    double fMode;            ///< mode of the distribution
0206    double fArea;            ///< area below pdf
0207
0208    // flags
0209    bool  fIsLogPdf;         ///< flag to control if function pointer represent log of pdf
0210    bool  fHasDomain;        ///< flag to control if distribution has a defined domain (otherwise is [-inf,+inf]
0211    bool  fHasMode;          ///< flag to control if distribution has a pre-computed mode
0212    bool  fHasArea;          ///< flag to control if distribution has a pre-computed area below the pdf
0213    bool  fOwnFunc;          ///< flag to indicate if class manages the function pointers
0214    //mutable double fX[1];  ///<! cached vector for using TF1::EvalPar
0215
0216    ClassDefOverride(TUnuranContDist,1)  //Wrapper class for one dimensional continuous distribution
0217
0218
0219 };
0220
0221
0222
0223 #endif /* ROOT_Math_TUnuranContDist */