RandomLib::RandomCanonical< Generator > Class Template Reference

Generate random integers, reals, and booleans. More...

#include <RandomLib/RandomCanonical.hpp>

List of all members.

Public Types

enum  { width = Generator::width }
typedef Generator::result_type result_type
typedef RandomSeed::seed_type seed_type

Public Member Functions

template<>
RandomCanonical
< MRandomGenerator32
Global (std::vector< unsigned long >(0))
template<>
RandomCanonical
< MRandomGenerator64
Global (std::vector< unsigned long >(0))
template<>
RandomCanonical
< SRandomGenerator32
Global (std::vector< unsigned long >(0))
template<>
RandomCanonical
< SRandomGenerator64
Global (std::vector< unsigned long >(0))
Constructors which set the seed



template<typename IntType >
 RandomCanonical (const std::vector< IntType > &v) throw (std::bad_alloc)
template<typename InputIterator >
 RandomCanonical (InputIterator a, InputIterator b)
 RandomCanonical (seed_type n) throw (std::bad_alloc)
 RandomCanonical () throw (std::bad_alloc)
 RandomCanonical (const std::string &s) throw (std::bad_alloc)
Member functions returning integers



result_type operator() () throw ()
result_type operator() (result_type n) throw ()
template<typename IntType , int bits>
IntType Integer () throw ()
template<int bits>
result_type Integer () throw ()
template<typename IntType >
IntType Integer () throw ()
result_type Integer () throw ()
template<typename IntType >
IntType Integer (IntType n) throw ()
template<typename IntType >
IntType IntegerC (IntType n) throw ()
template<typename IntType >
IntType IntegerC (IntType m, IntType n) throw ()
Member functions returning real fixed-point numbers



template<typename RealType , int prec>
RealType Fixed () throw ()
template<typename RealType >
RealType Fixed () throw ()
double Fixed () throw ()
template<typename RealType >
RealType Real () throw ()
double Real () throw ()
template<typename RealType , int prec>
RealType FixedU () throw ()
template<typename RealType >
RealType FixedU () throw ()
double FixedU () throw ()
template<typename RealType , int prec>
RealType FixedN () throw ()
template<typename RealType >
RealType FixedN () throw ()
double FixedN () throw ()
template<typename RealType , int prec>
RealType FixedW () throw ()
template<typename RealType >
RealType FixedW () throw ()
double FixedW () throw ()
template<typename RealType , int prec>
RealType FixedS () throw ()
template<typename RealType >
RealType FixedS () throw ()
double FixedS () throw ()
template<typename RealType , int prec>
RealType FixedO () throw ()
template<typename RealType >
RealType FixedO () throw ()
double FixedO () throw ()
template<typename RealType , int prec>
RealType FixedC () throw ()
template<typename RealType >
RealType FixedC () throw ()
double FixedC () throw ()
Member functions returning real floating-point numbers



template<typename RealType , int prec, int erange>
RealType Float () throw ()
template<typename RealType >
RealType Float () throw ()
double Float () throw ()
template<typename RealType , int prec, int erange>
RealType FloatU () throw ()
template<typename RealType >
RealType FloatU () throw ()
double FloatU () throw ()
template<typename RealType , int prec, int erange>
RealType FloatN () throw ()
template<typename RealType >
RealType FloatN () throw ()
double FloatN () throw ()
template<typename RealType , int prec, int erange>
RealType FloatW () throw ()
template<typename RealType >
RealType FloatW () throw ()
double FloatW () throw ()
Member functions returning booleans



bool Boolean () throw ()
template<typename NumericType >
bool Prob (NumericType p) throw ()
template<typename NumericType >
bool Prob (NumericType m, NumericType n) throw ()
Functions returning bitsets

These return random bits in a std::bitset.



template<int nbits>
std::bitset< nbits > Bits () throw ()

Static Public Attributes

static RandomCanonical Global

Private Types

typedef RandomSeed::u32 u32
typedef RandomSeed::u64 u64

Private Member Functions

template<typename UIntT >
UIntT::type Unsigned (typename UIntT::type n) throw ()
template<typename RealType , int prec, int erange, bool up>
RealType FloatZ (int b, result_type m) throw ()
template<typename RealType >
bool ProbF (RealType z) throw ()
template<typename RealType >
bool ProbF (RealType x, RealType y) throw ()

