G05 Chapter Contents
G05 Chapter Introduction
NAG Library Manual

NAG Library Routine DocumentG05KGF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

1  Purpose

G05KGF initializes the selected base generator to generate a non-repeatable sequence of variates. The base generator can then be used by the group of pseudorandom number routines (see G05KHFG05KJF, G05NCF, G05NDF, G05PDFG05PJF, G05PXFG05PZF, G05RCF, G05RDF, G05RYF, G05RZF and G05SAFG05TLF) and the quasi-random scrambled sequence initialization routine, G05YNF.

2  Specification

 SUBROUTINE G05KGF ( GENID, SUBID, STATE, LSTATE, IFAIL)
 INTEGER GENID, SUBID, STATE(LSTATE), LSTATE, IFAIL

3  Description

G05KGF selects a base generator through the input value of the parameters GENID and SUBID, and then initializes it based on the values taken from the real-time clock, resulting in the same base generator yielding different sequences of random numbers each time the calling program is run. It should be noted that there is no guarantee of statistical properties between sequences, only within sequences.
A definition of some of the terms used in this description, along with details of the various base generators can be found in the G05 Chapter Introduction.

4  References

L'Ecuyer P and Simard R (2002) TestU01: a software library in ANSI C for empirical testing of random number generators Departement d'Informatique et de Recherche Operationnelle, Universite de Montreal http://www.iro.umontreal.ca/~lecuyer
Maclaren N M (1989) The generation of multiple independent sequences of pseudorandom numbers Appl. Statist. 38 351–359
Matsumoto M and Nishimura T (1998) Mersenne twister: a 623-dimensionally equidistributed uniform pseudorandom number generator ACM Transactions on Modelling and Computer Simulations
Wichmann B A and Hill I D (2006) Generating good pseudo-random numbers Computational Statistics and Data Analysis 51 1614–1622
Wikramaratna R S (1989) ACORN - a new method for generating sequences of uniformly distributed pseudo-random numbers Journal of Computational Physics 83 16–31

5  Parameters

1:     GENID – INTEGERInput
On entry: must contain the type of base generator to use.
${\mathbf{GENID}}=1$
NAG basic generator.
${\mathbf{GENID}}=2$
Wichmann Hill I generator.
${\mathbf{GENID}}=3$
Mersenne Twister.
${\mathbf{GENID}}=4$
Wichmann Hill II generator.
${\mathbf{GENID}}=5$
ACORN generator.
${\mathbf{GENID}}=6$
L'Ecuyer MRG32k3a generator.
See the G05 Chapter Introduction for details of each of the base generators.
Constraint: ${\mathbf{GENID}}=1$, $2$, $3$, $4$, $5$ or $6$.
2:     SUBID – INTEGERInput
On entry: if ${\mathbf{GENID}}=2$, SUBID indicates which of the $273$ sub-generators to use. In this case, the  sub-generator is used.
If ${\mathbf{GENID}}=5$, SUBID indicates the values of $k$ and $p$ to use, where $k$ is the order of the generator, and $p$ controls the size of the modulus, $M$, with $M={2}^{\left(p×30\right)}$. If ${\mathbf{SUBID}}<1$, the default values of $k=10$ and $p=2$ are used, otherwise values for $k$ and $p$ are calculated from the formula, ${\mathbf{SUBID}}=k+1000\left(p-1\right)$.
If ${\mathbf{GENID}}=6$ and  the range of the generator is set to $\left(0,1\right]$, otherwise the range is set to $\left(0,1\right)$; in this case the sequence is identical to the implementation of MRG32k3a in TestU01 (see L'Ecuyer and Simard (2002)) for identical seeds.
For all other values of GENID, SUBID is not referenced.
3:     STATE(LSTATE) – INTEGER arrayCommunication Array
On exit: contains information on the selected base generator and its current state.
4:     LSTATE – INTEGERInput/Output
On entry: the dimension of the STATE array, or a value $<1$. If the Mersenne Twister (${\mathbf{GENID}}=3$) is being used and the skip ahead routine G05KJF or G05KKF will be called subsequently, then you must ensure that ${\mathbf{LSTATE}}\ge 1260$.
On exit: if ${\mathbf{LSTATE}}<1$ on entry, then the required length of the STATE array for the chosen base generator, otherwise LSTATE is unchanged. When ${\mathbf{GENID}}=3$ (Mersenne Twister) a value of $1260$ is returned, allowing for the skip ahead routine to be subsequently called. In all other cases the minimum length, as documented in the constraints below, is returned.
Constraints:
• if ${\mathbf{GENID}}=1$, ${\mathbf{LSTATE}}\ge 17$;
• if ${\mathbf{GENID}}=2$, ${\mathbf{LSTATE}}\ge 21$;
• if ${\mathbf{GENID}}=3$, ${\mathbf{LSTATE}}\ge 633$;
• if ${\mathbf{GENID}}=4$, ${\mathbf{LSTATE}}\ge 29$;
• if ${\mathbf{GENID}}=5$, ${\mathbf{LSTATE}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(\left(k+1\right)×p+9,14\right)+3$, where $k$ and $p$ are defined by SUBID;
• if ${\mathbf{GENID}}=6$, ${\mathbf{LSTATE}}\ge 58$;
• otherwise ${\mathbf{LSTATE}}<1$.
5:     IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.
On exit: ${\mathbf{IFAIL}}={\mathbf{0}}$ or $-1$ unless the routine detects an error or a warning has been flagged (see Section 6).
For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{​ or ​}1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{​ or ​}\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

6  Error Indicators and Warnings

If on entry ${\mathbf{IFAIL}}={\mathbf{0}}$ or $-{\mathbf{1}}$, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
${\mathbf{IFAIL}}=-1$
Minimum length for STATE array returned in parameter LSTATE but STATE array not initialized.
${\mathbf{IFAIL}}=1$
On entry, ${\mathbf{GENID}}\ne 1$, $2$, $3$, $4$, $5$ or $6$.
${\mathbf{IFAIL}}=2$
Invalid SUBID.
${\mathbf{IFAIL}}=4$
On entry, ${\mathbf{LSTATE}}>0$ and LSTATE is too small for specified base generator.

Not applicable.

None.

9  Example

This example prints the first five pseudorandom real numbers from a uniform distribution between $0$ and $1$, generated by G05SAF after initialization by G05KGF.

9.1  Program Text

Program Text (g05kgfe.f90)

9.2  Program Data

Program Data (g05kgfe.d)

9.3  Program Results

Program Results (g05kgfe.r)