Uniform random number generator. More...

#include <RandomLib/RandomEngine.hpp>

Inheritance diagram for RandomLib::RandomEngine< Algorithm, Mixer >:

Public Types
enum	{ width = result_t::width }

typedef result_t::type	result_type

Public Types inherited from RandomLib::RandomSeed
typedef Random_u32	u32

typedef Random_u64	u64

typedef RandomType < 32, unsigned long >	seed_t

typedef seed_t::type	seed_type

Public Member Functions
Constructors
template<typename IntType >
	RandomEngine (const std::vector< IntType > &v)

template<typename InputIterator >
	RandomEngine (InputIterator a, InputIterator b)

	RandomEngine (seed_type n)

	RandomEngine ()

	RandomEngine (const std::string &s)

Functions for returning random data
result_type	Ran () throw ()

u32::type	Ran32 () throw ()

u64::type	Ran64 () throw ()

result_type	operator() () throw ()

Comparing Random objects
bool	operator== (const RandomEngine &r) const throw ()

bool	operator!= (const RandomEngine &r) const throw ()

Interchanging Random objects
void	swap (RandomEngine &t) throw ()

Writing to and reading from a stream
void	Save (std::ostream &os, bool bin=true) const

void	Load (std::istream &is, bool bin=true)

Examining and advancing the Random generator
long long	Count () const throw ()

void	SetCount (long long n) throw ()

void	StepCount (long long n) throw ()

void	Reset () throw ()

Leapfrogging
void	SetStride (unsigned n=1, unsigned k=0)

unsigned	GetStride () const throw ()

Public Member Functions inherited from RandomLib::RandomSeed
virtual	~RandomSeed ()=0 throw ()

template<typename IntType >
void	Reseed (const std::vector< IntType > &v)

template<typename InputIterator >
void	Reseed (InputIterator a, InputIterator b)

void	Reseed (seed_type n)

void	Reseed ()

void	Reseed (const std::string &s)

const std::vector< seed_type > &	Seed () const throw ()

std::string	SeedString () const

Static Public Member Functions
static void	SelfTest ()

static std::string	Name ()

Static Public Member Functions inherited from RandomLib::RandomSeed
static seed_type	SeedWord ()

static std::vector< seed_type >	SeedVector ()

template<typename IntType >
static std::string	VectorToString (const std::vector< IntType > &v)

static std::vector< seed_type >	StringToVector (const std::string &s)

Static Public Attributes
static const result_type	min = result_t::min

static const result_type	max = result_t::max

Static Protected Attributes
static const result_type	mask = result_t::mask

Friends
Basic I/O
std::ostream &	operator<< (std::ostream &os, const RandomEngine &r)

std::istream &	operator>> (std::istream &is, RandomEngine &r)

Additional Inherited Members
Protected Attributes inherited from RandomLib::RandomSeed
std::vector< seed_type >	_seed

Detailed Description

template<class Algorithm, class Mixer>
class RandomLib::RandomEngine< Algorithm, Mixer >

Uniform random number generator.

This implements a generic random number generator. Such a generator requires two data holders RandomSeed, to hold the seed, and RandomEngine, to hold the state. In addition we need two piece of machinery, a "Mixer" to convert the seed into an initial state and an "Algorithm" to advance the state.

Template Parameters

Algorithm	the random number algorithm.
Mixer	the way seeds are turned into state.

RandomSeed is responsible for setting and reporting the seed.

Mixer has no state and implements only static methods. It needs to have the following public interface

typedef mixer_t: a RandomType giving the output type
unsigned version: an identifying version number
static std::string Name(): an identifying name for the mixer
static method SeedToState: converts a seed into n words of state.

Algorithm has no state and implements only static methods. It needs to have the following public interface

typedef engine_t: a RandomType giving the output type
typedef internal_type: a integer type used by Transition. This is usually the same as engine_t::type. However it allows the use of vector instructions on some platforms. We require that engine_t::type and internal_type line up properly in a union so that there is no need to convert the data explicitly between internal_type and engine_t::type.
unsigned version: an identifying version number
static std::string Name(): an identifying name for the mixer
enum N: the size of the state in units of engine_t.
static method Transition: steps the generator forwards or backwards.
static method Generate: tempers the state immediately prior to output
static method NormalizeState: force the initial state (the result of the Mixer) into a legal state.
static method CheckState accumulates the checksum for the state into check. In addition it throws an exception if the state is bad.

