naginterfaces.library.rand.multivar_​normal

naginterfaces.library.rand.multivar_normal(sorder, mode12, n, xmu, c, comm, statecomm)

multivar_normal sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Normal distribution with mean vector $a$ and covariance matrix $C$.

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

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

Parameters

sorderint

Determines the storage order of variates; the $(\text{i},\text{j})$th variate is stored in $x[\text{i}-1,\text{j}-1]$ if $sorder=1$, and $x[\text{j}-1,\text{i}-1]$ if $sorder=2$, for $\text{j}=1,2,\dots ,m$, for $\text{i}=1,2,\dots ,n$.

mode12int

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

$mode12=0$

Set up reference vector only.

$mode12=1$

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

$mode12=2$

Set up reference vector and generate variates.

nint

$n$, the number of random variates required.

xmufloat, array-like, shape $\left(m\right)$

$a$, the vector of means of the distribution.

cfloat, array-like, shape $(m,m)$

The covariance matrix of the distribution. Only the upper triangle need be set.

commdict, communication object, modified in place

Communication structure for the reference vector.

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

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().

Returns

xNone or float, ndarray, shape $(:,:)$

The array of pseudorandom multivariate Normal vectors generated by the function.

Two possible storage orders are available.

If $sorder=1$ then $x[i-1,j-1]$ holds the $j$th dimension for the $i$th variate.

If $sorder=2$ this ordering is reversed and $x[j-1,i-1]$ holds the $j$th dimension for the $i$th variate.

Raises

NagValueError

(errno $1$)

On entry, $mode12=⟨value⟩$.

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

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $3$)

On entry, $m=⟨value⟩$.

Constraint: $m>0$.

(errno $5$)

On entry, the covariance matrix $C$ is not positive semidefinite to machine precision.

(errno $7$)

$\text{m}$ is not the same as when $comm$[‘r’] was set up in a previous call.

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

(errno $9$)

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

Notes

When the covariance matrix is nonsingular (i.e., strictly positive definite), the distribution has probability density function

$$f\left(x\right)=\sqrt{\frac{\left|C^{-1}\right|}{{\left(2\pi \right)}^m}}exp(-\frac{1}{2}{(x-a)}^T{C}^{-1}(x-a))$$

where $m$ is the number of dimensions, $C$ is the covariance matrix, $a$ is the vector of means and $x$ is the vector of positions.

Covariance matrices are symmetric and positive semidefinite. Given such a matrix $C$, there exists a lower triangular matrix $L$ such that $L{L}^T=C$. $L$ is not unique, if $C$ is singular.

multivar_normal decomposes $C$ to find such an $L$. It then stores $m$, $a$ and $L$ in the reference vector $r$ which is used to generate a vector $x$ of independent standard Normal pseudorandom numbers. It then returns the vector $a+Lx$, which has the required multivariate Normal distribution.

It should be noted that this function will work with a singular covariance matrix $C$, provided $C$ is positive semidefinite, despite the fact that the above formula for the probability density function is not valid in that case. Wilkinson (1965) should be consulted if further information is required.

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

References

Knuth, D E, 1981, The Art of Computer Programming (Volume 2), (2nd Edition), Addison–Wesley

Wilkinson, J H, 1965, The Algebraic Eigenvalue Problem, Oxford University Press, Oxford