g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rand_init_repeatable (g05kfc)

## 1  Purpose

nag_rand_init_repeatable (g05kfc) initializes the selected base generator, as used by the group of pseudorandom number functions (see g05khcg05kjc, g05ncc, g05ndc, g05pdcg05pjc, g05pxcg05pzc, g05rcc, g05rdc, g05ryc, g05rzc and g05sacg05tlc), so as to generate a repeatable sequence of variates and the quasi-random scrambled sequence initialization function, nag_quasi_init_scrambled (g05ync).

## 2  Specification

 #include #include
 void nag_rand_init_repeatable (Nag_BaseRNG genid, Integer subid, const Integer seed[], Integer lseed, Integer state[], Integer *lstate, NagError *fail)

## 3  Description

nag_rand_init_repeatable (g05kfc) 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 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  Arguments

1:     genidNag_BaseRNGInput
On entry: must contain the type of base generator to use.
${\mathbf{genid}}=\mathrm{Nag_Basic}$
NAG basic generator.
${\mathbf{genid}}=\mathrm{Nag_WichmannHill_I}$
Wichmann Hill I generator.
${\mathbf{genid}}=\mathrm{Nag_MersenneTwister}$
Mersenne Twister.
${\mathbf{genid}}=\mathrm{Nag_WichmannHill_II}$
Wichmann Hill II generator.
${\mathbf{genid}}=\mathrm{Nag_ACORN}$
ACORN generator.
${\mathbf{genid}}=\mathrm{Nag_MRG32k3a}$
L'Ecuyer MRG32k3a generator.
See the g05 Chapter Introduction for details of each of the base generators.
Constraint: ${\mathbf{genid}}=\mathrm{Nag_Basic}$, $\mathrm{Nag_WichmannHill_I}$, $\mathrm{Nag_MersenneTwister}$, $\mathrm{Nag_WichmannHill_II}$, $\mathrm{Nag_ACORN}$ or $\mathrm{Nag_MRG32k3a}$.
2:     subidIntegerInput
On entry: if ${\mathbf{genid}}=\mathrm{Nag_WichmannHill_I}$, subid indicates which of the $273$ sub-generators to use. In this case, the  sub-generator is used.
If ${\mathbf{genid}}=\mathrm{Nag_ACORN}$, 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}}=\mathrm{Nag_MRG32k3a}$ 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:     seed[lseed]const IntegerInput
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 ${\mathbf{genid}}=\mathrm{Nag_Basic}$, one seed is required.
If ${\mathbf{genid}}=\mathrm{Nag_WichmannHill_I}$, four seeds are required.
If ${\mathbf{genid}}=\mathrm{Nag_MersenneTwister}$, $624$ seeds are required.
If ${\mathbf{genid}}=\mathrm{Nag_WichmannHill_II}$, four seeds are required.
If ${\mathbf{genid}}=\mathrm{Nag_ACORN}$, $\left(k+1\right)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 ${\mathbf{seed}}\left[0\right]$.
If ${\mathbf{genid}}=\mathrm{Nag_MRG32k3a}$, six seeds are required.
If insufficient seeds are provided then the first ${\mathbf{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 ${\mathbf{seed}}\left[{\mathbf{lseed}}-1\right]$.
Constraint: ${\mathbf{seed}}\left[\mathit{i}-1\right]\ge 1$, for $\mathit{i}=1,2,\dots ,{\mathbf{lseed}}$.
4:     lseedIntegerInput
On entry: the size of the seed array.
Constraint: ${\mathbf{lseed}}\ge 1$.
5:     state[lstate]IntegerCommunication Array
On exit: contains information on the selected base generator and its current state.
6:     lstateInteger *Input/Output
On entry: the dimension of the state array, or a value $<1$. If the Mersenne Twister (${\mathbf{genid}}=\mathrm{Nag_MersenneTwister}$) is being used and the skip ahead function nag_rand_skip_ahead (g05kjc) or nag_rand_skip_ahead_power2 (g05kkc) 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}}=\mathrm{Nag_MersenneTwister}$ (Mersenne Twister) a value of $1260$ is returned, allowing for the skip ahead function to be subsequently called. In all other cases the minimum length, as documented in the constraints below, is returned.
Constraints:
• if ${\mathbf{genid}}=\mathrm{Nag_Basic}$, ${\mathbf{lstate}}\ge 17$;
• if ${\mathbf{genid}}=\mathrm{Nag_WichmannHill_I}$, ${\mathbf{lstate}}\ge 21$;
• if ${\mathbf{genid}}=\mathrm{Nag_MersenneTwister}$, ${\mathbf{lstate}}\ge 633$;
• if ${\mathbf{genid}}=\mathrm{Nag_WichmannHill_II}$, ${\mathbf{lstate}}\ge 29$;
• if ${\mathbf{genid}}=\mathrm{Nag_ACORN}$, ${\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}}=\mathrm{Nag_MRG32k3a}$, ${\mathbf{lstate}}\ge 61$;
• otherwise ${\mathbf{lstate}}<1$.
7:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{lseed}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{lseed}}\ge 1$.
On entry, ${\mathbf{lstate}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{lstate}}\le 0$ or ${\mathbf{lstate}}\ge 〈\mathit{\text{value}}〉$.
NE_INT_ARRAY
On entry, invalid seed.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

Not applicable.

None.

## 9  Example

This example prints the first five pseudorandom real numbers from a uniform distribution between $0$ and $1$, generated by nag_rand_basic (g05sac) after initialization by nag_rand_init_repeatable (g05kfc).

### 9.1  Program Text

Program Text (g05kfce.c)

None.

### 9.3  Program Results

Program Results (g05kfce.r)