PRNG

PRNG — generate pseudo-random values

Synopsis

#include <libgretl.h>

void                gretl_rand_init                     (void);
void                gretl_rand_free                     (void);
void                gretl_rand_set_seed                 (unsigned int seed);
void                gretl_rand_set_multi_seed           (const gretl_matrix *seed);
unsigned int        gretl_rand_int                      (void);
unsigned int        gretl_rand_int_max                  (unsigned int max);
int                 gretl_rand_int_minmax               (int *a,
                                                         int n,
                                                         int min,
                                                         int max);
double              gretl_rand_01                       (void);
double              gretl_one_snormal                   (void);
void                gretl_rand_uniform                  (double *a,
                                                         int t1,
                                                         int t2);
int                 gretl_rand_uniform_minmax           (double *a,
                                                         int t1,
                                                         int t2,
                                                         double min,
                                                         double max);
void                gretl_rand_normal                   (double *a,
                                                         int t1,
                                                         int t2);
int                 gretl_rand_normal_full              (double *a,
                                                         int t1,
                                                         int t2,
                                                         double mean,
                                                         double sd);
int                 gretl_rand_chisq                    (double *a,
                                                         int t1,
                                                         int t2,
                                                         int v);
int                 gretl_rand_student                  (double *a,
                                                         int t1,
                                                         int t2,
                                                         double v);
int                 gretl_rand_F                        (double *a,
                                                         int t1,
                                                         int t2,
                                                         int v1,
                                                         int v2);
int                 gretl_rand_binomial                 (double *a,
                                                         int t1,
                                                         int t2,
                                                         int n,
                                                         double p);
int                 gretl_rand_poisson                  (double *a,
                                                         int t1,
                                                         int t2,
                                                         const double *m,
                                                         int vec);
int                 gretl_rand_weibull                  (double *a,
                                                         int t1,
                                                         int t2,
                                                         double shape,
                                                         double scale);
int                 gretl_rand_gamma                    (double *a,
                                                         int t1,
                                                         int t2,
                                                         double shape,
                                                         double scale);
int                 gretl_rand_GED                      (double *a,
                                                         int t1,
                                                         int t2,
                                                         double nu);
void                gretl_rand_set_sfmt                 (int s);
int                 gretl_rand_get_sfmt                 (void);
void                gretl_rand_set_box_muller           (int s);
int                 gretl_rand_get_box_muller           (void);
unsigned int        gretl_rand_get_seed                 (void);

Description

Libgretl uses the Mersenne Twister as its underlying engine for uniform random values, but offers added value in the form of generators for several distributions commonly used in econometrics.

Note that before using the libgretl PRNG you must call either libgretl_init() or the specific initialization function shown below, gretl_rand_init(). And once you're finished with it, you may call gretl_rand_free() or the global libgretl function libgretl_cleanup().

Details

gretl_rand_init ()

void                gretl_rand_init                     (void);

Initialize gretl's PRNG, using the system time as seed.


gretl_rand_free ()

void                gretl_rand_free                     (void);

Free the gretl_rand structure (may be called at program exit).


gretl_rand_set_seed ()

void                gretl_rand_set_seed                 (unsigned int seed);

Set a specific (and hence reproducible) seed for gretl's PRNG. But if the value 0 is given for seed, set the seed using the system time (which is the default when libgretl is initialized).

seed :

the chosen seed value.

gretl_rand_set_multi_seed ()

void                gretl_rand_set_multi_seed           (const gretl_matrix *seed);

Set a specific (and hence reproducible) set of seed values for gretl's PRNG, in the form of a matrix containing an array of 4 32-bit values.

seed :

the chosen seed values.

gretl_rand_int ()

unsigned int        gretl_rand_int                      (void);

Returns :

a pseudo-random unsigned int on the interval [0, 2^32-1] using the Mersenne Twister.

gretl_rand_int_max ()

unsigned int        gretl_rand_int_max                  (unsigned int max);

max :

the maximum value (open)

Returns :

a pseudo-random unsigned int in the interval [0, max-1] using the Mersenne Twister.

gretl_rand_int_minmax ()

int                 gretl_rand_int_minmax               (int *a,
                                                         int n,
                                                         int min,
                                                         int max);

Fill array a of length n with pseudo-random drawings from the uniform distribution on min to max, using the Mersenne Twister.

a :

target array.

n :

length of array.

min :

lower closed bound of range.

max :

upper closed bound of range.

Returns :

0 on success, 1 on invalid input.

gretl_rand_01 ()

double              gretl_rand_01                       (void);

Returns :

the next random double, equally distributed over the range [0..1).

gretl_one_snormal ()

double              gretl_one_snormal                   (void);

Returns :

a single drawing from the standard normal distribution.

gretl_rand_uniform ()

void                gretl_rand_uniform                  (double *a,
                                                         int t1,
                                                         int t2);

Fill the selected range of array a with pseudo-random drawings from the uniform distribution on [0-1), using the Mersenne Twister.

a :

target array

t1 :

start of the fill range

t2 :

end of the fill range

gretl_rand_uniform_minmax ()

int                 gretl_rand_uniform_minmax           (double *a,
                                                         int t1,
                                                         int t2,
                                                         double min,
                                                         double max);

Fill the selected subset of array a with pseudo-random drawings from the uniform distribution on min to max, using the Mersenne Twister.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

min :

lower bound of range.

max :

upper bound of range.

Returns :

0 on success, 1 on invalid input.

