g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_ref_vec_multi_normal (g05eac)

## 1  Purpose

nag_ref_vec_multi_normal (g05eac) sets up a reference vector for a multivariate Normal distribution with mean vector $a$ and variance-covariance matrix $C$, so that nag_return_multi_normal (g05ezc) may be used to generate pseudorandom vectors.

## 2  Specification

 #include #include
 void nag_ref_vec_multi_normal (const double a[], Integer n, const double c[], Integer tdc, double eps, double **r, NagError *fail)

## 3  Description

When the variance-covariance matrix is non-singular (i.e., strictly positive definite), the distribution has probability density function
 $f x = C -1 2π n exp - x-aT C -1 x-a$
where $n$ is the number of dimensions, $C$ is the variance-covariance matrix, $a$ is the vector of means and $x$ is the vector of positions.
Variance-covariance matrices are symmetric and positive semidefinite. Given such a matrix $C$, there exists a lower triangular matrix $L$ such that ${LL}^{\mathrm{T}}=C$. $L$ is not unique, if $C$ is singular.
nag_ref_vec_multi_normal (g05eac) decomposes $C$ to find such an $L$. It then stores $n$, $a$ and $L$ in the reference vector $r$ for later use by nag_return_multi_normal (g05ezc). nag_return_multi_normal (g05ezc) generates 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 variance-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.

## 4  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

## 5  Arguments

1:     a[n]const doubleInput
On entry: the vector of means, $a$, of the distribution.
2:     nIntegerInput
On entry: the number of dimensions, $n$, of the distribution.
Constraint: ${\mathbf{n}}>0$.
3:     c[${\mathbf{n}}×{\mathbf{tdc}}$]const doubleInput
Note: the $\left(i,j\right)$th element of the matrix $C$ is stored in ${\mathbf{c}}\left[\left(i-1\right)×{\mathbf{tdc}}+j-1\right]$.
On entry: the variance-covariance matrix of the distribution. Only the upper triangle need be set.
4:     tdcIntegerInput
On entry: the stride separating matrix column elements in the array c.
Constraint: ${\mathbf{tdc}}\ge {\mathbf{n}}$.
5:     epsdoubleInput
On entry: the maximum error in any element of $C$, relative to the largest element of $C$.
Constraint: $0.0\le {\mathbf{eps}}\le 0.1/{\mathbf{n}}$.
6:     rdouble **Output
On exit: reference vector for which memory will be allocated internally. This reference vector will subsequently be used by nag_return_multi_normal (g05ezc). If no memory is allocated to r (e.g., when an input error is detected) then r will be NULL on return, otherwise you should use the NAG macro NAG_FREE to free the storage allocated by r when it is no longer of use.
7:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_2_INT_ARG_LT
On entry, ${\mathbf{tdc}}=〈\mathit{\text{value}}〉$ while ${\mathbf{n}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{tdc}}\ge {\mathbf{n}}$.
NE_2_REAL_ARG_GT
On entry, ${\mathbf{eps}}=〈\mathit{\text{value}}〉$ while 0.1/${\mathbf{n}}=〈\mathit{\text{value}}〉$. These arguments must satisfy ${\mathbf{eps}}\le 0.1$/n.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INT_ARG_LT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 1$.
NE_NOT_POS_SEM_DEF
Matrix $C$ is not positive semidefinite.
NE_REAL_ARG_LT
On entry, eps must not be less than 0.0: ${\mathbf{eps}}=〈\mathit{\text{value}}〉$.

## 7  Accuracy

The maximum absolute error in ${LL}^{\mathrm{T}}$, and hence in the variance-covariance matrix of the resulting vectors, is less than $\left(n×\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{eps}},\epsilon \right)+\left(n+3\right)\epsilon /2\right)$ times the maximum element of $C$, where $\epsilon$ is the machine precision. Under normal circumstances, the above will be small compared to sampling error.

The time taken by nag_ref_vec_multi_normal (g05eac) is of order ${n}^{3}$.
It is recommended that the diagonal elements of $C$ should not differ too widely in order of magnitude. This may be achieved by scaling the variables if necessary. The actual matrix decomposed is $C+E={LL}^{\mathrm{T}}$, where $E$ is a diagonal matrix with small positive diagonal elements. This ensures that, even when $C$ is singular, or nearly singular, the Cholesky factor $L$ corresponds to a positive definite variance-covariance matrix that agrees with $C$ within a tolerance determined by eps.

## 9  Example

The example program prints five pseudorandom observations from a bivariate Normal distribution with means vector
 $1.0 2.0$
and variance-covariance matrix
 $2.0 1.0 1.0 3.0 ,$
generated by nag_ref_vec_multi_normal (g05eac) and nag_return_multi_normal (g05ezc) after initialization by nag_random_init_repeatable (g05cbc).

### 9.1  Program Text

Program Text (g05eace.c)

None.

### 9.3  Program Results

Program Results (g05eace.r)