Uniform random number generator. More...

#include <RandomLib-2010-01/RandomEngine.hpp>

Inheritance diagram for RandomLib::RandomEngine:

Public Types
enum	{ width = result_t::width }
typedef result_t::type	result_type
Public Member Functions
Constructors
template<typename IntType >
	RandomEngine (const std::vector< IntType > &v) throw (std::bad_alloc)
template<typename InputIterator >
	RandomEngine (InputIterator a, InputIterator b)
	RandomEngine (seed_type n) throw (std::bad_alloc)
	RandomEngine () throw (std::bad_alloc)
	RandomEngine (const std::string &s) throw (std::bad_alloc)
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 ()
Writing to and reading from a stream
void	Save (std::ostream &os, bool bin=true) const throw (std::ios::failure)
void	Load (std::istream &is, bool bin=true) throw (std::ios::failure, std::out_of_range, std::bad_alloc)
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) throw (std::invalid_argument)
unsigned	GetStride () const throw ()
Static Public Member Functions
static void	SelfTest ()
static std::string	Name () throw ()
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
Private Types
enum	{ N = Algorithm::N, NU = (N * width + mixer_t::width - 1) / mixer_t::width, NV = N * sizeof(result_type) / sizeof(engine_type) }
typedef Algorithm::engine_t	result_t
typedef Mixer::mixer_t	mixer_t
typedef Algorithm::internal_type	engine_type
Private Member Functions
void	Init () throw ()
void	Next () throw ()
u32::type	Check (u64::type v, u32::type e, u32::type m) const throw (std::out_of_range)
	RandomEngine (std::istream &is, bool bin) throw (std::ios::failure, std::out_of_range, std::bad_alloc)
template<>
Random_u32::type	SelfTestResult (unsigned i) throw()
template<>
Random_u64::type	SelfTestResult (unsigned i) throw()
template<>
Random_u32::type	SelfTestResult (unsigned i) throw()
template<>
Random_u64::type	SelfTestResult (unsigned i) throw()
template<>
Random_u32::type	SelfTestResult (unsigned i) throw()
template<>
Random_u64::type	SelfTestResult (unsigned i) throw()
template<>
Random_u32::type	SelfTestResult (unsigned i) throw()
template<>
Random_u64::type	SelfTestResult (unsigned i) throw()
Static Private Member Functions
static result_type	SelfTestResult (unsigned k) throw ()
Private Attributes
union {
result_type _state [N]
mixer_t::type _stateu [NU]
engine_type _statev [NV]
};
	Union for the state.
unsigned	_ptr
long long	_rounds
unsigned	_stride
Static Private Attributes
static const u64::type	version = 0x52616e644c696230ULL
static const unsigned	UNINIT = 0xffffffffU
Friends
Basic I/O
std::ostream &	operator<< (std::ostream &os, const RandomEngine &r)
std::istream &	operator>> (std::istream &is, RandomEngine &r)

Detailed Description

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.

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 explicity between interal_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 <charles@karney.com> and licensed under the LGPL. For more information, see http://randomlib.sourceforge.net/

Member Typedef Documentation

typedef Algorithm::engine_t RandomLib::RandomEngine::result_t [private]

The result RandomType (carried over from the Algorithm).

Definition at line 76 of file RandomEngine.hpp.

typedef Mixer::mixer_t RandomLib::RandomEngine::mixer_t [private]

The RandomType used by the Mixer.

Definition at line 80 of file RandomEngine.hpp.

typedef Algorithm::internal_type RandomLib::RandomEngine::engine_type [private]

The internal_type used by the Algorithm::Transition().

Definition at line 84 of file RandomEngine.hpp.

typedef result_t::type RandomLib::RandomEngine::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 97 of file RandomEngine.hpp.

Member Enumeration Documentation

anonymous enum

The number of random bits produced by Ran().

Enumerator:

width

Definition at line 89 of file RandomEngine.hpp.

anonymous enum [private]

Enumerator:

N	The size of the state in units of result_type
NU	The size of the state in units of mixer_t::type
NV	The size of the state in units of engine_type.

Definition at line 127 of file RandomEngine.hpp.

Constructor & Destructor Documentation

template<typename IntType >

RandomLib::RandomEngine::RandomEngine ( const std::vector< IntType > & v ) throw (std::bad_alloc) [inline, explicit]

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

Definition at line 186 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

template<typename InputIterator >

RandomLib::RandomEngine::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.

Definition at line 194 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

RandomLib::RandomEngine::RandomEngine ( seed_type n ) throw (std::bad_alloc) [inline, explicit]

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

