NAG Library Function Document

nag_rand_init_repeatable (g05kfc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:    $\mathbf{genid}$ – Nag_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:    $\mathbf{subid}$ – IntegerInput

On entry: if $\mathbf{genid}=\mathrm{Nag\_WichmannHill\_I}$, subid indicates which of the $273$ sub-generators to use. In this case, the $\left(\left(\left|\mathbf{subid}\right|+272\right) mod 273\right)+1$ 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\times 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 $\mathbf{subid}\mathrm{ mod }2=0$ 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:    $\mathbf{seed}\left[\mathbf{lseed}\right]$ – 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:    $\mathbf{lseed}$ – IntegerInput

On entry: the size of the seed array.

Constraint: $\mathbf{lseed}\ge 1$.

5:    $\mathbf{state}\left[\mathbf{lstate}\right]$ – IntegerCommunication Array

On exit: contains information on the selected base generator and its current state. If $\mathbf{lstate}<1$ then state may be NULL.

6:    $\mathbf{lstate}$ – Integer *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 \max \left(\left(k+1\right)\times 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:    $\mathbf{fail}$ – NagError *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.
See Section 3.2.1.2 in the Essential Introduction for further information.

NE_BAD_PARAM

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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (g05kfce.c)

10.2  Program Data

10.3  Program Results

Program Results (g05kfce.r)