Detailed Description

template<class Generator>
class RandomLib::RandomCanonical< Generator >

Generate random integers, reals, and booleans.

Use the random bits from Generator to produce random integers of various sizes, random reals with various precisions, a random probability, etc. RandomCanonical assumes that Generator produces random results as 32-bit quantities (of type uint32_t) via Generator::Ran32(), 64-bit quantities (of type uint64_t) via Generator::Ran64(), and in "natural" units of Generator::width bits (of type Generator::result_type) via Generator::Ran().

For the most part this class uses Ran() when needing width or fewer bits, otherwise it uses Ran64(). However, when width = 64, the resulting code is RandomCanonical::Unsigned(n) is inefficient because of the 64-bit arithmetic. For this reason RandomCanonical::Unsigned(n) uses Ran32() if less than 32 bits are required (even though this results in more numbers being produced by the Generator).

This class has been tested with the 32-bit and 64-bit versions of MT19937 and SFMT19937. Other random number generators could be used provided that they provide a whole number of random bits so that Ran() is uniformly distributed in [0,2w). Probably some modifications would be needed if w is not 32 or 64.

Definition at line 46 of file RandomCanonical.hpp.


Member Typedef Documentation

template<class Generator>
typedef Generator::result_type RandomLib::RandomCanonical< Generator >::result_type

The type of operator()().

Definition at line 51 of file RandomCanonical.hpp.

template<class Generator>
typedef RandomSeed::seed_type RandomLib::RandomCanonical< Generator >::seed_type

The type of elements of Seed().

Definition at line 55 of file RandomCanonical.hpp.

template<class Generator>
typedef RandomSeed::u32 RandomLib::RandomCanonical< Generator >::u32 [private]

Definition at line 593 of file RandomCanonical.hpp.

template<class Generator>
typedef RandomSeed::u64 RandomLib::RandomCanonical< Generator >::u64 [private]

Definition at line 594 of file RandomCanonical.hpp.


Member Enumeration Documentation

template<class Generator>
anonymous enum
Enumerator:
width 

The number of random bits in result_type.

Definition at line 56 of file RandomCanonical.hpp.


Constructor & Destructor Documentation

template<class Generator>
template<typename IntType >
RandomLib::RandomCanonical< Generator >::RandomCanonical ( const std::vector< IntType > &  v  )  throw (std::bad_alloc) [inline, explicit]

Initialize from a vector.

Definition at line 70 of file RandomCanonical.hpp.

template<class Generator>
template<typename InputIterator >
RandomLib::RandomCanonical< Generator >::RandomCanonical ( InputIterator  a,
InputIterator  b 
) [inline]

Initialize from a pair of iterator setting seed to [a, b)

Definition at line 76 of file RandomCanonical.hpp.

template<class Generator >
RandomLib::RandomCanonical< Generator >::RandomCanonical ( seed_type  n  )  throw (std::bad_alloc) [inline, explicit]
template<class Generator>
RandomLib::RandomCanonical< Generator >::RandomCanonical (  )  throw (std::bad_alloc) [inline]

Initialize with seed [SeedVector()]

Definition at line 84 of file RandomCanonical.hpp.

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

Initialize from a string. See RandomCanonical::StringToVector

Definition at line 88 of file RandomCanonical.hpp.


Member Function Documentation

template<class Generator>
result_type RandomLib::RandomCanonical< Generator >::operator() (  )  throw () [inline]

Return a raw result in [0, 2w) from the underlying Generator.

Definition at line 99 of file RandomCanonical.hpp.

template<class Generator>
result_type RandomLib::RandomCanonical< Generator >::operator() ( result_type  n  )  throw () [inline]

A random integer in [0, n). This allows a RandomCanonical object to be passed to those standard template library routines that require random numbers. E.g.,

   RandomCanonical r;
   int a[] = {0, 1, 2, 3, 4};
   std::random_shuffle(a, a+5, r);

Definition at line 111 of file RandomCanonical.hpp.

template<class Generator >
template<typename IntType >
IntType RandomLib::RandomCanonical< Generator >::Integer (  )  throw () [inline]

A random integer of type IntType in [0, 2b).

Definition at line 119 of file RandomCanonical.hpp.

