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