boost_1_45_0/libs/random/doc/random.qbk

[library Boost.Random
  [quickbook 1.5]
  [authors [Maurer, Jens]]
  [copyright 2000-2005 Jens Maurer, 2009 Steven Watanabe]
  [license
      Distributed under the Boost Software License, Version 1.0.
      (See accompanying file LICENSE_1_0.txt or copy at
      [@http://www.boost.org/LICENSE_1_0.txt])
  ]
  [purpose A complete system for random number generation]
]

[template sup[text]'''<superscript>'''[text]'''</superscript>''']

[template prng[text] [link boost_random.reference.concepts.pseudo_random_number_generator [text]]]
[template concepts[text] [link boost_random.reference.concepts [text]]]
[template generators[text] [link boost_random.reference.generators [text]]]
[template distributions[text] [link boost_random.reference.distributions [text]]]

[def __NumberGenerator [link boost_random.reference.concepts.number_generator NumberGenerator]]
[def __UniformRandomNumberGenerator [link boost_random.reference.concepts.uniform_random_number_generator UniformRandomNumberGenerator]]

[def __CopyConstructible [@boost:/doc/html/CopyConstructible.html CopyConstructible]]
[def __Assignable [@boost:/doc/html/Assignable.html Assignable]]
[def __LessThanComparable [@boost:/doc/html/LessThanComparable.html LessThanComparable]]
[def __EqualityComparable [@boost:/doc/html/EqualityComparable.html EqualityComparable]]
[def __Streamable Streamable]

[def __random_device [classref boost::random_device random_device]]
[def __random_number_generator [classref boost::random_number_generator random_number_generator]]
[def __variate_generator [classref boost::variate_generator variate_generator]]

[def __minstd_rand0 [classref boost::minstd_rand0 minstd_rand0]]
[def __minstd_rand [classref boost::minstd_rand minstd_rand]]
[def __rand48 [classref boost::rand48 rand48]]
[def __ecuyer1988 [classref boost::ecuyer1988 ecuyer1988]]
[def __kreutzer1986 [classref boost::kreutzer1986 kreutzer1986]]
[def __taus88 [classref boost::taus88 taus88]]
[def __hellekalek1995 [classref boost::hellekalek1995 hellekalek1995]]
[def __mt11213b [classref boost::mt11213b mt11213b]]
[def __mt19937 [classref boost::mt19937 mt19937]]
[def __lagged_fibonacci607 [classref boost::lagged_fibonacci607 lagged_fibonacci607]]
[def __lagged_fibonacci1279 [classref boost::lagged_fibonacci1279 lagged_fibonacci1279]]
[def __lagged_fibonacci2281 [classref boost::lagged_fibonacci2281 lagged_fibonacci2281]]
[def __lagged_fibonacci3217 [classref boost::lagged_fibonacci3217 lagged_fibonacci3217]]
[def __lagged_fibonacci4423 [classref boost::lagged_fibonacci4423 lagged_fibonacci4423]]
[def __lagged_fibonacci9689 [classref boost::lagged_fibonacci9689 lagged_fibonacci9689]]
[def __lagged_fibonacci19937 [classref boost::lagged_fibonacci19937 lagged_fibonacci19937]]
[def __lagged_fibonacci23209 [classref boost::lagged_fibonacci23209 lagged_fibonacci23209]]
[def __lagged_fibonacci44497 [classref boost::lagged_fibonacci44497 lagged_fibonacci44497]]
[def __ranlux3 [classref boost::ranlux3 ranlux3]]
[def __ranlux4 [classref boost::ranlux4 ranlux4]]
[def __ranlux64_3 [classref boost::ranlux64_3 ranlux64_3]]
[def __ranlux64_4 [classref boost::ranlux64_4 ranlux64_4]]
[def __ranlux3_01 [classref boost::ranlux3_01 ranlux3_01]]
[def __ranlux4_01 [classref boost::ranlux4_01 ranlux4_01]]
[def __ranlux64_3_01 [classref boost::ranlux64_3_01 ranlux64_3_01]]
[def __ranlux64_4_01 [classref boost::ranlux64_4_01 ranlux64_4_01]]

[def __uniform_smallint [classref boost::uniform_smallint uniform_smallint]]
[def __uniform_int [classref boost::uniform_int uniform_int]]
[def __uniform_01 [classref boost::uniform_01 uniform_01]]
[def __uniform_real [classref boost::uniform_real uniform_real]]
[def __bernoulli_distribution [classref boost::bernoulli_distribution bernoulli_distribution]]
[def __binomial_distribution [classref boost::binomial_distribution binomial_distribution]]
[def __cauchy_distribution [classref boost::cauchy_distribution cauchy_distribution]]
[def __gamma_distribution [classref boost::gamma_distribution gamma_distribution]]
[def __poisson_distribution [classref boost::poisson_distribution poisson_distribution]]
[def __geometric_distribution [classref boost::geometric_distribution geometric_distribution]]
[def __triangle_distribution [classref boost::triangle_distribution triangle_distribution]]
[def __exponential_distribution [classref boost::exponential_distribution exponential_distribution]]
[def __normal_distribution [classref boost::normal_distribution normal_distribution]]
[def __lognormal_distribution [classref boost::lognormal_distribution lognormal_distribution]]
[def __uniform_on_sphere [classref boost::uniform_on_sphere uniform_on_sphere]]

[include performance_data.qbk]

[section Introduction]

Random numbers are useful in a variety of applications. The Boost Random
Number Library (Boost.Random for short) provides a variety of
[generators generators] and [distributions distributions] to produce
random numbers having useful properties, such as uniform distribution.

You should read the [concepts concepts documentation] for an introduction and the
definition of the basic concepts. For a quick start, it may be sufficient
to have a look at [@boost:/libs/random/example/random_demo.cpp random_demo.cpp].

For a very quick start, here's an example:

  ``[classref boost::mt19937]`` rng;                 // produces randomness out of thin air
                                      // see pseudo-random number generators
  ``[classref boost::uniform_int]<>`` six(1,6);      // distribution that maps to 1..6
                                      // see random number distributions
  ``[classref boost::variate_generator]``<``[classref boost::mt19937]``&, ``[classref boost::uniform_int]``<> >
           die(rng, six);             // glues randomness with mapping
  int x = die();                      // simulate rolling a die

[endsect]

[section Tutorial]
[include tutorial.qbk]
[endsect]

[section Reference]

[section Concepts]
[include concepts.qbk]
[endsect]

[section Generators]
[include generators.qbk]
[endsect]

[section Distributions]
[include distributions.qbk]
[endsect]

[xinclude reference.xml]

[endsect]

[section Performance]
[include performance.qbk]
[endsect]

[section Rationale]

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.

[endsect]

[section History and Acknowledgements]

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.

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.

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.

Gary Powell contributed suggestions for code cleanliness. Dave Abrahams
and Howard Hinnant suggested to move the basic generator templates from
`namespace boost::detail` to `boost::random`.

Ed Brey asked to remove superfluous warnings and helped with `uint64_t`
handling. Andreas Scherer tested with MSVC. Matthias Troyer contributed
a [headerref boost/random/lagged_fibonacci.hpp lagged Fibonacci generator].
Michael Stevens found a bug in the copy semantics of __normal_distribution
and suggested documentation improvements.

[endsect]