Definition at line 200 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

RandomLib::RandomEngine::RandomEngine ( ) throw (std::bad_alloc) [inline]

Initialize with seed [SeedVector()]

Definition at line 205 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

RandomLib::RandomEngine::RandomEngine ( const std::string & s ) throw (std::bad_alloc) [inline, explicit]

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

Definition at line 209 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

RandomLib::RandomEngine::RandomEngine	(	std::istream &	is,
		bool	bin
	)		throw (std::ios::failure, std::out_of_range, std::bad_alloc) `[explicit, private]`

Read from an input stream. Potentially corrupts object. This private constructor is used by RandomEngine::Load so that it can avoid corrupting its state on bad input.

Definition at line 332 of file Random.cpp.

Member Function Documentation

result_type RandomLib::RandomEngine::Ran ( ) throw () [inline]

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

Definition at line 221 of file RandomEngine.hpp.

References N, Next(), _state, _ptr, and _stride.

Referenced by Ran32(), Ran64(), and operator()().

u32::type RandomLib::RandomEngine::Ran32 ( ) throw () [inline]

Return 32 bits of randomness.

Definition at line 233 of file RandomEngine.hpp.

References RandomLib::RandomType::cast(), and Ran().

u64::type RandomLib::RandomEngine::Ran64 ( ) throw () [inline]

Return 64 bits of randomness.

Definition at line 241 of file RandomEngine.hpp.

References Ran(), width, and RandomLib::RandomType::cast().

result_type RandomLib::RandomEngine::operator() ( ) throw () [inline]

Return width bits of randomness. Result is in [0, 2^w)

Definition at line 250 of file RandomEngine.hpp.

References Ran().

bool RandomLib::RandomEngine::operator== ( const RandomEngine & 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.

Definition at line 260 of file RandomEngine.hpp.

References Count(), and RandomLib::RandomSeed::_seed.

Referenced by operator!=().

bool RandomLib::RandomEngine::operator!= ( const RandomEngine & r ) const throw () [inline]

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

Definition at line 274 of file RandomEngine.hpp.

References operator==().

void RandomLib::RandomEngine::Save	(	std::ostream &	os,
		bool	bin = `true`
	)		const throw (std::ios::failure)

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.

Definition at line 367 of file Random.cpp.

Referenced by SelfTest().

void RandomLib::RandomEngine::Load	(	std::istream &	is,
		bool	bin = `true`
	)		throw (std::ios::failure, std::out_of_range, std::bad_alloc) `[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 date to make sure the input has not been corrupted. If an error occurs while reading, the Random object is unchanged.

Definition at line 310 of file RandomEngine.hpp.

References RandomLib::RandomSeed::_seed.

Referenced by SelfTest().

long long RandomLib::RandomEngine::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.)

Definition at line 350 of file RandomEngine.hpp.

References UNINIT, N, and _ptr.

Referenced by operator==(), and SetCount().

void RandomLib::RandomEngine::SetCount ( long long n ) throw () [inline]

Step the generator forwards of backwarks so that the value returned by Count() is n

Definition at line 356 of file RandomEngine.hpp.

References StepCount(), and Count().

Referenced by SelfTest().

void RandomLib::RandomEngine::StepCount ( long long n ) throw ()

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

Definition at line 390 of file Random.cpp.

Referenced by SelfTest(), SetCount(), and SetStride().

void RandomLib::RandomEngine::Reset ( ) throw () [inline, virtual]

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 366 of file RandomEngine.hpp.

References UNINIT.

Referenced by SelfTest().

void RandomLib::RandomEngine::SetStride	(	unsigned	n = `1`,
		unsigned	k = `0`
	)		throw (std::invalid_argument) `[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)/2. Reseed(...) and Reset() both reset the stride back to 1. See Leapfrogging for a description of how to use this facility.

Definition at line 384 of file RandomEngine.hpp.

References UNINIT, and StepCount().

unsigned RandomLib::RandomEngine::GetStride ( ) const throw () [inline]

Return leapfrogging stride.

Definition at line 399 of file RandomEngine.hpp.

References _stride.

void RandomLib::RandomEngine::SelfTest ( ) [static]

Tests basic engine. Throws out_of_range errors on bad results.

Definition at line 414 of file Random.cpp.

References SetCount(), RandomLib::RandomSeed::SeedString(), RandomLib::RandomSeed::Reseed(), StepCount(), Reset(), Save(), and Load().

Referenced by main().

static std::string RandomLib::RandomEngine::Name ( ) throw () [inline, static]

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

Definition at line 411 of file RandomEngine.hpp.

Referenced by main().

void RandomLib::RandomEngine::Init ( ) throw () [private]

Compute initial state from seed

Definition at line 235 of file Random.cpp.

References STATIC_ASSERT.

Referenced by Next().

void RandomLib::RandomEngine::Next ( ) throw () [inline, private]

The interface to Transition used by Ran().

Definition at line 423 of file RandomEngine.hpp.

References UNINIT, Init(), N, and _statev.

Referenced by Ran().

Random_u32::type RandomLib::RandomEngine::Check	(	u64::type	v,
		u32::type	e,
		u32::type	m
	)		const throw (std::out_of_range) `[private]`

Definition at line 298 of file Random.cpp.

static result_type RandomLib::RandomEngine::SelfTestResult ( unsigned k ) throw () [inline, static, private]

Definition at line 434 of file RandomEngine.hpp.

template<>

Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerMT0< Random_u32 > >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 459 of file Random.cpp.

template<>

Random_u64::type RandomLib::RandomEngine< MT19937< Random_u64 >, MixerMT0< Random_u64 > >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 467 of file Random.cpp.

template<>

Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerMT1< Random_u32 > >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 475 of file Random.cpp.

template<>

Random_u64::type RandomLib::RandomEngine< MT19937< Random_u64 >, MixerMT1< Random_u64 > >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 483 of file Random.cpp.

template<>

Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerSFMT >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 491 of file Random.cpp.

template<>

Random_u64::type RandomLib::RandomEngine< MT19937< Random_u64 >, MixerSFMT >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 499 of file Random.cpp.

template<>

Random_u32::type RandomLib::RandomEngine< SFMT19937< Random_u32 >, MixerSFMT >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 507 of file Random.cpp.

template<>

Random_u64::type RandomLib::RandomEngine< SFMT19937< Random_u64 >, MixerSFMT >::SelfTestResult ( unsigned i ) throw() [private]

Definition at line 515 of file Random.cpp.

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	os,
		const RandomEngine &	r
	)		`[friend]`

