g02 Chapter Contents
g02 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_nearest_correlation_bounded (g02abc)

## 1  Purpose

nag_nearest_correlation_bounded (g02abc) computes the nearest correlation matrix, in the Frobenius norm or weighted Frobenius norm, and optionally with bounds on the eigenvalues, to a given square, input matrix.

## 2  Specification

 #include #include
 void nag_nearest_correlation_bounded (Nag_OrderType order, double g[], Integer pdg, Integer n, Nag_NearCorr_ProbType opt, double alpha, double w[], double errtol, Integer maxits, Integer maxit, double x[], Integer pdx, Integer *iter, Integer *feval, double *nrmgrd, NagError *fail)

## 3  Description

Finds the nearest correlation matrix $X$ by minimizing $\frac{1}{2}{‖G-X‖}^{2}$ where $G$ is an approximate correlation matrix.
The norm can either be the Frobenius norm or the weighted Frobenius norm $\frac{1}{2}{‖{W}^{\frac{1}{2}}\left(G-X\right){W}^{\frac{1}{2}}‖}_{F}^{2}$.
You can optionally specify a lower bound on the eigenvalues, $\alpha$, of the computed correlation matrix, forcing the matrix to be positive definite, $0<\alpha <1$.
Note that if the weights vary by several orders of magnitude from one another the algorithm may fail to converge.

## 4  References

Borsdorf R and Higham N J (2010) A preconditioned (Newton) algorithm for the nearest correlation matrix IMA Journal of Numerical Analysis 30(1) 94–107
Qi H and Sun D (2006) A quadratically convergent Newton method for computing the nearest correlation matrix SIAM J. Matrix AnalAppl 29(2) 360–385

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     g[${\mathbf{pdg}}×{\mathbf{n}}$]doubleInput/Output
Note: the $\left(i,j\right)$th element of the matrix $G$ is stored in
• ${\mathbf{g}}\left[\left(j-1\right)×{\mathbf{pdg}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{g}}\left[\left(i-1\right)×{\mathbf{pdg}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: $G$, the initial matrix.
On exit: a symmetric matrix $\frac{1}{2}\left(G+{G}^{\mathrm{T}}\right)$ with the diagonal set to $I$.
3:     pdgIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array g.
Constraint: ${\mathbf{pdg}}\ge {\mathbf{n}}$.
4:     nIntegerInput
On entry: the order of the matrix $G$.
Constraint: ${\mathbf{n}}>0$.
5:     optNag_NearCorr_ProbTypeInput
On entry: indicates the problem to be solved.
${\mathbf{opt}}=\mathrm{Nag_LowerBound}$
The lower bound problem is solved.
${\mathbf{opt}}=\mathrm{Nag_WeightedNorm}$
The weighted norm problem is solved.
${\mathbf{opt}}=\mathrm{Nag_Both}$
Both problems are solved.
Constraint: ${\mathbf{opt}}=\mathrm{Nag_LowerBound}$, $\mathrm{Nag_WeightedNorm}$ or $\mathrm{Nag_Both}$.
On entry: the value of $\alpha$.
If ${\mathbf{opt}}=\mathrm{Nag_WeightedNorm}$, alpha need not be set.
Constraint: $0.0<{\mathbf{alpha}}<1.0$.
7:     w[n]doubleInput/Output
On entry: the square roots of the diagonal elements of $W$, that is the diagonal of ${W}^{\frac{1}{2}}$.
If ${\mathbf{opt}}=\mathrm{Nag_LowerBound}$, w need not be set.
On exit: if ${\mathbf{opt}}=\mathrm{Nag_WeightedNorm}$ or $\mathrm{Nag_Both}$, the array is scaled so $0<{\mathbf{w}}\left[\mathit{i}-1\right]\le 1$, for $\mathit{i}=1,2,\dots ,n$.
Constraint: ${\mathbf{w}}\left[\mathit{i}-1\right]>0.0$, for $\mathit{i}=1,2,\dots ,n$.
8:     errtoldoubleInput
On entry: the termination tolerance for the Newton iteration. If ${\mathbf{errtol}}\le 0.0$ then  is used.
9:     maxitsIntegerInput
On entry: specifies the maximum number of iterations to be used by the iterative scheme to solve the linear algebraic equations at each Newton step.
If ${\mathbf{maxits}}\le 0$, $2×{\mathbf{n}}$ is used.
10:   maxitIntegerInput
On entry: specifies the maximum number of Newton iterations.
If ${\mathbf{maxit}}\le 0$, $200$ is used.
11:   x[${\mathbf{pdx}}×{\mathbf{n}}$]doubleOutput
Note: the $\left(i,j\right)$th element of the matrix $X$ is stored in
• ${\mathbf{x}}\left[\left(j-1\right)×{\mathbf{pdx}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x}}\left[\left(i-1\right)×{\mathbf{pdx}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: contains the nearest correlation matrix.
12:   pdxIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array x.
Constraint: ${\mathbf{pdx}}\ge {\mathbf{n}}$.
13:   iterInteger *Output
On exit: the number of Newton steps taken.
14:   fevalInteger *Output
On exit: the number of function evaluations of the dual problem.
15:   nrmgrddouble *Output
On exit: the norm of the gradient of the last Newton step.
16:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_CONVERGENCE
Machine precision is limiting convergence. In this instance the returned matrix $X$ may be useful.
Newton iteration fails to converge in $〈\mathit{\text{value}}〉$ iterations. Increase maxit or check the call to the function.
NE_EIGENPROBLEM
Failure to solve intermediate eigenproblem.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}>0$.
NE_INT_2
On entry, ${\mathbf{pdg}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdg}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{pdx}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdx}}\ge {\mathbf{n}}$
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_REAL
On entry, ${\mathbf{alpha}}=〈\mathit{\text{value}}〉$.
Constraint: $0.0<{\mathbf{alpha}}<1.0$.
NE_WEIGHTS_NOT_POSITIVE
On entry, all elements of w were not positive.

## 7  Accuracy

The returned accuracy is controlled by errtol and limited by machine precision.

Arrays are internally allocated by nag_nearest_correlation_bounded (g02abc). The total size of these arrays is $12×{\mathbf{n}}+3×{\mathbf{n}}×{\mathbf{n}}+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(2×{\mathbf{n}}×{\mathbf{n}}+6×{\mathbf{n}}+1,120+9×{\mathbf{n}}\right)$ double elements and $5×{\mathbf{n}}+3$ Integer elements. All allocated memory is freed before return of nag_nearest_correlation_bounded (g02abc).

## 9  Example

This example finds the nearest correlation matrix to:
 $G = 2 -1 0 0 -1 2 -1 0 0 -1 2 -1 0 0 -1 2$
weighted by ${W}^{\frac{1}{2}}=\mathrm{diag}\left(100,20,20,20\right)$ with minimum eigenvalue $0.02$.

### 9.1  Program Text

Program Text (g02abce.c)

### 9.2  Program Data

Program Data (g02abce.d)

### 9.3  Program Results

Program Results (g02abce.r)