RandomLib  1.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerator Friends Macros Pages
Public Types | Static Public Member Functions | Static Public Attributes | Static Protected Attributes | List of all members
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

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_typeSeedVector ()
 
template<typename IntType >
static std::string VectorToString (const std::vector< IntType > &v)
 
static std::vector< seed_typeStringToVector (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
Algorithmthe random number algorithm.
Mixerthe 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

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 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
IntTypethe integral type of the elements of the vector.
Parameters
[in]vthe 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
InputIteratorthe type of the iterator.
Parameters
[in]athe beginning iterator.
[in]bthe 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]nthe 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]sthe 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, 2w). (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]rthe 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]rthe 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]tthe 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]osthe output stream.
[in]binif 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]isthe input stream.
[in]binif true (the default) load in binary mode.
Exceptions
RandomErrif 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 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.)

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]nthe 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]nhow 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]nthe stride (default 1).
[in]kthe initial increment (default 0).
Exceptions
RandomErrif 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
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]osthe output stream.
[in]rthe 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]isthe output stream.
[in]rthe RandomEngine object to be loaded.
Exceptions
RandomErrif 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() = 2w − 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: