GSL-RNG¶

This module introduce the class <gsl-rng> that provides a uniform interface to a large collection of random number generators.

To create a random number generator with the BSD $gsl-rng-rand generator and a seed:

let rng = make(<gsl-rng>, type: $gsl-rng-rand, seed: 1234);
format-out("generator type: %s\n", rng.gsl-rng-name);
format-out("seed = %d\n", rng.gsl-rng-seed);
format-out("first value = %d\n", rng.gsl-rng-get);

Random number environment variables¶

gsl-rng-env-setup Function¶

This function reads the environment variables GSL_RNG_TYPE and GSL_RNG_SEED and uses their values to set the corresponding library variables gsl_rng_default and gsl_rng_default_seed.

If you don’t specify a generator for GSL_RNG_TYPE then $gsl-rng-mt19937 is used as the default. The initial value of gsl-rng-default-seed is zero.

Signature:

gsl-rng-env-setup () => ()

Example:

Here we create a default random number generator with default seed:

gsl-rng-env-setup();

let rng = make(<gsl-rng>);

format-out("generator type: %s\n", rng.gsl-rng-name);
format-out("seed = %d\n", rng.gsl-rng-seed);
format-out("first value = %d\n", rng.gsl-rng-get);

Example:

Running the program without any environment variables,

$ test-rng.exe
generator type: mt19937
seed = 0
first value = 4293858116

Example:

We can pass the environment variables to choose type of algorithm and seed:

$ GSL_RNG_TYPE="taus" GSL_RNG_SEED=123 test-rng.exe
GSL_RNG_TYPE=taus
GSL_RNG_SEED=123
generator type: taus
seed = 123
first value = 2720986350

Random generator base class¶

<gsl-rng> Class¶

The class for random number generators.

Superclasses:

<object>

Init-Keywords:

type – Type of random number generator. An instance of <integer>. If no type is provided, it defaults to the environment variable GLS_RNG_TYPE.
seed –
An instance of <integer> that will be used as the seed for the random number generator. If no seed is provided it defaults to the GLS_RNG_SEED environment variable or 0, if the variable is absent.

example:
```
let r1 = make(<gsl-rng>, type: $gsl-rng-cmrg, seed: 123456);
let r2 = make(<gsl-rng>, seed: 123456);
let r3 = make(<gsl-rng>);
```
operations:

Sampling¶

gsl-rng-get Function¶

Returns a random number between the minimum and maximum value of the random number generator.

Signature:

gsl-rng-get (rng) => (number)

Parameters:

rng – An instance of <gsl-rng>.

Values number:

A random number between the minimum and maximum value of the random number generator as an instance of <integer>.

Example:

let r = make(<gsl-rng>);
let s = r.gsl-rng-get;

gsl-rng-uniform Function¶

Returns a random floating point number uniformly distributed in the range [0,1).

Signature:

gsl-rng-uniform (rng) => (number)

Parameters:

rng – An instance of <gsl-rng>.

Values number:

An instance of <float>. The range includes 0.0 but excludes 1.0.

Example:

let r = make(<gsl-rng>);
let s = r.gsl-rng-uniform;

gsl-rng-uniform-positive Function¶

Returns a positive random number uniformly distributed in the range (0,1), excluding both 0.0 and 1.0. The number is obtained by sampling the generator with the algorithm of gsl-rng-uniform until a non-zero value is obtained.

Signature:

gsl-rng-uniform-positive (rng) => (number)

Parameters:

rng – An instance of <gsl-rng>.

Values number:

An instance of <float>, between 0.0 and 1.0 excluding both endpoints.

Example:

let r = make(<gsl-rng>);
let s = r.gsl-rng-uniform-positive;

gsl-rng-uniform-integer Function¶

Returns a random number between 0 and n-1 of the random number generator.

Signature:

gsl-rng-uniform-integer (rng, n) => (number)

Parameters:

rng – An instance of <gsl-rng>.
n – An instance of <integer>. The parameter must be less than or equal to the range or the generator rng. If n is larger than the range of the generator an error will be signaled.

Values number:

A random number between 0 and n-1 of the random number generator as an instance of <integer>.

Example:

let r = make(<gsl-rng>);
let s = gsl-rng-uniform-integer(r, 10);

Auxiliary functions¶

gsl-rng-name Function¶

Returns the name of the random number generator.

Signature:

gsl-rng-name (rng) => (name)

Parameters:

rng – An instance of <gsl-rng>.

Values name:

The name of the random number generator as an instance of <string>.

Example:

let r = make(<gsl-rng>, type: $gsl-rng-rand);
format-out("%s", r.gsl-rng-name);
// rand

gsl-rng-seed(<gsl-rng>) Method¶

Returns the seed of the random number generator

Signature:

gsl-rng-seed (rng) => (seed)

Parameters:

rng – An instance of <gsl-rng>

Values seed:

An instance of <integer>

Example:

let r = make(<gsl-rng>, seed: 1234);
format-out("Seed: %d\n", r.gsl-rng-seed);
// Seed: 1234

gsl-rng-min Function¶

Returns the smallest value returned by the random number generator.

Signature:

gsl-rng-min (rng) => (min)

Parameters:

rng – An instance of <gsl-rng>.

Values min:

The minimum value returned by the random number generator as an instance of <integer>.

gsl-rng-max Function¶

Returns the maximum value returned by the random number generator.

Signature:

gsl-rng-max (rng) => (max)

Parameters:

rng – An instance of <gsl-rng>.

Values max:

The maximum value returned by the random number generator as an instance of <integer>.

Random number generator algorithms¶

Below are all the algorithms of random number generators available, whose constants can be passed in the class <gsl-rng> construction with the type: keyword.