fcppt.random

Description

Random number generators and distributions.

Introduction Using Random Header files

Introduction

Random number generation support in C++03 is very poor, only consisting of std::rand to draw pseudo random numbers between 0 and RAND_MAX, and std::srand to seed the generator. Boost.Random and now C++11 both have much better facilities, which are outlined below.

• Pseudo random number generators are classes that only produce random numbers. They have different trade-offs in randomness and speed. In a way, they are very similar to the functions provided by C++03: They must be seeded and produce random numbers in a certain range.

• Distributions map random numbers drawn from a random number generator into a specific range, for example into the range of ints from 0 to 10. They are a very important addition, because doing this by hand is not only hard but also very error prone.

fcppt wraps some of the classes provided by Boost.Random, because their interfaces are designed in a way that allow many mistakes to be made.

• The pseudo random number generators are all copyable, although it is discouraged to do so. A generator should usually be shared with different distributions to ensure an overall diverse randomness.

• Some of the random number generators as well as some of the distributions have very arbitrary default parameters that shouldn't be used accidentally.

• Some distributions like boost::uniform_real_distribution also work with integers, while boost::uniform_int_distribution doesn't work with floats by accident.

To overcome this situation, fcppt wraps these classes, making the pseudo random number generators noncopyable, and removing all of the default parameters, replacing them by strong typedefs instead. It also does some additional type checks on the distributions.

Using Random

To actually draw random numbers, you have to create a (pseudo) random number generator first. Such a generator must be seeded, for example with a time value obtained from fcppt::chrono.

        typedef fcppt::random::generator::minstd_rand generator_type;

        generator_type generator(
                fcppt::random::generator::seed_from_chrono<
                        generator_type::seed
                >()
        );

fcppt::random::variate is a class that combines a generator and a distribution into a single callable class. It takes the generator by reference and is also noncopyable itself. We are first going to create a variate object with a uniform int distribution.

        typedef fcppt::random::distribution::uniform_int<
                int
        > uniform_int;

        typedef fcppt::random::variate<
                generator_type,
                uniform_int
        > variate;

        variate rng(
                generator,
                uniform_int(
                        uniform_int::min(
                                0
                        ),
                        uniform_int::max(
                                10
                        )
                )
        );

        print_values(
                rng
        );

print_values is a function that draws 20 numbers and prints them. For example, the code could print: 5 7 3 7 6 8 9 5 7 9 7 10 1 6 5 6 3 2 5 0.

print_values is defined as follows:

template<
        typename Rng
>
void
print_values(
        Rng &rng
)
{
        for(
                unsigned i = 0;
                i < 20;
                ++i
        )
                fcppt::io::cout()
                        << rng()
                        << FCPPT_TEXT(' ');

        fcppt::io::cout()
                << FCPPT_TEXT('\n');
}

Using different distributions works similar to using a uniform int distribution, for example a normal distribution can be used like this:

        typedef fcppt::random::distribution::normal<
                double
        > normal;

        typedef fcppt::random::variate<
                generator_type,
                normal
        > variate;

        variate rng(
                generator,
                normal(
                        normal::mean(
                                0.
                        ),
                        normal::sigma(
                                5.
                        )
                )
        );

        print_values(
                rng
        );

For example, the code could print: 0.441851 5.37344 -7.79767 1.89097 -2.03191 3.17695 3.55056 -1.17422 2.86699 -7.46394 5.63758 2.65694 1.35165 0.953806 4.9783 2.02385 4.69477 -2.96583 5.22453 4.10744.

Header files

