NAG Toolbox: nag_rand_init_repeat (g05kf)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{genid}$ – int64int32nag_int scalar

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:     $\mathrm{subid}$ – int64int32nag_int scalar

If $\mathbf{genid}=2$, 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}=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\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}=6$ 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:     $\mathrm{seed}\left(\mathbf{lseed}\right)$ – int64int32nag_int array

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}=1$, one seed is required.

If $\mathbf{genid}=2$, four seeds are required.

If $\mathbf{genid}=3$, $624$ seeds are required.

If $\mathbf{genid}=4$, four seeds are required.

If $\mathbf{genid}=5$, $\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(1\right)$.

If $\mathbf{genid}=6$, 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}\right)$.

Constraint: $\mathbf{seed}\left(\mathit{i}\right)\ge 1$, for $\mathit{i}=1,2,\dots ,\mathbf{lseed}$.

Optional Input Parameters

1:     $\mathrm{lseed}$ – int64int32nag_int scalar

Default: the dimension of the array seed.

The size of the seed array.

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

Output Parameters

1:     $\mathrm{state}\left(\mathit{lstate}\right)$ – int64int32nag_int array

Contains information on the selected base generator and its current state.

2:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

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 argument, 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.

Error Indicators and Warnings

   $\mathbf{ifail}=1$

Constraint: $\mathbf{genid}=1$, $2$, $3$, $4$, $5$ or $6$.

   $\mathbf{ifail}=3$

On entry, invalid seed.

   $\mathbf{ifail}=4$

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

   $\mathbf{ifail}=6$

Constraint: $\mathit{lstate}\le 0$ or .

   $\mathbf{ifail}=-1$

Required length of state array returned in lstate but state array not initialized.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g05kf_example

function g05kf_example


fprintf('g05kf example results\n\n');

% Initialize the seed
seed = [int64(1762543)];

% genid and subid identify the base generator
genid = int64(1);
subid = int64(1);

% Initialize the generator to a repeatable sequence
[state, ifail] = g05kf( ...
                        genid, subid, seed);

% The number of pseudorandom numbers to be generated
n = int64(5);

% Generate the variates
[state, x, ifail] = g05sa( ...
                           n, state);

% Display variates
disp(x);

g05kf example results

    0.6364
    0.1065
    0.7460
    0.7983
    0.1046