[29] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
---|
| 2 | |
---|
| 3 | <html> |
---|
| 4 | <head> |
---|
| 5 | <meta http-equiv="Content-Language" content="en-us"> |
---|
| 6 | <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
---|
| 7 | |
---|
| 8 | <title>Boost Random Number Library Distributions</title> |
---|
| 9 | </head> |
---|
| 10 | |
---|
| 11 | <body bgcolor="#FFFFFF" text="#000000"> |
---|
| 12 | <h1>Random Number Library Distributions</h1> |
---|
| 13 | |
---|
| 14 | <ul> |
---|
| 15 | <li><a href="#intro">Introduction</a></li> |
---|
| 16 | |
---|
| 17 | <li><a href="#synopsis">Synopsis</a></li> |
---|
| 18 | |
---|
| 19 | <li><a href="#uniform_smallint">Class template |
---|
| 20 | <code>uniform_smallint</code></a></li> |
---|
| 21 | |
---|
| 22 | <li><a href="#uniform_int">Class template |
---|
| 23 | <code>uniform_int</code></a></li> |
---|
| 24 | |
---|
| 25 | <li><a href="#uniform_01">Class template <code>uniform_01</code></a></li> |
---|
| 26 | |
---|
| 27 | <li><a href="#uniform_real">Class template |
---|
| 28 | <code>uniform_real</code></a></li> |
---|
| 29 | |
---|
| 30 | <li><a href="#bernoulli_distribution">Class template |
---|
| 31 | <code>bernoulli_distribution</code></a></li> |
---|
| 32 | |
---|
| 33 | <li><a href="#geometric_distribution">Class template |
---|
| 34 | <code>geometric_distribution</code></a></li> |
---|
| 35 | |
---|
| 36 | <li><a href="#triangle_distribution">Class template |
---|
| 37 | <code>triangle_distribution</code></a></li> |
---|
| 38 | |
---|
| 39 | <li><a href="#exponential_distribution">Class template |
---|
| 40 | <code>exponential_distribution</code></a></li> |
---|
| 41 | |
---|
| 42 | <li><a href="#normal_distribution">Class template |
---|
| 43 | <code>normal_distribution</code></a></li> |
---|
| 44 | |
---|
| 45 | <li><a href="#lognormal_distribution">Class template |
---|
| 46 | <code>lognormal_distribution</code></a></li> |
---|
| 47 | |
---|
| 48 | <li><a href="#uniform_on_sphere">Class template |
---|
| 49 | <code>uniform_on_sphere</code></a></li> |
---|
| 50 | </ul> |
---|
| 51 | |
---|
| 52 | <h2><a name="intro" id="intro">Introduction</a></h2> |
---|
| 53 | |
---|
| 54 | <p>In addition to the <a href="random-generators.html">random number |
---|
| 55 | generators</a>, this library provides distribution functions which map one |
---|
| 56 | distribution (often a uniform distribution provided by some generator) to |
---|
| 57 | another.</p> |
---|
| 58 | |
---|
| 59 | <p>Usually, there are several possible implementations of any given |
---|
| 60 | mapping. Often, there is a choice between using more space, more |
---|
| 61 | invocations of the underlying source of random numbers, or more |
---|
| 62 | time-consuming arithmetic such as trigonometric functions. This interface |
---|
| 63 | description does not mandate any specific implementation. However, |
---|
| 64 | implementations which cannot reach certain values of the specified |
---|
| 65 | distribution or otherwise do not converge statistically to it are not |
---|
| 66 | acceptable.</p> |
---|
| 67 | |
---|
| 68 | <table border="1" summary=""> |
---|
| 69 | <tr> |
---|
| 70 | <th>distribution</th> |
---|
| 71 | |
---|
| 72 | <th>explanation</th> |
---|
| 73 | |
---|
| 74 | <th>example</th> |
---|
| 75 | </tr> |
---|
| 76 | |
---|
| 77 | <tr> |
---|
| 78 | <td><code><a href="#uniform_smallint">uniform_smallint</a></code></td> |
---|
| 79 | |
---|
| 80 | <td>discrete uniform distribution on a small set of integers (much |
---|
| 81 | smaller than the range of the underlying generator)</td> |
---|
| 82 | |
---|
| 83 | <td>drawing from an urn</td> |
---|
| 84 | </tr> |
---|
| 85 | |
---|
| 86 | <tr> |
---|
| 87 | <td><code><a href="#uniform_int">uniform_int</a></code></td> |
---|
| 88 | |
---|
| 89 | <td>discrete uniform distribution on a set of integers; the underlying |
---|
| 90 | generator may be called several times to gather enough randomness for |
---|
| 91 | the output</td> |
---|
| 92 | |
---|
| 93 | <td>drawing from an urn</td> |
---|
| 94 | </tr> |
---|
| 95 | |
---|
| 96 | <tr> |
---|
| 97 | <td><code><a href="#uniform_01">uniform_01</a></code></td> |
---|
| 98 | |
---|
| 99 | <td>continuous uniform distribution on the range [0,1); important basis |
---|
| 100 | for other distributions</td> |
---|
| 101 | |
---|
| 102 | <td>-</td> |
---|
| 103 | </tr> |
---|
| 104 | |
---|
| 105 | <tr> |
---|
| 106 | <td><code><a href="#uniform_real">uniform_real</a></code></td> |
---|
| 107 | |
---|
| 108 | <td>continuous uniform distribution on some range [min, max) of real |
---|
| 109 | numbers</td> |
---|
| 110 | |
---|
| 111 | <td>for the range [0, 2pi): randomly dropping a stick and measuring its |
---|
| 112 | angle in radiants (assuming the angle is uniformly distributed)</td> |
---|
| 113 | </tr> |
---|
| 114 | |
---|
| 115 | <tr> |
---|
| 116 | <td><code><a href= |
---|
| 117 | "#bernoulli_distribution">bernoulli_distribution</a></code></td> |
---|
| 118 | |
---|
| 119 | <td>Bernoulli experiment: discrete boolean valued distribution with |
---|
| 120 | configurable probability</td> |
---|
| 121 | |
---|
| 122 | <td>tossing a coin (p=0.5)</td> |
---|
| 123 | </tr> |
---|
| 124 | |
---|
| 125 | <tr> |
---|
| 126 | <td><code><a href= |
---|
| 127 | "#geometric_distribution">geometric_distribution</a></code></td> |
---|
| 128 | |
---|
| 129 | <td>measures distance between outcomes of repeated Bernoulli |
---|
| 130 | experiments</td> |
---|
| 131 | |
---|
| 132 | <td>throwing a die several times and counting the number of tries until |
---|
| 133 | a "6" appears for the first time</td> |
---|
| 134 | </tr> |
---|
| 135 | |
---|
| 136 | <tr> |
---|
| 137 | <td><code><a href= |
---|
| 138 | "#triangle_distribution">triangle_distribution</a></code></td> |
---|
| 139 | |
---|
| 140 | <td>?</td> |
---|
| 141 | |
---|
| 142 | <td>?</td> |
---|
| 143 | </tr> |
---|
| 144 | |
---|
| 145 | <tr> |
---|
| 146 | <td><code><a href= |
---|
| 147 | "#exponential_distribution">exponential_distribution</a></code></td> |
---|
| 148 | |
---|
| 149 | <td>exponential distribution</td> |
---|
| 150 | |
---|
| 151 | <td>measuring the inter-arrival time of alpha particles emitted by |
---|
| 152 | radioactive matter</td> |
---|
| 153 | </tr> |
---|
| 154 | |
---|
| 155 | <tr> |
---|
| 156 | <td><code><a href= |
---|
| 157 | "#normal_distribution">normal_distribution</a></code></td> |
---|
| 158 | |
---|
| 159 | <td>counts outcomes of (infinitely) repeated Bernoulli experiments</td> |
---|
| 160 | |
---|
| 161 | <td>tossing a coin 10000 times and counting how many front sides are |
---|
| 162 | shown</td> |
---|
| 163 | </tr> |
---|
| 164 | |
---|
| 165 | <tr> |
---|
| 166 | <td><code><a href= |
---|
| 167 | "#lognormal_distribution">lognormal_distribution</a></code></td> |
---|
| 168 | |
---|
| 169 | <td>lognormal distribution (sometimes used in simulations)</td> |
---|
| 170 | |
---|
| 171 | <td>measuring the job completion time of an assembly line worker</td> |
---|
| 172 | </tr> |
---|
| 173 | |
---|
| 174 | <tr> |
---|
| 175 | <td><code><a href= |
---|
| 176 | "#uniform_on_sphere">uniform_on_sphere</a></code></td> |
---|
| 177 | |
---|
| 178 | <td>uniform distribution on a unit sphere of arbitrary dimension</td> |
---|
| 179 | |
---|
| 180 | <td>choosing a random point on Earth (assumed to be a sphere) where to |
---|
| 181 | spend the next vacations</td> |
---|
| 182 | </tr> |
---|
| 183 | </table> |
---|
| 184 | |
---|
| 185 | <p>The template parameters of the distribution functions are always in the |
---|
| 186 | order</p> |
---|
| 187 | |
---|
| 188 | <ul> |
---|
| 189 | <li>Underlying source of random numbers</li> |
---|
| 190 | |
---|
| 191 | <li>If applicable, return type, with a default to a reasonable type.</li> |
---|
| 192 | </ul> |
---|
| 193 | |
---|
| 194 | <p><em>The distribution functions no longer satisfy the input iterator |
---|
| 195 | requirements (std:24.1.1 [lib.input.iterators]), because this is redundant |
---|
| 196 | given the Generator interface and imposes a run-time overhead on all users. |
---|
| 197 | Moreover, a Generator interface appeals to random number generation as |
---|
| 198 | being more "natural". Use an <a href= |
---|
| 199 | "../utility/iterator_adaptors.htm">iterator adaptor</a> if you need to wrap |
---|
| 200 | any of the generators in an input iterator interface.</em></p> |
---|
| 201 | |
---|
| 202 | <p>All of the distribution functions described below store a non-const |
---|
| 203 | reference to the underlying source of random numbers. Therefore, the |
---|
| 204 | distribution functions are not Assignable. However, they are |
---|
| 205 | CopyConstructible. Copying a distribution function will copy the parameter |
---|
| 206 | values. Furthermore, both the copy and the original will refer to the same |
---|
| 207 | underlying source of random numbers. Therefore, both the copy and the |
---|
| 208 | original will obtain their underlying random numbers from a single |
---|
| 209 | sequence.</p> |
---|
| 210 | |
---|
| 211 | <p>In this description, I have refrained from documenting those members in |
---|
| 212 | detail which are already defined in the <a href= |
---|
| 213 | "random-concepts.html">concept documentation</a>.</p> |
---|
| 214 | |
---|
| 215 | <h2><a name="synopsis" id="synopsis">Synopsis of the distributions</a> |
---|
| 216 | available from header <code><boost/random.hpp></code></h2> |
---|
| 217 | <pre> |
---|
| 218 | namespace boost { |
---|
| 219 | template<class IntType = int> |
---|
| 220 | class uniform_smallint; |
---|
| 221 | template<class IntType = int> |
---|
| 222 | class uniform_int; |
---|
| 223 | template<class RealType = double> |
---|
| 224 | class uniform_01; |
---|
| 225 | template<class RealType = double> |
---|
| 226 | class uniform_real; |
---|
| 227 | |
---|
| 228 | // discrete distributions |
---|
| 229 | template<class RealType = double> |
---|
| 230 | class bernoulli_distribution; |
---|
| 231 | template<class IntType = int> |
---|
| 232 | class geometric_distribution; |
---|
| 233 | |
---|
| 234 | // continuous distributions |
---|
| 235 | template<class RealType = double> |
---|
| 236 | class triangle_distribution; |
---|
| 237 | template<class RealType = double> |
---|
| 238 | class exponential_distribution; |
---|
| 239 | template<class RealType = double> |
---|
| 240 | class normal_distribution; |
---|
| 241 | template<class RealType = double> |
---|
| 242 | class lognormal_distribution; |
---|
| 243 | template<class RealType = double, |
---|
| 244 | class Cont = std::vector<RealType> > |
---|
| 245 | class uniform_on_sphere; |
---|
| 246 | } |
---|
| 247 | </pre> |
---|
| 248 | |
---|
| 249 | <h2><a name="uniform_smallint" id="uniform_smallint">Class template |
---|
| 250 | <code>uniform_smallint</code></a></h2> |
---|
| 251 | |
---|
| 252 | <h3>Synopsis</h3> |
---|
| 253 | <pre> |
---|
| 254 | #include <<a href= |
---|
| 255 | "../../boost/random/uniform_smallint.hpp">boost/random/uniform_smallint.hpp</a>> |
---|
| 256 | |
---|
| 257 | template<class IntType = int> |
---|
| 258 | class uniform_smallint |
---|
| 259 | { |
---|
| 260 | public: |
---|
| 261 | typedef IntType input_type; |
---|
| 262 | typedef IntType result_type; |
---|
| 263 | static const bool has_fixed_range = false; |
---|
| 264 | uniform_smallint(IntType min, IntType max); |
---|
| 265 | result_type min() const; |
---|
| 266 | result_type max() const; |
---|
| 267 | void reset(); |
---|
| 268 | template<class UniformRandomNumberGenerator> |
---|
| 269 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 270 | }; |
---|
| 271 | </pre> |
---|
| 272 | |
---|
| 273 | <h3>Description</h3> |
---|
| 274 | |
---|
| 275 | <p>The distribution function <code>uniform_smallint</code> models a |
---|
| 276 | <a href="random-concepts.html#random-dist">random distribution</a>. On each |
---|
| 277 | invocation, it returns a random integer value uniformly distributed in the |
---|
| 278 | set of integer numbers {min, min+1, min+2, ..., max}. It assumes that the |
---|
| 279 | desired range (max-min+1) is small compared to the range of the underlying |
---|
| 280 | source of random numbers and thus makes no attempt to limit quantization |
---|
| 281 | errors.</p> |
---|
| 282 | |
---|
| 283 | <p>Let r<sub>out</sub>=(max-min+1) the desired range of integer numbers, |
---|
| 284 | and let r<sub>base</sub> be the range of the underlying source of random |
---|
| 285 | numbers. Then, for the uniform distribution, the theoretical probability |
---|
| 286 | for any number i in the range r<sub>out</sub> will be p<sub>out</sub>(i) = |
---|
| 287 | 1/r<sub>out</sub>. Likewise, assume a uniform distribution on |
---|
| 288 | r<sub>base</sub> for the underlying source of random numbers, i.e. |
---|
| 289 | p<sub>base</sub>(i) = 1/r<sub>base</sub>. Let p<sub>out_s</sub>(i) denote |
---|
| 290 | the random distribution generated by <code>uniform_smallint</code>. Then |
---|
| 291 | the sum over all i in r<sub>out</sub> of |
---|
| 292 | (p<sub>out_s</sub>(i)/p<sub>out</sub>(i) -1)<sup>2</sup> shall not exceed |
---|
| 293 | r<sub>out</sub>/r<sub>base</sub><sup>2</sup> (r<sub>base</sub> mod |
---|
| 294 | r<sub>out</sub>)(r<sub>out</sub> - r<sub>base</sub> mod |
---|
| 295 | r<sub>out</sub>).</p> |
---|
| 296 | |
---|
| 297 | <p>The template parameter <code>IntType</code> shall denote an integer-like |
---|
| 298 | value type.</p> |
---|
| 299 | |
---|
| 300 | <p><em>Note:</em> The property above is the square sum of the relative |
---|
| 301 | differences in probabilities between the desired uniform distribution |
---|
| 302 | p<sub>out</sub>(i) and the generated distribution p<sub>out_s</sub>(i). The |
---|
| 303 | property can be fulfilled with the calculation (base_rng mod |
---|
| 304 | r<sub>out</sub>), as follows: Let r = r<sub>base</sub> mod r<sub>out</sub>. |
---|
| 305 | The base distribution on r<sub>base</sub> is folded onto the range |
---|
| 306 | r<sub>out</sub>. The numbers i < r have assigned (r<sub>base</sub> div |
---|
| 307 | r<sub>out</sub>)+1 numbers of the base distribution, the rest has only |
---|
| 308 | (r<sub>base</sub> div r<sub>out</sub>). Therefore, p<sub>out_s</sub>(i) = |
---|
| 309 | ((r<sub>base</sub> div r<sub>out</sub>)+1) / r<sub>base</sub> for i < r |
---|
| 310 | and p<sub>out_s</sub>(i) = (r<sub>base</sub> div |
---|
| 311 | r<sub>out</sub>)/r<sub>base</sub> otherwise. Substituting this in the above |
---|
| 312 | sum formula leads to the desired result.</p> |
---|
| 313 | |
---|
| 314 | <p><em>Note:</em> The upper bound for (r<sub>base</sub> mod |
---|
| 315 | r<sub>out</sub>)(r<sub>out</sub> - r<sub>base</sub> mod r<sub>out</sub>) is |
---|
| 316 | r<sub>out</sub><sup>2</sup>/4. Regarding the upper bound for the square sum |
---|
| 317 | of the relative quantization error of |
---|
| 318 | r<sub>out</sub><sup>3</sup>/(4*r<sub>base</sub><sup>2</sup>), it seems wise |
---|
| 319 | to either choose r<sub>base</sub> so that r<sub>base</sub> > |
---|
| 320 | 10*r<sub>out</sub><sup>2</sup> or ensure that r<sub>base</sub> is divisible |
---|
| 321 | by r<sub>out</sub>.</p> |
---|
| 322 | |
---|
| 323 | <h3>Members</h3> |
---|
| 324 | <pre> |
---|
| 325 | uniform_smallint(IntType min, IntType max) |
---|
| 326 | </pre> |
---|
| 327 | |
---|
| 328 | <p><strong>Effects:</strong> Constructs a <code>uniform_smallint</code> |
---|
| 329 | functor. <code>min</code> and <code>max</code> are the lower and upper |
---|
| 330 | bounds of the output range, respectively.</p> |
---|
| 331 | |
---|
| 332 | <h2><a name="uniform_int" id="uniform_int">Class template |
---|
| 333 | <code>uniform_int</code></a></h2> |
---|
| 334 | |
---|
| 335 | <h3>Synopsis</h3> |
---|
| 336 | <pre> |
---|
| 337 | #include <<a href= |
---|
| 338 | "../../boost/random/uniform_int.hpp">boost/random/uniform_int.hpp</a>> |
---|
| 339 | |
---|
| 340 | template<class IntType = int> |
---|
| 341 | class uniform_int |
---|
| 342 | { |
---|
| 343 | public: |
---|
| 344 | typedef IntType input_type; |
---|
| 345 | typedef IntType result_type; |
---|
| 346 | static const bool has_fixed_range = false; |
---|
| 347 | explicit uniform_int(IntType min = 0, IntType max = 9); |
---|
| 348 | result_type min() const; |
---|
| 349 | result_type max() const; |
---|
| 350 | void reset(); |
---|
| 351 | template<class UniformRandomNumberGenerator> |
---|
| 352 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 353 | template<class UniformRandomNumberGenerator> |
---|
| 354 | result_type operator()(UniformRandomNumberGenerator& urng, result_type n); |
---|
| 355 | }; |
---|
| 356 | </pre> |
---|
| 357 | |
---|
| 358 | <h3>Description</h3> |
---|
| 359 | |
---|
| 360 | <p>The distribution function <code>uniform_int</code> models a <a href= |
---|
| 361 | "random-concepts.html#random-dist">random distribution</a>. On each |
---|
| 362 | invocation, it returns a random integer value uniformly distributed in the |
---|
| 363 | set of integer numbers {min, min+1, min+2, ..., max}.</p> |
---|
| 364 | |
---|
| 365 | <p>The template parameter <code>IntType</code> shall denote an integer-like |
---|
| 366 | value type.</p> |
---|
| 367 | |
---|
| 368 | <h3>Members</h3> |
---|
| 369 | <pre> |
---|
| 370 | uniform_int(IntType min = 0, IntType max = 9) |
---|
| 371 | </pre> |
---|
| 372 | |
---|
| 373 | <p><strong>Requires:</strong> min <= max<br> |
---|
| 374 | <strong>Effects:</strong> Constructs a <code>uniform_int</code> object. |
---|
| 375 | <code>min</code> and <code>max</code> are the parameters of the |
---|
| 376 | distribution.</p> |
---|
| 377 | <pre> |
---|
| 378 | result_type min() const |
---|
| 379 | </pre> |
---|
| 380 | |
---|
| 381 | <p><strong>Returns:</strong> The "min" parameter of the distribution.</p> |
---|
| 382 | <pre> |
---|
| 383 | result_type max() const |
---|
| 384 | </pre> |
---|
| 385 | |
---|
| 386 | <p><strong>Returns:</strong> The "max" parameter of the distribution.</p> |
---|
| 387 | <pre> |
---|
| 388 | result_type operator()(UniformRandomNumberGenerator& urng, result_type |
---|
| 389 | n) |
---|
| 390 | </pre> |
---|
| 391 | |
---|
| 392 | <p><strong>Returns:</strong> A uniform random number x in the range 0 <= |
---|
| 393 | x < n. <em>[Note: This allows a <code>variate_generator</code> object |
---|
| 394 | with a <code>uniform_int</code> distribution to be used with |
---|
| 395 | std::random_shuffe, see [lib.alg.random.shuffle]. ]</em></p> |
---|
| 396 | |
---|
| 397 | <h2><a name="uniform_01" id="uniform_01">Class template |
---|
| 398 | <code>uniform_01</code></a></h2> |
---|
| 399 | |
---|
| 400 | <h3>Synopsis</h3> |
---|
| 401 | <pre> |
---|
| 402 | #include <<a href= |
---|
| 403 | "../../boost/random/uniform_01.hpp">boost/random/uniform_01.hpp</a>> |
---|
| 404 | |
---|
| 405 | template<class UniformRandomNumberGenerator, class RealType = double> |
---|
| 406 | class uniform_01 |
---|
| 407 | { |
---|
| 408 | public: |
---|
| 409 | typedef UniformRandomNumberGenerator base_type; |
---|
| 410 | typedef RealType result_type; |
---|
| 411 | static const bool has_fixed_range = false; |
---|
| 412 | explicit uniform_01(base_type & rng); |
---|
| 413 | result_type operator()(); |
---|
| 414 | result_type min() const; |
---|
| 415 | result_type max() const; |
---|
| 416 | }; |
---|
| 417 | </pre> |
---|
| 418 | |
---|
| 419 | <h3>Description</h3> |
---|
| 420 | |
---|
| 421 | <p>The distribution function <code>uniform_01</code> models a <a href= |
---|
| 422 | "random-concepts.html#random-dist">random distribution</a>. On each |
---|
| 423 | invocation, it returns a random floating-point value uniformly distributed |
---|
| 424 | in the range [0..1). The value is computed using |
---|
| 425 | <code>std::numeric_limits<RealType>::digits</code> random binary |
---|
| 426 | digits, i.e. the mantissa of the floating-point value is completely filled |
---|
| 427 | with random bits. [<em>Note:</em> Should this be configurable?]</p> |
---|
| 428 | |
---|
| 429 | <p>The template parameter <code>RealType</code> shall denote a float-like |
---|
| 430 | value type with support for binary operators +, -, and /. It must be large |
---|
| 431 | enough to hold floating-point numbers of value |
---|
| 432 | <code>rng.max()-rng.min()+1</code>.</p> |
---|
| 433 | |
---|
| 434 | <p><code>base_type::result_type</code> must be a number-like value type, it |
---|
| 435 | must support <code>static_cast<></code> to <code>RealType</code> and |
---|
| 436 | binary operator -.</p> |
---|
| 437 | |
---|
| 438 | <p><em>Note:</em> The current implementation is buggy, because it may not |
---|
| 439 | fill all of the mantissa with random bits. I'm unsure how to fill a |
---|
| 440 | (to-be-invented) <code>boost::bigfloat</code> class with random bits |
---|
| 441 | efficiently. It's probably time for a traits class.</p> |
---|
| 442 | |
---|
| 443 | <h3>Members</h3> |
---|
| 444 | <pre> |
---|
| 445 | explicit uniform_01(base_type & rng) |
---|
| 446 | </pre> |
---|
| 447 | |
---|
| 448 | <p><strong>Effects:</strong> Constructs a <code>uniform_01</code> functor |
---|
| 449 | with the given uniform random number generator as the underlying source of |
---|
| 450 | random numbers.</p> |
---|
| 451 | |
---|
| 452 | <h2><a name="uniform_real" id="uniform_real">Class template |
---|
| 453 | <code>uniform_real</code></a></h2> |
---|
| 454 | |
---|
| 455 | <h3>Synopsis</h3> |
---|
| 456 | <pre> |
---|
| 457 | #include <<a href= |
---|
| 458 | "../../boost/random/uniform_real.hpp">boost/random/uniform_real.hpp</a>> |
---|
| 459 | |
---|
| 460 | template<class RealType = double> |
---|
| 461 | class uniform_real |
---|
| 462 | { |
---|
| 463 | public: |
---|
| 464 | typedef RealType input_type; |
---|
| 465 | typedef RealType result_type; |
---|
| 466 | static const bool has_fixed_range = false; |
---|
| 467 | uniform_real(RealType min = RealType(0), RealType max = RealType(1)); |
---|
| 468 | result_type min() const; |
---|
| 469 | result_type max() const; |
---|
| 470 | void reset(); |
---|
| 471 | template<class UniformRandomNumberGenerator> |
---|
| 472 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 473 | }; |
---|
| 474 | </pre> |
---|
| 475 | |
---|
| 476 | <h3>Description</h3> |
---|
| 477 | |
---|
| 478 | <p>The distribution function <code>uniform_real</code> models a <a href= |
---|
| 479 | "random-concepts.html#random-dist">random distribution</a>. On each |
---|
| 480 | invocation, it returns a random floating-point value uniformly distributed |
---|
| 481 | in the range [min..max). The value is computed using |
---|
| 482 | <code>std::numeric_limits<RealType>::digits</code> random binary |
---|
| 483 | digits, i.e. the mantissa of the floating-point value is completely filled |
---|
| 484 | with random bits.</p> |
---|
| 485 | |
---|
| 486 | <p><em>Note:</em> The current implementation is buggy, because it may not |
---|
| 487 | fill all of the mantissa with random bits.</p> |
---|
| 488 | |
---|
| 489 | <h3>Members</h3> |
---|
| 490 | <pre> |
---|
| 491 | uniform_real(RealType min = RealType(0), RealType max = RealType(1)) |
---|
| 492 | </pre> |
---|
| 493 | |
---|
| 494 | <p><strong>Requires:</strong> min <= max<br> |
---|
| 495 | <strong>Effects:</strong> Constructs a <code>uniform_real</code> object; |
---|
| 496 | <code>min</code> and <code>max</code> are the parameters of the |
---|
| 497 | distribution.</p> |
---|
| 498 | <pre> |
---|
| 499 | result_type min() const |
---|
| 500 | </pre> |
---|
| 501 | |
---|
| 502 | <p><strong>Returns:</strong> The "min" parameter of the distribution.</p> |
---|
| 503 | <pre> |
---|
| 504 | result_type max() const |
---|
| 505 | </pre> |
---|
| 506 | |
---|
| 507 | <p><strong>Returns:</strong> The "max" parameter of the distribution.</p> |
---|
| 508 | |
---|
| 509 | <h2><a name="bernoulli_distribution" id="bernoulli_distribution">Class |
---|
| 510 | template <code>bernoulli_distribution</code></a></h2> |
---|
| 511 | |
---|
| 512 | <h3>Synopsis</h3> |
---|
| 513 | <pre> |
---|
| 514 | #include <<a href= |
---|
| 515 | "../../boost/random/bernoulli_distribution.hpp">boost/random/bernoulli_distribution.hpp</a>> |
---|
| 516 | |
---|
| 517 | template<class RealType = double> |
---|
| 518 | class bernoulli_distribution |
---|
| 519 | { |
---|
| 520 | public: |
---|
| 521 | typedef int input_type; |
---|
| 522 | typedef bool result_type; |
---|
| 523 | |
---|
| 524 | explicit bernoulli_distribution(const RealType& p = RealType(0.5)); |
---|
| 525 | RealType p() const; |
---|
| 526 | void reset(); |
---|
| 527 | template<class UniformRandomNumberGenerator> |
---|
| 528 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 529 | }; |
---|
| 530 | </pre> |
---|
| 531 | |
---|
| 532 | <h3>Description</h3> |
---|
| 533 | |
---|
| 534 | <p>Instantiations of class template <code>bernoulli_distribution</code> |
---|
| 535 | model a <a href="random-concepts.html#random-dist">random distribution</a>. |
---|
| 536 | Such a random distribution produces <code>bool</code> values distributed |
---|
| 537 | with probabilities P(true) = p and P(false) = 1-p. p is the parameter of |
---|
| 538 | the distribution.</p> |
---|
| 539 | |
---|
| 540 | <h3>Members</h3> |
---|
| 541 | <pre> |
---|
| 542 | bernoulli_distribution(const RealType& p = RealType(0.5)) |
---|
| 543 | </pre> |
---|
| 544 | |
---|
| 545 | <p><strong>Requires:</strong> 0 <= p <= 1<br> |
---|
| 546 | <strong>Effects:</strong> Constructs a <code>bernoulli_distribution</code> |
---|
| 547 | object. <code>p</code> is the parameter of the distribution.</p> |
---|
| 548 | <pre> |
---|
| 549 | RealType p() const |
---|
| 550 | </pre> |
---|
| 551 | |
---|
| 552 | <p><strong>Returns:</strong> The "p" parameter of the distribution.</p> |
---|
| 553 | |
---|
| 554 | <h2><a name="geometric_distribution" id="geometric_distribution">Class |
---|
| 555 | template <code>geometric_distribution</code></a></h2> |
---|
| 556 | |
---|
| 557 | <h3>Synopsis</h3> |
---|
| 558 | <pre> |
---|
| 559 | #include <<a href= |
---|
| 560 | "../../boost/random/geometric_distribution.hpp">boost/random/geometric_distribution.hpp</a>> |
---|
| 561 | |
---|
| 562 | template<class UniformRandomNumberGenerator, class IntType = int> |
---|
| 563 | class geometric_distribution |
---|
| 564 | { |
---|
| 565 | public: |
---|
| 566 | typedef RealType input_type; |
---|
| 567 | typedef IntType result_type; |
---|
| 568 | |
---|
| 569 | explicit geometric_distribution(const RealType& p = RealType(0.5)); |
---|
| 570 | RealType p() const; |
---|
| 571 | void reset(); |
---|
| 572 | template<class UniformRandomNumberGenerator> |
---|
| 573 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 574 | }; |
---|
| 575 | </pre> |
---|
| 576 | |
---|
| 577 | <h3>Description</h3> |
---|
| 578 | |
---|
| 579 | <p>Instantiations of class template <code>geometric_distribution</code> |
---|
| 580 | model a <a href="random-concepts.html#random-dist">random distribution</a>. |
---|
| 581 | A <code>geometric_distribution</code> random distribution produces integer |
---|
| 582 | values <em>i</em> >= 1 with p(i) = (1-p) * p<sup>i-1</sup>. p is the |
---|
| 583 | parameter of the distribution.</p> |
---|
| 584 | |
---|
| 585 | <h3>Members</h3> |
---|
| 586 | <pre> |
---|
| 587 | geometric_distribution(const RealType& p = RealType(0.5)) |
---|
| 588 | </pre> |
---|
| 589 | |
---|
| 590 | <p><strong>Requires:</strong> 0 < p < 1<br> |
---|
| 591 | <strong>Effects:</strong> Constructs a <code>geometric_distribution</code> |
---|
| 592 | object; <code>p</code> is the parameter of the distribution.</p> |
---|
| 593 | <pre> |
---|
| 594 | RealType p() const |
---|
| 595 | </pre> |
---|
| 596 | |
---|
| 597 | <p><strong>Returns:</strong> The "p" parameter of the distribution.</p> |
---|
| 598 | |
---|
| 599 | <h2><a name="triangle_distribution" id="triangle_distribution">Class |
---|
| 600 | template <code>triangle_distribution</code></a></h2> |
---|
| 601 | |
---|
| 602 | <h3>Synopsis</h3> |
---|
| 603 | <pre> |
---|
| 604 | #include <<a href= |
---|
| 605 | "../../boost/random/triangle_distribution.hpp">boost/random/triangle_distribution.hpp</a>> |
---|
| 606 | |
---|
| 607 | template<class RealType = double> |
---|
| 608 | class triangle_distribution |
---|
| 609 | { |
---|
| 610 | public: |
---|
| 611 | typedef RealType input_type; |
---|
| 612 | typedef RealType result_type; |
---|
| 613 | triangle_distribution(result_type a, result_type b, result_type c); |
---|
| 614 | result_type a() const; |
---|
| 615 | result_type b() const; |
---|
| 616 | result_type c() const; |
---|
| 617 | void reset(); |
---|
| 618 | template<class UniformRandomNumberGenerator> |
---|
| 619 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 620 | }; |
---|
| 621 | </pre> |
---|
| 622 | |
---|
| 623 | <h3>Description</h3> |
---|
| 624 | |
---|
| 625 | <p>Instantiations of class template <code>triangle_distribution</code> |
---|
| 626 | model a <a href="random-concepts.html#random-dist">random distribution</a>. |
---|
| 627 | The returned floating-point values <code>x</code> satisfy <code>a <= x |
---|
| 628 | <= c</code>; <code>x</code> has a triangle distribution, where |
---|
| 629 | <code>b</code> is the most probable value for <code>x</code>.</p> |
---|
| 630 | |
---|
| 631 | <h3>Members</h3> |
---|
| 632 | <pre> |
---|
| 633 | triangle_distribution(result_type a, result_type b, result_type c) |
---|
| 634 | </pre> |
---|
| 635 | |
---|
| 636 | <p><strong>Effects:</strong> Constructs a |
---|
| 637 | <code>triangle_distribution</code> functor. <code>a, b, c</code> are the |
---|
| 638 | parameters for the distribution.</p> |
---|
| 639 | |
---|
| 640 | <h2><a name="exponential_distribution" id="exponential_distribution">Class |
---|
| 641 | template <code>exponential_distribution</code></a></h2> |
---|
| 642 | |
---|
| 643 | <h3>Synopsis</h3> |
---|
| 644 | <pre> |
---|
| 645 | #include <<a href= |
---|
| 646 | "../../boost/random/exponential_distribution.hpp">boost/random/exponential_distribution.hpp</a>> |
---|
| 647 | |
---|
| 648 | template<class RealType = double> |
---|
| 649 | class exponential_distribution |
---|
| 650 | { |
---|
| 651 | public: |
---|
| 652 | typedef RealType input_type; |
---|
| 653 | typedef RealType result_type; |
---|
| 654 | explicit exponential_distribution(const result_type& lambda); |
---|
| 655 | RealType lambda() const; |
---|
| 656 | void reset(); |
---|
| 657 | template<class UniformRandomNumberGenerator> |
---|
| 658 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 659 | }; |
---|
| 660 | </pre> |
---|
| 661 | |
---|
| 662 | <h3>Description</h3> |
---|
| 663 | |
---|
| 664 | <p>Instantiations of class template <code>exponential_distribution</code> |
---|
| 665 | model a <a href="random-concepts.html#random-dist">random distribution</a>. |
---|
| 666 | Such a distribution produces random numbers x > 0 distributed with |
---|
| 667 | probability density function p(x) = lambda * exp(-lambda * x), where lambda |
---|
| 668 | is the parameter of the distribution.</p> |
---|
| 669 | |
---|
| 670 | <h3>Members</h3> |
---|
| 671 | <pre> |
---|
| 672 | exponential_distribution(const result_type& lambda = result_type(1)) |
---|
| 673 | </pre> |
---|
| 674 | |
---|
| 675 | <p><strong>Requires:</strong> lambda > 0<br> |
---|
| 676 | <strong>Effects:</strong> Constructs an |
---|
| 677 | <code>exponential_distribution</code> object with <code>rng</code> as the |
---|
| 678 | reference to the underlying source of random numbers. <code>lambda</code> |
---|
| 679 | is the parameter for the distribution.</p> |
---|
| 680 | <pre> |
---|
| 681 | RealType lambda() const |
---|
| 682 | </pre> |
---|
| 683 | |
---|
| 684 | <p><strong>Returns:</strong> The "lambda" parameter of the |
---|
| 685 | distribution.</p> |
---|
| 686 | |
---|
| 687 | <h2><a name="normal_distribution" id="normal_distribution">Class template |
---|
| 688 | <code>normal_distribution</code></a></h2> |
---|
| 689 | |
---|
| 690 | <h3>Synopsis</h3> |
---|
| 691 | <pre> |
---|
| 692 | #include <<a href= |
---|
| 693 | "../../boost/random/normal_distribution.hpp">boost/random/normal_distribution.hpp</a>> |
---|
| 694 | |
---|
| 695 | template<class RealType = double> |
---|
| 696 | class normal_distribution |
---|
| 697 | { |
---|
| 698 | public: |
---|
| 699 | typedef RealType input_type; |
---|
| 700 | typedef RealType result_type; |
---|
| 701 | explicit normal_distribution(const result_type& mean = 0, |
---|
| 702 | const result_type& sigma = 1); |
---|
| 703 | RealType mean() const; |
---|
| 704 | RealType sigma() const; |
---|
| 705 | void reset(); |
---|
| 706 | template<class UniformRandomNumberGenerator> |
---|
| 707 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 708 | }; |
---|
| 709 | </pre> |
---|
| 710 | |
---|
| 711 | <h3>Description</h3> |
---|
| 712 | |
---|
| 713 | <p>Instantiations of class template <code>normal_distribution</code> model |
---|
| 714 | a <a href="random-concepts.html#random-dist">random distribution</a>. Such |
---|
| 715 | a distribution produces random numbers x distributed with probability |
---|
| 716 | density function p(x) = 1/sqrt(2*pi*sigma) * exp(- (x-mean)<sup>2</sup> / |
---|
| 717 | (2*sigma<sup>2</sup>) ), where mean and sigma are the parameters of the |
---|
| 718 | distribution.</p> |
---|
| 719 | |
---|
| 720 | <h3>Members</h3> |
---|
| 721 | <pre> |
---|
| 722 | explicit normal_distribution(const result_type& mean = 0, |
---|
| 723 | const result_type& sigma = 1); |
---|
| 724 | </pre> |
---|
| 725 | |
---|
| 726 | <p><strong>Requires:</strong> sigma > 0<br> |
---|
| 727 | <strong>Effects:</strong> Constructs a <code>normal_distribution</code> |
---|
| 728 | object; <code>mean</code> and <code>sigma</code> are the parameters for the |
---|
| 729 | distribution.</p> |
---|
| 730 | <pre> |
---|
| 731 | RealType mean() const |
---|
| 732 | </pre> |
---|
| 733 | |
---|
| 734 | <p><strong>Returns:</strong> The "mean" parameter of the distribution.</p> |
---|
| 735 | <pre> |
---|
| 736 | RealType sigma() const |
---|
| 737 | </pre> |
---|
| 738 | |
---|
| 739 | <p><strong>Returns:</strong> The "sigma" parameter of the distribution.</p> |
---|
| 740 | |
---|
| 741 | <h2><a name="lognormal_distribution" id="lognormal_distribution">Class |
---|
| 742 | template <code>lognormal_distribution</code></a></h2> |
---|
| 743 | |
---|
| 744 | <h3>Synopsis</h3> |
---|
| 745 | <pre> |
---|
| 746 | #include <<a href= |
---|
| 747 | "../../boost/random/lognormal_distribution.hpp">boost/random/lognormal_distribution.hpp</a>> |
---|
| 748 | |
---|
| 749 | template<class RealType = double> |
---|
| 750 | class lognormal_distribution |
---|
| 751 | { |
---|
| 752 | public: |
---|
| 753 | typedef typename normal_distribution<RealType>::input_type |
---|
| 754 | typedef RealType result_type; |
---|
| 755 | explicit lognormal_distribution(const result_type& mean = 1.0, |
---|
| 756 | const result_type& sigma = 1.0); |
---|
| 757 | RealType& mean() const; |
---|
| 758 | RealType& sigma() const; |
---|
| 759 | void reset(); |
---|
| 760 | template<class UniformRandomNumberGenerator> |
---|
| 761 | result_type operator()(UniformRandomNumberGenerator& urng); |
---|
| 762 | }; |
---|
| 763 | </pre> |
---|
| 764 | |
---|
| 765 | <h3>Description</h3> |
---|
| 766 | |
---|
| 767 | <p>Instantiations of class template <code>lognormal_distribution</code> |
---|
| 768 | model a <a href="random-concepts.html#random-dist">random distribution</a>. |
---|
| 769 | Such a distribution produces random numbers with p(x) = 1/(x * normal_sigma |
---|
| 770 | * sqrt(2*pi)) * exp( -(log(x)-normal_mean)<sup>2</sup> / |
---|
| 771 | (2*normal_sigma<sup>2</sup>) ) for x > 0, where normal_mean = |
---|
| 772 | log(mean<sup>2</sup>/sqrt(sigma<sup>2</sup> + mean<sup>2</sup>)) and |
---|
| 773 | normal_sigma = sqrt(log(1 + sigma<sup>2</sup>/mean<sup>2</sup>)).</p> |
---|
| 774 | |
---|
| 775 | <h3>Members</h3> |
---|
| 776 | <pre> |
---|
| 777 | lognormal_distribution(const result_type& mean, |
---|
| 778 | const result_type& sigma) |
---|
| 779 | </pre> |
---|
| 780 | |
---|
| 781 | <p><strong>Effects:</strong> Constructs a |
---|
| 782 | <code>lognormal_distribution</code> functor. <code>mean</code> and |
---|
| 783 | <code>sigma</code> are the mean and standard deviation of the lognormal |
---|
| 784 | distribution.</p> |
---|
| 785 | |
---|
| 786 | <h2><a name="uniform_on_sphere" id="uniform_on_sphere">Class template |
---|
| 787 | <code>uniform_on_sphere</code></a></h2> |
---|
| 788 | |
---|
| 789 | <h3>Synopsis</h3> |
---|
| 790 | <pre> |
---|
| 791 | #include <<a href= |
---|
| 792 | "../../boost/random/uniform_on_sphere.hpp">boost/random/uniform_on_sphere.hpp</a>> |
---|
| 793 | |
---|
| 794 | template<class RealType = double, |
---|
| 795 | class Cont = std::vector<RealType> > |
---|
| 796 | class uniform_on_sphere |
---|
| 797 | { |
---|
| 798 | public: |
---|
| 799 | typedef RealType input_type; |
---|
| 800 | typedef Cont result_type; |
---|
| 801 | explicit uniform_on_sphere(int dim = 2); |
---|
| 802 | void reset(); |
---|
| 803 | template<class UniformRandomNumberGenerator> |
---|
| 804 | const result_type & operator()(UniformRandomNumberGenerator& urng); |
---|
| 805 | }; |
---|
| 806 | </pre> |
---|
| 807 | |
---|
| 808 | <h3>Description</h3> |
---|
| 809 | |
---|
| 810 | <p>Instantiations of class template <code>uniform_on_sphere</code> model a |
---|
| 811 | <a href="random-concepts.html#random-dist">random distribution</a>. Such a |
---|
| 812 | distribution produces random numbers uniformly distributed on the unit |
---|
| 813 | sphere of arbitrary dimension <code>dim</code>. The <code>Cont</code> |
---|
| 814 | template parameter must be a STL-like container type with |
---|
| 815 | <code>begin</code> and <code>end</code> operations returning non-const |
---|
| 816 | ForwardIterators of type <code>Cont::iterator</code>.</p> |
---|
| 817 | |
---|
| 818 | <h3>Members</h3> |
---|
| 819 | <pre> |
---|
| 820 | explicit uniform_on_sphere(int dim = 2) |
---|
| 821 | </pre> |
---|
| 822 | |
---|
| 823 | <p><strong>Effects:</strong> Constructs a <code>uniform_on_sphere</code> |
---|
| 824 | functor. <code>dim</code> is the dimension of the sphere.</p> |
---|
| 825 | <hr> |
---|
| 826 | |
---|
| 827 | <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src= |
---|
| 828 | "http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Transitional" |
---|
| 829 | height="31" width="88"></a></p> |
---|
| 830 | |
---|
| 831 | <p>Revised |
---|
| 832 | <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 |
---|
| 833 | December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p> |
---|
| 834 | |
---|
| 835 | <p><i>Copyright © 2000-2004 <a href= |
---|
| 836 | "../../people/jens_maurer.htm">Jens Maurer</a></i></p> |
---|
| 837 | |
---|
| 838 | <p><i>Distributed under the Boost Software License, Version 1.0. (See |
---|
| 839 | accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or |
---|
| 840 | copy at <a href= |
---|
| 841 | "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p> |
---|
| 842 | </body> |
---|
| 843 | </html> |
---|