Logo ROOT   6.10/09
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 
246  bool SetMultiDistribution(const TUnuranMultiContDist & dist );
247 
248  bool SetDiscreteDistribution(const TUnuranDiscrDist & dist );
249 
250  bool SetEmpiricalDistribution(const TUnuranEmpDist & dist );
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 */
TRandom * GetRandom()
return instance of the random engine used
Definition: TUnuran.h:214
UNUR_URNG * fUrng
Definition: TUnuran.h:263
double dist(Rotation3D const &r1, Rotation3D const &r2)
Definition: 3DDistances.cxx:48
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:438
double Sample()
Sample 1D distribution User is responsible for having previously correctly initialized with TUnuran::...
Definition: TUnuran.cxx:389
bool ReInitDiscrDist(unsigned int npar, double *params)
Reinitialize UNURAN by changing the distribution parameters but mantaining same distribution and meth...
Definition: TUnuran.cxx:453
TUnuran & operator=(const TUnuran &rhs)
Assignment operator.
Definition: TUnuran.cxx:72
int SampleDiscr()
Sample discrete distributions User is responsible for having previously correctly initialized with TU...
Definition: TUnuran.cxx:382
bool SampleMulti(double *x)
Sample multidimensional distributions User is responsible for having previously correctly initialized...
Definition: TUnuran.cxx:396
bool SetLogLevel(unsigned int iflag=1)
set log level
Definition: TUnuran.cxx:408
Double_t x[n]
Definition: legend1.C:17
This is the base class for the ROOT Random number generators.
Definition: TRandom.h:27
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:423
void SetSeed(unsigned int seed)
set the seed for the random number generator
Definition: TUnuran.cxx:404
TRandom * fRng
Definition: TUnuran.h:265
TUnuranDiscrDist class for one dimensional discrete distribution.
bool SetMultiDistribution(const TUnuranMultiContDist &dist)
Definition: TUnuran.cxx:219
struct unur_gen UNUR_GEN
Definition: TUnuran.h:64
TUnuranEmpDist class for describing empiral distributions.
bool SetLogStream()
set stream for log and error (not yet implemented)
Definition: TUnuran.h:232
bool SetContDistribution(const TUnuranContDist &dist)
Definition: TUnuran.cxx:173
~TUnuran()
Destructor.
Definition: TUnuran.cxx:57
TRandom2 r(17)
struct unur_urng UNUR_URNG
Definition: TUnuran.h:73
TUnuranMultiContDist class describing multi dimensional continuous distributions. ...
std::string fMethod
Definition: TUnuran.h:266
TUnuran(TRandom *r=0, unsigned int log=0)
Constructor with a generator instance and given level of log output.
Definition: TUnuran.cxx:36
bool SetMethodAndInit()
change the method and initialize Unuran with the previously given distribution
Definition: TUnuran.cxx:351
TUnuran class.
Definition: TUnuran.h:79
bool SetDiscreteDistribution(const TUnuranDiscrDist &dist)
Definition: TUnuran.cxx:304
The TH1 histogram class.
Definition: TH1.h:56
UNUR_GEN * fGen
Definition: TUnuran.h:261
bool SetRandomGenerator()
Definition: TUnuran.cxx:156
const std::string & MethodName() const
used Unuran method
Definition: TUnuran.h:237
UNUR_DISTR * fUdistr
Definition: TUnuran.h:262
TUnuranContDist class describing one dimensional continuous distribution.
bool Init(const std::string &distr, const std::string &method)
initialize with Unuran string interface
Definition: TUnuran.cxx:79
struct unur_distr UNUR_DISTR
Definition: TUnuran.h:70
std::unique_ptr< TUnuranBaseDist > fDist
Definition: TUnuran.h:264
bool SetEmpiricalDistribution(const TUnuranEmpDist &dist)
Definition: TUnuran.cxx:263
void SetRandom(TRandom *r)
set the random engine.
Definition: TUnuran.h:207
double log(double)