RandomEngine is the glue that holds everything together. It repacks the mixer_t data from Mixer into engine_t if necessary. It deals with delivering individual random results, stepping the state forwards and backwards, leapfrogging the generator, I/O of the generator, etc.

Written by Charles Karney charl.nosp@m.es@k.nosp@m.arney.nosp@m..com and licensed under the MIT/X11 License. For more information, see http://randomlib.sourceforge.net/

Definition at line 81 of file RandomEngine.hpp.

Member Typedef Documentation

template<class Algorithm, class Mixer>

typedef result_t::type RandomLib::RandomEngine< Algorithm, Mixer >::result_type

A type large enough to hold width bits. This is used for the internal state of the generator and the result returned by Ran().

Definition at line 107 of file RandomEngine.hpp.

Member Enumeration Documentation

template<class Algorithm, class Mixer>

anonymous enum

The number of random bits produced by Ran().

Enumerator
width

Definition at line 99 of file RandomEngine.hpp.

Constructor & Destructor Documentation

template<class Algorithm, class Mixer>

template<typename IntType >

RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine ( const std::vector< IntType > & v )

inlineexplicit

Initialize from a vector. Only the low 32 bits of each element are used.

Template Parameters

IntType the integral type of the elements of the vector.

Parameters

[in] v the vector of elements.

Definition at line 200 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

template<typename InputIterator >

RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine	(	InputIterator	a,
		InputIterator	b
	)

inline

Initialize from a pair of iterators setting seed to [a, b). The iterator must produce results which can be converted into seed_type. Only the low 32 bits of each element are used.

Template Parameters

InputIterator the type of the iterator.

Parameters

[in]	a	the beginning iterator.
[in]	b	the ending iterator.

Definition at line 211 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine ( seed_type n )

inlineexplicit

Initialize with seed [n]. Only the low width bits of n are used.

Parameters

[in] n the new seed to use.

Definition at line 218 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine ( )

inline

Initialize with seed []. This can be followed by a call to Reseed() to select a unique seed.

Definition at line 223 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine ( const std::string & s )

inlineexplicit

Initialize from a string. See Reseed(const std::string& s)

Parameters

[in] s the string to be decoded into a seed.

Definition at line 229 of file RandomEngine.hpp.

Member Function Documentation

template<class Algorithm, class Mixer>

result_type RandomLib::RandomEngine< Algorithm, Mixer >::Ran	(	)
throw	(
	)

inline

Return width bits of randomness. This is the natural unit of random data produced random number generator.

Returns: the next random number of width width.

Definition at line 243 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

u32::type RandomLib::RandomEngine< Algorithm, Mixer >::Ran32	(	)
throw	(
	)

inline

Return 32 bits of randomness.

Returns: a 32-bit random number.

Definition at line 257 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

u64::type RandomLib::RandomEngine< Algorithm, Mixer >::Ran64	(	)
throw	(
	)

inline

Return 64 bits of randomness.

Returns: a 64-bit random number.

Definition at line 267 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

result_type RandomLib::RandomEngine< Algorithm, Mixer >::operator()	(	)
throw	(
	)

inline

Return width bits of randomness. Result is in [0, 2^w). (This just calls Ran().)

Returns: the next random number of width width.

Definition at line 278 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

bool RandomLib::RandomEngine< Algorithm, Mixer >::operator==	(	const RandomEngine< Algorithm, Mixer > &	r	)	const
throw	(
	)

inline

Test equality of two Random objects. This test that the seeds match and that they have produced the same number of random numbers.

Parameters

[in] r the RandomEngine object to compare.

Returns: true if the RandomEngine objects produce the same results.

Definition at line 322 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

