Random Number Generation

Classes
class	itpp::Random_Generator
	Base class for random (stochastic) sources. More...
class	itpp::Bernoulli_RNG
	Bernoulli distribution. More...
class	itpp::I_Uniform_RNG
	Integer uniform distributionExample: Generation of random uniformly distributed integers in the interval [0,10]. More...
class	itpp::Uniform_RNG
	Uniform distribution. More...
class	itpp::Exponential_RNG
	Exponential distribution. More...
class	itpp::Normal_RNG
	Normal distributionNormal (Gaussian) random variables, using a simplified Ziggurat method. More...
class	itpp::Gamma_RNG
	Gamma distributionGenerate samples from Gamma(alpha,beta) density, according to the following equation: . More...
class	itpp::Laplace_RNG
	Laplacian distribution. More...
class	itpp::Complex_Normal_RNG
	A Complex Normal Source. More...
class	itpp::AR1_Normal_RNG
	Filtered normal distribution. More...
class	itpp::Weibull_RNG
	Weibull distribution. More...
class	itpp::Rayleigh_RNG
	Rayleigh distribution. More...
class	itpp::Rice_RNG
	Rice distribution. More...
class	itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >
	C++ implementation of dSFMT random number generator. More...
struct	itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::Context
	DSFMT context structure. More...
union	itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::Context::W128_T
	Data structure to hold 128-bit values. More...

Typedefs
typedef Normal_RNG	itpp::Gauss_RNG
	Gauss_RNG is the same as Normal Source.
typedef AR1_Normal_RNG	itpp::AR1_Gauss_RNG
	AR1_Gauss_RNG is the same as AR1_Normal_RNG.
typedef DSFMT_19937_RNG	itpp::random_details::ActiveDSFMT
	Active Generator for random (stochastic) sources.

Functions
void	itpp::GlobalRNG_reset (unsigned int seed)
	Set the internal seed of the Global Seed Provider.
void	itpp::GlobalRNG_reset ()
	Reset the internal seed of the Global Seed Provider to the previously set value.
unsigned int	itpp::GlobalRNG_get_local_seed ()
	Get new seed to initialize thread-local generators.
void	itpp::GlobalRNG_randomize ()
	Set a random seed for the Global Seed Provider seed.
void	itpp::GlobalRNG_get_state (ivec &state)
	Save current full state of global seed provider in memory.
void	itpp::GlobalRNG_set_state (const ivec &state)
	Resume the global seed provider state saved in memory.
void	itpp::RNG_reset (unsigned int seed)
	Set the seed for all Random Number Generators in the current thread.
void	itpp::RNG_reset ()
	Reset the seed to the previously set value for all Random Number Generators in the current thread.
void	itpp::RNG_randomize ()
	Set a random seed for all Random Number Generators in the current thread.
void	itpp::RNG_get_state (ivec &state)
	Save Random Number generation context used in the current thread.
void	itpp::RNG_set_state (const ivec &state)
	Resume Random Number generation in the current thread with previously stored context.
bin	itpp::randb (void)
	Generates a random bit (equally likely 0s and 1s)
void	itpp::randb (int size, bvec &out)
	Generates a random bit vector (equally likely 0s and 1s)
bvec	itpp::randb (int size)
	Generates a random bit vector (equally likely 0s and 1s)
void	itpp::randb (int rows, int cols, bmat &out)
	Generates a random bit matrix (equally likely 0s and 1s)
bmat	itpp::randb (int rows, int cols)
	Generates a random bit matrix (equally likely 0s and 1s)
double	itpp::randu (void)
	Generates a random uniform (0,1) number.
void	itpp::randu (int size, vec &out)
	Generates a random uniform (0,1) vector.
vec	itpp::randu (int size)
	Generates a random uniform (0,1) vector.
void	itpp::randu (int rows, int cols, mat &out)
	Generates a random uniform (0,1) matrix.
mat	itpp::randu (int rows, int cols)
	Generates a random uniform (0,1) matrix.
int	itpp::randi (int low, int high)
	Generates a random integer in the interval [low,high].
ivec	itpp::randi (int size, int low, int high)
	Generates a random ivec with elements in the interval [low,high].
imat	itpp::randi (int rows, int cols, int low, int high)
	Generates a random imat with elements in the interval [low,high].
vec	itpp::randray (int size, double sigma=1.0)
	Generates a random Rayleigh vector.
vec	itpp::randrice (int size, double sigma=1.0, double s=1.0)
	Generates a random Rice vector (See J.G. Poakis, "Digital Communications, 3rd ed." p.47)
vec	itpp::randexp (int size, double lambda=1.0)
	Generates a random complex Gaussian vector.
double	itpp::randn (void)
	Generates a random Gaussian (0,1) variable.
void	itpp::randn (int size, vec &out)
	Generates a random Gaussian (0,1) vector.
vec	itpp::randn (int size)
	Generates a random Gaussian (0,1) vector.
void	itpp::randn (int rows, int cols, mat &out)
	Generates a random Gaussian (0,1) matrix.
mat	itpp::randn (int rows, int cols)
	Generates a random Gaussian (0,1) matrix.
