MODULE random_seq_mod¶

Overview¶

Provides access to any number of reproducible random sequences. Can sample from uniform, gaussian, two-dimensional gaussian, gamma, inverse gamma, and exponential distributions.

The current random sequence generator is a Fortran version of the GNU Library implementation of the Mersenne Twister algorithm. The original code is in the C language and the conversion to Fortran was done by the DART team.

There are test programs in the developer_tests/random_seq directory which show examples of calling these routines. Build and run these tests in the test subdirectory.

Other modules used¶

types_mod
utilities_mod

Public interfaces¶

use random_seq_mod, only :	random_seq_type
	init_random_seq
	random_uniform
	random_gaussian
	several_random_gaussians
	twod_gaussians
	random_gamma
	random_inverse_gamma
	random_exponential

A note about documentation style. Optional arguments are enclosed in brackets [like this].

type random_seq_type
   private

   integer     :: mti
   integer(i8) :: mt(624)
   real(r8)    :: lastg
   logical     :: gset

end type random_seq_type

This type is used to uniquely identify a sequence. Keeps the state history of the linear congruential number generator. In this implementation it is based on the Mersenne Twister from the GNU Scientific Library.

call init_random_seq(r, [, seed])

type(random_seq_type),           intent(inout) :: r
integer,               optional, intent(in)    :: seed

Initializes a random sequence for use. This must be called before any random numbers can be generated from this sequence. Any number of independent, reproducible random sequences can be generated by having multiple instances of a random_seq_type. A specified integer seed, optional, can produce a specific ‘random’ sequence.

`r`	A random sequence type to be initialized.
`seed`	A seed for a random sequence.

var = random_uniform(r)

real(r8)                             :: random_uniform
type(random_seq_type), intent(inout) :: r

Returns a random draw from a uniform distribution on interval [0,1].

`random_uniform`	A random draw from a Uniform[0,1] distribution.
`r`	An initialized random sequence type.

var = random_gaussian(r, mean, standard_deviation)

real(r8)                             :: random_gaussian
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: mean
real(r8),              intent(in)    :: standard_deviation

Returns a random draw from a Gaussian distribution with the specified mean and standard deviation.

See this Wikipedia page for more explanation about this function.

`random_gaussian`	A random draw from a gaussian distribution.
`r`	An initialized random sequence type.
`mean`	Mean of the gaussian.
`standard_deviation`	Standard deviation of the gaussian.

call several_random_gaussians(r, mean, standard_deviation, n, rnum)

type(random_seq_type),  intent(inout) :: r
real(r8),               intent(in)    :: mean
real(r8),               intent(in)    :: standard_deviation
integer,                intent(in)    :: n
real(r8), dimension(:), intent(out)   :: rnum

Returns n random samples from a gaussian distribution with the specified mean and standard deviation. Array rnum must be at least size n.

`r`	An initialized random sequence type.
`mean`	Mean of the Gaussian to be sampled.
`standard_deviation`	Standard deviation of the Gaussian.
`n`	Number of samples to return
`rnum`	The random samples of the Gaussian.

call twod_gaussians(r, mean, cov, rnum)

type(random_seq_type),    intent(inout) :: r
real(r8), dimension(2),   intent(in)    :: mean
real(r8), dimension(2,2), intent(in)    :: cov
real(r8), dimension(2),   intent(out)   :: rnum

Returns a random draw from a 2D gaussian distribution with the specified mean and covariance.

The algorithm used is from Knuth, exercise 13, section 3.4.1. See this Wikipedia page for more explanation about this function.

`r`	An initialized random sequence type.
`mean`	Mean of 2D gaussian distribution.
`cov`	Covariance of 2D gaussian.
`rnum`	Returned random draw from gaussian.

var = random_gamma(r, rshape, rscale)

real(r8)                             :: random_gamma
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: rshape
real(r8),              intent(in)    :: rscale

Returns a random draw from a Gamma distribution with specified rshape and rscale. Both must be positive.

Note that there are three different parameterizations in common use:

With shape parameter κ (kappa) and scale parameter θ (theta).
With shape parameter α (alpha) and rate parameter β (beta). Alpha is the same as kappa, and beta is an inverse scale parameter so β = 1/θ.
With shape parameter κ (kappa) and mean parameter μ (mu). μ = κ/β, so β = κ/μ.

This form uses the first parameterization, shape (κ) and scale (θ). The distribution mean is κθ and the variance is κ(θ²). This routine is based on the Gamma(a,b) generator from the GNU Scientific library. See this Wikipedia page for more explanation of the various parameterizations of this function.

`random_gamma`	A random draw from a gamma distribution.
`r`	An initialized random sequence type.
`rshape`	Shape parameter. Often written as either alpha or kappa.
`rscale`	Scale parameter. Often written as theta. If you have a rate parameter (often beta) pass in (1/rate) for scale.

var = random_inverse_gamma(r, rshape, rscale)

real(r8)                             :: random_inverse_gamma
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: rshape
real(r8),              intent(in)    :: rscale

Returns a random draw from an inverse Gamma distribution with the specified shape and scale. Both must be positive. If you have ‘rate’ instead of ‘scale’ pass in (1/rate) for scale.

See this Wikipedia page for more explanation about this function.

`random_inverse_gamma`	A random draw from an inverse gamma distribution.
`r`	An initialized random sequence type.
`rshape`	Shape parameter. Often written as either alpha or kappa.
`rscale`	Scale parameter. Often written as theta. If you have a rate parameter (often beta) pass in (1/rate) for scale.

var = random_exponential(r, rate)

real(r8)                             :: random_exponential
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: rate

Returns a random draw from an exponential distribution with the specified rate. If you have a scale parameter (which is the same as the mean, the standard deviation, and the survival parameter), specify (1/scale) for rate.

See this Wikipedia page for more explanation about this function.

`random_exponential`	A random draw from an exponential distribution.
`r`	An initialized random sequence type.
`rate`	Rate parameter. Often written as lambda. If you have a scale parameter pass in (1/scale) for rate.

Namelist¶

This module has no namelist input.

Files¶

NONE

References¶

Knuth, Vol 2.
GNU Scientific Library Reference Manual

Private components¶

	init_ran
	ran_unif
	ran_gauss
	ran_gamma

call init_ran(s, seed)

type(random_seq_type), intent(out) :: s
integer,               intent(in)  :: seed

Initializes a random sequence with an integer. Any sequence initialized with the same integer will produce the same sequence of pseudo-random numbers.

`s`	A random sequence to be initialized
`seed`	An integer seed to start the sequence.

var = ran_unif(s)

real(r8)                             :: ran_unif
type(random_seq_type), intent(inout) :: s

Generate the next uniform [0, 1] random number in the sequence.

`ran_unif`	Next uniformly distributed [0, 1] number in sequence.
`s`	A random sequence.

var = ran_gauss(s)

real(r8)                             :: ran_gauss
type(random_seq_type), intent(inout) :: s

Generates a random draw from a standard gaussian.

`ran_gauss`	A random draw from a standard gaussian.
`s`	A random sequence.

var = ran_gamma(r, rshape, rscale)

real(r8)                             :: ran_gamma
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: rshape
real(r8),              intent(in)    :: rscale

Generates a random draw from a Gamma distribution. See notes in the random_gamma() section about (alpha,beta) vs (kappa,theta) vs (kappa,mu) parameterizations. This is transcribed from C code in the GNU Scientific library and keeps the (shape,scale) interface.

`ran_gamma`	A random draw from a Gamma distribution.
`r`	A random sequence.
`rshape`	Shape parameter.
`rscale`	Scale parameter. (This is the inverse of a rate parameter.)