bool RandomLib::RandomEngine< Algorithm, Mixer >::operator!=	(	const RandomEngine< Algorithm, Mixer > &	r	)	const
throw	(
	)

inline

Test inequality of two Random objects. See Random::operator==

Parameters

[in] r the RandomEngine object to compare.

Returns: true if the RandomEngine objects produce different results.

Definition at line 339 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

void RandomLib::RandomEngine< Algorithm, Mixer >::swap	(	RandomEngine< Algorithm, Mixer > &	t	)
throw	(
	)

inline

Swap with another Random object.

Parameters

[in,out] t the RandomEngine object to swap with.

Definition at line 352 of file RandomEngine.hpp.

References std::swap().

template<typename Algorithm , typename Mixer >

void RandomLib::RandomEngine< Algorithm, Mixer >::Save	(	std::ostream &	os,
		bool	bin = `true`
	)		const

Save the state of the Random object to an output stream. Format is a sequence of unsigned 32-bit integers written either in decimal (bin false, text format) or in network order with most significant byte first (bin true, binary format). Data consists of:

RandomLib magic string + version (2 words)
Algorithm version (1 word)
Mixer version (1 word)
_seed.size() (1 word)
_seed data (_seed.size() words)
_ptr (1 word)
_stride (1 word)
if _ptr != UNINIT, _rounds (2 words)
if _ptr != UNINIT, _state (N words or 2 N words)
checksum

Shortest possible saved result consists of 8 words. This corresponds to RandomSeed() = [] and Count() = 0.

Parameters

[in,out]	os	the output stream.
[in]	bin	if true (the default) save in binary mode.

Definition at line 375 of file Random.cpp.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest().

template<class Algorithm, class Mixer>

void RandomLib::RandomEngine< Algorithm, Mixer >::Load	(	std::istream &	is,
		bool	bin = `true`
	)

inline

Restore the state of the Random object from an input stream. If bin, read in binary, else use text format. See documentation of RandomEngine::Save for the format. Include error checking on data to make sure the input has not been corrupted. If an error occurs while reading, the Random object is unchanged.

Parameters

[in,out]	is	the input stream.
[in]	bin	if true (the default) load in binary mode.

Exceptions

RandomErr if the state read from is is illegal.

Definition at line 400 of file RandomEngine.hpp.

References RandomLib::RandomSeed::_seed.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest().

template<class Algorithm, class Mixer>

long long RandomLib::RandomEngine< Algorithm, Mixer >::Count	(	)	const
throw	(
	)

inline

Return the number of random numbers used. This needs to return a long long result since it can reasonably exceed 2³¹. (On a 1GHz machine, it takes about a minute to produce 2³² random numbers.) More precisely this is the (zero-based) index of the next random number to be produced. (This distinction is important when leapfrogging is in effect.)

Returns: the count of random numbers used.

Definition at line 450 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

void RandomLib::RandomEngine< Algorithm, Mixer >::SetCount	(	long long	n	)
throw	(
	)

inline

Step the generator forwards or backwards so that the value returned by Count() is n

Parameters

[in] n the new count.

Definition at line 458 of file RandomEngine.hpp.

Referenced by main(), and RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest().

template<typename Algorithm , typename Mixer >

void RandomLib::RandomEngine< Algorithm, Mixer >::StepCount	(	long long	n	)
throw	(
	)

Step the generator forward n steps. n can be negative.

Parameters

[in] n how much to step the generator forward.

Definition at line 397 of file Random.cpp.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest().

template<class Algorithm, class Mixer>

void RandomLib::RandomEngine< Algorithm, Mixer >::Reset	(	)
throw	(
	)

inlinevirtual

Resets the sequence. Equivalent to SetCount(0), but works by reinitializing the Random object from its seed, rather than by stepping the sequence backwards. In addition, this undoes leapfrogging.

Implements RandomLib::RandomSeed.

Definition at line 470 of file RandomEngine.hpp.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest().

template<class Algorithm, class Mixer>

void RandomLib::RandomEngine< Algorithm, Mixer >::SetStride	(	unsigned	n = `1`,
		unsigned	k = `0`
	)

inline

