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

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

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

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,2^w). Probably some modifications would be needed if w is not 32 or 64.

Member Typedef Documentation

typedef Generator::result_type RandomLib::RandomCanonical::result_type

The type of operator()().

Definition at line 50 of file RandomCanonical.hpp.

typedef RandomSeed::seed_type RandomLib::RandomCanonical::seed_type

The type of elements of Seed().

Definition at line 54 of file RandomCanonical.hpp.

typedef RandomSeed::u32 RandomLib::RandomCanonical::u32 [private]

Definition at line 592 of file RandomCanonical.hpp.

typedef RandomSeed::u64 RandomLib::RandomCanonical::u64 [private]

Definition at line 593 of file RandomCanonical.hpp.

Member Enumeration Documentation

anonymous enum

Enumerator:

width

The number of random bits in result_type.

Definition at line 55 of file RandomCanonical.hpp.

Constructor & Destructor Documentation

template<typename IntType >

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

Initialize from a vector.

Definition at line 69 of file RandomCanonical.hpp.

template<typename InputIterator >

RandomLib::RandomCanonical::RandomCanonical	(	InputIterator	a,
		InputIterator	b
	)		`[inline]`

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

Definition at line 75 of file RandomCanonical.hpp.

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

Initialize with seed [n]

Definition at line 620 of file RandomCanonical.hpp.

References STATIC_ASSERT, RANDOM_LONGDOUBLEPREC, RandomLib::RandomPower2::minpow, RANDOM_HASDENORM, RandomLib::RandomPower2::maxpow, and width.

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

Initialize with seed [SeedVector()]

Definition at line 83 of file RandomCanonical.hpp.

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

Initialize from a string. See RandomCanonical::StringToVector

Definition at line 87 of file RandomCanonical.hpp.

Member Function Documentation

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

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

Definition at line 98 of file RandomCanonical.hpp.

result_type RandomLib::RandomCanonical::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 110 of file RandomCanonical.hpp.

template<typename IntType , int bits>

IntType RandomLib::RandomCanonical::Integer ( ) throw () [inline]

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

Definition at line 118 of file RandomCanonical.hpp.

References STATIC_ASSERT, width, and RandomLib::RandomType::mask.

template<int bits>

result_type RandomLib::RandomCanonical::Integer ( ) throw () [inline]

A random integer in [0, 2^b).

Definition at line 138 of file RandomCanonical.hpp.

template<typename IntType >

IntType RandomLib::RandomCanonical::Integer ( ) throw ()

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

result_type RandomLib::RandomCanonical::Integer ( ) throw () [inline]

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

Definition at line 149 of file RandomCanonical.hpp.

template<typename IntType >

IntType RandomLib::RandomCanonical::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,2³¹) with RandomCanonical::Integer<int>() which returns a result in [-2³¹,2³¹).

Definition at line 718 of file RandomCanonical.hpp.

References STATIC_ASSERT, and RandomLib::RandomType::mask.

template<typename IntType >

IntType RandomLib::RandomCanonical::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 739 of file RandomCanonical.hpp.

References STATIC_ASSERT, and RandomLib::RandomType::mask.

Referenced by main().

template<typename IntType >

IntType RandomLib::RandomCanonical::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 755 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::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/2^p. Each of the functions come in three variants, e.g.,

RandomCanonical::Fixed<RealType,p>() --- return fixed-point real of type RealType, precision p;

RandomCanonical::Fixed<RealType>() --- as above with p = std::numeric_limits<RealType>::digits;
RandomCanonical::Fixed() --- as above with RealType = double.

See the summary for a comparison of the functions.

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

Definition at line 196 of file RandomCanonical.hpp.

References STATIC_ASSERT, and width.

Referenced by Real(), and main().

template<typename RealType >

RealType RandomLib::RandomCanonical::Fixed ( ) throw () [inline]

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

Definition at line 221 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::Fixed ( ) throw () [inline]

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

Definition at line 226 of file RandomCanonical.hpp.

template<typename RealType >

RealType RandomLib::RandomCanonical::Real ( ) throw () [inline]

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

Definition at line 232 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::Real ( ) throw () [inline]

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

Definition at line 238 of file RandomCanonical.hpp.

References Fixed().

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::FixedU ( ) throw () [inline]

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

Definition at line 245 of file RandomCanonical.hpp.

template<typename RealType >

RealType RandomLib::RandomCanonical::FixedU ( ) throw () [inline]

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

Definition at line 250 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FixedU ( ) throw () [inline]

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

Definition at line 255 of file RandomCanonical.hpp.

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::FixedN ( ) throw () [inline]

Return i h with i in [0,2^p] 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 263 of file RandomCanonical.hpp.

References Boolean().

template<typename RealType >

RealType RandomLib::RandomCanonical::FixedN ( ) throw () [inline]

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

Definition at line 270 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FixedN ( ) throw () [inline]

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

Definition at line 275 of file RandomCanonical.hpp.

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::FixedW ( ) throw () [inline]

Return i h with i in [-2^p, 2^p] 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 284 of file RandomCanonical.hpp.

References STATIC_ASSERT, width, and Boolean().

template<typename RealType >

RealType RandomLib::RandomCanonical::FixedW ( ) throw () [inline]

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

Definition at line 306 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FixedW ( ) throw () [inline]

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

Definition at line 311 of file RandomCanonical.hpp.

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::FixedS ( ) throw () [inline]

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

Definition at line 318 of file RandomCanonical.hpp.

Referenced by main().

template<typename RealType >

RealType RandomLib::RandomCanonical::FixedS ( ) throw () [inline]

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

