PRNG

PRNG — generate pseudo-random values

Functions

Object Hierarchy


Includes

#include <libgretl.h>

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().

Functions

gretl_rand_init ()

void
gretl_rand_init (void);

Initialize gretl's PRNG, using the system time as seed. Default version, as opposed to DCMT.


gretl_rand_free ()

void
gretl_rand_free (void);

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


gretl_dcmt_init ()

void
gretl_dcmt_init (int n,
                 int self,
                 unsigned int seed);

Initialize DCMT, if needed.


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).

Parameters

seed

the chosen seed value.

 

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);

Parameters

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 , max ], using the Mersenne Twister.

Parameters

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.

Parameters

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.

Parameters

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_uniform_int_minmax ()

int
gretl_rand_uniform_int_minmax (double *a,
                               int t1,
                               int t2,
                               int min,
                               int max,
                               gretlopt opt);

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

Parameters

a

target array.

 

t1

start of the fill range.

 

t2

end of the fill range.

 

min

lower closed bound of range.

 

max

upper closed bound of range.

 

opt

include OPT_O for sampling without replacement.

 

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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_gamma_one ()

double
gretl_rand_gamma_one (double shape,
                      double scale);

Returns


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.

Parameters

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_beta ()

int
gretl_rand_beta (double *x,
                 int t1,
                 int t2,
                 double s1,
                 double s2);

Fill the selected range of array a with pseudo-random drawings from the beta distribution with shape parameters s1 and s2 . The code here is adapted from http://www.netlib.org/random/random.f90 which implements the method of R.C.H. Cheng, "Generating beta variates with nonintegral shape parameters", Communications of the ACM, 21(4), April 1978.

Parameters

x

target array.

 

t1

start of the fill range.

 

t2

end of the fill range.

 

s1

shape parameter > 0.

 

s2

shape parameter > 0.

 

Returns

0 on success, non-zero if s1 or s2 are out of bounds.


gretl_rand_beta_binomial ()

int
gretl_rand_beta_binomial (double *x,
                          int t1,
                          int t2,
                          int n,
                          double s1,
                          double s2);

Fill the selected range of array x with pseudo-random drawings from the binomial distribution with n trials and success probability distributed according to the beta distribution with shape parameters s1 and s2 .

Parameters

x

target array.

 

t1

start of the fill range.

 

t2

end of the fill range.

 

n

number of trials.

 

s1

beta shape parameter > 0.

 

s2

beta shape parameter > 0.

 

Returns

0 on success, non-zero if n , s1 or s2 are out of bounds.


halton_matrix ()

gretl_matrix *
halton_matrix (int m,
               int r,
               int offset,
               int *err);

Parameters

m

number of rows (sequences); the maximum is 40.

 

r

number of columns (elements in each sequence).

 

offset

the number of initial values to discard.

 

err

location to receive error code.

 

Returns

an m x r matrix containing m Halton sequences. The sequences are contructed using the first m primes, and the first offset elements of each sequence are discarded.


inverse_wishart_matrix ()

gretl_matrix *
inverse_wishart_matrix (const gretl_matrix *S,
                        int v,
                        int *err);

Computes a draw from the Inverse Wishart distribution with v degrees of freedom, using the method of Odell and Feiveson, "A numerical procedure to generate a sample covariance matrix", JASA 61, pp. 199­203, 1966.

Parameters

S

p x p positive definite scale matrix.

 

v

degrees of freedom.

 

err

location to receive error code.

 

Returns

a p x p Inverse Wishart matrix, or NULL on error.


inverse_wishart_sequence ()

gretl_matrix *
inverse_wishart_sequence (const gretl_matrix *S,
                          int v,
                          int replics,
                          int *err);

Returns


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.

Parameters

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.


gretl_rand_set_dcmt ()

int
gretl_rand_set_dcmt (int s);

Returns


gretl_rand_get_dcmt ()

int
gretl_rand_get_dcmt (void);

Returns

Types and Values