[/
  Copyright 2011 - 2020 John Maddock.
  Copyright 2013 - 2019 Paul A. Bristow.
  Copyright 2013 Christopher Kormanyos.

  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).
]

[section:random Generating Random Numbers]

Random numbers are generated in conjunction with Boost.Random.

There is a single generator that supports generating random integers with large bit counts:
[@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`].
This type can be used with either ['unbounded] integer types, or with ['bounded] (ie fixed precision) unsigned integers:

[random_eg1]

Program output is:

[random_eg1_out]

In addition, the generator adaptors [@http://www.boost.org/doc/html/boost/random/discard_block_engine.html `discard_block`],
[@http://www.boost.org/doc/html/boost/random/xor_combine_engine.html `xor_combine_engine`] and
[@http://www.boost.org/doc/html/boost/random/discrete_distribution.html `discrete_distribution`] can be used
with multiprecision types.  Note that if you seed an `independent_bits_engine`, then you are actually seeding
the underlying generator, and should therefore provide a sequence of unsigned 32-bit values as the seed.

Alternatively we can generate integers in a given range using
[@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`], this will
invoke the underlying engine multiple times to build up the required number of bits in the result:

[random_eg2]

[random_eg2_out]

It is also possible to use [@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`]
with a multiprecision generator such as [@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`].
Or to use [@http://www.boost.org/doc/html/boost/random/uniform_smallint.html `uniform_smallint`] or
[@http://www.boost.org/doc/html/boost/random/random_number_generator.html `random_number_generator`] with multiprecision types.

floating-point values in \[0,1) are most easily generated using [@http://www.boost.org/doc/html/boost/random/generate_canonical.html `generate_canonical`],
note that `generate_canonical` will call the generator multiple times to produce the requested number of bits, for example we can use
it with a regular generator like so:

[random_eg3]

[random_eg3_out]

Note however, the distributions do not invoke the generator multiple times to fill up the mantissa of a multiprecision floating-point type
with random bits.  For these therefore, we should probably use a multiprecision generator (ie `independent_bits_engine`) in combination
with the distribution:

[random_eg4]

[random_eg4_out]

And finally, it is possible to use the floating-point generators [@http://www.boost.org/doc/html/boost/random/lagged_fibonacci_01_engine.html `lagged_fibonacci_01_engine`]
and [@http://www.boost.org/doc/html/boost/random/subtract_with_idp144360752.html `subtract_with_carry_01_engine`] directly with multiprecision floating-point types.
It's worth noting however, that there is a distinct lack of literature on generating high bit-count random numbers, and therefore a lack of "known good" parameters to
use with these generators in this situation.  For this reason, these should probably be used for research purposes only:

[random_eg5]

[endsect] [/section:random Generating Random Numbers]