Logo ROOT  
Reference Guide
TUnuran.h
Go to the documentation of this file.
1 // @(#)root/unuran:$Id$
2 // Author: L. Moneta Tue Sep 26 16:25:09 2006
3 
4 /**********************************************************************
5  * *
6  * Copyright (c) 2006 LCG ROOT Math Team, CERN/PH-SFT *
7  * *
8  * *
9  **********************************************************************/
10 
11 // Header file for class TUnuran
12 
13 #ifndef ROOT_TUnuran
14 #define ROOT_TUnuran
15 
16 #include <string>
17 
18 #include "TUnuranBaseDist.h"
19 
20 
21 class TUnuranContDist;
22 class TUnuranDiscrDist;
24 class TUnuranEmpDist;
25 
26 #include <memory>
27 
28 
29 /**
30 
31  \class TUnuran
32  \ingroup Unuran
33 
34  TUnuran class.
35  Interface to the UNU.RAN package for generating non uniform random
36  numbers. This class wraps the UNU.RAN calls in C++ methods.
37  It provides methods for initializing Unuran and then to sample the
38  desired distribution.
39  It provides support for initializing UNU.RAN in these following way (various signatures
40  for TUnuran::Init)
41  - with string API via TUnuran::Init passing the distribution type and the method
42  - using a one-dimensional distribution object defined by TUnuranContDist
43  - using a multi-dimensional distribution object defined by TUnuranMultiContDist
44  - using a discrete one-dimensional distribution object defined by TUnuranDiscrDist
45  - using an empirical distribution defined by TUnuranEmpDist
46  - using pre-defined distributions. Presently only support for Poisson (TUnuran::InitPoisson)
47  and Binomial (TUnuran::InitBinomial) are provided. Other distributions can however be generated
48  using the previous methods (in particular via the string API)
49 
50  The sampling is provided via these methods:
51  - TUnuran::Sample() returns a double for all one-dimensional distribution
52  - TUnuran::SampleDiscr() returns an integer for one-dimensional discrete distribution
53  - TUnuran::Sample(double *) sample a multi-dimensional distribution. A pointer to a vector with
54  size at least equal to the distribution dimension must be passed
55 
56  In addition is possible to set the random number generator in the constructor of the class, its seed
57  via the TUnuran::SetSeed() method.
58 */
59 
60 
61 
62 //class TUnuranGenerator;
63 struct unur_gen;
64 typedef struct unur_gen UNUR_GEN;
65 
66 // struct unur_urng_generic;
67 // typedef struct unur_urng_generic UNUR_URNG;
68 
69 struct unur_distr;
70 typedef struct unur_distr UNUR_DISTR;
71 
72 struct unur_urng;
73 typedef struct unur_urng UNUR_URNG;
74 
75 
76 class TRandom;
77 class TH1;
78 
79 class TUnuran {
80 
81 public:
82 
83  /**
84  Constructor with a generator instance and given level of log output
85  */
86  TUnuran (TRandom * r = 0, unsigned int log = 0);
87 
88 
89  /**
90  Destructor
91  */
92  ~TUnuran ();
93 
94 private:
95  // usually copying is non trivial, so we make this unaccessible
96 
97  /**
98  Copy constructor
99  */
100  TUnuran(const TUnuran &);
101 
102  /**
103  Assignment operator
104  */
105  TUnuran & operator = (const TUnuran & rhs);
106 
107 public:
108 
109 
110  /**
111  initialize with Unuran string interface
112  */
113  bool Init(const std::string & distr, const std::string & method);
114 
115 
116  /**
117  Initialize method for continuous one-dimensional distribution.
118  User must provide a distribution object (which is copied inside) and a string for a method.
119  For the list of available method for 1D cont. distribution see the
120  <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fCONT">UnuRan doc</A>.
121  A re-initialization is needed whenever distribution parameters have been changed.
122  */
123  bool Init(const TUnuranContDist & distr, const std::string & method = "auto");
124 
125  /**
126  Initialize method for continuous multi-dimensional distribution.
127  User must provide a distribution object (which is copied inside) and a string for a method.
128  For the list of available method for multivariate cont. distribution see the
129  <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fCVEC">UnuRan doc</A>
130  A re-initialization is needed whenever distribution parameters have been changed.
131 
132  */
133  bool Init(const TUnuranMultiContDist & distr, const std::string & method = "hitro");
134 
135 
136  /**
137  Initialize method for continuous one-dimensional discrete distribution.
138  User must provide a distribution object (which is copied inside) and a string for a method.
139  For the list of available method for 1D discrete distribution see the
140  <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fDISCR">UnuRan doc</A>
141  A re-initialization is needed whenever distribution parameters have been changed.
142 
143  */
144  bool Init(const TUnuranDiscrDist & distr, const std::string & method = "auto");
145 
146 
147  /**
148  Initialize method for continuous empirical distribution.
149  User must provide a distribution object (which is copied inside) and a string for a method.
150  The distribution object can represent binned (only 1D) or unbinned (1D or multi-dim) data
151  The method for the unbinned empirical distribution are based on the kernel smoothing, see
152  <A href="http://statmath.wu-wien.ac.at/software/unuran/doc/unuran.html#EMPK">UnuRan doc</A>
153  A re-initialization is needed whenever distribution parameters have been changed.
154 
155  */
156  bool Init(const TUnuranEmpDist & distr, const std::string & method = "empk");
157 
158 
159  /**
160  Initialize method for the Poisson distribution
161  Used to generate poisson numbers for a constant parameter mu of the Poisson distribution.
162  Use after the method TUnuran::SampleDiscr to generate the numbers.
163  The flag reinit perform a fast re-initialization when only the distribution parameters
164  are changed in the subsequent calls.
165  If the same TUnuran object is used to generate with other distributions it cannot be used.
166  */
167  bool InitPoisson(double mu, const std::string & method = "dstd");
168 
169  /**
170  Initialize method for the Binomial distribution
171  Used to generate poisson numbers for a constant parameters (n,p) of the Binomial distribution.
172  Use after the method TUnuran::SampleDiscr to generate the numbers.
173  The flag reinit perform a fast re-initialization when only the distribution parameters
174  are changed in the subsequent calls.
175  If the same TUnuran object is used to generate with other distributions it cannot be used.
176  */
177  bool InitBinomial(unsigned int ntot, double prob, const std::string & method = "dstd");
178 
179  /**
180  Reinitialize UNURAN by changing the distribution parameters but mantaining same distribution and method
181  It is implemented now only for predefined discrete distributions like the poisson or the binomial
182  */
183  bool ReInitDiscrDist(unsigned int npar, double * params);
184 
185  /**
186  Sample 1D distribution
187  User is responsible for having previously correctly initialized with TUnuran::Init
188  */
189  double Sample();
190 
191  /**
192  Sample multidimensional distributions
193  User is responsible for having previously correctly initialized with TUnuran::Init
194  */
195  bool SampleMulti(double * x);
196 
197  /**
198  Sample discrete distributions
199  User is responsible for having previously correctly initialized with TUnuran::Init
200  */
201  int SampleDiscr();
202 
203  /**
204  set the random engine.
205  Must be called before init to have effect
206  */
207  void SetRandom(TRandom * r) {
208  fRng = r;
209  }
210 
211  /**
212  return instance of the random engine used
213  */
215  return fRng;
216  }
217 
218 
219  /**
220  set the seed for the random number generator
221  */
222  void SetSeed(unsigned int seed);
223 
224  /**
225  set log level
226  */
227  bool SetLogLevel(unsigned int iflag = 1);
228 
229  /**
230  set stream for log and error (not yet implemented)
231  */
232  bool SetLogStream() { return false;}
233 
234  /**
235  used Unuran method
236  */
237  const std::string & MethodName() const { return fMethod; }
238 
239 protected:
240 
241 
242  bool SetRandomGenerator();
243 
245 
247 
249 
251 
252  /**
253  change the method and initialize Unuran with the previously given distribution
254  */
255  bool SetMethodAndInit();
256 
257 
258 
259 // private:
260 
261  UNUR_GEN * fGen; //pointer to the UnuRan C generator struct
262  UNUR_DISTR * fUdistr; //pointer to the UnuRan C distribution struct
263  UNUR_URNG * fUrng; // pointer to Unuran C random generator struct
264  std::unique_ptr<TUnuranBaseDist> fDist; // pointer for distribution wrapper
265  TRandom * fRng; //pointer to ROOT random number generator
266  std::string fMethod; //string representing the method
267 
268 };
269 
270 
271 #endif /* ROOT_Math_TUnuran */
TUnuran::TUnuran
TUnuran(TRandom *r=0, unsigned int log=0)
Constructor with a generator instance and given level of log output.
Definition: TUnuran.cxx:32
TUnuran::fGen
UNUR_GEN * fGen
Definition: TUnuran.h:261
TUnuran::SetLogStream
bool SetLogStream()
set stream for log and error (not yet implemented)
Definition: TUnuran.h:232
TUnuran::SetMultiDistribution
bool SetMultiDistribution(const TUnuranMultiContDist &dist)
Definition: TUnuran.cxx:215
r
ROOT::R::TRInterface & r
Definition: Object.C:4
TUnuran::SetSeed
void SetSeed(unsigned int seed)
set the seed for the random number generator
Definition: TUnuran.cxx:400
TUnuran::SampleDiscr
int SampleDiscr()
Sample discrete distributions User is responsible for having previously correctly initialized with TU...
Definition: TUnuran.cxx:378
TUnuran::~TUnuran
~TUnuran()
Destructor.
Definition: TUnuran.cxx:53
TUnuran::SetDiscreteDistribution
bool SetDiscreteDistribution(const TUnuranDiscrDist &dist)
Definition: TUnuran.cxx:300
log
double log(double)
UNUR_GEN
struct unur_gen UNUR_GEN
Definition: TUnuran.h:64
x
Double_t x[n]
Definition: legend1.C:17
TUnuran::GetRandom
TRandom * GetRandom()
return instance of the random engine used
Definition: TUnuran.h:214
TUnuran::SetLogLevel
bool SetLogLevel(unsigned int iflag=1)
set log level
Definition: TUnuran.cxx:404
TUnuranBaseDist.h
TUnuran::fUdistr
UNUR_DISTR * fUdistr
Definition: TUnuran.h:262
TUnuran::InitPoisson
bool InitPoisson(double mu, const std::string &method="dstd")
Initialize method for the Poisson distribution Used to generate poisson numbers for a constant parame...
Definition: TUnuran.cxx:419
ROOT::Math::gv_detail::dist
double dist(Rotation3D const &r1, Rotation3D const &r2)
Definition: 3DDistances.cxx:63
TUnuran::SetRandomGenerator
bool SetRandomGenerator()
Definition: TUnuran.cxx:152
TUnuran::fRng
TRandom * fRng
Definition: TUnuran.h:265
TRandom
Definition: TRandom.h:27
TUnuranContDist
Definition: TUnuranContDist.h:48
UNUR_URNG
struct unur_urng UNUR_URNG
Definition: TUnuran.h:73
TUnuran::Init
bool Init(const std::string &distr, const std::string &method)
initialize with Unuran string interface
Definition: TUnuran.cxx:75
TUnuran::fUrng
UNUR_URNG * fUrng
Definition: TUnuran.h:263
TUnuranMultiContDist
TUnuranMultiContDist class describing multi dimensional continuous distributions.
Definition: TUnuranMultiContDist.h:47
TUnuran::operator=
TUnuran & operator=(const TUnuran &rhs)
Assignment operator.
Definition: TUnuran.cxx:68
TUnuran::InitBinomial
bool InitBinomial(unsigned int ntot, double prob, const std::string &method="dstd")
Initialize method for the Binomial distribution Used to generate poisson numbers for a constant param...
Definition: TUnuran.cxx:434
TUnuran::ReInitDiscrDist
bool ReInitDiscrDist(unsigned int npar, double *params)
Reinitialize UNURAN by changing the distribution parameters but mantaining same distribution and meth...
Definition: TUnuran.cxx:449
TUnuran::MethodName
const std::string & MethodName() const
used Unuran method
Definition: TUnuran.h:237
TUnuran::SampleMulti
bool SampleMulti(double *x)
Sample multidimensional distributions User is responsible for having previously correctly initialized...
Definition: TUnuran.cxx:392
TUnuran::SetMethodAndInit
bool SetMethodAndInit()
change the method and initialize Unuran with the previously given distribution
Definition: TUnuran.cxx:347
TUnuran::SetContDistribution
bool SetContDistribution(const TUnuranContDist &dist)
Definition: TUnuran.cxx:169
TUnuranDiscrDist
TUnuranDiscrDist class for one dimensional discrete distribution.
Definition: TUnuranDiscrDist.h:51
TH1
Definition: TH1.h:57
TUnuran::SetRandom
void SetRandom(TRandom *r)
set the random engine.
Definition: TUnuran.h:207
TUnuran::SetEmpiricalDistribution
bool SetEmpiricalDistribution(const TUnuranEmpDist &dist)
Definition: TUnuran.cxx:259
UNUR_DISTR
struct unur_distr UNUR_DISTR
Definition: TUnuran.h:70
TUnuran::fMethod
std::string fMethod
Definition: TUnuran.h:266
TUnuran
Definition: TUnuran.h:79
TUnuranEmpDist
Definition: TUnuranEmpDist.h:49
TUnuran::Sample
double Sample()
Sample 1D distribution User is responsible for having previously correctly initialized with TUnuran::...
Definition: TUnuran.cxx:385
TUnuran::fDist
std::unique_ptr< TUnuranBaseDist > fDist
Definition: TUnuran.h:264