NAG FL Interface
g05tdf (int_​general)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{mode}$ – Integer Input

On entry: a code for selecting the operation to be performed by the routine.

$\mathbf{mode}=0$

Set up reference vector only.

$\mathbf{mode}=1$

Generate variates using reference vector set up in a prior call to g05tdf.

$\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: $\mathbf{n}$ – Integer Input

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

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

3: $\mathbf{p}\left(\mathbf{np}\right)$ – Real (Kind=nag_wp) array Input

On entry: 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: $\mathbf{np}$ – Integer Input

On entry: the number of values supplied in p defining the PDF or CDF of the discrete distribution.

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

5: $\mathbf{ip1}$ – Integer Input

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

6: $\mathbf{itype}$ – Integer Input

On entry: 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$.

7: $\mathbf{r}\left(\mathbf{lr}\right)$ – Real (Kind=nag_wp) array Communication Array

On entry: if $\mathbf{mode}=1$, the reference vector from the previous call to g05tdf.

On exit: the reference vector.

8: $\mathbf{lr}$ – Integer Input

On entry: the dimension of the array r as declared in the (sub)program from which g05tdf is called.

Suggested values:

• if $\mathbf{mode}\ne 3$, $\mathbf{lr}=10+1.4\times \mathbf{np}$ approximately (for optimum efficiency in generating variates);
• otherwise $\mathbf{lr}=1$.

Constraints:

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

9: $\mathbf{state}\left(*\right)$ – Integer array Communication Array

Note: the actual argument supplied must be the array state supplied to the initialization routines g05kff or g05kgf.

On entry: contains information on the selected base generator and its current state.

On exit: contains updated information on the state of the generator.

10: $\mathbf{x}\left(\mathbf{n}\right)$ – Integer array Output

On exit: contains $n$ pseudorandom numbers from the specified discrete distribution.

11: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 4 in the Introduction to the NAG Library FL Interface for details.

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.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{mode}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{mode}=0$, $1$ or $2$.

$\mathbf{ifail}=2$

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 0$.

$\mathbf{ifail}=3$

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.

On entry, $\mathbf{p}\left(\mathbf{np}\right)=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{itype}=2$, $\mathbf{p}\left(\mathbf{np}\right)=1.0$.

$\mathbf{ifail}=4$

On entry, $\mathbf{np}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{np}>0$.

$\mathbf{ifail}=6$

On entry, $\mathbf{itype}=〈\mathit{\text{value}}〉$.
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.
Previous value of $\mathbf{np}=〈\mathit{\text{value}}〉$ and $\mathbf{np}=〈\mathit{\text{value}}〉$.
Previous value of $\mathbf{ip1}=〈\mathit{\text{value}}〉$ and $\mathbf{ip1}=〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=8$

On entry, lr is too small when $\mathbf{mode}=0$ or $2$: $\mathbf{lr}=〈\mathit{\text{value}}〉$, minimum length required $=〈\mathit{\text{value}}〉$.

$\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.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{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.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results