Logo ROOT  
Reference Guide
 
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Modules Pages
Loading...
Searching...
No Matches
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 = nullptr, unsigned int log = 0);
87
88
89 /**
90 Destructor
91 */
92 ~TUnuran ();
93
94 // usually copying is non trivial, so we delete this
95 TUnuran(const TUnuran &) = delete;
96 TUnuran & operator = (const TUnuran & rhs) = delete;
97 TUnuran(TUnuran &&) = delete;
98 TUnuran & operator = (TUnuran && rhs) = delete;
99
100 /**
101 Initialize with Unuran string API interface.
102 See https://statmath.wu.ac.at/unuran/doc/unuran.html#StringAPI
103
104 @param distr : UNU.RAN distribution string
105 @param method : UNU.RAN method string
106
107 Here is an example using the string API:
108 ```
109 Tunuran unr;
110 unr.Init("normal(3.,0.75); domain = (0,inf)", "method = tdr; c = 0");
111 ```
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 Note that the method string can contain in addition to the method name all the specific method
123 parameters specified using the UNURAN method string API.
124 For example a valid string can be `"method=arou; max_segments=1000; max_sqhratio = 0.9"`
125 */
126 bool Init(const TUnuranContDist & distr, const std::string & method = "auto");
127
128 /**
129 Initialize method for continuous multi-dimensional distribution.
130 User must provide a distribution object (which is copied inside) and a string for a method.
131 For the list of available method for multivariate cont. distribution see the
132 <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fCVEC">UnuRan doc</A>
133 A re-initialization is needed whenever distribution parameters have been changed.
134
135 The default method used for multi-dimensional distributions is "vnrou"
136 Note that some of the multi-dimensional continuous distribution methods like "hitro" are based on Markov-CHain sampler and
137 they are much faster for sampling but require more time to converge. Furthermore, since they are Markov-Chain methods their
138 generated sample values are correlated and cannot be used as i.i.d., one can instead use the obtained sample distribution.
139 (see also the ROOT issue: #10222 ).
140
141 */
142 bool Init(const TUnuranMultiContDist & distr, const std::string & method = "vnrou");
143
144
145 /**
146 Initialize method for continuous one-dimensional discrete distribution.
147 User must provide a distribution object (which is copied inside) and a string for a method.
148 For the list of available method for 1D discrete distribution see the
149 <A href="http://statmath.wu-wien.ac.at/unuran/doc/unuran.html#Methods_005ffor_005fDISCR">UnuRan doc</A>
150 A re-initialization is needed whenever distribution parameters have been changed.
151
152 */
153 bool Init(const TUnuranDiscrDist & distr, const std::string & method = "auto");
154
155
156 /**
157 Initialize method for continuous empirical distribution.
158 User must provide a distribution object (which is copied inside) and a string for a method.
159 The distribution object can represent binned (only 1D) or unbinned (1D or multi-dim) data
160 The method for the unbinned empirical distribution are based on the kernel smoothing, see
161 <A href="http://statmath.wu-wien.ac.at/software/unuran/doc/unuran.html#EMPK">UnuRan doc</A>
162 A re-initialization is needed whenever distribution parameters have been changed.
163
164 */
165 bool Init(const TUnuranEmpDist & distr, const std::string & method = "empk");
166
167
168 /**
169 Initialize method for the Poisson distribution.
170 Used to generate poisson numbers for a constant parameter mu of the Poisson distribution.
171 Use after the method TUnuran::SampleDiscr to generate the numbers.
172 The flag reinit perform a fast re-initialization when only the distribution parameters
173 are changed in the subsequent calls.
174 If the same TUnuran object is used to generate with other distributions it cannot be used.
175 */
176 bool InitPoisson(double mu, const std::string & method = "dstd");
177
178 /**
179 Initialize method for the Binomial distribution.
180 Used to generate poisson numbers for a constant parameters (n,p) of the Binomial distribution.
181 Use after the method TUnuran::SampleDiscr to generate the numbers.
182 The flag reinit perform a fast re-initialization when only the distribution parameters
183 are changed in the subsequent calls.
184 If the same TUnuran object is used to generate with other distributions it cannot be used.
185 */
186 bool InitBinomial(unsigned int ntot, double prob, const std::string & method = "dstd");
187
188 /**
189 Reinitialize UNURAN by changing the distribution parameters but maintaining same distribution and method.
190 It is implemented now only for predefined discrete distributions like the poisson or the binomial
191 */
192 bool ReInitDiscrDist(unsigned int npar, double * params);
193
194 /**
195 Sample 1D distribution.
196 User is responsible for having previously correctly initialized with TUnuran::Init
197 */
198 double Sample();
199
200 /**
201 Sample multidimensional distributions.
202 User is responsible for having previously correctly initialized with TUnuran::Init
203 */
204 bool SampleMulti(double * x);
205
206 /**
207 Sample discrete distributions.
208 User is responsible for having previously correctly initialized with TUnuran::Init
209 */
210 int SampleDiscr();
211
212 /**
213 Set the random engine.
214 Must be called before init to have effect
215 */
217 fRng = r;
218 }
219
220 /**
221 Return instance of the random engine used.
222 */
224 return fRng;
225 }
226
227 /**
228 Return an information string about the used Unuran generator method.
229 @param extended : if true return some helper information about the existing options of the method.
230 */
231 std::string GetInfo(bool extended = false);
232
233 /**
234 Return an ID string about the unuran generator method.
235 */
236 std::string GetGenId() const;
237
238 /**
239 Return the dimension of unuran generator method.
240 For 1D method returns 1 and for the multi-dimensional case
241 must be equal to the distribution dimension.
242 */
243 int GetDimension() const;
244
245 /**
246 Return the type of the distribution.
247 See documentation of `unuran_distr_get_type` for the possible
248 types of distributions.
249 */
250 int GetDistType() const;
251
252 /// Return true for a univariate continuous distribution.
253 bool IsDistCont() const;
254 /// Return true for a multivariate continuous distribution.
255 bool IsDistMultiCont() const;
256 /// Return true for a discrete distribution.
257 bool IsDistDiscrete() const;
258 /// Return true for an empirical distribution.
259 bool IsDistEmpirical() const;
260
261
262
263 /**
264 set the seed for the random number generator
265 */
266 void SetSeed(unsigned int seed);
267
268 /**
269 set log level
270 */
271 bool SetLogLevel(unsigned int iflag = 1);
272
273 /**
274 set stream for log and error (not yet implemented)
275 */
276 bool SetLogStream() { return false;}
277
278 /**
279 used Unuran method
280 */
281 const std::string & MethodName() const { return fMethod; }
282
283protected:
284
285
286 bool SetRandomGenerator();
287
288 bool SetContDistribution(const TUnuranContDist & dist );
289
290 bool SetMultiDistribution(const TUnuranMultiContDist & dist );
291
292 bool SetDiscreteDistribution(const TUnuranDiscrDist & dist );
293
294 bool SetEmpiricalDistribution(const TUnuranEmpDist & dist );
295
296 /**
297 change the method and initialize Unuran with the previously given distribution
298 */
299 bool SetMethodAndInit();
300
301
302
303// private:
304
305 UNUR_GEN * fGen; //pointer to the UnuRan C generator struct
306 UNUR_DISTR * fUdistr; //pointer to the UnuRan C distribution struct
307 UNUR_URNG * fUrng; // pointer to Unuran C random generator struct
308 std::unique_ptr<TUnuranBaseDist> fDist; // pointer for distribution wrapper
309 TRandom * fRng; //pointer to ROOT random number generator
310 std::string fMethod; //string representing the method
311
312};
313
314
315#endif /* ROOT_Math_TUnuran */
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t r
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:59
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 empirical 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:369
bool IsDistCont() const
Return true for a univariate continuous distribution.
Definition TUnuran.cxx:390
bool SetMethodAndInit()
change the method and initialize Unuran with the previously given distribution
Definition TUnuran.cxx:332
int SampleDiscr()
Sample discrete distributions.
Definition TUnuran.cxx:407
bool SetLogStream()
set stream for log and error (not yet implemented)
Definition TUnuran.h:276
const std::string & MethodName() const
used Unuran method
Definition TUnuran.h:281
TUnuran(TUnuran &&)=delete
std::unique_ptr< TUnuranBaseDist > fDist
Definition TUnuran.h:308
bool SetDiscreteDistribution(const TUnuranDiscrDist &dist)
Definition TUnuran.cxx:287
int GetDistType() const
Return the type of the distribution.
Definition TUnuran.cxx:383
bool InitBinomial(unsigned int ntot, double prob, const std::string &method="dstd")
Initialize method for the Binomial distribution.
Definition TUnuran.cxx:462
bool SetContDistribution(const TUnuranContDist &dist)
Definition TUnuran.cxx:156
std::string GetInfo(bool extended=false)
Return an information string about the used Unuran generator method.
Definition TUnuran.cxx:362
bool SampleMulti(double *x)
Sample multidimensional distributions.
Definition TUnuran.cxx:421
bool ReInitDiscrDist(unsigned int npar, double *params)
Reinitialize UNURAN by changing the distribution parameters but maintaining same distribution and met...
Definition TUnuran.cxx:477
bool IsDistMultiCont() const
Return true for a multivariate continuous distribution.
Definition TUnuran.cxx:394
UNUR_DISTR * fUdistr
Definition TUnuran.h:306
bool Init(const std::string &distr, const std::string &method)
Initialize with Unuran string API interface.
Definition TUnuran.cxx:62
TUnuran & operator=(const TUnuran &rhs)=delete
UNUR_GEN * fGen
Definition TUnuran.h:305
bool SetRandomGenerator()
Definition TUnuran.cxx:139
bool SetLogLevel(unsigned int iflag=1)
set log level
Definition TUnuran.cxx:433
UNUR_URNG * fUrng
Definition TUnuran.h:307
TRandom * fRng
Definition TUnuran.h:309
bool SetMultiDistribution(const TUnuranMultiContDist &dist)
Definition TUnuran.cxx:202
bool IsDistEmpirical() const
Return true for an empirical distribution.
Definition TUnuran.cxx:402
double Sample()
Sample 1D distribution.
Definition TUnuran.cxx:414
bool SetEmpiricalDistribution(const TUnuranEmpDist &dist)
Definition TUnuran.cxx:246
TRandom * GetRandom()
Return instance of the random engine used.
Definition TUnuran.h:223
TUnuran(const TUnuran &)=delete
~TUnuran()
Destructor.
Definition TUnuran.cxx:53
bool InitPoisson(double mu, const std::string &method="dstd")
Initialize method for the Poisson distribution.
Definition TUnuran.cxx:448
std::string fMethod
Definition TUnuran.h:310
int GetDimension() const
Return the dimension of unuran generator method.
Definition TUnuran.cxx:376
void SetSeed(unsigned int seed)
set the seed for the random number generator
Definition TUnuran.cxx:429
void SetRandom(TRandom *r)
Set the random engine.
Definition TUnuran.h:216
bool IsDistDiscrete() const
Return true for a discrete distribution.
Definition TUnuran.cxx:398
Double_t x[n]
Definition legend1.C:17