gretl_rand_normal ()

void                gretl_rand_normal                   (double *a,
                                                         int t1,
                                                         int t2);

Fill the selected range of array a with pseudo-random drawings from the standard normal distribution, using the Mersenne Twister for uniform input and either the Ziggurat or the Box-Muller method for converting to the normal distribution.

a :

target array

t1 :

start of the fill range

t2 :

end of the fill range

gretl_rand_normal_full ()

int                 gretl_rand_normal_full              (double *a,
                                                         int t1,
                                                         int t2,
                                                         double mean,
                                                         double sd);

Fill the selected range of array a with pseudo-random drawings from the normal distribution with the given mean and standard deviation, using the Mersenne Twister for uniform input and either the Ziggurat or the Box-Muller method for converting to the normal distribution.

a :

target array

t1 :

start of the fill range

t2 :

end of the fill range

mean :

mean of the distribution

sd :

standard deviation

Returns :

0 on success, 1 on invalid input.

gretl_rand_chisq ()

int                 gretl_rand_chisq                    (double *a,
                                                         int t1,
                                                         int t2,
                                                         int v);

Fill the selected range of array a with pseudo-random drawings from the Chi-Squared distribution with v degrees of freedom, using the gamma r.v. generator.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

v :

degrees of freedom.

Returns :

0 on success, non-zero on error.

gretl_rand_student ()

int                 gretl_rand_student                  (double *a,
                                                         int t1,
                                                         int t2,
                                                         double v);

Fill the selected range of array a with pseudo-random drawings from the Student t distribution with v degrees of freedom, using the Mersenne Twister for uniform input and the ziggurat method for converting to the normal distribution.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

v :

degrees of freedom.

Returns :

0 on success, non-zero on error.

gretl_rand_F ()

int                 gretl_rand_F                        (double *a,
                                                         int t1,
                                                         int t2,
                                                         int v1,
                                                         int v2);

Fill the selected range of array a with pseudo-random drawings from the F distribution with v1 and v2 degrees of freedom, using the Mersenne Twister for uniform input and the Box-Muller method for converting to the normal distribution.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

v1 :

numerator degrees of freedom.

v2 :

denominator degrees of freedom.

Returns :

0 on success, non-zero on error.

gretl_rand_binomial ()

int                 gretl_rand_binomial                 (double *a,
                                                         int t1,
                                                         int t2,
                                                         int n,
                                                         double p);

Fill the selected range of array a with pseudo-random drawings from the binomial distribution with parameters n and p.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

n :

number of trials.

p :

success probability per trial.

Returns :

0 on success, non-zero on error.

gretl_rand_poisson ()

int                 gretl_rand_poisson                  (double *a,
                                                         int t1,
                                                         int t2,
                                                         const double *m,
                                                         int vec);

Fill the selected range of array a with pseudo-random drawings from the Poisson distribution with a mean determined by m, which can either be a pointer to a scalar, or an array of length greater than or equal to t2 + 1.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

m :

mean (see below).

vec :

should be 1 if m is an array, else 0.

Returns :

0 on success, non-zero on error.

gretl_rand_weibull ()

int                 gretl_rand_weibull                  (double *a,
                                                         int t1,
                                                         int t2,
                                                         double shape,
                                                         double scale);

Fill the selected range of array a with pseudo-random drawings from the Weibull distribution with shape k and scale lambda.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

shape :

shape parameter > 0.

scale :

scale parameter > 0.

Returns :

0 on success, non-zero if either parameter is out of bounds.

gretl_rand_gamma ()

int                 gretl_rand_gamma                    (double *a,
                                                         int t1,
                                                         int t2,
                                                         double shape,
                                                         double scale);

Fill the selected range of array a with pseudo-random drawings from the specified gamma distribution.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

shape :

shape parameter.

scale :

scale parameter.

Returns :

0 on success, non-zero on error.

gretl_rand_GED ()

int                 gretl_rand_GED                      (double *a,
                                                         int t1,
                                                         int t2,
                                                         double nu);

Fill the selected range of array a with pseudo-random drawings from the GED distribution with shape nu. We exploit the fact that if x ~ GED(n), then |x/k|^n is a Gamma rv.

a :

target array.

t1 :

start of the fill range.

t2 :

end of the fill range.

nu :

shape parameter > 0.

Returns :

0 on success, non-zero if nu is out of bounds.

gretl_rand_set_sfmt ()

void                gretl_rand_set_sfmt                 (int s);

If s is non-zero, set libgretl's generator for uniform variates to use SFMT, as opposed to GLib's implementation of the Mersenne Twister.

s :

1 or 0.

gretl_rand_get_sfmt ()

int                 gretl_rand_get_sfmt                 (void);

Returns :

non-zero if libgretl is using the SFMT RNG.

gretl_rand_set_box_muller ()

void                gretl_rand_set_box_muller           (int s);

If s is non-zero, set libgretl's generator for normal variates to use the Box-Muller method, as opposed to the default which is to use the Ziggurat method. If s is zero, reset to the Ziggurat.

s :

1 or 0.

gretl_rand_get_box_muller ()

int                 gretl_rand_get_box_muller           (void);

Returns :

non-zero if libgretl is using the Box-Muller method for generating normal random variates, zero if the default Ziggurat method is in use.

gretl_rand_get_seed ()

unsigned int        gretl_rand_get_seed                 (void);

Returns :

the value of the seed for gretl's PRNG.