Set leapfrogging stride to a positive number n and increment Count() by k < n. If the current Count() is i, then normally the next 3 random numbers would have (zero-based) indices i, i + 1, i + 2, and the new Count() is i + 2. However, after SetStride(n, k) the next 3 random numbers have indices i + k, i + k + n, i + k + 2n, and the new Count() is i + k + 3n. With leapfrogging in effect, the time to produce raw random numbers is roughly proportional to 1 + (n − 1)/3. Reseed(...) and Reset() both reset the stride back to 1. See Parallelization for a description of how to use this facility.

Parameters

[in]	n	the stride (default 1).
[in]	k	the initial increment (default 0).

Exceptions

RandomErr if n is 0 or too large or if k is not less than n.

Definition at line 494 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

unsigned RandomLib::RandomEngine< Algorithm, Mixer >::GetStride	(	)	const
throw	(
	)

inline

Return leapfrogging stride.

Returns: the stride.

Definition at line 510 of file RandomEngine.hpp.

template<typename Algorithm , typename Mixer >

void RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest ( )

static

Tests basic engine.

Exceptions

RandomErr if any of the tests fail.

Definition at line 421 of file Random.cpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::Load(), RandomLib::RandomSeed::Reseed(), RandomLib::RandomEngine< Algorithm, Mixer >::Reset(), RandomLib::RandomEngine< Algorithm, Mixer >::Save(), RandomLib::RandomSeed::SeedString(), RandomLib::RandomEngine< Algorithm, Mixer >::SetCount(), and RandomLib::RandomEngine< Algorithm, Mixer >::StepCount().

template<class Algorithm, class Mixer>

static std::string RandomLib::RandomEngine< Algorithm, Mixer >::Name ( )

inlinestatic

Return the name of the generator. This incorporates the names of the Algorithm and Mixer.

Returns: the name of the generator.

Definition at line 526 of file RandomEngine.hpp.

Referenced by main().

Friends And Related Function Documentation

template<class Algorithm, class Mixer>

std::ostream& operator<<	(	std::ostream &	os,
		const RandomEngine< Algorithm, Mixer > &	r
	)

friend

Write the state of a generator to stream os as text

Parameters

[in,out]	os	the output stream.
[in]	r	the RandomEngine object to be saved.

Definition at line 418 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

std::istream& operator>>	(	std::istream &	is,
		RandomEngine< Algorithm, Mixer > &	r
	)

friend

Read the state of a generator from stream is as text

Parameters

[in,out]	is	the output stream.
[in]	r	the RandomEngine object to be loaded.

Exceptions

RandomErr if the state read from is is illegal.

Definition at line 430 of file RandomEngine.hpp.

Member Data Documentation

template<class Algorithm, class Mixer>

const result_type RandomLib::RandomEngine< Algorithm, Mixer >::min = result_t::min

static

The minimum result returned by Ran() = 0.

Definition at line 112 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

const result_type RandomLib::RandomEngine< Algorithm, Mixer >::max = result_t::max

static

The maximum result returned by Ran() = 2^w − 1.

Definition at line 117 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

const result_type RandomLib::RandomEngine< Algorithm, Mixer >::mask = result_t::mask

staticprotected

The mask for the result_t.

Definition at line 124 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

result_type RandomLib::RandomEngine< Algorithm, Mixer >::_state[N]

the result_type representation returned by Ran()

Definition at line 162 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

mixer_t::type RandomLib::RandomEngine< Algorithm, Mixer >::_stateu[NU]

the mixer_t::type representation returned by Mixer::SeedToState.

Definition at line 166 of file RandomEngine.hpp.

template<class Algorithm, class Mixer>

engine_type RandomLib::RandomEngine< Algorithm, Mixer >::_statev[NV]

the engine_type representation returned by Algorithm::Transition.

Definition at line 170 of file RandomEngine.hpp.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Protected Attributes

Friends

Additional Inherited Members

Detailed Description

template<class Algorithm, class Mixer> class RandomLib::RandomEngine< Algorithm, Mixer >

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<class Algorithm, class Mixer>
class RandomLib::RandomEngine< Algorithm, Mixer >