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
21class TUnuranContDist;
24class 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;
63struct unur_gen;
64typedef struct unur_gen UNUR_GEN;
65
66// struct unur_urng_generic;
67// typedef struct unur_urng_generic UNUR_URNG;
68
69struct unur_distr;
70typedef struct unur_distr UNUR_DISTR;
71
72struct unur_urng;
73typedef struct unur_urng UNUR_URNG;
74
75
76class TRandom;
77class TH1;
78
79class TUnuran {
80
81public:
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
94private:
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
107public:
108 /**
109 Initialize with Unuran string API interface.
110 See https://statmath.wu.ac.at/unuran/doc/unuran.html#StringAPI
111
112 @param distr : UNU.RAN distribution string
113 @param method : UNU.RAN method string
114
115 Here is an example using the string API:
116 ```
117 Tunuran unr;
118 unr.Init("normal(3.,0.75); domain = (0,inf)", "method = tdr; c = 0");
119 ```
120 */
121 bool Init(const std::string & distr, const std::string & method);
122
123
124 /**
125 Initialize method for continuous one-dimensional distribution.
126 User must provide a distribution object (which is copied inside) and a string for a method.
127 For the list of available method for 1D cont. distribution see the
128 <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fCONT">UnuRan doc</A>.
129 A re-initialization is needed whenever distribution parameters have been changed.
130 Note that the method string can contain in addition to the method name all the specific method
131 parameters specified using the UNURAN method string API.
132 For example a valid string can be `"method=arou; max_segments=1000; max_sqhratio = 0.9"`
133 */
134 bool Init(const TUnuranContDist & distr, const std::string & method = "auto");
135
136 /**
137 Initialize method for continuous multi-dimensional 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 multivariate cont. distribution see the
140 <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fCVEC">UnuRan doc</A>
141 A re-initialization is needed whenever distribution parameters have been changed.
142
143 */
144 bool Init(const TUnuranMultiContDist & distr, const std::string & method = "hitro");
145
146
147 /**
148 Initialize method for continuous one-dimensional discrete distribution.
149 User must provide a distribution object (which is copied inside) and a string for a method.
150 For the list of available method for 1D discrete distribution see the
151 <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fDISCR">UnuRan doc</A>
152 A re-initialization is needed whenever distribution parameters have been changed.
153
154 */
155 bool Init(const TUnuranDiscrDist & distr, const std::string & method = "auto");
156
157
158 /**
159 Initialize method for continuous empirical distribution.
160 User must provide a distribution object (which is copied inside) and a string for a method.
161 The distribution object can represent binned (only 1D) or unbinned (1D or multi-dim) data
162 The method for the unbinned empirical distribution are based on the kernel smoothing, see
163 <A href="http://statmath.wu-wien.ac.at/software/unuran/doc/unuran.html#EMPK">UnuRan doc</A>
164 A re-initialization is needed whenever distribution parameters have been changed.
165
166 */
167 bool Init(const TUnuranEmpDist & distr, const std::string & method = "empk");
168
169
170 /**
171 Initialize method for the Poisson distribution.
172 Used to generate poisson numbers for a constant parameter mu of the Poisson distribution.
173 Use after the method TUnuran::SampleDiscr to generate the numbers.
174 The flag reinit perform a fast re-initialization when only the distribution parameters
175 are changed in the subsequent calls.
176 If the same TUnuran object is used to generate with other distributions it cannot be used.
177 */
178 bool InitPoisson(double mu, const std::string & method = "dstd");
179
180 /**
181 Initialize method for the Binomial distribution.
182 Used to generate poisson numbers for a constant parameters (n,p) of the Binomial distribution.
183 Use after the method TUnuran::SampleDiscr to generate the numbers.
184 The flag reinit perform a fast re-initialization when only the distribution parameters
185 are changed in the subsequent calls.
186 If the same TUnuran object is used to generate with other distributions it cannot be used.
187 */
188 bool InitBinomial(unsigned int ntot, double prob, const std::string & method = "dstd");
189
190 /**
191 Reinitialize UNURAN by changing the distribution parameters but mantaining same distribution and method.
192 It is implemented now only for predefined discrete distributions like the poisson or the binomial
193 */
194 bool ReInitDiscrDist(unsigned int npar, double * params);
195
196 /**
197 Sample 1D distribution.
198 User is responsible for having previously correctly initialized with TUnuran::Init
199 */
200 double Sample();
201
202 /**
203 Sample multidimensional distributions.
204 User is responsible for having previously correctly initialized with TUnuran::Init
205 */
206 bool SampleMulti(double * x);
207
208 /**
209 Sample discrete distributions.
210 User is responsible for having previously correctly initialized with TUnuran::Init
211 */
212 int SampleDiscr();
213
214 /**
215 Set the random engine.
216 Must be called before init to have effect
217 */
219 fRng = r;
220 }
221
222 /**
223 Return instance of the random engine used.
224 */
226 return fRng;
227 }
228
229 /**
230 Return an information string about the used Unuran generator method.
231 @param extended : if true return some helper information about the existing options of the method.
232 */
233 std::string GetInfo(bool extended = false);
234
235 /**
236 Return an ID string about the unuran generator method.
237 */
238 std::string GetGenId() const;
239
240 /**
241 Return the dimension of unuran generator method.
242 For 1D method returns 1 and for the multi-dimensional case
243 must be equal to the distribution dimension.
244 */
245 int GetDimension() const;
246
247 /**
248 Return the type of the distribution.
249 See documentation of `unuran_distr_get_type` for the possible
250 types of distributions.
251 */
252 int GetDistType() const;
253
254 /// Return true for a univariate continous distribution.
255 bool IsDistCont() const;
256 /// Return true for a multivariate continous distribution.
257 bool IsDistMultiCont() const;
258 /// Return true for a discrete distribution.
259 bool IsDistDiscrete() const;
260 /// Return true for an empirical distribution.
261 bool IsDistEmpirical() const;
262
263
264
265 /**
266 set the seed for the random number generator
267 */
268 void SetSeed(unsigned int seed);
269
270 /**
271 set log level
272 */
273 bool SetLogLevel(unsigned int iflag = 1);
274
275 /**
276 set stream for log and error (not yet implemented)
277 */
278 bool SetLogStream() { return false;}
279
280 /**
281 used Unuran method
282 */
283 const std::string & MethodName() const { return fMethod; }
284
285protected:
286
287
288 bool SetRandomGenerator();
289
291
293
295
297
298 /**
299 change the method and initialize Unuran with the previously given distribution
300 */
301 bool SetMethodAndInit();
302
303
304
305// private:
306
307 UNUR_GEN * fGen; //pointer to the UnuRan C generator struct
308 UNUR_DISTR * fUdistr; //pointer to the UnuRan C distribution struct
309 UNUR_URNG * fUrng; // pointer to Unuran C random generator struct
310 std::unique_ptr<TUnuranBaseDist> fDist; // pointer for distribution wrapper
311 TRandom * fRng; //pointer to ROOT random number generator
312 std::string fMethod; //string representing the method
313
314};
315
316
317#endif /* ROOT_Math_TUnuran */
ROOT::R::TRInterface & r
Definition: Object.C:4
double log(double)
struct unur_urng UNUR_URNG
Definition: TUnuran.h:73
struct unur_gen UNUR_GEN
Definition: TUnuran.h:64
struct unur_distr UNUR_DISTR
Definition: TUnuran.h:70
TH1 is the base class of all histogram classes in ROOT.
Definition: TH1.h:58
This is the base class for the ROOT Random number generators.
Definition: TRandom.h:27
TUnuranContDist class describing one dimensional continuous distribution.
TUnuranDiscrDist class for one dimensional discrete distribution.
TUnuranEmpDist class for describing empiral distributions.
TUnuranMultiContDist class describing multi dimensional continuous distributions.
TUnuran class.
Definition: TUnuran.h:79
std::string GetGenId() const
Return an ID string about the unuran generator method.
Definition: TUnuran.cxx:384
bool IsDistCont() const
Return true for a univariate continous distribution.
Definition: TUnuran.cxx:405
TUnuran(TRandom *r=0, unsigned int log=0)
Constructor with a generator instance and given level of log output.
Definition: TUnuran.cxx:32
bool SetMethodAndInit()
change the method and initialize Unuran with the previously given distribution
Definition: TUnuran.cxx:347
int SampleDiscr()
Sample discrete distributions.
Definition: TUnuran.cxx:422
bool SetLogStream()
set stream for log and error (not yet implemented)
Definition: TUnuran.h:278
const std::string & MethodName() const
used Unuran method
Definition: TUnuran.h:283
std::unique_ptr< TUnuranBaseDist > fDist
Definition: TUnuran.h:310
bool SetDiscreteDistribution(const TUnuranDiscrDist &dist)
Definition: TUnuran.cxx:300
int GetDistType() const
Return the type of the distribution.
Definition: TUnuran.cxx:398
bool InitBinomial(unsigned int ntot, double prob, const std::string &method="dstd")
Initialize method for the Binomial distribution.
Definition: TUnuran.cxx:477
bool SetContDistribution(const TUnuranContDist &dist)
Definition: TUnuran.cxx:169
std::string GetInfo(bool extended=false)
Return an information string about the used Unuran generator method.
Definition: TUnuran.cxx:377
bool SampleMulti(double *x)
Sample multidimensional distributions.
Definition: TUnuran.cxx:436
bool ReInitDiscrDist(unsigned int npar, double *params)
Reinitialize UNURAN by changing the distribution parameters but mantaining same distribution and meth...
Definition: TUnuran.cxx:492
bool IsDistMultiCont() const
Return true for a multivariate continous distribution.
Definition: TUnuran.cxx:409
UNUR_DISTR * fUdistr
Definition: TUnuran.h:308
bool Init(const std::string &distr, const std::string &method)
Initialize with Unuran string API interface.
Definition: TUnuran.cxx:75
UNUR_GEN * fGen
Definition: TUnuran.h:307
bool SetRandomGenerator()
Definition: TUnuran.cxx:152
bool SetLogLevel(unsigned int iflag=1)
set log level
Definition: TUnuran.cxx:448
UNUR_URNG * fUrng
Definition: TUnuran.h:309
TRandom * fRng
Definition: TUnuran.h:311
bool SetMultiDistribution(const TUnuranMultiContDist &dist)
Definition: TUnuran.cxx:215
bool IsDistEmpirical() const
Return true for an empirical distribution.
Definition: TUnuran.cxx:417
double Sample()
Sample 1D distribution.
Definition: TUnuran.cxx:429
bool SetEmpiricalDistribution(const TUnuranEmpDist &dist)
Definition: TUnuran.cxx:259
TRandom * GetRandom()
Return instance of the random engine used.
Definition: TUnuran.h:225
~TUnuran()
Destructor.
Definition: TUnuran.cxx:53
bool InitPoisson(double mu, const std::string &method="dstd")
Initialize method for the Poisson distribution.
Definition: TUnuran.cxx:463
std::string fMethod
Definition: TUnuran.h:312
TUnuran & operator=(const TUnuran &rhs)
Assignment operator.
Definition: TUnuran.cxx:68
int GetDimension() const
Return the dimension of unuran generator method.
Definition: TUnuran.cxx:391
void SetSeed(unsigned int seed)
set the seed for the random number generator
Definition: TUnuran.cxx:444
void SetRandom(TRandom *r)
Set the random engine.
Definition: TUnuran.h:218
bool IsDistDiscrete() const
Return true for a discrete distribution.
Definition: TUnuran.cxx:413
Double_t x[n]
Definition: legend1.C:17
double dist(Rotation3D const &r1, Rotation3D const &r2)
Definition: 3DDistances.cxx:48