NAG Library Function Document

nag_rngs_gen_discrete (g05mzc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     mode – IntegerInput

On entry: 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_rngs_gen_discrete (g05mzc).

$\mathbf{mode}=2$

Set up reference vector and generate variates.

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

2:     p[np] – const doubleInput

On entry: the PDF or CDF of the distribution.

3:     np – IntegerInput

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

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

4:     ip1 – IntegerInput

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

5:     comp_type – Nag_ComputeTypeInput

On entry: indicates the type of information contained in p.

$\mathbf{comp\_type}=\mathrm{Nag\_Compute\_1}$

p contains a probability distribution function (PDF).

$\mathbf{comp\_type}=\mathrm{Nag\_Compute\_2}$

p contains a cumulative distribution function (CDF).

Constraint: $\mathbf{comp\_type}=\mathrm{Nag\_Compute\_1}$ or $\mathrm{Nag\_Compute\_2}$.

6:     n – IntegerInput

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

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

7:     x[n] – IntegerOutput

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

8:     igen – IntegerInput

On entry: must contain the identification number for the generator to be used to return a pseudorandom number and should remain unchanged following initialization by a prior call to nag_rngs_init_repeatable (g05kbc) or nag_rngs_init_nonrepeatable (g05kcc).

9:     iseed[$4$] – IntegerCommunication Array

On entry: contains values which define the current state of the selected generator.

On exit: contains updated values defining the new state of the selected generator.

10:   r[$8+1.4\times \mathbf{np}$] – doubleCommunication Array

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

On exit: the reference vector.

11:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_INT

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

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

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

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.

NE_NOT_INCREASING

On entry, $\mathbf{comp\_type}=\mathrm{Nag\_Compute\_2}$ and the values in p are not all in non-descending order.

NE_PREV_CALL

comp_type is not the same as when r was set up in a previous call. Previous value of $\mathbf{comp\_type}=〈\mathit{\text{value}}〉$ and $\mathbf{comp\_type}=〈\mathit{\text{value}}〉$.

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}}〉$.

NE_REAL_ARRAY_ELEM_CONS

On entry, at least one element of the vector p is negative. The first found is at position $i=〈\mathit{\text{value}}〉$, $\mathbf{p}\left[i-1\right]=〈\mathit{\text{value}}〉$.

NE_REAL_ARRAY_SUM

On entry, the sum of the elements of p is not one. The difference from unity in the summation is: $〈\mathit{\text{value}}〉$.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g05mzce.c)

9.2  Program Data

9.3  Program Results

Program Results (g05mzce.r)