Random Number Generation
Base Module

## 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 distribution. More...
class | itpp::Uniform_RNG
| Uniform distribution. More...
class | itpp::Exponential_RNG
| Exponential distribution. More...
class | itpp::Normal_RNG
| Normal distribution. More...
class | itpp::Gamma_RNG
| Gamma distribution. 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...

## 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);
itpp::GlobalRNG_get_state
void GlobalRNG_get_state(ivec &state)
Save current full state of global seed provider in memory.
Definition random.cpp:213
itpp::GlobalRNG_get_local_seed
unsigned int GlobalRNG_get_local_seed()
Get new seed to initialize thread-local generators.
Definition random.cpp:193
itpp::GlobalRNG_reset
void GlobalRNG_reset()
Reset the internal seed of the Global Seed Provider to the previously set value.
Definition random.cpp:185
itpp::GlobalRNG_randomize
void GlobalRNG_randomize()
Set a random seed for the Global Seed Provider seed.
Definition random.cpp:204
itpp::GlobalRNG_set_state
void GlobalRNG_set_state(const ivec &state)
Resume the global seed provider state saved in memory.
Definition random.cpp:222

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
itpp::RNG_reset
void RNG_reset()
Reset the seed to the previously set value for all Random Number Generators in the current thread.
Definition random.cpp:238

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);
itpp::RNG_set_state
void RNG_set_state(const ivec &state)
Resume Random Number generation in the current thread with previously stored context.
Definition random.cpp:274
itpp::RNG_get_state
void RNG_get_state(ivec &state)
Save Random Number generation context used in the current thread.
Definition random.cpp:262

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();
itpp::random_details::lc_mark_initialized
void lc_mark_initialized()
Function to mark thread-local context as initialized.
Definition random.cpp:57
itpp::random_details::lc_is_initialized
bool lc_is_initialized()
Function to check if thread-local context is initialized.
Definition random.cpp:52
itpp::random_details::lc_get
ActiveDSFMT::Context & lc_get()
Function to access thread-local context for random numbers generation.
Definition random.cpp:47

## Typedef Documentation

## Gauss_RNG

typedef Normal_RNG itpp::Gauss_RNG

Gauss_RNG is the same as Normal Source.

Definition at line 693 of file random.h.

## AR1_Gauss_RNG

typedef AR1_Normal_RNG itpp::AR1_Gauss_RNG

AR1_Gauss_RNG is the same as AR1_Normal_RNG.

Definition at line 699 of file random.h.

## ActiveDSFMT

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

## GlobalRNG_reset() [1/2]

ITPP_EXPORT void itpp::GlobalRNG_reset | ( | unsigned int | seed | ) |

Set the internal seed of the Global Seed Provider.

Definition at line 176 of file random.cpp.

## GlobalRNG_reset() [2/2]

ITPP_EXPORT void itpp::GlobalRNG_reset | ( |  | ) |

Reset the internal seed of the Global Seed Provider to the previously set value.

Definition at line 185 of file random.cpp.

## GlobalRNG_get_local_seed()

ITPP_EXPORT unsigned int itpp::GlobalRNG_get_local_seed | ( |  | ) |

Get new seed to initialize thread-local generators.

Definition at line 193 of file random.cpp.

Referenced by itpp::Random_Generator::Random_Generator(), and itpp::RNG_reset().

## GlobalRNG_randomize()

ITPP_EXPORT void itpp::GlobalRNG_randomize | ( |  | ) |

Set a random seed for the Global Seed Provider seed.

Definition at line 204 of file random.cpp.

## GlobalRNG_get_state()

ITPP_EXPORT void itpp::GlobalRNG_get_state | ( | ivec & | state | ) |

Save current full state of global seed provider in memory.

Definition at line 213 of file random.cpp.

## GlobalRNG_set_state()

ITPP_EXPORT void itpp::GlobalRNG_set_state | ( | const ivec & | state | ) |

Resume the global seed provider state saved in memory.

Definition at line 222 of file random.cpp.

## RNG_reset() [1/2]

ITPP_EXPORT void itpp::RNG_reset | ( | unsigned int | seed | ) |

Set the seed for all Random Number Generators in the current thread.

Definition at line 230 of file random.cpp.

References itpp::random_details::lc_get(), and itpp::random_details::lc_mark_initialized().

## RNG_reset() [2/2]

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::lc_get(), itpp::random_details::lc_is_initialized(), and itpp::random_details::lc_mark_initialized().

