boost/random
2
0
Fork 0
mirror of https://github.com/boostorg/random.git synced 2026-01-19 04:22:17 +00:00
Code Issues Projects Releases Wiki Activity

Initial HTML commit

Browse Source 
[SVN r7640]
This commit is contained in:
Beman Dawes
2000-07-27 14:27:00 +00:00
parent d20ee06221
commit 14dccab670
6 changed files with 2224 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
index.html Normal file
View File

@@ -0,0 +1,84 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Boost Random Number Library</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
<td><a href="../../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td>
<td><a href="../../libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td>
<td><a href="../../people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td>
<td><a href="../../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td>
<td><a href="../../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td>
</tr>
</table>
<h1>Boost Random Number Library</h1>
By <a href="../../people/jens_maurer.htm">Jens Maurer</a>
<p>You should read the <a href="random-concepts.html">concepts documentation</a>
before moving on.</p>
<p>For a quick start, it may be sufficient to have a look at <a href="random_demo.cpp">random_demo.cpp</a>.
<p>&nbsp;
<table border="1" cellpadding="5">
<tr>
<td align="center"><b><i>Header</i></b></td>
<td align="center"><b><i>Contents</i></b></td>
</tr>
<tr>
<td align="center"><code><a href="../../boost/random.hpp">&lt;boost/random.hpp&gt;</a></code>
<p><a href="random-generators.html">documentation for generators</a><br>
<a href="random-distributions.html">documentation for distributions</a><br>
<a href="random-misc.html">documentation for miscellaneous classes</a></td>
<td>Pseudo-random number generators (linear congruential, inversive
congruential, and others), distribution functions (uniform, normal,
exponential, and others) and miscellaneous decorator classes such as <strong>random_number_generator</strong>
for use in simulations, games, and testing.</td>
</tr>
<tr>
<td align="center"><code><a href="../../boost/nondet_random.hpp">&lt;boost/nondet_random.hpp&gt;</a></code>
<p><a href="nondet_random.html">documentation</a></td>
<td>Non-deterministic random number generators.</td>
</tr>
</table>
&nbsp;
<p>An extensive test suite for the pseudo-random number generators and
distributions is available as <a href="random_test.cpp">random_test.cpp</a>.</p>
<p>Additional test programs include <a href="statistic_tests.cpp">statistic_test.cpp</a>
and <a href="histogram.cpp">histogram.cpp</a>.</p>
<p><font size="5">Rationale</font></p>
The methods for generating and evaluating deterministic and non-deterministic
random numbers differ radically. Furthermore, due to the inherent deterministic
design of present-day computers, it is often difficult to implement
non-deterministic random number generation facilities. Thus, the random number
library is split into separate header files, mirroring the two different
application domains.
<h2><font size="5">History and Acknowledgements</font></h2>
In November 1999, Jeet Sukumaran proposed a framework based on virtual
functions, and later sketched a template-based approach. Ed Brey pointed out
that Microsoft Visual C++ does not support in-class member initializations and
suggested the enum workaround. Dave Abrahams highlighted quantization issues.<br>
<br>
The first public release of this random number library materialized in March
2000 after extensive discussions on the boost mailing list. Many thanks to Beman
Dawes for his original min_rand class, portability fixes, documentation
suggestions, and general guidance. Harry Erwin sent a header file which provided
additional insight into the requirements. Ed Brey and Beman Dawes wanted an
iterator-like interface.<br>
<br>
Beman Dawes managed the formal review, during which Matthias Troyer, Csaba
Szepesvari, and Thomas Holenstein gave detailed comments. The reviewed version
became an official part of boost on 17 June 2000.<br>
<br>
Gary Powell contributed suggestions for code cleanliness.<br>
<hr>
Jens Maurer, 2000-06-27
</body>
</html>

119
nondet_random.html Normal file
View File

@@ -0,0 +1,119 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost RNG Library - Non-Deterministic Random Number Generators</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)"
align="center" width="277" height="86">Header
<a href="../../boost/nondet_random.hpp">&lt;boost/nondet_random.hpp&gt;</a></h1>
<ul>
<li><a href="#synopsis">Synopsis</a>
<li><a href="#random_device">Class <code>random_device</code></a>
<li><a href="#performance">Performance</a>
</ul>
<h2><a name="synopsis">Header</a><code>&lt;boost/nondet_random.hpp&gt;</code>
Synopsis</h2>
<pre>
namespace boost {
class random_device;
} // namespace boost
</pre>
<h2><a name="random_device">Class <code>random_device</code></a></h2>
<h3>Synopsis</h3>
<pre>
class random_device : noncopyable
{
public:
typedef unsigned int result_type;
static const bool has_fixed_range = true;
static const result_type min_value = /* implementation defined */;
static const result_type max_value = /* implementation defined */;
explicit random_device(const std::string& token = default_token);
~random_device();
unsigned int operator()();
};
</pre>
<h3>Description</h3>
Class <code>random_device</code> models a
<a href="random-concepts.html#nondet-rng">non-deterministic random number
generator</a>.
It uses one or more implementation-defined stochastic processes to
generate a sequence of uniformly distributed non-deterministic random
numbers. For those environments where a non-deterministic random
number generator is not available, class <code>random_device</code>
must not be implemented. See
<blockquote>
"Randomness Recommendations for Security", D. Eastlake, S.
Crocker, J. Schiller, Network Working Group, RFC1750, December 1994
</blockquote>
for further discussions.
<p>
<em>Note:</em> Some operating systems abstract the computer hardware
enough to make it difficult to non-intrusively monitor stochastic
processes. However, several do provide a special device for exactly
this purpose. It seems to be impossible to emulate the functionality
using Standard C++ only, so users should be aware that this class may
not be available on all platforms.
<h3>Members</h3>
<pre>explicit random_device(const std::string& token = default_token)</pre>
<strong>Effects:</strong> Constructs a <code>random_device</code>,
optionally using the given <code>token</code> as an access
specification (for example, a URL) to some implementation-defined
service for monitoring a stochastic process.
<h3>Implementation Note for Linux</h3>
On the Linux operating system, <code>token</code> is interpreted as a
filesystem path. It is assumed that this path denotes an operating
system pseudo-device which generates a stream of non-deterministic
random numbers. The pseudo-device should never signal an error or
end-of-file. Otherwise, <code>std::ios_base::failure</code> is
thrown. By default, <code>random_device</code> uses the
<code>/dev/urandom</code> pseudo-device to retrieve the random
numbers. Another option would be to specify the
<code>/dev/random</code> pseudo-device, which blocks on reads if the
entropy pool has no more random bits available.
<h2><a name="performance">Performance</a></h2>
The test program <a href="nondet_random_speed.cpp">nondet_random_speed.cpp</a>
measures the execution times of the
<a href="../../boost/nondet_random.hpp">nondet_random.hpp</a> implementation of the above
algorithms in a tight loop. The performance has been evaluated on a
Pentium Pro 200 MHz with gcc 2.95.2, Linux 2.2.13, glibc 2.1.2.
<p>
<table border=1>
<tr><th>class</th><th>time per invocation [usec]</th></tr>
<tr><td>random_device</td><td>92.0</td></tr>
</table>
<p>
The measurement error is estimated at +/- 1 usec.
<p>
<hr>
Jens Maurer, 2000-03-05
</body>
</html>

344
random-concepts.html Normal file
View File