Write the state of a generator to stream os as text

Definition at line 325 of file RandomEngine.hpp.

std::istream& operator>>	(	std::istream &	is,
		RandomEngine &	r
	)		`[friend]`

Read the state of a generator from stream is as text

Definition at line 333 of file RandomEngine.hpp.

Member Data Documentation

const result_type RandomLib::RandomEngine::min = result_t::min [static]

The minimum result returned by Ran().

Definition at line 102 of file RandomEngine.hpp.

const result_type RandomLib::RandomEngine::max = result_t::max [static]

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

Definition at line 107 of file RandomEngine.hpp.

const result_type RandomLib::RandomEngine::mask = result_t::mask [static, protected]

The mask for the result_t.

Definition at line 114 of file RandomEngine.hpp.

const u64::type RandomLib::RandomEngine::version = 0x52616e644c696230ULL [static, private]

A version number "RandLib0" to ensure safety of Save/Load. The next 7 bytes can be regarded as a "signature" and the 8th byte a version number.

Definition at line 122 of file RandomEngine.hpp.

const unsigned RandomLib::RandomEngine::UNINIT = 0xffffffffU [static, private]

Marker for uninitialized object

Definition at line 126 of file RandomEngine.hpp.

Referenced by Count(), Reset(), SetStride(), and Next().

result_type RandomLib::RandomEngine::_state[N]

the result_type representation returned by Ran()

Definition at line 152 of file RandomEngine.hpp.

Referenced by Ran().

mixer_t::type RandomLib::RandomEngine::_stateu[NU]

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

Definition at line 156 of file RandomEngine.hpp.

engine_type RandomLib::RandomEngine::_statev[NV]

the engine_type representation returned by Algorithm::Transition.

Definition at line 160 of file RandomEngine.hpp.

Referenced by Next().

union { ... } [private]

Union for the state.

A union to hold the state in the result_type, mixer_t::type, and engine_type representations.

unsigned RandomLib::RandomEngine::_ptr [private]

The index for the next random value

Definition at line 166 of file RandomEngine.hpp.

Referenced by Ran(), and Count().

long long RandomLib::RandomEngine::_rounds [private]

How many times has Transition() been called

Definition at line 170 of file RandomEngine.hpp.

unsigned RandomLib::RandomEngine::_stride [private]

Stride for leapfrogging

Definition at line 174 of file RandomEngine.hpp.

Referenced by Ran(), and GetStride().

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

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation