RandomLib::RandomEngine< Algorithm, Mixer > Class Template Reference

Uniform random number generator. More...

#include <RandomLib/RandomEngine.hpp>

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

List of all members.

Public Types

enum  { width = result_t::width }
typedef result_t::type result_type

Public Member Functions

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()
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)

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

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.

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

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

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://charles.karney.info/random/

Definition at line 72 of file RandomEngine.hpp.


Member Typedef Documentation

template<class Algorithm , class Mixer >
typedef Algorithm::engine_t RandomLib::RandomEngine< Algorithm, Mixer >::result_t [private]

The result RandomType (carried over from the Algorithm).

Definition at line 77 of file RandomEngine.hpp.

template<class Algorithm , class Mixer >
typedef Mixer::mixer_t RandomLib::RandomEngine< Algorithm, Mixer >::mixer_t [private]

The RandomType used by the Mixer.

Definition at line 81 of file RandomEngine.hpp.

template<class Algorithm , class Mixer >
typedef Algorithm::internal_type RandomLib::RandomEngine< Algorithm, Mixer >::engine_type [private]

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

Definition at line 85 of file RandomEngine.hpp.

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

template<class Algorithm , class Mixer >
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 128 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  )  throw (std::bad_alloc) [inline, explicit]

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

Definition at line 187 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

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.

Definition at line 195 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

template<class Algorithm , class Mixer >
RandomLib::RandomEngine< Algorithm, Mixer >::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 201 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

template<class Algorithm , class Mixer >
RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine (  )  throw (std::bad_alloc) [inline]

Initialize with seed [SeedVector()]

Definition at line 206 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

template<class Algorithm , class Mixer >
RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine ( const std::string &  s  )  throw (std::bad_alloc) [inline, explicit]

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

Definition at line 210 of file RandomEngine.hpp.

References RandomLib::RandomSeed::Reseed().