@@ -0,0 +1,344 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Random Number Library Concepts</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>Random Number Generator Library Concepts</h1>
<h2>Introduction</h2>
Random numbers are required in a number of different problem domains,
such as
<ul>
<li>numerics (simulation, Monte-Carlo integration)
<li>games (non-deterministic enemy behavior)
<li>security (key generation)
<li>testing (random coverage in white-box tests)
</ul>
The Boost Random Number Generator Library provides a framework
for random number generators with well-defined properties so that the
generators can be used in the demanding numerics and security domains.
For a general introduction to random numbers in numerics, see
<blockquote>
"Numerical Recipes in C: The art of scientific computing", William
H. Press, Saul A. Teukolsky, William A. Vetterling, Brian P. Flannery,
2nd ed., 1992, pp. 274-328
</blockquote>
Depending on the requirements of the problem domain, different
variations of random number generators are appropriate:
<ul>
<li>non-deterministic random number generator
<li>pseudo-random number generator
<li>quasi-random number generator
</ul>
All variations have some properties in common, these concepts (in the
STL sense) are called NumberGenerator and
UniformRandomNumberGenerator. Each concept will be defined in a
subsequent section.
<p>
The goals for this library are the following:
<ul>
<li>allow easy integration of third-party random-number generators
<li>define a validation interface for the generators
<li>provide easy-to-use front-end classes which model popular
distributions
<li>provide maximum efficiency
<li>allow control on quantization effects in front-end processing
(not yet done)
</ul>
<h2><a name="number_generator">Number Generator</a></h2>
A number generator is a <em>function object</em> (std:20.3
[lib.function.objects]) that takes zero arguments. Each call to
<code>operator()</code> returns a number.
In the following table, <code>X</code> denotes a number generator
class returning objects of type <code>T</code>, and <code>u</code> is
a value of <code>X</code>.
<p>
<table border=1>
<tr><th colspan=3 align=center><code>NumberGenerator</code>
requirements</th></tr>
<tr><td>expression</td><td>return&nbsp;type</td>
<td>pre/post-condition</td></tr>
<tr><td><code>X::result_type</code></td><td>T</td>
<td><code>std::numeric_limits&lt;T&gt;::is_specialized</code> is true,
<code>T</code> is <code>LessThanComparable</code></td></tr>
<tr><td><code>u.operator()()</code></td><td>T</td><td>-</td></tr>
</table>
<p>
<em>Note:</em> The NumberGenerator requirements do not impose any
restrictions on the characteristics of the returned numbers.
<h2><a name="uniform-rng">Uniform Random Number Generator</a></h2>
A uniform random number generator is a NumberGenerator that provides a
sequence of random numbers uniformly distributed on a given range.
The range can be compile-time fixed or available (only) after run-time
construction of the object.
<p>
The <em>tight lower bound</em> of some (finite) set S is the (unique)
member l in S, so that for all v in S, l <= v holds. Likewise, the
<em>tight upper bound</em> of some (finite) set S is the (unique)
member u in S, so that for all v in S, v <= u holds.
<p>
In the following table, <code>X</code> denotes a number generator
class returning objects of type <code>T</code>, and <code>v</code> is
a const value of <code>X</code>.
<p>
<table border=1>
<tr><th colspan=3 align=center><code>UniformRandomNumberGenerator</code>
requirements</th></tr>
<tr><td>expression</td><td>return&nbsp;type</td>
<td>pre/post-condition</td></tr>
<tr><td><code>X::has_fixed_range</code></td><td><code>bool</code></td>
<td>compile-time constant; if <code>true</code>, the range on which
the random numbers are uniformly distributed is known at compile-time
and members <code>min_value</code> and <code>max_value</code>
exist. <em>Note:</em> This flag may also be <code>false</code> due to
compiler limitations.</td></tr>
<tr><td><code>X::min_value</code></td><td><code>T</code></td>
<td>compile-time constant; <code>min_value</code> is equal to
<code>v.min()</code></td></tr>
<tr><td><code>X::max_value</code></td><td><code>T</code></td>
<td>compile-time constant; <code>max_value</code> is equal to
<code>v.max()</code></td></tr>
<tr><td><code>v.min()</code></td><td><code>T</code></td>
<td>tight lower bound on the set of all values returned by
<code>operator()</code>. The return value of this function shall not
change during the lifetime of the object.</td></tr>
<tr><td><code>v.max()</code></td><td><code>T</code></td>
<td>if <code>std::numeric_limits&lt;T&gt;::is_integer</code>, tight
upper bound on the set of all values returned by
<code>operator()</code>, otherwise, the smallest representable number
larger than the tight upper bound on the set of all values returned by
<code>operator()</code>. In any case, the return value of this
function shall not change during the lifetime of the
object.</code></td></tr>
</table>
<p>
The member functions <code>min</code>, <code>max</code>, and
<code>operator()</code> shall have amortized constant time complexity.
<p>
<em>Note:</em> For integer generators (i.e. integer <code>T</code>),
the generated values <code>x</code> fulfill <code>min() <= x <=
max()</code>, for non-integer generators (i.e. non-integer
<code>T</code>), the generated values <code>x</code> fulfill
<code>min() <= x < max()</code>.
<br>
<em>Rationale:</em> The range description with <code>min</code> and
<code>max</code> serves two purposes. First, it allows scaling of the
values to some canonical range, such as [0..1). Second, it describes
the significant bits of the values, which may be relevant for further
processing.
<br>
The range is a closed interval [min,max] for integers, because the
underlying type may not be able to represent the half-open interval
[min,max+1). It is a half-open interval [min, max) for non-integers,
because this is much more practical for borderline cases of continuous
distributions.
<p>
<em>Note:</em> The UniformRandomNumberGenerator concept does not
require <code>operator()(long)</code> and thus it does not fulfill the
RandomNumberGenerator (std:25.2.11 [lib.alg.random.shuffle])
requirements. Use the
<a href="random-misc.html#random_number_generator"><code>random_number_generator</code></a>
adapter for that.
<br>
<em>Rationale:</em> <code>operator()(long)</code> is not provided,
because mapping the output of some generator with integer range to a
different integer range is not trivial.
<h2><a name="nondet-rng">Non-deterministic Uniform Random Number
Generator</a></h2>
A non-deterministic uniform random number generator is a
UniformRandomNumberGenerator that is based on some stochastic process.
Thus, it provides a sequence of truly-random numbers. Examples for
such processes are nuclear decay, noise of a Zehner diode, tunneling
of quantum particles, rolling a die, drawing from an urn, and tossing
a coin. Depending on the environment, inter-arrival times of network
packets or keyboard events may be close approximations of stochastic
processes.
<p>
The class
<code><a href="nondet_random.html#random_device">random_device</a></code>
is a model for a non-deterministic random number generator.
<p>
<em>Note:</em> This type of random-number generator is useful for
security applications, where it is important to prevent that an
outside attacker guesses the numbers and thus obtains your
encryption or authentication key. Thus, models of this concept should
be cautious not to leak any information, to the extent possible by the
environment. For example, it might be advisable to explicitly clear
any temporary storage as soon as it is no longer needed.
<h2><a name="pseudo-rng">Pseudo-Random Number Generator</a></h2>
A pseudo-random number generator is a UniformRandomNumberGenerator
which provides a deterministic sequence of pseudo-random numbers,
based on some algorithm and internal state. Linear congruential and
inversive congruential generators are examples of such pseudo-random
number generators. Often, these generators are very sensitive to
their parameters. In order to prevent wrong implementations from
being used, an external testsuite should check that the generated
sequence and the validation value provided do indeed match.
<p>
Donald E. Knuth gives an extensive overview on pseudo-random number
generation in his book "The Art of Computer Programming, Vol. 2, 3rd
edition, Addison-Wesley, 1997". The descriptions for the specific
generators contain additional references.
<p>
<em>Note:</em> Because the state of a pseudo-random number generator
is necessarily finite, the sequence of numbers returned by the
generator will loop eventually.
<p>
In addition to the UniformRandomNumberGenerator requirements, a
pseudo-random number generator has some additional requirements. In
the following table, <code>X</code> denotes a pseudo-random number
generator class returning objects of type <code>T</code>,
<code>x</code> is a value of <code>T</code>, <code>u</code> is a value
of <code>X</code>, and <code>v</code> is a <code>const</code> value of
<code>X</code>.
<p>
<table border=1>
<tr><th colspan=3 align=center><code>PseudoRandomNumberGenerator</code>
requirements</th></tr>
<tr><td>expression</td><td>return&nbsp;type</td>
<td>pre/post-condition</td></tr>
<tr><td><code>X()</code></td><td>-</td>
<td>creates a generator in some implementation-defined
state. <em>Note:</em> Several generators thusly created may possibly
produce dependent or identical sequences of random numbers.</td></tr>
<tr><td><code>explicit X(...)</code></td><td>-</td>
<td>creates a generator with user-provided state; the implementation
shall specify the the constructor argument(s)</td></tr>
<tr><td><code>u.seed(...)</code></td><td>void</td>
<td>sets the current state according to the argument(s); at least
functions with the same signature as the non-default
constructor(s) shall be provided.
<tr><td><code>v.validation(x)</code></td><td><code>bool</code></td>
<td>compares the pre-computed and hardcoded 10001th element in the
generator's random number sequence with <code>x</code>. The generator
must have been constructed by its default constructor and
<code>seed</code> must not have been called for the validation to
be meaningful.
</table>
<p>
<em>Note:</em> The <code>seed</code> member function is similar to the
<code>assign</code> member function in STL containers. However, the
naming did not seem appropriate.
<p>
Classes which model a pseudo-random number generator shall also model
EqualityComparable, i.e. implement <code>operator==</code>. Two
pseudo-random number generators are defined to be <em>equivalent</em>
if they both return an identical sequence of numbers starting from a
given state.
<p>
Classes which model a pseudo-random number generator should also model
the Streamable concept, i.e. implement <code>operator&lt;&lt;</code>
and <code>operator&gt;&gt;</code>. If so,
<code>operator&lt;&lt;</code> writes all current state of the
pseudo-random number generator to the given <code>ostream</code> so
that <code>operator&gt;&gt;</code> can restore the state at a later
time. The state shall be written in a platform-independent manner,
but it is assumed that the <code>locale</code>s used for writing and
reading be the same.
The pseudo-random number generator with the restored state and the
original at the just-written state shall be equivalent.
<p>
Classes which model a pseudo-random number generator may also model
the CopyConstructible and Assignable concepts. However, note that the
sequences of the original and the copy are strongly correlated (in
fact, they are identical), which may make them unsuitable for some
problem domains. Thus, copying pseudo-random number generators is
discouraged; they should always be passed by (non-<code>const</code>)
reference.
<p>
The classes
<code><a href="random-generators.html#rand48">rand48</a></code>,
<code><a href="random-generators.html#linear_congruential">minstd_rand</a></code>,
and
<code><a href="random-generators.html#mersenne_twister">mt19937</a></code>
are models for a pseudo-random number generator.
<p>
<em>Note:</em> This type of random-number generator is useful for
numerics, games and testing. The none-zero arguments constructor(s)
and the <code>seed()</code> member function(s) allow for a
user-provided state to be installed in the generator. This is useful
for debugging Monte-Carlo algorithms and analyzing particular test
scenarios. The Streamable concept allows to save/restore the state of
the generator, for example to re-run a test suite at a later time.
<h2><a name="quasi-rng">Quasi-Random Number Generators</a></h2>
A quasi-random number generator is a Number Generator which provides a
deterministic sequence of numbers, based on some algorithm and
internal state. The numbers do not have any statistical properties
(such as uniform distribution or independence of successive values).
<p>
<em>Note:</em> Quasi-random number generators are useful for
Monte-Carlo integrations where specially crafted sequences of random
numbers will make the approximation converge faster.
<p>
<em>[Does anyone have a model?]</em>
<p>
<hr>
Jens Maurer, 2000-02-23
</body>
</html>

