Next Previous Contents

## 11.Random Number Module

The `rand` module provides a number of random number functions. It may be loaded using `require("rand")`.

## 11.1rand_exp

Synopsis

Generate exponentially distributed random numbers

Usage

`X = rand_exp([Rand_Type g,] beta [,num])`

Description

This function generates random numbers that are distributed according to an exponential distribution with parameter beta > 0. The distribution's probability density is given by

``` P(x,beta) = (1/beta) exp(-x/beta) ```

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

Notes

The exponential generator is commonly used to simulate waiting times between events.

`rand_new, rand_uniform`

## 11.2rand_int

Synopsis

Generate random integers

Usage

`X = rand_int ([Rand_Type g,] imin, imax [,num])`

Description

This function may be used to generate a random integer `X` such that `imin <= X <= imax`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform, rand, rand_new`

## 11.3rand_tdist

Synopsis

Generate random numbers from the Student t distribution

Usage

`X = rand_tdist ([Rand_Type g,] nu [,num])`

Description

This function generates random numbers that are distributed according to the Student-t distribution with nu>0.0 degrees of freedom.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform, rand_new, rand_chisq, rand_fdist`

## 11.4rand_fdist

Synopsis

Generate random numbers from the F distribution

Usage

`X = rand_fdist ([Rand_Type g,], nu1, nu2 [,num])`

Description

This function generates random numbers that are distributed according to the F-distribution, which is the ratio of two chi-squared distributed variates whose degrees of freedom are given by `nu1` (numerator) and `nu2` (denominator).

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform, rand_chisq, rand_tdist, rand_gauss, rand_new`

## 11.5rand_chisq

Synopsis

Generate Chi-Square distributed random numbers

Usage

`X = rand_fdist ([Rand_Type g,] nu, [,num])`

Description

This function generates random numbers that are distributed according to the Chi-squared distribution with `nu > 0` degrees of freedom.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform, rand_fdist, rand_tdist, rand_gauss, rand_new`

## 11.6rand_flat

Synopsis

Generate uniformly distributed random numbers

Usage

`X = rand_fdist ([Rand_Type g,] xmin, xmax [,num])`

Description

This function generates random double-precision floating point numbers that are uniformly distributed in the range `xmin<=X<xmax`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform, rand_uniform_pos, rand_int, rand, rand_new`

## 11.7rand_gamma

Synopsis

Generate Gamma distributed random numbers

Usage

`X = rand_gamma ([Rand_Type g,], k, theta [,num])`

Description

This function returns random deviates that are Gamma-distributed according to the probability density

``` P(x; k,theta) = x^(k-1)*exp(-x/theta)/(theta^k * Gamma(k)) ```
where `k,theta>0.0`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_beta, rand_uniform, rand_binomial, rand_new`

## 11.8rand_binomial

Synopsis

Generate random numbers from the binomial distribution

Usage

`X = rand_binomial ([Rand_Type g,], p, n, [,num])`

Description

This function generates binomial distributed random numbers according to the probability density

``` P(x;p,n) = n!/(k!*(n-k)!) * p^k * (1-p)^(n-k) ```
where `n` is a non-negative integer and `0<=p<=1`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_gamma, rand_poisson, rand_uniform, rand_new`

## 11.9rand_poisson

Synopsis

Generate Poisson distributed random numbers

Usage

`k = rand_poisson ([Rand_Type g,] mu [,num])`

Description

This function generates random unsigned integers that are poisson-distributed according to the probability distribution

``` P(k;mu) = mu^k/k! * exp(-mu) ```
where `mu>0.0`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_gauss, rand_uniform, rand_binomial, rand_new`

## 11.10rand_geometric

Synopsis

Generate random numbers from the geometric distribution

Usage

`k = rand_geometric ([Rand_Type g,] p [,num])`

Description

This function generates random numbers that are distributed according to a geometric distribution with a probability density

``` P(k; p) = p*(1-p)^(k-1) ```
where `0<=p<=1`

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_poisson, rand_exp, rand_gauss, rand_uniform, rand_new`

## 11.11rand_cauchy

Synopsis

Generate random numbers from the Cauchy distribution

Usage

`X = rand_cauchy ([Rand_Type g,] gamma [,num])`

Description

This function generates random numbers that are distributed according to a cauchy-distribution with a probability density

``` P(x; gamma) = 1/(PI*gamma)/(1+(x/gamma)^2) ```
where `gamma>=0.0`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_gauss, rand_poisson, rand_exp, rand_new`

## 11.12rand_beta

Synopsis

Generate random numbers from the beta distribution

Usage

`X = rand_fdist ([Rand_Type g,] a, b [,num])`

Description

This function generates random numbers that are distributed according to a Beta-distribution with a probability density

``` P(x; a,b) = x^(a-1)*(1-x)^(b-1)/B(a,b) ```
where `a, b > 0`.

`rand_gamma, rand_binomial, rand_chisq`