Header file	Description
variate_fwd.hpp	Contains fcppt::random::variate's declaration.
variate_decl.hpp	Contains fcppt::random::variate's definition.
variate_impl.hpp	Contains the definition of fcppt::random::variate's member functions.
variate.hpp	Contains all of fcppt::random::variate
distribution/normal_fwd.hpp	Contains fcppt::random::distribution::normal's declaration.
distribution/normal_decl.hpp	Contains fcppt::random::distribution::normal's definition.
distribution/normal_impl.hpp	Contains the definition of fcppt::random::distribution::normal's member functions.
distribution/normal.hpp	Contains all of fcppt::random::distribution::normal
distribution/uniform_int_fwd.hpp	Contains fcppt::random::distribution::uniform_int's declaration.
distribution/uniform_int_decl.hpp	Contains fcppt::random::distribution::uniform_int's definition.
distribution/uniform_int_impl.hpp	Contains the definition of fcppt::random::distribution::uniform_int's member functions.
distribution/uniform_int.hpp	Contains all of fcppt::random::distribution::uniform_int
distribution/uniform_real_fwd.hpp	Contains fcppt::random::distribution::uniform_real's declaration.
distribution/uniform_real_decl.hpp	Contains fcppt::random::distribution::uniform_real's definition.
distribution/uniform_real_impl.hpp	Contains the definition of fcppt::random::distribution::uniform_real's member functions.
distribution/uniform_real.hpp	Contains all of fcppt::random::distribution::uniform_real
generator/basic_pseudo_fwd.hpp	Contains fcppt::random::generator::basic_pseudo's declaration.
generator/basic_pseudo_decl.hpp	Contains fcppt::random::generator::basic_pseudo's definition.
generator/basic_pseudo_impl.hpp	Contains the definition of fcppt::random::generator::basic_pseudo's member functions.
generator/basic_pseudo.hpp	Contains all of fcppt::random::generator::basic_pseudo
generator/minstd_rand_fwd.hpp	Contains fcppt::random::generator::minstd_rand's declaration.
generator/minstd_rand_decl.hpp	Contains fcppt::random::generator::minstd_rand's definition.
generator/minstd_rand_impl.hpp	Contains the definition of fcppt::random::generator::minstd_rand's member functions.
generator/minstd_rand.hpp	Contains all of fcppt::random::generator::minstd_rand
generator/seed_from_chrono.hpp	Contains fcppt::random::generator::seed_from_chrono

Classes
class	fcppt::random::distribution::normal< FloatType >
	A wrapper around a normal distribution. More...
class	fcppt::random::distribution::uniform_int< IntType >
	A wrapper around a uniform int distribution. More...
class	fcppt::random::distribution::uniform_real< FloatType >
	A wrapper around a uniform real distribution. More...
class	fcppt::random::generator::basic_pseudo< Generator >
	A wrapper around pseudo random number generators. More...
class	fcppt::random::variate< Generator, Distribution >
	Combines a generator and a distribution. More...

Macros
#define	FCPPT_RANDOM_DISTRIBUTION_DECLARE_CALL
	Declares the call operator for a distribution.
#define	FCPPT_RANDOM_DISTRIBUTION_DEFINE_CALL(template_decl, template_pre)
	Defines the call operator for a distribution.

Functions
template<typename Seed >
boost::enable_if < boost::is_integral< typename Seed::value_type >, Seed > ::type const	fcppt::random::generator::seed_from_chrono ()
	Creates a seed from a chrono clock.

Macro Definition Documentation

#define FCPPT_RANDOM_DISTRIBUTION_DECLARE_CALL

Value:

template<\
        typename Engine\
>\
result_type \
operator()(\
        Engine &\
)

Declares the call operator for a distribution.

#define FCPPT_RANDOM_DISTRIBUTION_DEFINE_CALL	(		template_decl,
			template_pre
	)

Value:

template_decl \
template<\
        typename Engine\
>\
typename \
template_pre :: result_type \
template_pre :: operator()(\
        Engine &_engine\
)\
{\
        return \
                wrapped_(\
                        _engine\
                );\
}

Defines the call operator for a distribution.

Parameters

template_decl	The template declaration, for example template<typename IntType>
template_pre	The class name with full scope, for example mynamespace::myclass<IntType> .

Function Documentation

template<typename Seed >

boost::enable_if< boost::is_integral< typename Seed::value_type >, Seed>::type const fcppt::random::generator::seed_from_chrono

(

)

Creates a seed from a chrono clock.

Creates a seed of type Seed from a chrono clock.

Template Parameters

The	seed type of a pseudo random number generator. Its value_type must be an integral type.

Note

If you use this function, you must link to boost.chrono

Returns

The seed