738
random-distributions.html Normal file
View File

@@ -0,0 +1,738 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Random Number Library Distributions</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>Random Number Library Distributions</h1>
<ul>
<li><a href="#intro">Introduction</a>
<li><a href="#synopsis">Synopsis</a>
<li><a href="#uniform_smallint">Class template
<code>uniform_smallint</code></a>
<li><a href="#uniform_int">Class template <code>uniform_int</code></a>
<li><a href="#uniform_01">Class template <code>uniform_01</code></a>
<li><a href="#uniform_real">Class template
<code>uniform_real</code></a>
<li><a href="#bernoulli_distribution">Class template
<code>bernoulli_distribution</code></a>
<li><a href="#geometric_distribution">Class template
<code>geometric_distribution</code></a>
<li><a href="#triangle_distribution">Class template
<code>triangle_distribution</code></a>
<li><a href="#exponential_distribution">Class template
<code>exponential_distribution</code></a>
<li><a href="#normal_distribution">Class template
<code>normal_distribution</code></a>
<li><a href="#lognormal_distribution">Class template
<code>lognormal_distribution</code></a>
<li><a href="#uniform_on_sphere">Class template
<code>uniform_on_sphere</code></a>
</ul>
<h2><a name="intro">Introduction</a></h2>
In addition to the <a href="random-generators.html">random number
generators</a>, this library provides distribution functions which map
one distribution (often a uniform distribution provided by some
generator) to another.
<p>
Usually, there are several possible implementations of any given
mapping. Often, there is a choice between using more space, more
invocations of the underlying source of random numbers, or more
time-consuming arithmetic such as trigonometric functions. This
interface description does not mandate any specific implementation.
However, implementations which cannot reach certain values of the
specified distribution or otherwise do not converge statistically to
it are not acceptable.
<p>
<table border="1">
<tr><th>distribution</th><th>explanation</th><th>example</th></tr>
<tr>
<td><code><a href="#uniform_smallint">uniform_smallint</a></code></td>
<td>discrete uniform distribution on a small set of integers (much
smaller than the range of the underlying generator)</td>
<td>drawing from an urn</td>
</tr>
<tr>
<td><code><a href="#uniform_int">uniform_int</a></code></td>
<td>discrete uniform distribution on a set of integers; the underlying
generator may be called several times to gather enough randomness for
the output</td>
<td>drawing from an urn</td>
</tr>
<tr>
<td><code><a href="#uniform_01">uniform_01</a></code></td>
<td>continuous uniform distribution on the range [0,1); important
basis for other distributions</td>
<td>-</td>
</tr>
<tr>
<td><code><a href="#uniform_real">uniform_real</a></code></td>
<td>continuous uniform distribution on some range [min, max) of real
numbers</td>
<td>for the range [0, 2pi): randomly dropping a stick and measuring
its angle in radiants (assuming the angle is uniformly
distributed)</td>
</tr>
<tr>
<td><code><a href="#bernoulli_distribution">bernoulli_distribution</a></code></td>
<td>Bernoulli experiment: discrete boolean valued distribution with
configurable probability</td>
<td>tossing a coin (p=0.5)</td>
</tr>
<tr>
<td><code><a href="#geometric_distribution">geometric_distribution</a></code></td>
<td>measures distance between outcomes of repeated Bernoulli experiments</td>
<td>throwing a die several times and counting the number of tries
until a "6" appears for the first time</td>
</tr>
<tr>
<td><code><a href="#triangle_distribution">triangle_distribution</a></code></td>
<td>?</td>
<td>?</td>
</tr>
<tr>
<td><code><a href="#exponential_distribution">exponential_distribution</a></code></td>
<td>exponential distribution</td>
<td>measuring the inter-arrival time of alpha particles emitted by
radioactive matter</td>
</tr>
<tr>
<td><code><a href="#normal_distribution">normal_distribution</a></code></td>
<td>counts outcomes of (infinitely) repeated Bernoulli experiments</td>
<td>tossing a coin 10000 times and counting how many front sides are shown</td>
</tr>
<tr>
<td><code><a href="#lognormal_distribution">lognormal_distribution</a></code></td>
<td>lognormal distribution (sometimes used in simulations)</td>
<td>measuring the job completion time of an assembly line worker</td>
</tr>
<tr>
<td><code><a href="#uniform_on_sphere">uniform_on_sphere</a></code></td>
<td>uniform distribution on a unit sphere of arbitrary dimension</td>
<td>choosing a random point on Earth (assumed to be a sphere) where to
spend the next vacations</td>
</tr>
</table>
<p>
The template parameters of the distribution functions are always in
the order
<ul>
<li>Underlying source of random numbers
<li>If applicable, return type, with a default to a reasonable type.
</ul>
<p>
All distribution functions satisfy the input iterator requirements
(std:24.1.1 [lib.input.iterators]) in addition to the NumberGenerator
requirements. After an invocation of <code>operator()</code>, the
effects of invocations of <code>operator*</code> are undefined until
the next call to <code>operator++</code>.
<p>
In this description, I have refrained from documenting those members
in detail which are already defined in the
<a href="random-concepts.html">concept documentation</a>.
<h2><a name="synopsis">Synopsis of the distributions</a> in header
<code>&lt;boost/random.hpp&gt;</code> </h2>
<pre>
namespace boost {
template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class uniform_smallint;
template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class uniform_int;
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class uniform_01;
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class uniform_real;
// discrete distributions
template&lt;class UniformRandomNumberGenerator&gt;
class bernoulli_distribution;
template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class geometric_distribution;
// continuous distributions
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class triangle_distribution;
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class exponential_distribution;
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class normal_distribution;
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class lognormal_distribution;
template&lt;class UniformRandomNumberGenerator, class RealType = double,
class Cont = std::vector&lt;RealType&gt; &gt;
class uniform_on_sphere;
}
</pre>
<h2><a name="uniform_smallint">Class template
<code>uniform_smallint</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class uniform_smallint
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef IntType result_type;
static const bool has_fixed_range = false;
uniform_smallint(base_type & rng, IntType min, IntType max);
result_type operator()();
result_type min() const;
result_type max() const;
};
</pre>
<h3>Description</h3>
The distribution function <code>uniform_smallint</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>. On each invocation, it returns a random integer value
uniformly distributed in the set of integer numbers {min, min+1,
min+2, ..., max}. It assumes that the desired range (max-min+1) is
small compared to the range of the underlying source of random
numbers and thus makes no attempt to limit quantization errors.
<p>
Let r<sub>out</sub>=(max-min+1) the desired range of integer numbers,
and let r<sub>base</sub> be the range of the underlying source of
random numbers. Then, for the uniform distribution, the theoretical
probability for any number i in the range r<sub>out</sub> will be
p<sub>out</sub>(i) = 1/r<sub>out</sub>. Likewise, assume a uniform
distribution on r<sub>base</sub> for the underlying source of random
numbers, i.e. p<sub>base</sub>(i) = 1/r<sub>base</sub>. Let
p<sub>out_s</sub>(i) denote the random distribution generated by
<code>uniform_smallint</code>. Then the sum over all i in
r<sub>out</sub> of (p<sub>out_s</sub>(i)/p<sub>out</sub>(i)
-1)<sup>2</sup> shall not exceed
r<sub>out</sub>/r<sub>base</sub><sup>2</sup> (r<sub>base</sub> mod
r<sub>out</sub>)(r<sub>out</sub> - r<sub>base</sub> mod
r<sub>out</sub>).
<p>
The template parameter <code>UniformRandomNumberGenerator</code> shall
denote a class which models a uniform random number generator.
Additionally, <code>UniformRandomNumberGenerator::result_type</code>
shall denote an integral type. The template parameter
<code>IntType</code> shall denote an integer-like value type.
<p>
<em>Note:</em> The property above is the square sum of the relative
differences in probabilities between the desired uniform distribution
p<sub>out</sub>(i) and the generated distribution
p<sub>out_s</sub>(i). The property can be fulfilled with the
calculation (base_rng mod r<sub>out</sub>), as follows: Let r =
r<sub>base</sub> mod r<sub>out</sub>. The base distribution on
r<sub>base</sub> is folded onto the range r<sub>out</sub>. The
numbers i &lt; r have assigned (r<sub>base</sub> div
r<sub>out</sub>)+1 numbers of the base distribution, the rest has only
(r<sub>base</sub> div r<sub>out</sub>). Therefore,
p<sub>out_s</sub>(i) = ((r<sub>base</sub> div r<sub>out</sub>)+1) /
r<sub>base</sub> for i &lt; r and p<sub>out_s</sub>(i) =
(r<sub>base</sub> div r<sub>out</sub>)/r<sub>base</sub> otherwise.
Substituting this in the above sum formula leads to the desired
result.
<p>
<em>Note:</em> The upper bound for (r<sub>base</sub> mod r<sub>out</sub>)(r<sub>out</sub> - r<sub>base</sub>
mod r<sub>out</sub>) is r<sub>out</sub><sup>2</sup>/4. Regarding the upper bound for the square
sum of the relative quantization error of r<sub>out</sub><sup>3</sup>/(4*r<sub>base</sub><sup>2</sup>), it
seems wise to either choose r<sub>base</sub> so that r<sub>base</sub> &gt; 10*r<sub>out</sub><sup>2</sup> or
ensure that r<sub>base</sub> is divisible by r<sub>out</sub>.
<h3>Members</h3>
<pre>uniform_smallint(base_type & rng, IntType min, IntType max)</pre>
<strong>Effects:</strong> Constructs a <code>uniform_smallint</code>
functor with the uniform random number generator <code>rng</code> as
the underlying source of random numbers. <code>min</code> and
<code>max</code> are the lower and upper bounds of the output range,
respectively.
<h2><a name="uniform_int">Class template <code>uniform_int</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class uniform_int
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef IntType result_type;
static const bool has_fixed_range = false;
uniform_int(base_type & rng, IntType min, IntType max);
IntType operator()();
result_type min() const;
result_type max() const;
};
</pre>
<h3>Description</h3>
The distribution function <code>uniform_int</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>. On each invocation, it returns a random integer
value uniformly distributed in the set of integer numbers
{min, min+1, min+2, ..., max}.
<p>
The template parameter <code>IntType</code> shall denote an
integer-like value type.
<h3>Members</h3>
<pre>uniform_int(base_type & rng, IntType min, IntType max)</pre>
<strong>Effects:</strong> Constructs a <code>uniform_int</code> functor
with the uniform random number generator <code>rng</code> as the
underlying source of random numbers. <code>min</code> and
<code>max</code> are the lower and upper bounds of the output range,
respectively.
<p>
<em>Note:</em> Invocations of <code>operator()</code> may call the
underlying generator several times and concatenate the result to build
the required range. Thus, using this distribution with generators
such as linear congruential ones which tend to produce non-random bits
in some positions is strongly discouraged.
<h2><a name="uniform_01">Class template <code>uniform_01</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class uniform_01
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef RealType result_type;
static const bool has_fixed_range = false;
explicit uniform_01(base_type & rng);
result_type operator()();
result_type min() const;
result_type max() const;
};
</pre>
<h3>Description</h3>
The distribution function <code>uniform_01</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>. On each invocation, it returns a random floating-point
value uniformly distributed in the range [0..1).
The value is computed using
<code>std::numeric_limits&lt;RealType&gt;::digits</code> random binary
digits, i.e. the mantissa of the floating-point value is completely
filled with random bits. [<em>Note:</em> Should this be configurable?]
<p>
The template parameter <code>RealType</code> shall denote a float-like
value type with support for binary operators +, -, and /. It must be
large enough to hold floating-point numbers of value
<code>rng.max()-rng.min()+1</code>.
<p>
<code>base_type::result_type</code> must be a number-like value type,
it must support <code>static_cast&lt;&gt;</code> to
<code>RealType</code> and binary operator -.
<p>
<em>Note:</em> The current implementation is buggy, because it may not
fill all of the mantissa with random bits. I'm unsure how to fill a
(to-be-invented) <code>boost::bigfloat</code> class with random bits
efficiently. It's probably time for a traits class.
<h3>Members</h3>
<pre>explicit uniform_01(base_type & rng)</pre>
<strong>Effects:</strong> Constructs a <code>uniform_01</code> functor
with the given uniform random number generator as the underlying
source of random numbers.
<h2><a name="uniform_real">Class template <code>uniform_real</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class uniform_real
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef RealType result_type;
static const bool has_fixed_range = false;
uniform_real(base_type & rng, RealType min, RealType max);
result_type operator()();
result_type min() const;
result_type max() const;
};
</pre>
<h3>Description</h3>
The distribution function <code>uniform_real</code> models a
<a href="random-concepts.html#uniform-rng">uniform random number
generator</a>. On each invocation, it returns a random floating-point
value uniformly distributed in the range [min..max). The value is
computed using
<code>std::numeric_limits&lt;RealType&gt;::digits</code> random binary
digits, i.e. the mantissa of the floating-point value is completely
filled with random bits.
<p>
<em>Note:</em> The current implementation is buggy, because it may not
fill all of the mantissa with random bits.
<h3>Members</h3>
<pre>explicit uniform_real(base_type & rng, RealType min, RealType max)</pre>
<strong>Effects:</strong> Constructs a <code>uniform_real</code>
functor. <code>rng</code> specifies the uniform random number
generator to be used as the underlying source of random numbers,
<code>min</code> and <code>max</code> are the lower and upper bounds of
the output range.
<h2><a name="bernoulli_distribution">Class template
<code>bernoulli_distribution</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator&gt;
class bernoulli_distribution
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef bool result_type;
bernoulli_distribution(base_type & rng, double q);
result_type operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>bernoulli_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>. It transforms a uniform distribution into a Bernoulli
one.
<h3>Members</h3>
<pre>bernoulli_distribution(base_type & rng, double q)</pre>
<strong>Effects:</strong> Constructs a
<code>bernoulli_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>q</code> is the parameter for the distribution.
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random boolean value with p(true) = q and
p(false) = 1-q. For example, with q = 1/2 this can be interpreted as
tossing a coin.
<h2><a name="geometric_distribution">Class template
<code>geometric_distribution</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class IntType = int&gt;
class geometric_distribution
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef IntType result_type;
geometric_distribution(base_type& rng, double q);
result_type operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>geometric_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>. It transforms a uniform distribution into a geometric
one.
<h3>Members</h3>
<pre>geometric_distribution(base_type& rng, const result_type& q)</pre>
<strong>Effects:</strong> Constructs a
<code>geometric_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>q</code> is the parameter for the distribution.
<p>
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random integer value <em>i</em> >= 1 with
p(i) = (1-q) * q<sup>i-1</sup>. For example, with q = 5/6 this can be
interpreted as the number of times one has to roll a die until a given
number shows up.
<h2><a name="triangle_distribution">Class template
<code>triangle_distribution</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class triangle_distribution
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef RealType result_type;
triangle_distribution(base_type& rng, result_type a, result_type b, result_type c);
result_type operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>triangle_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>. It transforms a uniform distribution into a triangle
one.
<h3>Members</h3>
<pre>triangle_distribution(base_type& rng, result_type a, result_type b, result_type c)</pre>
<strong>Effects:</strong> Constructs a
<code>triangle_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>a, b, c</code> are the parameters for the distribution.
<p>
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random floating-point value <code>x</code>
where <code>a <= x <= c</code>; <code>x</code> has a triangle
distribution, where <code>b</code> is the most probable value for
<code>x</code>.
<h2><a name="exponential_distribution">Class template
<code>exponential_distribution</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class exponential_distribution
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef RealType result_type;
exponential_distribution(base_type& rng, const result_type& lambda);
result_type operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>exponential_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>. It transforms a uniform distribution into an
exponential one.
<h3>Members</h3>
<pre>exponential_distribution(base_type& rng, const result_type& lambda)</pre>
<strong>Effects:</strong> Constructs an
<code>exponential_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>lambda</code> is the parameter for the distribution.
<p>
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random floating-point value <em>x</em>
&gt; 0 with p(x) = <code>lambda</code> * exp(-<code>lambda</code> *
x).
<h2><a name="normal_distribution">Class template
<code>normal_distribution</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class normal_distribution
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef RealType result_type;
explicit normal_distribution(base_type& rng, const result_type& mean = 0,
const result_type& sigma = 1);
result_type operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>normal_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>. It transforms a uniform distribution into a
normal (Gaussian) one.
<h3>Members</h3>
<pre>normal_distribution(base_type& rng, const result_type& mean = 0,
const result_type& sigma = 1)</pre>
<strong>Effects:</strong> Constructs a
<code>normal_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>mean</code> and <code>sigma</code> are the parameters for
the distribution.
<p>
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random floating-point value <em>x</em>
with p(x) = 1/sqrt(2*pi*sigma) * exp(- (x-mean)<sup>2</sup> /
(2*sigma<sup>2</sup>) ).
<h2><a name="lognormal_distribution">Class template
<code>lognormal_distribution</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double&gt;
class lognormal_distribution
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef RealType result_type;
explicit lognormal_distribution(base_type& rng, const result_type& mean,
const result_type& sigma);
result_type operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>lognormal_distribution</code>
model a <a href="random-concepts.html#number_generator">number
generator</a>. It transforms a uniform distribution into a
lognormal one.
<h3>Members</h3>
<pre>lognormal_distribution(base_type& rng, const result_type& mean = 0,
const result_type& sigma = 1)</pre>
<strong>Effects:</strong> Constructs a
<code>normal_distribution</code> functor with the uniform random
number generator <code>rng</code> as the underlying source of random
numbers. <code>mean</code> and <code>sigma</code> are the parameters for
the distribution.
<p>
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A random floating-point value <em>x</em>
with p(x) = 1/(x * sigma * sqrt(2*pi*sigma)) * exp(-
(log(x)-mean)<sup>2</sup> / (2*sigma<sup>2</sup>) ) for x > 0.
<h2><a name="uniform_on_sphere">Class template
<code>uniform_on_sphere</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class RealType = double,
class Cont = std::vector&lt;RealType&gt; &gt;
class uniform_on_sphere
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef Cont result_type;
explicit uniform_on_sphere(base_type & rng, int dim = 2);
const result_type & operator()();
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>uniform_on_sphere</code> model a
Generator (std:25.2.6 [lib.alg.generate]). It transforms a uniform
distribution into a uniform distribution on the unit sphere of
arbitrary dimension. The <code>Cont</code> template parameter must be
a STL-like container type with <code>begin</code> and <code>end</code>
operations returning non-const ForwardIterators of type
<code>Cont::iterator</code>.
<h3>Members</h3>
<pre>explicit uniform_on_sphere(base_type & rng, int dim = 2)</pre>
<strong>Effects:</strong> Constructs a <code>uniform_on_sphere</code>
functor with the uniform random number generator <code>rng</code> as
the underlying source of random numbers. <code>dim</code> is the
dimension of the sphere.
<p>
<pre>result_type operator()()</pre>
<strong>Returns:</strong> A position on the unit sphere of
<code>dim</code> dimensions in cartesian coordinates. The positions
are uniformly distributed on the unit sphere.
<p>
<strong>Complexity:</strong> Proportional to the number of dimensions.
<p>
<hr>
Jens Maurer, 2000-06-14
</body>
</html>