## 11.13rand_gauss

Synopsis

Generate gaussian-distributed random numbers

Usage

`X = rand_gauss ([Rand_Type g,] sigma [,num])`

Description

This function generates gaussian random numbers with the specified sigma and mean of 0 according to the probability density

``` P(x; sigma) = 1/sqrt(2*PI*sigma^2) * exp(-0.5*x^2/sigma^2) ```

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

Notes

This implementation utilizes the Box-Muller algorithm.

`rand_uniform, rand_poisson, rand_chisq, rand_gauss, rand_new`

## 11.14rand

Synopsis

Generate random integers numbers

Usage

`X = rand ([Rand_Type g,] [,num])`

Description

This function generates unsigned 32 bit randomly distributed integers on the closed interval 0<=X<=0xFFFFFFFFUL.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_new, rand_int, rand_uniform, rand_flat`

## 11.15rand_uniform_pos

Synopsis

Generate uniform positive random numbers

Usage

`X = rand_uniform_pos ([Rand_Type] [num])`

Description

This function generates uniformly distributed random numbers in open interval `0<X<1`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform, rand_new`

## 11.16rand_uniform

Synopsis

Generate uniform random numbers

Usage

`X = rand_uniform ([Rand_Type g] [num])`

Description

This function generates uniformly distributed double precision numbers on the semi-closed interval `0<=r<1`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

`rand_uniform_pos, rand_int, rand_flat, rand_new`

## 11.17srand

Synopsis

Seed the random number generator

Usage

`srand ([Rand_Type g,] Array_Type seeds)`

Description

This function may be used to seed an instance of a rand number generator using the values of an array of an unsigned long integers. If a generator (created by `rand_new`) is specified as the first argument, then is will be seeded; otherwise, the seeds will get applied to the default generator.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information. The `num` parameter indicates that `num` random values are to be generated and returned as an array.

Example

``` gen = rand_new (); srand (gen, [_time(), _pid(), 0xFF80743]); ```

`rand_new, rand, rand_uniform`

## 11.18rand_new

Synopsis

Instantiate a new random number generator

Usage

`Rand_Type rand_new ([array-of-seeds])`

Description

This function creates a new instance of the basic random number generator. An optional array of 32 bit unsigned integers may be used to seed the generator. By default, the generator is seeding using the current time and process id. The `srand` function may also be used to seed the generator. The generator created by the `rand_new` function may be passed as the first argument to most of the other functions in the module to indicate that this instance should be used as the basic generator.

Example

The following example shows how to create an array of 512 uniform random numbers derived from the default instance of the basic generator:

``` x = rand_uniform (512); ```
A specific instance of the generator may be created using the `rand_new` function and used by `rand_uniform` as follows:
``` g = rand_new ([0x1234, 0x5678912, 0xEFAB1234]); x = rand_uniform (g, 512); ```

Notes

The generator is a hybrid one that sums the results of 3 separate generators: George Marsaglia's MZRAN13 generator, a multiply with carry generator (also by Marsaglia), and a product generator. The combined generator has a 192 bit state and a period exceeding 10^46.

The resulting random sequences were tested using version 2.24.4 of the dieharder random number testing program. The tests showed that this generator performed better than the famous Marsenne Twister (`mt19937`) both in terms of randomness and speed. More information about the test results may be found at http://www.jedsoft.org/slang/modules/rand.html.

The `mt19937` generator is separately available via the GSL module.

`srand, rand_int, rand_uniform`

## 11.19rand_sample

Synopsis

Randomly sample from one or more arrays

Usage

`(b1 [,b2,...]) = rand_sample ([Rand_Type g,] a1 [,a2,...], num);`

Description

This function may be used to randomly sample `num` elements from one or more arrays (`a1,...`). The arrays must be consistent in the sense that they must have the same leading dimension, which is the one to be sampled.

The optional first argument may be used to specify a different instance of a random number generator. Otherwise, the default generator will be used.

Example

Suppose A is a 1-d array with 20 elements, and B is a 2d array with dimensions [20,30]. Then

``` (A1, B1) = rand_sample (A, B, 5); ```
will produce a 1d array A1 with 5 elements and a 2d array B1 with dimensions [5,30].

Notes

The indices used to sample the arrays are created using the first `num` elements of a random permutation of the integers `[0:dim0-1]` where `dim0` is the size of the leading dimension. The same set of indices are used for all the arrays. Hence any correspondence between `a0[i,..]` and `a1[i,...` will be preserved in the samples.

`rand_permutation, rand_new`

## 11.20rand_permutation

Synopsis

Generate a random permutation of integers

Usage

`p = rand_permutation ([Rand_Type g,] Int_Type n)`

Description

This function may be used to generate a random permutation of the sequence of integers `0,1,..,n-1`.

The optional parameter `g` may be used to specify the underlying random number generator. See the documentation for the `rand_new` function for more information.

`rand_sample`