References RandomLib::RandomType< bits, UIntType >::mask, STATIC_ASSERT, and RandomLib::RandomCanonical< Generator >::width.

template<class Generator>
template<int bits>
result_type RandomLib::RandomCanonical< Generator >::Integer (  )  throw () [inline]

A random integer in [0, 2b).

Definition at line 139 of file RandomCanonical.hpp.

template<class Generator>
template<typename IntType >
IntType RandomLib::RandomCanonical< Generator >::Integer (  )  throw () [inline]

A random integer of type IntType in [std::numeric_limits<IntType>::min(), std::numeric_limits::max()].

template<class Generator>
result_type RandomLib::RandomCanonical< Generator >::Integer (  )  throw () [inline]

A random result_type in [0, std::numeric_limits<result_type>::max()].

Definition at line 150 of file RandomCanonical.hpp.

template<class Generator >
template<typename IntType >
IntType RandomLib::RandomCanonical< Generator >::Integer ( IntType  n  )  throw () [inline]

A random integer of type IntType in [0, n). Excludes n. If n == 0, treat as std::numeric_limits::max() + 1. If n < 0, return 0. Compare RandomCanonical::Integer<int>(0) which returns a result in [0,231) with RandomCanonical::Integer<int>() which returns a result in [-231,231).

Definition at line 719 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<class Generator >
template<typename IntType >
IntType RandomLib::RandomCanonical< Generator >::IntegerC ( IntType  n  )  throw () [inline]

A random integer of type IntType in Closed interval [0, n]. Includes n. If n < 0, return 0.

Definition at line 740 of file RandomCanonical.hpp.

References STATIC_ASSERT.

Referenced by main().

template<class Generator >
template<typename IntType >
IntType RandomLib::RandomCanonical< Generator >::IntegerC ( IntType  m,
IntType  n 
) throw () [inline]

A random integer of type IntType in Closed interval [m, n]. Includes both endpoints. If n < m, return m.

Definition at line 756 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::Fixed (  )  throw () [inline]

In the description of the functions FixedX returning fixed-point numbers, u is a random real number uniformly distributed in (0, 1), p is the precision, and h = 1/2p. Each of the functions come in three variants, e.g.,

See the summary for a comparison of the functions.

Return i h with i in [0,2p) by rounding u down to the previous fixed real. Result is in default interval [0,1).

Definition at line 197 of file RandomCanonical.hpp.

References STATIC_ASSERT, and RandomLib::RandomCanonical< Generator >::width.

Referenced by main(), and RandomLib::RandomCanonical< Generator >::Real().

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::Fixed (  )  throw () [inline]

See documentation for RandomCanonical::Fixed<RealType,prec>().

Definition at line 222 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::Fixed (  )  throw () [inline]

See documentation for RandomCanonical::Fixed<RealType,prec>().

Definition at line 227 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::Real (  )  throw () [inline]

An alias for RandomCanonical::Fixed<RealType>(). Returns a random number of type RealType in [0,1).

Definition at line 233 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::Real (  )  throw () [inline]

An alias for RandomCanonical::Fixed(). Returns a random double in [0,1).

Definition at line 239 of file RandomCanonical.hpp.

References RandomLib::RandomCanonical< Generator >::Fixed().

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::FixedU (  )  throw () [inline]

Return i h with i in (0,2p] by rounding u up to the next fixed real. Result is in upper interval (0,1].

Definition at line 246 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FixedU (  )  throw () [inline]

See documentation for RandomCanonical::FixedU<RealType,prec>().

Definition at line 251 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FixedU (  )  throw () [inline]

See documentation for RandomCanonical::FixedU<RealType,prec>().

Definition at line 256 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::FixedN (  )  throw () [inline]

Return i h with i in [0,2p] by rounding u to the nearest fixed real. Result is in nearest interval [0,1]. The probability of returning interior values is h while the probability of returning the endpoints is h/2.

Definition at line 264 of file RandomCanonical.hpp.

References RandomLib::RandomCanonical< Generator >::Boolean().

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FixedN (  )  throw () [inline]

See documentation for RandomCanonical::FixedN<RealType,prec>().

Definition at line 271 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FixedN (  )  throw () [inline]

See documentation for RandomCanonical::FixedN<RealType,prec>().