template<typename Algorithm , typename Mixer >
RandomLib::RandomEngine< Algorithm, Mixer >::RandomEngine ( std::istream &  is,
bool  bin 
) throw (std::ios::failure, std::out_of_range, std::bad_alloc) [inline, 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 333 of file Random.cpp.


Member Function Documentation

template<class Algorithm , class Mixer >
result_type RandomLib::RandomEngine< Algorithm, Mixer >::Ran (  )  throw () [inline]
template<class Algorithm , class Mixer >
u32::type RandomLib::RandomEngine< Algorithm, Mixer >::Ran32 (  )  throw () [inline]

Return 32 bits of randomness.

Definition at line 234 of file RandomEngine.hpp.

References RandomLib::RandomType< bits, UIntType >::cast(), and RandomLib::RandomEngine< Algorithm, Mixer >::Ran().

template<class Algorithm , class Mixer >
u64::type RandomLib::RandomEngine< Algorithm, Mixer >::Ran64 (  )  throw () [inline]
template<class Algorithm , class Mixer >
result_type RandomLib::RandomEngine< Algorithm, Mixer >::operator() (  )  throw () [inline]

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

Definition at line 251 of file RandomEngine.hpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::Ran().

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.

Definition at line 261 of file RandomEngine.hpp.

References RandomLib::RandomSeed::_seed, and RandomLib::RandomEngine< Algorithm, Mixer >::Count().

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::operator!=().

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==

Definition at line 275 of file RandomEngine.hpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::operator==().

template<typename Algorithm , typename Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::Save ( std::ostream &  os,
bool  bin = true 
) const throw (std::ios::failure) [inline]

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 368 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 
) 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 311 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 231. (On a 1GHz machine, it takes about a minute to produce 232 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 351 of file RandomEngine.hpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::N, and RandomLib::RandomEngine< Algorithm, Mixer >::UNINIT.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::operator==(), and RandomLib::RandomEngine< Algorithm, Mixer >::SetCount().

template<class Algorithm , class Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::SetCount ( long long  n  )  throw () [inline]

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

Definition at line 357 of file RandomEngine.hpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::Count(), and RandomLib::RandomEngine< Algorithm, Mixer >::StepCount().

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

template<typename Algorithm , typename Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::StepCount ( long long  n  )  throw () [inline]
template<class Algorithm , class Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::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 367 of file RandomEngine.hpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::UNINIT.

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

template<class Algorithm , class Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::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 385 of file RandomEngine.hpp.

References RandomLib::RandomEngine< Algorithm, Mixer >::StepCount(), and RandomLib::RandomEngine< Algorithm, Mixer >::UNINIT.

template<class Algorithm , class Mixer >
unsigned RandomLib::RandomEngine< Algorithm, Mixer >::GetStride (  )  const throw () [inline]

Return leapfrogging stride.

Definition at line 400 of file RandomEngine.hpp.

template<typename Algorithm , typename Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest (  )  [inline, static]
template<class Algorithm , class Mixer >
static std::string RandomLib::RandomEngine< Algorithm, Mixer >::Name (  )  throw () [inline, static]

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

Definition at line 412 of file RandomEngine.hpp.

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

template<class Algorithm , class Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::Init (  )  throw () [inline, private]
template<class Algorithm , class Mixer >
void RandomLib::RandomEngine< Algorithm, Mixer >::Next (  )  throw () [inline, private]
template<class Algorithm , class Mixer >
Random_u32::type RandomLib::RandomEngine< Algorithm, Mixer >::Check ( u64::type  v,
u32::type  e,
u32::type  m 
) const throw (std::out_of_range) [inline, private]

Definition at line 299 of file Random.cpp.

template<class Algorithm , class Mixer >
static result_type RandomLib::RandomEngine< Algorithm, Mixer >::SelfTestResult ( unsigned  k  )  throw () [inline, static, private]
template<>
Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerMT0< Random_u32 > >::SelfTestResult ( unsigned  i  )  throw() [inline]

Definition at line 460 of file Random.cpp.

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

Definition at line 468 of file Random.cpp.

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

Definition at line 476 of file Random.cpp.

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

Definition at line 484 of file Random.cpp.

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

Definition at line 492 of file Random.cpp.

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

Definition at line 500 of file Random.cpp.

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

Definition at line 508 of file Random.cpp.

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

Definition at line 516 of file Random.cpp.


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

Print a RandomNumber. Format is n.dddd... where the base for printing is 2max(4,b). The ... represents an infinite sequence of ungenerated random digits (uniformly distributed). Thus with b = 1, 0.0... = (0,1/2), 0.00... = (0,1/4), 0.11... = (3/4,1), etc.

Definition at line 326 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

Definition at line 334 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().

Definition at line 103 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() = 2w - 1

Definition at line 108 of file RandomEngine.hpp.

template<class Algorithm , class Mixer >
const result_type RandomLib::RandomEngine< Algorithm, Mixer >::mask = result_t::mask [static, protected]

The mask for the result_t.

Definition at line 115 of file RandomEngine.hpp.

template<class Algorithm , class Mixer >
const u64::type RandomLib::RandomEngine< Algorithm, Mixer >::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 123 of file RandomEngine.hpp.

template<class Algorithm , class Mixer >
const unsigned RandomLib::RandomEngine< Algorithm, Mixer >::UNINIT = 0xffffffffU [static, private]
template<class Algorithm , class Mixer >
result_type RandomLib::RandomEngine< Algorithm, Mixer >::_state[N]

the result_type representation returned by Ran()

Definition at line 153 of file RandomEngine.hpp.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::Init(), and RandomLib::RandomEngine< Algorithm, Mixer >::Ran().

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

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

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

the engine_type representation returned by Algorithm::Transition.

Definition at line 161 of file RandomEngine.hpp.

Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::Init(), and RandomLib::RandomEngine< Algorithm, Mixer >::Next().

union { ... } [private]

Union for the state.

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

template<class Algorithm , class Mixer >
unsigned RandomLib::RandomEngine< Algorithm, Mixer >::_ptr [private]

The index for the next random value

Definition at line 167 of file RandomEngine.hpp.

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

template<class Algorithm , class Mixer >
long long RandomLib::RandomEngine< Algorithm, Mixer >::_rounds [private]

How many times has Transition() been called

Definition at line 171 of file RandomEngine.hpp.

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

template<class Algorithm , class Mixer >
unsigned RandomLib::RandomEngine< Algorithm, Mixer >::_stride [private]

Stride for leapfrogging

Definition at line 175 of file RandomEngine.hpp.


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

Generated on Thu Dec 31 15:24:30 2009 by  doxygen 1.6.1