naginterfaces.library.rand.int_​general

naginterfaces.library.rand.int_general(mode, n, p, ip1, itype, statecomm, comm=None)

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

For full information please refer to the NAG Library document for g05td

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g05/g05tdf.html

Parameters

modeint

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

$mode=0$

Set up reference vector only.

$mode=1$

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

$mode=2$

Set up reference vector and generate variates.

$mode=3$

Generate variates without using the reference vector.

nint

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

pfloat, array-like, shape $\left(\text{np}\right)$

The PDF or CDF of the distribution.

ip1int

The value of the variate, a whole number, to which the probability in $p\left[0\right]$ corresponds.

itypeint

Indicates the type of information contained in $p$.

$itype=1$

$p$ contains a probability distribution function (PDF).

$itype=2$

$p$ contains a cumulative distribution function (CDF).

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

commNone or dict, communication object, optional, modified in place

Communication structure for the reference vector.

If $mode=1$, this argument must have been initialized by a prior call to int_general.

If $mode=3$, $comm$ is not referenced and may be None.

Returns

xNone or int, ndarray, shape $\left(n\right)$

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

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=0$, $1$ or $2$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $3$)

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

(errno $3$)

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

(errno $3$)

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

(errno $3$)

On entry, $p[\text{np}-1]=⟨value⟩$.

Constraint: if $itype=2$, $p[\text{np}-1]=1.0$.

(errno $4$)

On entry, $\text{np}=⟨value⟩$.

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

(errno $6$)

On entry, $itype=⟨value⟩$.

Constraint: $itype=1$ or $2$.

(errno $7$)

The value of $\text{np}$ or $ip1$ is not the same as when $comm$[‘r’] was set up in a previous call.

Previous value of $\text{np}=⟨value⟩$ and $\text{np}=⟨value⟩$.

Previous value of $ip1=⟨value⟩$ and $ip1=⟨value⟩$.

(errno $7$)

On entry, some of the elements of the array $comm$[‘r’] have been corrupted or have not been initialized.

(errno $9$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

Notes

int_general 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.

Setting up the reference vector and subsequent generation of variates can each be performed by separate calls to int_general or may be combined in a single call.

One of the initialization functions init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to int_general.

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