Definition at line 276 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::FixedW (  )  throw () [inline]

Return i h with i in [-2p, 2p] by rounding 2u - 1 to the nearest fixed real. Result is in wide interval [-1,1]. The probability of returning interior values is h/2 while the probability of returning the endpoints is h/4.

Definition at line 285 of file RandomCanonical.hpp.

References RandomLib::RandomCanonical< Generator >::Boolean(), STATIC_ASSERT, and RandomLib::RandomCanonical< Generator >::width.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FixedW (  )  throw () [inline]

See documentation for RandomCanonical::FixedW<RealType,prec>().

Definition at line 307 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FixedW (  )  throw () [inline]

See documentation for RandomCanonical::FixedW<RealType,prec>().

Definition at line 312 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::FixedS (  )  throw () [inline]

Return (i+1/2)h with i in [2p-1, 2p-1) by rounding u - 1/2 to nearest offset fixed real. Result is in symmetric interval (-1/2,1/2).

Definition at line 319 of file RandomCanonical.hpp.

Referenced by main().

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FixedS (  )  throw () [inline]

See documentation for RandomCanonical::FixedS<RealType,prec>().

Definition at line 325 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FixedS (  )  throw () [inline]

See documentation for RandomCanonical::FixedS<RealType,prec>().

Definition at line 330 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::FixedO (  )  throw () [inline]

Return i h with i in (0,2p) by rounding (1 - h)u up to next fixed real. Result is in open interval (0,1).

Definition at line 337 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FixedO (  )  throw () [inline]

See documentation for RandomCanonical::FixedO<RealType,prec>().

Definition at line 354 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FixedO (  )  throw () [inline]

See documentation for RandomCanonical::FixedO<RealType,prec>().

Definition at line 359 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec>
RealType RandomLib::RandomCanonical< Generator >::FixedC (  )  throw () [inline]

Return i h with i in [0,2p] by rounding (1 + h)u down to previous fixed real. Result is in closed interval [0,1].

Definition at line 366 of file RandomCanonical.hpp.

References STATIC_ASSERT, and RandomLib::RandomCanonical< Generator >::width.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FixedC (  )  throw () [inline]

See documentation for RandomCanonical::FixedC<RealType,prec>().

Definition at line 426 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FixedC (  )  throw () [inline]

See documentation for RandomCanonical::FixedC<RealType,prec>().

Definition at line 431 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec, int erange>
RealType RandomLib::RandomCanonical< Generator >::Float (  )  throw () [inline]

In the description of the functions FloatX returning floating-point numbers, u is a random real number uniformly distributed in (0, 1), p is the precision, and e is the exponent range. Each of the functions come in three variants, e.g.,

See the summary for a comparison of the functions.

Return result is in default interval [0,1) by rounding u down to the previous floating real.

Definition at line 459 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::Float (  )  throw () [inline]

See documentation for RandomCanonical::Float<RealType,prec,erange>().

Definition at line 464 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::Float (  )  throw () [inline]

See documentation for RandomCanonical::Float<RealType,prec,erange>().

Definition at line 471 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec, int erange>
RealType RandomLib::RandomCanonical< Generator >::FloatU (  )  throw () [inline]

Return result is in upper interval (0,1] by round u up to the next floating real.

Definition at line 477 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FloatU (  )  throw () [inline]

See documentation for RandomCanonical::FloatU<RealType,prec,erange>().

Definition at line 482 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FloatU (  )  throw () [inline]

See documentation for RandomCanonical::FloatU<RealType,prec,erange>().

Definition at line 489 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec, int erange>
RealType RandomLib::RandomCanonical< Generator >::FloatN (  )  throw () [inline]

Return result is in nearest interval [0,1] by rounding u to the nearest floating real.

Definition at line 495 of file RandomCanonical.hpp.

References RandomLib::RandomCanonical< Generator >::width.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FloatN (  )  throw () [inline]

See documentation for RandomCanonical::FloatN<RealType,prec,erange>().

Definition at line 511 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FloatN (  )  throw () [inline]

See documentation for RandomCanonical::FloatN<RealType,prec,erange>().

Definition at line 518 of file RandomCanonical.hpp.