## RNG_randomize()

ITPP_EXPORT void itpp::RNG_randomize | ( |  | ) |

Set a random seed for all Random Number Generators in the current thread.

Definition at line 254 of file random.cpp.

References itpp::random_details::lc_get(), and itpp::random_details::lc_mark_initialized().

## RNG_get_state()

ITPP_EXPORT void itpp::RNG_get_state | ( | ivec & | state | ) |

Save Random Number generation context used in the current thread.

Definition at line 262 of file random.cpp.

References itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::Context::idx, itpp::random_details::lc_get(), itpp::Array< T >::set_size(), itpp::size(), and itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::Context::status.

## RNG_set_state()

ITPP_EXPORT void itpp::RNG_set_state | ( | const ivec & | state | ) |

Resume Random Number generation in the current thread with previously stored context.

Definition at line 274 of file random.cpp.

References itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::Context::idx, it_assert, itpp::random_details::lc_get(), itpp::Array< T >::size(), itpp::size(), and itpp::random_details::DSFMT< MEXP, POS1, SL1, MSK1, MSK2, FIX1_V, FIX2_V, PCV1_V, PCV2_V >::Context::status.

## randb() [1/5]

bin itpp::randb | ( | void |  | ) |

inline

Generates a random bit (equally likely 0s and 1s)

Definition at line 793 of file random.h.

Referenced by itpp::randb(), and itpp::randb().

## randb() [2/5]

void itpp::randb | ( | int | size,
|  | bvec & | out
| ) |  |

inline

Generates a random bit vector (equally likely 0s and 1s)

Definition at line 795 of file random.h.

References itpp::size().

## randb() [3/5]

bvec itpp::randb | ( | int | size | ) |

inline

Generates a random bit vector (equally likely 0s and 1s)

Definition at line 797 of file random.h.

References itpp::randb(), and itpp::size().

## randb() [4/5]

void itpp::randb | ( | int | rows,
|  | int | cols,
|  | bmat & | out
| ) |  |

inline

Generates a random bit matrix (equally likely 0s and 1s)

Definition at line 799 of file random.h.

## randb() [5/5]

bmat itpp::randb | ( | int | rows,
|  | int | cols
| ) |  |

inline

Generates a random bit matrix (equally likely 0s and 1s)

Definition at line 801 of file random.h.

References itpp::randb().

## randu() [1/5]

double itpp::randu | ( | void |  | ) |

inline

Generates a random uniform (0,1) number.

Definition at line 804 of file random.h.

Referenced by itpp::LDPC_Generator_Systematic::construct(), itpp::LDPC_Parity_Unstructured::cycle_removal_MGW(), fpica(), itpp::LDPC_Parity_Unstructured::generate_random_H(), getSamples(), itpp::Rice_Fading_Generator::init_MEDS(), itpp::Sequence_Interleaver< T >::randomize_interleaver_sequence(), itpp::randu(), itpp::randu(), itpp::Sequence_Interleaver< T >::Sequence_Interleaver(), and itpp::Turbo_Codec::wcdma_turbo_interleaver_sequence().

## randu() [2/5]

void itpp::randu | ( | int | size,
|  | vec & | out
| ) |  |

inline

Generates a random uniform (0,1) vector.

Definition at line 806 of file random.h.

References itpp::size().

## randu() [3/5]

vec itpp::randu | ( | int | size | ) |

inline

Generates a random uniform (0,1) vector.

Definition at line 808 of file random.h.

References itpp::randu(), and itpp::size().

## randu() [4/5]

void itpp::randu | ( | int | rows,
|  | int | cols,
|  | mat & | out
| ) |  |

inline

Generates a random uniform (0,1) matrix.

Definition at line 810 of file random.h.

## randu() [5/5]

mat itpp::randu | ( | int | rows,
|  | int | cols
| ) |  |

inline

Generates a random uniform (0,1) matrix.

Definition at line 812 of file random.h.

References itpp::randu().

## randi() [1/3]

int itpp::randi | ( | int | low,
|  | int | high
| ) |  |

inline

Generates a random integer in the interval [low,high].

Definition at line 815 of file random.h.

Referenced by itpp::LDPC_Parity_Unstructured::cycle_removal_MGW(), and itpp::LDPC_Parity_Unstructured::generate_random_H().

## randi() [2/3]

