MODULE random_seq_mod

DART project logo

Jump to DART Documentation Main Index
version information for this file:
$Id: random_seq_mod.html 6382 2013-08-07 20:45:16Z nancy $

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

Overview

Provides access to any number of reproducible random sequences and allows uniform, gaussian, and two-dimensional gaussian distributions to be sampled.

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.

[top]

OTHER MODULES USED

types_mod
utilities_mod
[top]

PUBLIC INTERFACES

use random_seq_mod, only : random_seq_type
 init_random_seq
 random_gaussian
 several_random_gaussians
 random_uniform
 twod_gaussians

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.
seed    A seed for a random sequence.


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 mean and standard deviation.

random_gaussian A random draw from a gaussian distribution.
r The reproducible random sequence.
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 with mean and standard deviation. Make sure that there is enough room in rnum for all the returned values.

r A reproducible random sequence.
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.


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 A random sequence.


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 with mean and covariance. The algorithm used is from Knuth, exercise 13, section 3.4.1.

r A random sequence.
mean    Mean of 2D gaussian distribution.
cov Covariance of 2D gaussian.
rnum Returned random draw from gaussian.

[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

call init_ran(s,temp)
type(random_seq_type), intent(out) :: s
integer,               intent(in)  :: temp

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

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

[top]

Terms of Use

DART software - Copyright 2004 - 2013 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: 6382 $
Source: $URL: https://svn-dares-dart.cgd.ucar.edu/DART/releases/Lanai/random_seq/random_seq_mod.html $
Change Date: $Date: 2013-08-07 14:45:16 -0600 (Wed, 07 Aug 2013) $
Change history:  try "svn log" or "svn diff"