NAG FL Interface
g05kff (init_​repeat)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

g05kff initializes the selected base generator, as 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

Fortran Interface
Subroutine g05kff ( genid, subid, seed, lseed, state, lstate, ifail)
Integer, Intent (In) :: genid, subid, seed(lseed), lseed
Integer, Intent (Inout) :: state(lstate), lstate, ifail
C Header Interface
#include <nag.h>
void  g05kff_ (const Integer *genid, const Integer *subid, const Integer seed[], const Integer *lseed, Integer state[], Integer *lstate, Integer *ifail)
The routine may be called by the names g05kff or nagf_rand_init_repeat.

3 Description

g05kff selects a base generator through the input value of the arguments genid and subid, and then initializes it based on the values given in the array seed.
A given base generator will yield different sequences of random numbers if initialized with different values of seed. Alternatively, the same sequence of random numbers will be generated if the same value of seed is used. 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 https://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 Arguments

1: genid Integer Input
On entry: must contain the type of base generator to use.
genid=1
NAG basic generator.
genid=2
Wichmann Hill I generator.
genid=3
Mersenne Twister.
genid=4
Wichmann Hill II generator.
genid=5
ACORN generator.
genid=6
L'Ecuyer MRG32k3a generator.
See the G05 Chapter Introduction for details of each of the base generators.
Constraint: genid=1, 2, 3, 4, 5 or 6.
2: subid Integer Input
On entry: if genid=2, subid indicates which of the 273 sub-generators to use. In this case, the ((|subid|+272) mod 273) + 1 sub-generator is used.
If 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 (p×30) . If subid<1, the default values of k=10 and p=2 are used, otherwise values for k and p are calculated from the formula, subid=k+1000(p-1).
If genid=6 and subid mod 2=0 the range of the generator is set to (0,1], otherwise the range is set to (0,1); 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: seed(lseed) Integer array Input
On entry: the initial (seed) values for the selected base generator. The number of initial values required varies with each of the base generators.
If genid=1, one seed is required.
If genid=2, four seeds are required.
If genid=3, 624 seeds are required.
If genid=4, four seeds are required.
If genid=5, (k+1)p seeds are required, where k and p are defined by subid. For the ACORN generator it is recommended that an odd value is used for seed(1).
If genid=6, six seeds are required.
If insufficient seeds are provided then the first lseed-1 values supplied in seed are used and the remaining values are randomly generated using the NAG basic generator. In such cases the NAG basic generator is initialized using the value supplied in seed(lseed).
Constraint: seed(i)1, for i=1,2,,lseed.
4: lseed Integer Input
On entry: the size of the seed array.
Constraint: lseed1.
5: state(lstate) Integer array Communication Array
On exit: contains information on the selected base generator and its current state.
6: lstate Integer Input/Output
On entry: the dimension of the state array, or a value <1. If the Mersenne Twister (genid=3) is being used and the skip ahead routine g05kjf or g05kkf will be called subsequently, then you must ensure that lstate1260.
On exit: if lstate<1 on entry, then the required length of the state array for the chosen base generator, otherwise lstate is unchanged. When 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 genid=1, lstate17;
  • if genid=2, lstate21;
  • if genid=3, lstate633;
  • if genid=4, lstate29;
  • if genid=5, lstatemax((k+1)×p+9,14)+3, where k and p are defined by subid;
  • if genid=6, lstate61;
  • otherwise lstate<1.
7: ifail Integer Input/Output
On entry: ifail must be set to 0, -1 or 1 to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of 0 causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of -1 means that an error message is printed while a value of 1 means that it is not.
If halting is not appropriate, the value -1 or 1 is recommended. If message printing is undesirable, then the value 1 is recommended. Otherwise, the value 0 is recommended. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or -1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
On entry, genid=value.
Constraint: genid=1, 2, 3, 4, 5 or 6.
ifail=3
On entry, invalid seed.
ifail=4
On entry, lseed=value.
Constraint: lseed1.
ifail=6
On entry, lstate=value.
Constraint: lstate0 or lstatevalue.
ifail=-1
Required length of state array returned in lstate but state array not initialized.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

g05kff is not threaded in any implementation.

9 Further Comments

None.

10 Example

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

10.1 Program Text

Program Text (g05kffe.f90)

10.2 Program Data

Program Data (g05kffe.d)

10.3 Program Results

Program Results (g05kffe.r)