MODULE random_seq_mod

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: random_seq_mod.html 11864 2017-08-02 19:40:28Z nancy@ucar.edu $

INTERFACES / NAMELIST / FILES / REFERENCES / ERRORS / PLANS / PRIVATE COMPONENTS / TERMS OF USE

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.

[top]

OTHER MODULES USED

types_mod
utilities_mod
[top]

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, shape, scale)
real(r8)                             :: random_gamma
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: shape
real(r8),              intent(in)    :: scale

Returns a random draw from a Gamma distribution with specified shape and scale. Both must be positive.

Note that there are three different parameterizations in common use:

  1. With shape parameter κ (kappa) and scale parameter θ (theta).
  2. With shape parameter α (alpha) and rate parameter β (beta).
    Alpha is the same as kappa, and beta is an inverse scale parameter so β = 1/θ.
  3. 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.
shape Shape parameter. Often written as either alpha or kappa.
scale 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, shape, scale)
real(r8)                             :: random_inverse_gamma
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: shape
real(r8),              intent(in)    :: scale

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.
shape Shape parameter. Often written as either alpha or kappa.
scale 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.

[top]

NAMELIST

This module has no namelist input.

[top]

FILES

[top]

REFERENCES

  1. Knuth, Vol 2.
  2. GNU Scientific Library Reference Manual
[top]

ERROR CODES and CONDITIONS

RoutineMessageComment
     

KNOWN BUGS

none at this time

[top]

FUTURE PLANS

none at this time

[top]

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, shape, scale)
real(r8)                             :: ran_gamma
type(random_seq_type), intent(inout) :: r
real(r8),              intent(in)    :: shape
real(r8),              intent(in)    :: scale

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.
shape Shape parameter.
scale Scale parameter. (This is the inverse of a rate parameter.)

[top]

Terms of Use

DART software - Copyright UCAR. This open source software is provided by UCAR, "as is", without charge, subject to all terms of use at http://www.image.ucar.edu/DAReS/DART/DART_download

Contact: DART core group
Revision: $Revision: 11864 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Manhattan/assimilation_code/modules/utilities/random_seq_mod.html $
Change Date: $Date: 2017-08-02 13:40:28 -0600 (Wed, 02 Aug 2017) $
Change history:  try "svn log" or "svn diff"