std::complex< double >	itpp::randn_c (void)
	Generates a random complex Gaussian (0,1) variable.
void	itpp::randn_c (int size, cvec &out)
	Generates a random complex Gaussian (0,1) vector.
cvec	itpp::randn_c (int size)
	Generates a random complex Gaussian (0,1) vector.
void	itpp::randn_c (int rows, int cols, cmat &out)
	Generates a random complex Gaussian (0,1) matrix.
cmat	itpp::randn_c (int rows, int cols)
	Generates a random complex Gaussian (0,1) matrix.
ActiveDSFMT::Context &	itpp::random_details::lc_get ()
	Function to access thread-local context for random numbers generation.
bool	itpp::random_details::lc_is_initialized ()
	Function to check if thread-local context is initialized.
void	itpp::random_details::lc_mark_initialized ()
	Function to mark thread-local context as initialized.

Detailed Description

end of algebra group

Set of functions to work with global seed provider:

void GlobalRNG_reset(unsigned int seed);
void GlobalRNG_reset();
unsigned int GlobalRNG_get_local_seed();
void GlobalRNG_randomize();
void GlobalRNG_get_state(ivec &state);
void GlobalRNG_set_state(const ivec &state);

Global seed provider generate default seeds to initialize per-thread generators of pseudo-random numbers. Functions implement mutually exclusive access to the global seed provider instance.

Be carefull,

Mutual exclusion serializes access to the global seed provider context and protects its integrity. It does not guarantee the expected results if global seed provider is accessed simultaneously from several threads.

For example,

ivec st_before,st_after;
GlobalRNG_get_state(st_before);
GlobalRNG_set_state(st_before);
GlobalRNG_get_state(st_after);
assert(st_before==st_after);

last assert can fail in multithreaded environment.

Be aware,

Global seed provider generates seeds to initialize non-initialized per-thread RNG contexts. Global seed provider is just a random numbers generator starting with default seed equal to 4257U. When RNGs are created in some thread, global seed provider is queried for the new seed to initialize random number generation in the current thread. The first seed returned by the global seed provider is also 4257U by default. Other seeds are taken from the rng output directly. It is implemented this way because some ITPP tests implicitly rely on this value. Global seed provider internals are defined in random.cpp and can be changed easily if such a behaviour is not desirable. Global initialization can be overriden by the explicit call of the local context initialization function. Global seed provider changes will not affect already initialized contexts in running or parked threads, since global seeds are used during the local context initialization only. Local contexts get initialized upon creation of first RandomGenerator object in each thread. RNG_reset() without arguments can also query a global seed if local context is not initialized when the function is called. For example, if you want the main thread context to be affected by global settings, GlobalRNG_reset(seed) shall be called BEFORE the construction of first RandomGenerator object. The best place to do it is the very beginning of your main() function. If you create itpp library objects, encapsulating RNGs, statically, the main thread context will not be affected by any call to GlobalRNG_reset(s)/GlobalRNG_set_state(s). If you still want to have main-thread state be derived from the global context, you should do the following trick at the beginning of main():

unsigned int my_global_seed = 0xAAAAAAAA;
GlobalRNG_reset(my_global_seed);
unsigned int s = GlobalRNG_get_local_seed(); //query new local seed
RNG_reset(s); //set it maually for the main thread
//you can call your main-thread RNGs here

Local (per-thread) RNG context management.

void RNG_reset(unsigned int seed);
void RNG_reset();
void RNG_get_state(ivec &state);
void RNG_set_state(const ivec &state);

This set of functions allow to override seed value set from global seed provider and use custom seeds/initialization vectors for each thread (including main thread).

Some functions to deal with thread-local RNG generation context:

ActiveDSFMT::Context& lc_get();
bool lc_is_initialized();
void lc_mark_initialized();

Typedef Documentation

typedef DSFMT_19937_RNG itpp::random_details::ActiveDSFMT

Active Generator for random (stochastic) sources.

ActiveDSFMT is a typedef of DSFMT class specialization using 19937 generation period. Library shall be recompiled if switched to other available algorithm.

See Also

DSFMT

Definition at line 395 of file random_dsfmt.h.

Function Documentation

ITPP_EXPORT void itpp::RNG_reset

(

)

Reset the seed to the previously set value for all Random Number Generators in the current thread.

Seed will be queried from the global seed provider if Random Number generation context is not initialized

Definition at line 238 of file random.cpp.

References itpp::GlobalRNG_get_local_seed(), itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::init_gen_rand(), itpp::random_details::lc_get(), itpp::random_details::lc_is_initialized(), and itpp::random_details::lc_mark_initialized().

std::complex<double> itpp::randn_c ( void  )

inline

Generates a random complex Gaussian (0,1) variable.

The real and imaginary parts are independent and have variances equal to 0.5

Definition at line 845 of file random.h.

References itpp::Complex_Normal_RNG::sample().

Referenced by itpp::Independent_Fading_Generator::generate(), itpp::FIR_Fading_Generator::generate(), itpp::IFFT_Fading_Generator::generate_Jakes(), itpp::Static_Fading_Generator::init(), itpp::FIR_Fading_Generator::init(), and itpp::randn_c().