Uniform random number generator. More...
#include <RandomLib/RandomEngine.hpp>
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) |
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.
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.
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.
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.
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.
anonymous enum |
The number of random bits produced by Ran().
Definition at line 90 of file RandomEngine.hpp.
anonymous enum [private] |
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.
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().
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().
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().
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().
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().
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.
result_type RandomLib::RandomEngine< Algorithm, Mixer >::Ran | ( | ) | throw () [inline] |
Return width bits of randomness. This is the natural unit of random data produced random numnber generator.
Definition at line 222 of file RandomEngine.hpp.
References RandomLib::RandomEngine< Algorithm, Mixer >::_state, RandomLib::RandomEngine< Algorithm, Mixer >::N, and RandomLib::RandomEngine< Algorithm, Mixer >::Next().
Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::operator()(), RandomLib::RandomEngine< Algorithm, Mixer >::Ran32(), and RandomLib::RandomEngine< Algorithm, Mixer >::Ran64().
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().
u64::type RandomLib::RandomEngine< Algorithm, Mixer >::Ran64 | ( | ) | throw () [inline] |
Return 64 bits of randomness.
Definition at line 242 of file RandomEngine.hpp.
References RandomLib::RandomType< bits, UIntType >::cast(), RandomLib::RandomEngine< Algorithm, Mixer >::Ran(), and RandomLib::RandomEngine< Algorithm, Mixer >::width.
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().
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!=().
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==().
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:
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().
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().
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().
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().
void RandomLib::RandomEngine< Algorithm, Mixer >::StepCount | ( | long long | n | ) | throw () [inline] |
Step the generator forward n steps. n can be negative.
Definition at line 391 of file Random.cpp.
Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest(), RandomLib::RandomEngine< Algorithm, Mixer >::SetCount(), and RandomLib::RandomEngine< Algorithm, Mixer >::SetStride().
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().
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.
unsigned RandomLib::RandomEngine< Algorithm, Mixer >::GetStride | ( | ) | const throw () [inline] |
Return leapfrogging stride.
Definition at line 400 of file RandomEngine.hpp.
void RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest | ( | ) | [inline, static] |
Tests basic engine. Throws out_of_range errors on bad results.
Definition at line 415 of file Random.cpp.
References RandomLib::RandomEngine< Algorithm, Mixer >::Load(), RandomLib::RandomEngine< Algorithm, Mixer >::Name(), RandomLib::RandomSeed::Reseed(), RandomLib::RandomEngine< Algorithm, Mixer >::Reset(), RandomLib::RandomEngine< Algorithm, Mixer >::Save(), RandomLib::RandomSeed::SeedString(), RandomLib::RandomEngine< Algorithm, Mixer >::SelfTestResult(), RandomLib::RandomEngine< Algorithm, Mixer >::SetCount(), and RandomLib::RandomEngine< Algorithm, Mixer >::StepCount().
Referenced by main().
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().
void RandomLib::RandomEngine< Algorithm, Mixer >::Init | ( | ) | throw () [inline, private] |
Compute initial state from seed
Definition at line 236 of file Random.cpp.
References RandomLib::RandomEngine< Algorithm, Mixer >::_ptr, RandomLib::RandomEngine< Algorithm, Mixer >::_rounds, RandomLib::RandomSeed::_seed, RandomLib::RandomEngine< Algorithm, Mixer >::_state, RandomLib::RandomEngine< Algorithm, Mixer >::_stateu, RandomLib::RandomEngine< Algorithm, Mixer >::_statev, RandomLib::RandomEngine< Algorithm, Mixer >::N, RandomLib::RandomEngine< Algorithm, Mixer >::NU, STATIC_ASSERT, and RandomLib::RandomEngine< Algorithm, Mixer >::width.
Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::Next().
void RandomLib::RandomEngine< Algorithm, Mixer >::Next | ( | ) | throw () [inline, private] |
The interface to Transition used by Ran().
Definition at line 424 of file RandomEngine.hpp.
References RandomLib::RandomEngine< Algorithm, Mixer >::_statev, RandomLib::RandomEngine< Algorithm, Mixer >::Init(), RandomLib::RandomEngine< Algorithm, Mixer >::N, and RandomLib::RandomEngine< Algorithm, Mixer >::UNINIT.
Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::Ran().
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.
static result_type RandomLib::RandomEngine< Algorithm, Mixer >::SelfTestResult | ( | unsigned | k | ) | throw () [inline, static, private] |
Definition at line 435 of file RandomEngine.hpp.
Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::SelfTest().
Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerMT0< Random_u32 > >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 460 of file Random.cpp.
Random_u64::type RandomLib::RandomEngine< MT19937< Random_u64 >, MixerMT0< Random_u64 > >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 468 of file Random.cpp.
Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerMT1< Random_u32 > >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 476 of file Random.cpp.
Random_u64::type RandomLib::RandomEngine< MT19937< Random_u64 >, MixerMT1< Random_u64 > >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 484 of file Random.cpp.
Random_u32::type RandomLib::RandomEngine< MT19937< Random_u32 >, MixerSFMT >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 492 of file Random.cpp.
Random_u64::type RandomLib::RandomEngine< MT19937< Random_u64 >, MixerSFMT >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 500 of file Random.cpp.
Random_u32::type RandomLib::RandomEngine< SFMT19937< Random_u32 >, MixerSFMT >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 508 of file Random.cpp.
Random_u64::type RandomLib::RandomEngine< SFMT19937< Random_u64 >, MixerSFMT >::SelfTestResult | ( | unsigned | i | ) | throw() [inline] |
Definition at line 516 of file Random.cpp.
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.
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.
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.
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.
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.
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.
const unsigned RandomLib::RandomEngine< Algorithm, Mixer >::UNINIT = 0xffffffffU [static, private] |
Marker for uninitialized object
Definition at line 127 of file RandomEngine.hpp.
Referenced by RandomLib::RandomEngine< Algorithm, Mixer >::Count(), RandomLib::RandomEngine< Algorithm, Mixer >::Next(), RandomLib::RandomEngine< Algorithm, Mixer >::Reset(), and RandomLib::RandomEngine< Algorithm, Mixer >::SetStride().
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().
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().
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.
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().
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().
unsigned RandomLib::RandomEngine< Algorithm, Mixer >::_stride [private] |
Stride for leapfrogging
Definition at line 175 of file RandomEngine.hpp.