naginterfaces.library.rand.multivar_​normal

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

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

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

https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/g05/g05rzf.html

Parameters
sorderint

Determines the storage order of variates; the th variate is stored in if , and if , for , for .

mode12int

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

Set up reference vector only.

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

Set up reference vector and generate variates.

nint

, the number of random variates required.

xmufloat, array-like, shape

, the vector of means of the distribution.

cfloat, array-like, shape

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 , 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 then holds the th dimension for the th variate.

If this ordering is reversed and holds the th dimension for the th variate.

Raises
NagValueError
(errno )

On entry, .

Constraint: , or .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

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

(errno )

is not the same as when [‘r’] was set up in a previous call.

Previous value of and .

(errno )

On entry, [‘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

where is the number of dimensions, is the covariance matrix, is the vector of means and is the vector of positions.

Covariance matrices are symmetric and positive semidefinite. Given such a matrix , there exists a lower triangular matrix such that . is not unique, if is singular.

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

It should be noted that this function will work with a singular covariance matrix , provided 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