g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

NAG Library Function Documentnag_rngs_gen_discrete (g05mzc)

1  Purpose

nag_rngs_gen_discrete (g05mzc) generates a vector of pseudorandom integers from a discrete distribution with a given PDF (probability density function) or CDF (cumulative distribution function) $p$.

2  Specification

 #include #include
 void nag_rngs_gen_discrete (Integer mode, const double p[], Integer np, Integer ip1, Nag_ComputeType comp_type, Integer n, Integer x[], Integer igen, Integer iseed[], double r[], NagError *fail)

3  Description

nag_rngs_gen_discrete (g05mzc) generates a sequence of $n$ integers ${x}_{i}$, from a discrete distribution defined by information supplied in p. This may either be the PDF or CDF of the distribution. A reference vector is first set up to contain the CDF of the distribution in its higher elements, followed by an index. The full specifications of the reference vector are as follows.
• ${\mathbf{r}}\left[0\right]=\text{}$ the number of elements of index, $k$.
• ${\mathbf{r}}\left[1\right]=\text{}$ a check number to make sure that the values of ip1 and comp_type haven't changed when calling nag_rngs_gen_discrete (g05mzc) with ${\mathbf{mode}}=1$.
• ${\mathbf{r}}\left[2\right]=\text{}$ the number of values the variates can take (i.e., the first value of $k$ such that $\mathrm{CDF}\left(k\right)=1$).
• ${\mathbf{r}}\left[3\right]={\mathbf{ip1}}-1$.
• ${\mathbf{r}}\left[4\right]=\text{}$ the space available for indexing $\text{}=8+1.4×{\mathbf{np}}-\left({\mathbf{r}}\left[2\right]+5\right)$.
• ${\mathbf{r}}\left[\mathit{i}+4\right]$, for $\mathit{i}=1,2,\dots ,{\mathbf{r}}\left[2\right]$, the CDF.
• ${\mathbf{r}}\left[\mathit{i}-1\right]=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left\{j\mid \mathrm{CDF}\left(j\right)>\left(\mathit{i}-1\right)/k\right\}$, for $\mathit{i}={\mathbf{r}}\left[2\right]+6,\dots ,8+1.4×{\mathbf{np}}$.
Setting up the reference vector and subsequent generation of variates can each be performed by separate calls to nag_rngs_gen_discrete (g05mzc) or may be combined in a single call.
One of the initialization functions nag_rngs_init_repeatable (g05kbc) (for a repeatable sequence if computed sequentially) or nag_rngs_init_nonrepeatable (g05kcc) (for a non-repeatable sequence) must be called prior to the first call to nag_rngs_gen_discrete (g05mzc).

4  References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

5  Arguments

1:     modeIntegerInput
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:     npIntegerInput
On entry: the number of values supplied in p defining the PDF or CDF of the discrete distribution.
Constraint: ${\mathbf{np}}>0$.
4:     ip1IntegerInput
On entry: the value of the variate, a whole number, to which the probability in ${\mathbf{p}}\left[0\right]$ corresponds.
5:     comp_typeNag_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:     nIntegerInput
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:     igenIntegerInput
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×{\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:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

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

Not applicable.

None.

9  Example

This example prints $20$ pseudorandom variates from a discrete distribution whose PDF, $f\left(n\right)$, is defined as follows:
 $n fn -5 0.01 -4 0.02 -3 0.04 -2 0.08 -1 0.20 -0 0.30 -1 0.20 -2 0.08 -3 0.04 -4 0.02 -5 0.01$
The reference vector is set up and and the variates are generated by a single call to nag_rngs_gen_discrete (g05mzc), after initialization by nag_rngs_init_repeatable (g05kbc).

9.1  Program Text

Program Text (g05mzce.c)

None.

9.3  Program Results

Program Results (g05mzce.r)