780
random-generators.html Normal file
View File

@@ -0,0 +1,780 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Random Number Library Generators</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>Random Number Library Generators</h1>
<ul>
<li><a href="#intro">Introduction</a>
<li><a href="#synopsis">Synopsis</a>
<li><a href="#const_mod">Class template
<code>detail::const_mod</code></a>
<li><a href="#linear_congruential">Class template
<code>detail::linear_congruential</code></a>
<li><a href="#rand48">Class <code>rand48</code></a>
<li><a href="#additive_combine">Class template
<code>detail::additive_combined</code></a>
<li><a href="#shuffle_output">Class template
<code>detail::shuffle_output</code></a>
<li><a href="#inversive_congruential">Class template
<code>detail::inversive_congruential</code></a>
<li><a href="#mersenne_twister">Class template
<code>detail::mersenne_twister</code></a>
<li><a href="#performance">Performance</a>
</ul>
<h2><a name="intro">Introduction</a></h2>
This library provides several pseudo-random number generators.
The quality of a pseudo-random number generator crucially depends on
both the algorithm and its parameters. This library implements the
algorithms as class templates with template value parameters, hidden
in namespace <code>detail</code>. Any particular choice of parameters
is represented as the appropriately specializing <code>typedef</code>
in namespace <code>boost</code>.
<p>
The following table gives an overview of some characteristics of the
generators. The cycle length is a rough estimate of the quality of
the generator; the approximate relative speed is a performance
measure, higher numbers mean faster random number generation.
<p>
<table border="1">
<tr><th>generator</th><th>length of cycle</th><th>memory
requirements</th><th>approximate relative speed</th><th>comment</th></tr>
<tr>
<td><a href="#minstd_rand"><code>minstd_rand</code></a></td>
<td>2**31-2</td>
<td><code>sizeof(int32_t)</code></td>
<td>0.4</td>
<td>-</td>
</tr>
<tr>
<td><a href="#rand48"><code>rand48</code></a></td>
<td>2**48-1</td>
<td><code>sizeof(uint64_t)</code></td>
<td>0.8</td>
<td>-</td>
</tr>
<tr>
<td><code>lrand48</code> (C library)</td>
<td>2**48-1</td>
<td>-</td>
<td>0.2</td>
<td>global state</td>
</tr>
<tr>
<td><a href="#ecuyer1988"><code>ecuyer1988</code></a></td>
<td>approx. 2**61</td>
<td><code>2*sizeof(int32_t)</code></td>
<td>0.2</td>
<td>-</td>
</tr>
<tr>
<td><code><a href="#kreutzer1986">kreutzer1986</a></code></td>
<td>?</td>
<td><code>1368*sizeof(uint32_t)</code></td>
<td>0.6</td>
<td>-</td>
</tr>
<tr>
<td><code><a href="#hellekalek1995">hellekalek1995</a></code></td>
<td>2**31-1</td>
<td><code>sizeof(int32_t)</code></td>
<td>0.03</td>
<td>good uniform distribution in several dimensions</td>
</tr>
<tr>
<td><code><a href="#mt11213b">mt11213b</a></code></</td>
<td>2**11213-1</td>
<td><code>352*sizeof(uint32_t)</code></td>
<td>1</td>
<td>good uniform distribution in up to 350 dimensions</td>
</tr>
<tr>
<td><code><a href="#mt19937">mt19937</a></code></</td>
<td>2**19937-1</td>
<td><code>625*sizeof(uint32_t)</code></td>
<td>1</td>
<td>good uniform distribution in up to 623 dimensions</td>
</tr>
</table>
<p>
As observable from the table, there is generally a
quality/performance/memory trade-off to be decided upon when choosing
a random-number generator. The multitude of generators provided in
this library allows the application programmer to optimize the
trade-off with regard to his application domain. Additionally,
employing several fundamentally different random number generators for
a given application of Monte Carlo simulation will improve the
confidence in the results.
<p>
<em>Note:</em> These random number generators are not indended for use
in applications where non-deterministic random numbers are required.
See <a href="nondet_random.html">nondet_random.html</a> for a choice
of (hopefully) non-deterministic random number generators.
<p>
In this description, I have refrained from documenting those members
in detail which are already defined in the
<a href="random-concepts.html">concept documentation</a>.
<h2><a name="synopsis">Synopsis of the generators</a> in header
<code>&lt;boost/random.hpp&gt;</code></h2>
<pre>
namespace boost {
namespace detail {
template&lt;class IntType, IntType m&gt;
class const_mod;
template&lt;class IntType, IntType a, IntType c, IntType m, IntType val&gt;
class linear_congruential;
}
class rand48;
typedef detail::linear_congruential&lt; /* ... */ &gt minstd_rand0;
typedef detail::linear_congruential&lt; /* ... */ &gt minstd_rand;
namespace detail {
template&lt;class DataType, int n, int m, int r, DataType a, int u,
int s, DataType b, int t, DataType c, int l, IntType val&gt;
class mersenne_twister;
}
typedef detail::mersenne_twister&lt; /* ... */ &gt; mt11213b;
typedef detail::mersenne_twister&lt; /* ... */ &gt; mt19937;
} // namespace boost
</pre>
<h2><a name="const_mod">Class template
<code>detail::const_mod</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class IntType, IntType m&gt;
class detail::const_mod
{
public:
template&lt;IntType c&gt;
static IntType add(IntType x);
template&lt;IntType a&gt;
static IntType mult(IntType x);
template&lt;IntType a, IntType c&gt;
static IntType mult_add(IntType x);
static IntType invert(IntType x);
private:
const_mod(); // don't instantiate
};
</pre>
<h3>Description</h3>
Class template <code>const_mod</code> provides functions performing
modular arithmetic, carefully avoiding overflows. All member
functions are static; there shall be no objects of type
<code>const_mod&lt;&gt;</code>.
<p>
The template parameter <code>IntType</code> shall denote an integral
type, <code>m</code> is the modulus.
<p>
<em>Note:</em> For modulo multiplications with large m, a trick allows
fast computation under certain conditions, see
<blockquote>
"A more portable FORTRAN random number generator", Linus Schrage, ACM
Transactions on Mathematical Software, Vol. 5, No. 2, June 1979, pp. 132-138
</blockquote>
<h3>Member functions</h3>
<pre>template&lt;IntType c&gt; static IntType add(IntType x)</pre>
<strong>Returns:</strong> (x+c) mod m
<pre>template&lt;IntType a&gt; static IntType mult(IntType x)</pre>
<strong>Returns:</strong> (a*x) mod m
<pre>template&lt;IntType a, IntType c&gt; static IntType
mult_add(IntType x)</pre>
<strong>Returns:</strong> (a*x+c) mod m
<pre>static IntType invert(IntType x)</pre>
<strong>Returns:</strong> i so that (a*i) mod m == 1
<br>
<strong>Precondition:</strong> m is prime
<h2><a name="linear_congruential">Class template
<code>detail::linear_congruential</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class IntType, IntType a, IntType c, IntType m&gt;
class linear_congruential
{
public:
typedef IntType result_type;
static const IntType multiplier = a;
static const IntType increment = c;
static const IntType modulus = m;
static const bool has_fixed_range = true;
static const result_type min_value;
static const result_type max_value;
explicit linear_congruential_fixed(IntType x0 = 1);
// compiler-generated copy constructor and assignment operator are fine
void seed(IntType x0);
IntType operator()();
};
typedef detail::linear_congruential&lt;long, 16807L, 0, 2147483647L,
1043618065L&gt; minstd_rand0;
typedef detail::linear_congruential&lt;long, 48271L, 0, 2147483647L,
399268537L&gt; minstd_rand;
</pre>
<h3>Description</h3>
Instantiations of class template <code>linear_congruential</code>
model a <a href="random-concepts.html#pseudo-rng">pseudo-random number
generator</a>. Linear congruential pseudo-random number generators
are described in:
<blockquote>
"Mathematical methods in large-scale computing units", D. H. Lehmer,
Proc. 2nd Symposium on Large-Scale Digital Calculating Machines,
Harvard University Press, 1951, pp. 141-146
</blockquote>
Let x(n) denote the sequence of numbers returned by
some pseudo-random number generator. Then for the linear congruential
generator, x(n+1) := (a * x(n) + c) mod m. Parameters for the
generator are x(0), a, c, m.
The template parameter <code>IntType</code> shall denote an
integral type. It must be large enough to hold values a, c, and m.
The template parameters a and c must be smaller than m.
<p>
<em>Note:</em> The quality of the generator crucially depends on the
choice of the parameters. User code should use one of the sensibly
parameterized generators such as <code>minstd_rand</code> instead.
<br>
For each choice of the parameters a, c, m, some distinct type is
defined, so that the <code>static</code> members do not interfere with
regard to the one definition rule.
<h3>Members</h3>
<pre>explicit linear_congruential(IntType x0 = 1)</pre>
<strong>Effects:</strong> Constructs a
<code>linear_congruential</code> generator with x(0) :=
<code>x0</code>.
<pre>void seed(IntType x0)</pre>
<strong>Effects:</strong> Changes the current value x(n) of the
generator to <code>x0</code>.
<h3><a name="minstd_rand">Specializations</a></h3>
The specialization <code>minstd_rand0</code> was originally suggested
in
<blockquote>
A pseudo-random number generator for the System/360, P.A. Lewis,
A.S. Goodman, J.M. Miller, IBM Systems Journal, Vol. 8, No. 2, 1969,
pp. 136-146
</blockquote>
It is examined more closely together with <code>minstd_rand</code> in
<blockquote>
"Random Number Generators: Good ones are hard to find", Stephen
K. Park and Keith W. Miller, Communications of the ACM, Vol. 31,
No. 10, October 1988, pp. 1192-1201
</blockquote>
<h2><a name="rand48">Class <code>rand48</code></code></h2>
<h3>Synopsis</h3>
<pre>
class rand48
{
public:
typedef int32_t result_type;
static const bool has_fixed_range = true;
static const int32_t min_value = 0;
static const int32_t max_value = 0x7fffffff;
explicit rand48(int32_t x0 = 1);
explicit rand48(uint64_t x0);
// compiler-generated copy ctor and assignment operator are fine
void seed(int32_t x0);
void seed(uint64_t x0);
int32_t operator()();
};
</pre>
<h3>Description</h3>
Class <code>rand48</code> models a
<a href="random-concepts.html#pseudo-rng">pseudo-random number
generator</a>. It uses the linear congruential algorithm with the
parameters a = 0x5DEECE66D, c = 0xB, m = 2**48. It delivers identical
results to the <code>lrand48()</code> function available on some
systems (assuming <code>lcong48</code> has not been called).
<p>
It is only available on systems where <code>uint64_t</code> is provided.
<h3>Constructors</h3>
<pre>rand48(int32_t x0)</pre>
<strong>Effects:</strong> Constructs a <code>rand48</code> generator
with x(0) := (<code>x0</code> << 16) | 0x330e.
<pre>rand48(uint64_t x0)</pre>
<strong>Effects:</strong> Constructs a <code>rand48</code> generator
with x(0) := <code>x0</code>.
<h3>Seeding</h3>
<pre>void seed(int32_t x0)</pre>
<strong>Effects:</strong> Changes the current value x(n) of the
generator to (<code>x0</code> << 16) | 0x330e.
<pre>void seed(uint64_t x0)</pre>
<strong>Effects:</strong> Changes the current value x(n) of the
generator to <code>x0</code>.
<h2><a name="additive_combine">Class template
<code>detail::additive_combine</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class MLCG1, class MLCG2, typename MLCG1::result_type val&gt;
class detail::additive_combine
{
public:
typedef MLCG1 first_base;
typedef MLCG2 second_base;
typedef typename MLCG1::result_type result_type;
static const bool has_fixed_range = true;
static const result_type min_value = 1;
static const result_type max_value = MLCG1::max_value-1;
additive_combine();
additive_combine(typename MLCG1::result_type seed1,
typename MLCG2::result_type seed2);
result_type operator()();
bool validation(result_type x) const;
};
typedef detail::additive_combine&lt;
detail::linear_congruential&lt;int32_t, 40014, 0, 2147483563, 0&gt;,
detail::linear_congruential&lt;int32_t, 40692, 0, 2147483399, 0&gt;,
/* unknown */ 0&gt; ecuyer1988;
</pre>
<h3>Description</h3>
Instatiations of class template <code>additive_combine</code> model a
<a href="random-concepts.html#pseudo-rng">pseudo-random number
generator</a>. It combines two multiplicative linear congruential
number generators, i.e. those with c = 0. It is described in
<blockquote>
"Efficient and Portable Combined Random Number Generators", Pierre
L'Ecuyer, Communications of the ACM, Vol. 31, No. 6, June 1988,
pp. 742-749, 774
</blockquote>
The template parameters <code>MLCG1</code> and <code>MLCG2</code>
shall denote two different linear congruential number generators, each
with c = 0. Each invocation returns a random number X(n) := (MLCG1(n)
- MLCG2(n)) mod (m1 - 1), where m1 denotes the modulus of
<code>MLCG1</code>.
<p>
The template parameter <code>val</code> is the validation value
checked by <code>validation</code>.
<h3>Members</h3>
<pre>additive_combine()</pre>
<strong>Effects:</strong> Constructs an <code>additive_combine</code>
generator using the default constructors of the two base generators.
<pre>additive_combine(typename MLCG1::result_type seed1,
typename MLCG2::result_type seed2)</pre>
<strong>Effects:</strong> Constructs an <code>additive_combine</code>
generator, using <code>seed1</code> and <code>seed2</code> as the
constructor argument to the first and second base generator,
respectively.
<h3><a name="ecuyer1988">Specialization</a></h3>
The specialization <code>ecuyer1988</code> was suggested in the above
paper.
<h2><a name="shuffle_output">Class template
<code>detail::shuffle_output</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, int k,
class IntType = typename UniformRandomNumberGenerator::result_type,
typename UniformRandomNumberGenerator::result_type val = 0&gt;
class detail::shuffle_output
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef typename base_type::result_type result_type;
static const bool has_fixed_range = false;
shuffle_output();
template&lt;class T&gt; explicit shuffle_output(T seed);
explicit shuffle_output(const base_type & rng);
template&lt;class T&gt; void seed(T s);
result_type operator()();
result_type min() const;
result_type max() const;
bool validation(result_type) const;
};
</pre>
<h3>Description</h3>
Instatiations of class template <code>shuffle_output</code> model a
<a href="random-concepts.html#pseudo-rng">pseudo-random number
generator</a>. It mixes the output of some (usually linear
congruential) uniform random number generator to get better
statistical properties. According to Donald E. Knuth, "The Art of
Computer Programming, Vol. 2", the algorithm is described in
<blockquote>
"Improving a poor random number generator", Carter Bays and
S.D. Durham, ACM Transactions on Mathematical Software, Vol. 2, 1979,
pp. 59-64.
</blockquote>
The output of the base generator is buffered in an array of length
k. Every output X(n) has a second role: It gives an index into the
array where X(n+1) will be retrieved. Used array elements are
replaced with fresh output from the base generator.
<p>
Template parameters are the base generator and the array length k,
which should be around 100. As an implementation detail, the template
parameter <code>IntType</code> shall denote an integer-like type which
is large enough to hold integer numbers of value k *
<code>base_type::max()</code>. The template parameter
<code>val</code> is the validation value checked by
<code>validation</code>.
<h3>Members</h3>
<pre>shuffle_output()</pre>
<strong>Effects:</strong> Constructs a <code>shuffle_output</code>
generator by invoking the default constructor of the base generator.
<p>
<strong>Complexity:</strong> Exactly k+1 invocations of the base
generator.
<pre>template&lt;class T&gt; explicit shuffle_output(T seed)</pre>
<strong>Effects:</strong> Constructs a <code>shuffle_output</code>
generator by invoking the one-argument constructor of the base
generator with the parameter <code>seed</code>.
<p>
<strong>Complexity:</strong> Exactly k+1 invocations of the base
generator.
<pre>explicit shuffle_output(const base_type & rng)</pre>
<strong>Precondition:</strong> The template argument
<code>UniformRandomNumberGenerator</code> shall denote a
CopyConstructible type.
<p>
<strong>Effects:</strong> Constructs a <code>shuffle_output</code>
generator by using a copy of the provided generator.
<p>
<strong>Complexity:</strong> Exactly k+1 invocations of the base
generator.
<pre>template&lt;class T&gt; void seed(T s)</pre>
<strong>Effects:</strong> Invokes the one-argument <code>seed</code>
method of the base generator with the parameter <code>seed</code> and
re-initializes the internal buffer array.
<p>
<strong>Complexity:</strong> Exactly k+1 invocations of the base
generator.
<h3><a name="kreutzer1986">Specializations</a></h3>
According to Harry Erwin (private e-mail), the specialization
<code>kreutzer1986</code> was suggested in:
<blockquote>
"System Simulation: programming Styles and Languages (International
Computer Science Series)", Wolfgang Kreutzer, Addison-Wesley, December
1986.
</blockquote>
<h2><a name="inversive_congruential">Class template
<code>detail::inversive_congruential</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class IntType, IntType a, IntType b, IntType p&gt;
class detail::inversive_congruential
{
public:
typedef IntType result_type;
static const bool has_fixed_range = true;
static const result_type min_value = (b == 0 ? 1 : 0);
static const result_type max_value = p-1;
static const result_type multiplier = a;
static const result_type increment = b;
static const result_type modulus = p;
explicit inversive_congruential(IntType y0 = 1);
void seed(IntType y0);
IntType operator()();
};
typedef detail::inversive_congruential&lt;int32_t, 9102, 2147483647-36884165, 2147483647&gt; hellekalek1995;
</pre>
<h3>Description</h3>
Instantiations of class template <code>inversive_congruential</code> model a
<a href="random-concepts.html#pseudo-rng">pseudo-random number
generator</a>. It uses the inversive congruential algorithm (ICG)
described in
<blockquote>
"Inversive pseudorandom number generators: concepts, results and
links", Peter Hellekalek, In: "Proceedings of the 1995 Winter
Simulation Conference", C. Alexopoulos, K. Kang, W.R. Lilegdon, and
D. Goldsman (editors), 1995, pp. 255-262.
<a href="ftp://random.mat.sbg.ac.at/pub/data/wsc95.ps">ftp://random.mat.sbg.ac.at/pub/data/wsc95.ps</a>
</blockquote>
The output sequence is defined by x(n+1) = (a*inv(x(n)) - b) (mod p),
where x(0), a, b, and the prime number p are parameters of the
generator. The expression inv(k) denotes the multiplicative inverse
of k in the field of integer numbers modulo p, with inv(0) := 0.
<p>
The template parameter <code>IntType</code> shall denote a signed
integral type large enough to hold p; a, b, and p are the parameters
of the generators.
<p>
<em>Note:</em> The implementation currently uses the Euclidian
Algorithm to compute the multiplicative inverse. Therefore, the
inversive generators are about 10-20 times slower than the others (see
section"<a href="#performance">performance</a>"). However, the paper
talks of only 3x slowdown, so the Euclidian Algorithm is probably not
optimal for calculating the multiplicative inverse.
<h3>Members</h3>
<pre>inversive_congruential(IntType y0 = 1)</pre>
<strong>Effects:</strong> Constructs an
<code>inversive_congruential</code> generator with
<code>y0</code> as the initial state.
<pre>void seed(IntType y0)</pre>
<strong>Effects:</strong>
Changes the current state to <code>y0</code>.
<h3><a name="hellekalek1995">Specialization</a></h3>
The specialization <code>hellekalek1995</code> was suggested in the
above paper.
<h2><a name="mersenne_twister">Class template
<code>detail::mersenne_twister</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class DataType, int n, int m, int r, DataType a, int u,
int s, DataType b, int t, DataType c, int l, IntType val&gt;
class detail::mersenne_twister
{
public:
typedef DataType result_type;
static const bool has_fixed_range = true;
static const result_type min_value;
static const result_type max_value;
mersenne_twister();
explicit mersenne_twister(DataType value);
template&lt;class Generator&gt; explicit mersenne_twister(Generator & gen);
// compiler-generated copy ctor and assignment operator are fine
void seed();
void seed(DataType value);
template&lt;class Generator&gt; void seed(Generator & gen);
result_type operator()();
bool validation(result_type) const;
};
typedef mersenne_twister&lt;uint32_t,351,175,19,0xccab8ee7,11,7,0x31b6ab00,15,0xffe50000,17, /* unknown */ 0&gt; mt11213b;
typedef mersenne_twister&lt;uint32_t,624,397,31,0x9908b0df,11,7,0x9d2c5680,15,0xefc60000,18, 3346425566U&gt; mt19937;
</pre>
<h3>Description</h3>
Instantiations of class template <code>mersenne_twister</code> model a
<a href="random-concepts.html#pseudo-rng">pseudo-random number
generator</a>. It uses the algorithm described in
<blockquote>
"Mersenne Twister: A 623-dimensionally equidistributed uniform
pseudo-random number generator", Makoto Matsumoto and Takuji Nishimura,
ACM Transactions on Modeling and Computer Simulation: Special Issue
on Uniform Random Number Generation, Vol. 8, No. 1, January 1998,
pp. 3-30.
<a href="http://www.math.keio.ac.jp/matumoto/emt.html">http://www.math.keio.ac.jp/matumoto/emt.html</a>
</blockquote>
<em>Note: </em> The boost variant has been implemented from scratch
and does not derive from or use mt19937.c provided on the above WWW
site. However, it was verified that both produce identical output.
<br>
The quality of the generator crucially depends on the choice of the
parameters. User code should employ one of the sensibly parameterized
generators such as <code>mt19937</code> instead.
<br>
The generator requires considerable amounts of memory for the storage
of its state array. For example, <code>mt11213b</code> requires about
1408 bytes and <code>mt19937</code> requires about 2496 bytes.
<h3>Constructors</h3>
<pre>mersenne_twister()</pre>
<strong>Effects:</strong> Constructs a <code>mersenne_twister</code>
and calls <code>seed()</code>.
<pre>explicit mersenne_twister(DataType value)</pre>
<strong>Effects:</strong> Constructs a <code>mersenne_twister</code>
and calls <code>seed(value)</code>.
<pre>template&lt;class Generator&gt; explicit mersenne_twister(Generator & gen)</pre>
<strong>Effects:</strong> Constructs a <code>mersenne_twister</code>
and calls <code>seed(gen)</code>.
<h3>Seeding</h3>
<pre>void seed()</pre>
<strong>Effects:</strong> Calls <code>seed(4357)</code>.
<pre>void seed(DataType value)</pre>
<strong>Effects:</strong> Constructs a
<code>linear_congruential&lt;uint32_t, 69069, 0, 0, 0&gt;</code>
generator with the constructor parameter
<code>value</code> and calls <code>seed</code> with it.
<pre>template&lt;class Generator&gt; void seed(Generator & gen)</pre>
<strong>Effects:</strong> Sets the state of this
<code>mersenne_twister</code> to the values returned by <code>n</code>
invocations of <code>gen</code>.
<p>
<strong>Complexity:</strong> Exactly <code>n</code> invocations of <code>gen</code>.
<h3><a name="mt11213b"></a><a name="mt19937">Specializations</a></h3>
The specializations <code>mt11213b</code> and <code>mt19937</code> are
from the paper cited above.
<h2><a name="performance">Performance</a></h2>
The test program <a href="random_speed.cpp">random_speed.cpp</a>
measures the execution times of the
<a href="../../boost/random.hpp">random.hpp</a> implementation of the above
algorithms in a tight loop. The performance has been evaluated on a
Pentium Pro 200 MHz with gcc 2.95.2, Linux 2.2.13, glibc 2.1.2.
<p>
<table border=1>
<tr><th>class</th><th>time per invocation [usec]</th></tr>
<tr><td>rand48</td><td>0.096</td></tr>
<tr><td>rand48 run-time configurable</td><td>0.697</td></tr>
<tr><td>lrand48 glibc 2.1.2</td><td>0.844</td></tr>
<tr><td>minstd_rand</td><td>0.174</td></tr>
<tr><td>ecuyer1988</td><td>0.445</td></tr>
<tr><td>kreutzer1986</td><td>0.249</td></tr>
<tr><td>hellekalek1995 (inversive)</td><td>4.895</td></tr>
<tr><td>mt11213b</td><td>0.165</td></tr>
<tr><td>mt19937</td><td>0.165</td></tr>
<tr><td>mt19937 original</td><td>0.185</td></tr>
</table>
<p>
The measurement error is estimated at +/- 10 nsec.
<p>
<hr>
Jens Maurer, 2000-06-13
</body>
</html>

159
random-misc.html Normal file
View File

@@ -0,0 +1,159 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Random Number Generator Library (Miscellaneous)</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>Random Number Generator Library --- Miscellaneous Decorators</h1>
<ul>
<li><a href="#random_number_generator">Class template
<code>random_number_generator</code></a>
<li><a href="#generator_iterator">Class template
<code>generator_iterator</code></a>
</ul>
<h2>Introduction</h2>
These decorator class templates allow adaption of the random number
generators and distribution functions to concepts found in the C++
Standard Library, in particular the RandomNumberGenerator and the
InputIterator concepts. The latter adaption is useful, because the
the basic random number generators do not implement the InputIterator
requirements per se, in contrast to the distribution functions.
<h2><a name="synopsis">Synopsis</a> of miscellaneous decorators in
header <code>&lt;boost/random.hpp&gt;</code></h2>
<pre>
namespace boost {
template&lt;class UniformRandomNumberGenerator, class IntType = long&gt;
class random_number_generator;
template&lt;class Generator&gt;
class generator_iterator;
} // namespace boost
</pre>
<h2><a name="random_number_generator">Class template
<code>random_number_generator</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class UniformRandomNumberGenerator, class IntType = long&gt;
class random_number_generator
{
public:
typedef UniformRandomNumberGenerator base_type;
typedef IntType argument_type;
typedef IntType result_type;
random_number_generator(base_type & rng);
result_type operator()(argument_type n);
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>random_number_generator</code>
model a RandomNumberGenerator (std:25.2.11 [lib.alg.random.shuffle]).
On each invocation, it returns a uniformly distributed integer in
the range [0..<code>n</code>).
<p>
The template parameter <code>IntType</code> shall denote some
integer-like value type.
<p>
<em>Note:</em> I consider it unfortunate that the C++ Standard uses
the name RandomNumberGenerator for something rather specific.
<h3>Members</h3>
<pre>random_number_generator(base_type & rng)</pre>
<strong>Effects:</strong> Constructs a
<code>random_number_generator</code> functor with the given uniform
random number generator as the underlying source of random numbers.
<pre>result_type operator()(argument_type n)</pre>
<strong>Returns:</strong> The value of
<code>uniform_int&lt;base_type&gt;(rng, 0, n-1)()</code>.
<h2><a name="generator_iterator">Class template
<code>generator_iterator</code></a></h2>
<h3>Synopsis</h3>
<pre>
template&lt;class Generator&gt;
class generator_iterator
: equality_comparable&lt;generator_iterator&lt;Generator&gt; &gt;,
incrementable&lt;generator_iterator&lt;Generator&gt; &gt;,
dereferenceable&lt;generator_iterator&lt;Generator&gt;,
typename Generator::result_type&gt;
{
public:
typedef typename Generator::result_type value_type;
typedef std::ptrdiff_t difference_type;
typedef const typename Generator::result_type * pointer;
typedef const typename Generator::result_type & reference;
typedef std::input_iterator_tag iterator_category;
explicit generator_iterator(Generator & g);
generator_iterator& operator++();
reference operator*() const;
friend bool operator==(const generator_iterator&lt;Generator&gt;& x,
const generator_iterator&lt;Generator&gt;& y);
};
</pre>
<h3>Description</h3>
Instantiations of class template <code>generator_iterator</code>
satisfy the input iterator requirements (std:24.1.1
[lib.input.iterators]). It allows iterator-like access to a
generator, e.g. a NumberGenerator. Note that all distribution
functions now satisfy the input iterator requirements as-is. However,
the base generators do not.
<h3>Members</h3>
<pre>explicit generator_iterator(Generator & g)</pre>
<strong>Effects:</strong> Constructs a <code>generator_iterator</code>
with <code>g</code> as the underlying generator. Invokes the
underlying generator functor.
<pre>generator_iterator& operator++()</pre>
<strong>Effects:</strong> Invokes the underlying generator functor.
<p>
<strong>Returns:</strong> <code>*this</code>
<pre>reference operator*() const</pre>
<strong>Returns:</strong> The value of the last invocation of the
underlying generator functor.
<h3>Overloaded global operators</h3>
<pre>bool operator==(const generator_iterator&lt;Generator&gt;& x,
const generator_iterator&lt;Generator&gt;& y)</pre>
<strong>Returns:</strong> <code>true</code> iff the <code>x</code> and
<code>y</code> have been initialized with a reference to the same
generator functor and <code>*x == *y</code>.
<p>
<hr>
Jens Maurer, 2000-03-06
</body>
</html>