NAG Toolbox: nag_rand_int_general (g05td)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

A code for selecting the operation to be performed by the function.

$\mathbf{mode}=0$

Set up reference vector only.

$\mathbf{mode}=1$

Generate variates using reference vector set up in a prior call to nag_rand_int_general (g05td).

$\mathbf{mode}=2$

Set up reference vector and generate variates.

$\mathbf{mode}=3$

Generate variates without using the reference vector.

Constraint: $\mathbf{mode}=0$, $1$, $2$ or $3$.

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

$n$, the number of pseudorandom numbers to be generated.

Constraint: $\mathbf{n}\ge 0$.

3:     $\mathrm{p}\left(\mathbf{np}\right)$ – double array

The PDF or CDF of the distribution.

Constraints:

• $0.0\le \mathbf{p}\left(\mathit{i}\right)\le 1.0$, for $\mathit{i}=1,2,\dots ,\mathbf{np}$;
• if $\mathbf{itype}=1$, ${\displaystyle \sum _{\mathit{i}=1}^{\mathbf{np}}}\mathbf{p}\left(\mathit{i}\right)=1.0$;
• if $\mathbf{itype}=2$, $\mathbf{p}\left(\mathit{i}\right)<\mathbf{p}\left(j\right)\text{, }\mathit{i}<j\text{ and }\mathbf{p}\left(\mathbf{np}\right)=1.0$.

4:     $\mathrm{ip1}$ – int64int32nag_int scalar

The value of the variate, a whole number, to which the probability in $\mathbf{p}\left(1\right)$ corresponds.

5:     $\mathrm{itype}$ – int64int32nag_int scalar

Indicates the type of information contained in p.

$\mathbf{itype}=1$

p contains a probability distribution function (PDF).

$\mathbf{itype}=2$

p contains a cumulative distribution function (CDF).

Constraint: $\mathbf{itype}=1$ or $2$.

6:     $\mathrm{r}\left(\mathit{lr}\right)$ – double array

lr, the dimension of the array, must satisfy the constraint

• if $\mathbf{mode}=0$ or $2$, $\mathit{lr}\ge \mathbf{np}+8$;
• if $\mathbf{mode}=1$, lr should remain unchanged from the previous call to nag_rand_int_general (g05td).

If $\mathbf{mode}=1$, the reference vector from the previous call to nag_rand_int_general (g05td).

7:     $\mathrm{state}\left(:\right)$ – int64int32nag_int array

Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).

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

Optional Input Parameters

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

Default: the dimension of the array p.

The number of values supplied in p defining the PDF or CDF of the discrete distribution.

Constraint: $\mathbf{np}>0$.

Output Parameters

1:     $\mathrm{r}\left(\mathit{lr}\right)$ – double array

The reference vector.

2:     $\mathrm{state}\left(:\right)$ – int64int32nag_int array

Contains updated information on the state of the generator.

3:     $\mathrm{x}\left(\mathbf{n}\right)$ – int64int32nag_int array

Contains $n$ pseudorandom numbers from the specified discrete distribution.

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

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

Constraint: $\mathbf{mode}=0$, $1$ or $2$.

   $\mathbf{ifail}=2$

Constraint: $\mathbf{n}\ge 0$.

   $\mathbf{ifail}=3$

Constraint: if $\mathbf{itype}=2$, $\mathbf{p}\left(\mathbf{np}\right)=1.0$.

On entry, at least one element of the vector p is less than $0.0$ or greater than $1.0$.

On entry, $\mathbf{itype}=1$ and the sum of the elements of p do not equal one.

On entry, $\mathbf{itype}=2$ and the values of p are not all in stricly ascending order.

   $\mathbf{ifail}=4$

Constraint: $\mathbf{np}>0$.

   $\mathbf{ifail}=6$

Constraint: $\mathbf{itype}=1$ or $2$.

   $\mathbf{ifail}=7$

On entry, some of the elements of the array r have been corrupted or have not been initialized.

The value of np or ip1 is not the same as when r was set up in a previous call.

   $\mathbf{ifail}=8$

On entry, lr is too small when $\mathbf{mode}=0$ or $2$.

   $\mathbf{ifail}=9$

On entry, state vector has been corrupted or 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: g05td_example

function g05td_example


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

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

% Number of variates
n = int64(20);

% Parameters (PDF) 
p = [0.01;     0.02;     0.04;    0.08;     0.2;     0.3;
     0.2;      0.08;     0.04;    0.02;     0.01];
ip1 = int64(-5);
itype = int64(1);

% Generate variates from PDF defined by p and ip1
mode = int64(2);
r = zeros(60, 1);
[r, state, x, ifail] = g05td( ...
                              mode, n, p, ip1, itype, r, state);

disp('Variates');
disp(double(x));

g05td example results

Variates
     0
    -2
     1
     1
    -2
     0
     0
     1
     0
     1
    -3
    -1
     0
    -3
     0
    -1
    -1
     5
     2
     0