ivec itpp::randi | ( | int | size,
|  | int | low,
|  | int | high
| ) |  |

inline

Generates a random ivec with elements in the interval [low,high].

Definition at line 817 of file random.h.

References itpp::size().

## randi() [3/3]

imat itpp::randi | ( | int | rows,
|  | int | cols,
|  | int | low,
|  | int | high
| ) |  |

inline

Generates a random imat with elements in the interval [low,high].

Definition at line 819 of file random.h.

## randray()

vec itpp::randray | ( | int | size,
|  | double | sigma = `1.0`
| ) |  |

inline

Generates a random Rayleigh vector.

Definition at line 822 of file random.h.

References itpp::size().

## randrice()

vec itpp::randrice | ( | int | size,
|  | double | sigma = `1.0`,
|  | double | s = `1.0`
| ) |  |

inline

Generates a random Rice vector (See J.G. Poakis, "Digital Communications, 3rd ed." p.47)

Definition at line 825 of file random.h.

References itpp::size().

## randexp()

vec itpp::randexp | ( | int | size,
|  | double | lambda = `1.0`
| ) |  |

inline

Generates a random complex Gaussian vector.

Definition at line 828 of file random.h.

References itpp::size().

## randn() [1/5]

double itpp::randn | ( | void |  | ) |

inline

Generates a random Gaussian (0,1) variable.

Definition at line 831 of file random.h.

Referenced by itpp::EXIT::generate_apriori_info(), itpp::randn(), and itpp::randn().

## randn() [2/5]

void itpp::randn | ( | int | size,
|  | vec & | out
| ) |  |

inline

Generates a random Gaussian (0,1) vector.

Definition at line 833 of file random.h.

References itpp::size().

## randn() [3/5]

vec itpp::randn | ( | int | size | ) |

inline

Generates a random Gaussian (0,1) vector.

Definition at line 835 of file random.h.

References itpp::randn(), and itpp::size().

## randn() [4/5]

void itpp::randn | ( | int | rows,
|  | int | cols,
|  | mat & | out
| ) |  |

inline

Generates a random Gaussian (0,1) matrix.

Definition at line 837 of file random.h.

## randn() [5/5]

mat itpp::randn | ( | int | rows,
|  | int | cols
| ) |  |

inline

Generates a random Gaussian (0,1) matrix.

Definition at line 839 of file random.h.

References itpp::randn().

## randn_c() [1/5]

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.

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(), itpp::randn_c(), and itpp::randn_c().

## randn_c() [2/5]

void itpp::randn_c | ( | int | size,
|  | cvec & | out
| ) |  |

inline

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

Definition at line 847 of file random.h.

References itpp::size().

## randn_c() [3/5]

cvec itpp::randn_c | ( | int | size | ) |

inline

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

Definition at line 849 of file random.h.

References itpp::randn_c(), and itpp::size().

## randn_c() [4/5]

void itpp::randn_c | ( | int | rows,
|  | int | cols,
|  | cmat & | out
| ) |  |

inline

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

Definition at line 851 of file random.h.

## randn_c() [5/5]

cmat itpp::randn_c | ( | int | rows,
|  | int | cols
| ) |  |

inline

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

Definition at line 853 of file random.h.

References itpp::randn_c().

## lc_get()

ITPP_EXPORT ActiveDSFMT::Context & itpp::random_details::lc_get | ( |  | ) |

Function to access thread-local context for random numbers generation.

Definition at line 47 of file random.cpp.

Referenced by itpp::RNG_get_state(), itpp::RNG_randomize(), itpp::RNG_reset(), itpp::RNG_reset(), and itpp::RNG_set_state().

## lc_is_initialized()

ITPP_EXPORT bool itpp::random_details::lc_is_initialized | ( |  | ) |

Function to check if thread-local context is initialized.

Definition at line 52 of file random.cpp.

Referenced by itpp::Random_Generator::Random_Generator(), and itpp::RNG_reset().

## lc_mark_initialized()

ITPP_EXPORT void itpp::random_details::lc_mark_initialized | ( |  | ) |

Function to mark thread-local context as initialized.

Definition at line 57 of file random.cpp.

Referenced by itpp::Random_Generator::Random_Generator(), itpp::RNG_randomize(), itpp::RNG_reset(), and itpp::RNG_reset().

Generated on Mon Jun 10 2024 11:49:30 for IT++ by Doxygen 1.9.8