<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<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/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>
Random numbers are useful in a variety of applications. The Boost
Random Number Library (Boost.Random for short) provides a vast variety
of generators and distributions to produce random numbers having
useful properties, such as uniform distribution.
<p>
You should read the
<a href="random-concepts.html">concepts documentation</a>
for an introduction and the definition of the basic concepts. For a
quick start, it may be sufficient to have a look at <a
href="random_demo.cpp">random_demo.cpp</a>.
<p>
For a very quick start, here's an example:
<pre>
boost::mt19937 rng; // produces randomness out of thin air
// see pseudo-random number generators
boost::uniform_int<> six(1,6) // distribution that maps to 1..6
// see random number distributions
boost::variate_generator<boost::mt19937, boost::uniform_int<> >
die(rng, six); // glues randomness with mapping
int x = die(); // simulate rolling a die
</pre>
<h2>Library Organization</h2>
The library is separated into several header files, all within the
<code>boost/random/</code> directory. Additionally, a convenience
header file which includes all other headers in
<code>boost/random/</code> is available as
<code><a href="../../boost/random.hpp">boost/random.hpp</a></code>.
<p>
A front-end class template called <code>variate_generate</code> is
provided; please read the
<a href="random-variate.html">documentation</a> about it.
<ul>
<li><code><a href="../../boost/random/variate_generator.hpp">boost/random/variate_generator.hpp</a></code>
</ul>
Several random number generators are available in the following
header files; please read the
<a href="random-generators.html">documentation</a> about these.
<ul>
<li><code><a href="../../boost/random/linear_congruential.hpp">boost/random/linear_congruential.hpp</a></code>
<li><code><a href="../../boost/random/additive_combine.hpp">boost/random/additive_combine.hpp</a></code>
<li><code><a href="../../boost/random/inversive_congruential.hpp">boost/random/inversive_congruential.hpp</a></code>
<li><code><a href="../../boost/random/shuffle_output.hpp">boost/random/shuffle_output.hpp</a></code>
<li><code><a href="../../boost/random/mersenne_twister.hpp">boost/random/mersenne_twister.hpp</a></code>
<li><code><a href="../../boost/random/lagged_fibonacci.hpp">boost/random/lagged_fibonacci.hpp</a></code>
</ul>
Similarly, several random number distributions are available in the
following header files; please read the
<a href="random-distributions.html">documentation</a> about these.
<ul>
<li><code><a href="../../boost/random/uniform_smallint.hpp">boost/random/uniform_smallint.hpp</a></code>
<li><code><a href="../../boost/random/uniform_int.hpp">boost/random/uniform_int.hpp</a></code>
<li><code><a href="../../boost/random/uniform_01.hpp">boost/random/uniform_01.hpp</a></code>
<li><code><a href="../../boost/random/uniform_real.hpp">boost/random/uniform_real.hpp</a></code>
<li><code><a href="../../boost/random/triangle_distribution.hpp">boost/random/triangle_distribution.hpp</a></code>
<li><code><a href="../../boost/random/bernoulli_distribution.hpp">boost/random/bernoulli_distribution.hpp</a></code>
<li><code><a href="../../boost/random/cauchy_distribution.hpp">boost/random/cauchy_distribution.hpp</a></code>
<li><code><a href="../../boost/random/exponential_distribution.hpp">boost/random/exponential_distribution.hpp</a></code>
<li><code><a href="../../boost/random/geometric_distribution.hpp">boost/random/geometric_distribution.hpp</a></code>
<li><code><a href="../../boost/random/normal_distribution.hpp">boost/random/normal_distribution.hpp</a></code>
<li><code><a href="../../boost/random/lognormal_distribution.hpp">boost/random/lognormal_distribution.hpp</a></code>
<li><code><a href="../../boost/random/uniform_on_sphere.hpp">boost/random/uniform_on_sphere.hpp</a></code>
</ul>
Additionally, non-deterministic random number generators are available
in the header
<code><a href="../../boost/nondet_random.hpp"><boost/nondet_random.hpp></a></code>.
<a href="nondet_random.html">Documentation</a> is also available.
<p>
In order to map the interface of the generators and distribution functions
to other concepts, some <a href="random-misc.html">decorators</a> are available.
<h2>Tests</h2>
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>
Some <a href="random-performance.html">performance results</a> obtained
using <a href="random_speed.cpp">random_speed.cpp</a> are also available.
<h2>Rationale</h2>
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>History and Acknowledgements</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 <code>enum</code> workaround. Dave
Abrahams highlighted quantization issues.
<p>
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 <code>min_rand</code>
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.
<p>
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.
<p>
Gary Powell contributed suggestions for code cleanliness. Dave
Abrahams and Howard Hinnant suggested to move the basic generator
templates from namespace <code>boost::detail</code> to
<code>boost::random</code>.
<p>
Ed Brey asked to remove superfluous warnings and helped with
<code>uint64_t</code> handling. Andreas Scherer tested with MSVC.
Matthias Troyer contributed a lagged Fibonacci generator. Michael
Stevens found a bug in the copy semantics of normal_distribution and
suggested documentation improvements.
<p>
<hr>
<a href="../../people/jens_maurer.htm">Jens Maurer</a>,
2001-08-31
</body>
</html>