template<class Generator>
template<typename RealType , int prec, int erange>
RealType RandomLib::RandomCanonical< Generator >::FloatW (  )  throw () [inline]

Return result is in wide interval [-1,1], by rounding 2u - 1 to the nearest floating real.

Definition at line 525 of file RandomCanonical.hpp.

References RandomLib::RandomCanonical< Generator >::width.

template<class Generator>
template<typename RealType >
RealType RandomLib::RandomCanonical< Generator >::FloatW (  )  throw () [inline]

See documentation for RandomCanonical::FloatW<RealType,prec,erange>().

Definition at line 538 of file RandomCanonical.hpp.

template<class Generator>
double RandomLib::RandomCanonical< Generator >::FloatW (  )  throw () [inline]

See documentation for RandomCanonical::FloatW<RealType,prec,erange>().

Definition at line 545 of file RandomCanonical.hpp.

template<class Generator>
bool RandomLib::RandomCanonical< Generator >::Boolean (  )  throw () [inline]
template<class Generator>
template<typename NumericType >
bool RandomLib::RandomCanonical< Generator >::Prob ( NumericType  p  )  throw () [inline]

The Bernoulli distribution, true with probability p. False if p <= 0; true if p >= 1. Equivalent to RandomCanonical::Float() < p, but typically faster.

Referenced by main().

template<class Generator>
template<typename NumericType >
bool RandomLib::RandomCanonical< Generator >::Prob ( NumericType  m,
NumericType  n 
) throw () [inline]

True with probability m/n. False if m <= 0 or n < 0; true if m >= n. With real types, Prob(x, y) is exact but slower than Prob(x/y).

template<class Generator >
template<int nbits>
std::bitset< nbits > RandomLib::RandomCanonical< Generator >::Bits (  )  throw () [inline]

Return nbits random bits

Definition at line 1003 of file RandomCanonical.hpp.

References STATIC_ASSERT, and RandomLib::RandomCanonical< Generator >::width.

template<class Generator >
template<typename UIntT >
UIntT::type RandomLib::RandomCanonical< Generator >::Unsigned ( typename UIntT::type  n  )  throw () [inline, private]

A helper for Integer(n). A random unsigned integer in [0, n]. If n >= 232, this must be invoked with onep = false. Otherwise, it should be invoked with onep = true.

Definition at line 678 of file RandomCanonical.hpp.

template<class Generator >
template<typename RealType , int prec, int erange, bool up>
RealType RandomLib::RandomCanonical< Generator >::FloatZ ( int  b,
result_type  m 
) throw () [inline, private]

A helper for Float and FloatU. Produces up ? FloatU() : Float(). On entry the low b bits of m are usable random bits.

Definition at line 776 of file RandomCanonical.hpp.

References RandomLib::RandomPower2::minpow, RANDOM_HASDENORM, and STATIC_ASSERT.

template<class Generator >
template<typename RealType >
bool RandomLib::RandomCanonical< Generator >::ProbF ( RealType  z  )  throw () [inline, private]

The one-argument version of Prob for real types

Definition at line 885 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<class Generator >
template<typename RealType >
bool RandomLib::RandomCanonical< Generator >::ProbF ( RealType  x,
RealType  y 
) throw () [inline, private]

The two-argument version of Prob for real types

Definition at line 940 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<>
RandomCanonical< MRandomGenerator32 > RandomLib::RandomCanonical< MRandomGenerator32 >::Global ( std::vector< unsigned long >  0  )  [inline]
template<>
RandomCanonical< MRandomGenerator64 > RandomLib::RandomCanonical< MRandomGenerator64 >::Global ( std::vector< unsigned long >  0  )  [inline]
template<>
RandomCanonical< SRandomGenerator32 > RandomLib::RandomCanonical< SRandomGenerator32 >::Global ( std::vector< unsigned long >  0  )  [inline]
template<>
RandomCanonical< SRandomGenerator64 > RandomLib::RandomCanonical< SRandomGenerator64 >::Global ( std::vector< unsigned long >  0  )  [inline]

Member Data Documentation

template<class Generator>
RandomCanonical RandomLib::RandomCanonical< Generator >::Global [static]

A "global" random number generator (not thread-safe!), initialized with a fixed seed [].

Definition at line 590 of file RandomCanonical.hpp.


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

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