Definition at line 324 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FixedS ( ) throw () [inline]

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

Definition at line 329 of file RandomCanonical.hpp.

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::FixedO ( ) throw () [inline]

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

Definition at line 336 of file RandomCanonical.hpp.

References STATIC_ASSERT.

template<typename RealType >

RealType RandomLib::RandomCanonical::FixedO ( ) throw () [inline]

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

Definition at line 353 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FixedO ( ) throw () [inline]

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

Definition at line 358 of file RandomCanonical.hpp.

template<typename RealType , int prec>

RealType RandomLib::RandomCanonical::FixedC ( ) throw () [inline]

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

Definition at line 365 of file RandomCanonical.hpp.

References STATIC_ASSERT, and width.

template<typename RealType >

RealType RandomLib::RandomCanonical::FixedC ( ) throw () [inline]

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

Definition at line 425 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FixedC ( ) throw () [inline]

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

Definition at line 430 of file RandomCanonical.hpp.

template<typename RealType , int prec, int erange>

RealType RandomLib::RandomCanonical::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.,

RandomCanonical::Float<RealType,p,e>() --- return floating-point real of type RealType, precision p, and exponent range e;
RandomCanonical::Float<RealType>() --- as above with p = std::numeric_limits<RealType>::digits and e = -std::numeric_limits<RealType>::min_exponent;
RandomCanonical::Float() --- as above with RealType = double.

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 458 of file RandomCanonical.hpp.

template<typename RealType >

RealType RandomLib::RandomCanonical::Float ( ) throw () [inline]

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

Definition at line 463 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::Float ( ) throw () [inline]

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

Definition at line 470 of file RandomCanonical.hpp.

template<typename RealType , int prec, int erange>

RealType RandomLib::RandomCanonical::FloatU ( ) throw () [inline]

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

Definition at line 476 of file RandomCanonical.hpp.

template<typename RealType >

RealType RandomLib::RandomCanonical::FloatU ( ) throw () [inline]

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

Definition at line 481 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FloatU ( ) throw () [inline]

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

Definition at line 488 of file RandomCanonical.hpp.

template<typename RealType , int prec, int erange>

RealType RandomLib::RandomCanonical::FloatN ( ) throw () [inline]

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

Definition at line 494 of file RandomCanonical.hpp.

References width.

template<typename RealType >

RealType RandomLib::RandomCanonical::FloatN ( ) throw () [inline]

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

Definition at line 510 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FloatN ( ) throw () [inline]

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

Definition at line 517 of file RandomCanonical.hpp.

template<typename RealType , int prec, int erange>

RealType RandomLib::RandomCanonical::FloatW ( ) throw () [inline]

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

Definition at line 524 of file RandomCanonical.hpp.

References width.

template<typename RealType >

RealType RandomLib::RandomCanonical::FloatW ( ) throw () [inline]

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

Definition at line 537 of file RandomCanonical.hpp.

double RandomLib::RandomCanonical::FloatW ( ) throw () [inline]

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

Definition at line 544 of file RandomCanonical.hpp.

bool RandomLib::RandomCanonical::Boolean ( ) throw () [inline]

A coin toss. Equivalent to RandomCanonical::Integer<bool>().

Definition at line 553 of file RandomCanonical.hpp.

Referenced by FixedN(), FixedW(), and main().

template<typename NumericType >

bool RandomLib::RandomCanonical::Prob ( NumericType p ) throw ()

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<typename NumericType >

bool RandomLib::RandomCanonical::Prob	(	NumericType	m,
		NumericType	n
	)		throw ()

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<int nbits>

std::bitset< nbits > RandomLib::RandomCanonical::Bits ( ) throw () [inline]

Return nbits random bits

Definition at line 1002 of file RandomCanonical.hpp.

References STATIC_ASSERT, and width.

template<typename UIntT >

UIntT::type RandomLib::RandomCanonical::Unsigned ( typename UIntT::type n ) throw () [inline, private]

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

Definition at line 677 of file RandomCanonical.hpp.

References width, and RandomLib::RandomType::mask.

template<typename RealType , int prec, int erange, bool up>

RealType RandomLib::RandomCanonical::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 775 of file RandomCanonical.hpp.

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

template<typename RealType >

bool RandomLib::RandomCanonical::ProbF ( RealType z ) throw () [inline, private]

The one-argument version of Prob for real types

Definition at line 884 of file RandomCanonical.hpp.

References STATIC_ASSERT, and width.

template<typename RealType >

bool RandomLib::RandomCanonical::ProbF	(	RealType	x,
		RealType	y
	)		throw () `[inline, private]`

The two-argument version of Prob for real types

Definition at line 939 of file RandomCanonical.hpp.

References STATIC_ASSERT, and width.

template<>

RandomCanonical< MRandomGenerator32 > RandomLib::RandomCanonical< MRandomGenerator32 >::Global ( std::vector< unsigned long > 0 )

template<>

RandomCanonical< MRandomGenerator64 > RandomLib::RandomCanonical< MRandomGenerator64 >::Global ( std::vector< unsigned long > 0 )

template<>

RandomCanonical< SRandomGenerator32 > RandomLib::RandomCanonical< SRandomGenerator32 >::Global ( std::vector< unsigned long > 0 )

template<>

RandomCanonical< SRandomGenerator64 > RandomLib::RandomCanonical< SRandomGenerator64 >::Global ( std::vector< unsigned long > 0 )

Member Data Documentation

RandomCanonical RandomLib::RandomCanonical::Global [static]

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

Definition at line 589 of file RandomCanonical.hpp.

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

RandomCanonical.hpp

Public Types

Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation