g02 Chapter Contents
g02 Chapter Introduction
NAG Library Manual

NAG Library Function Documentnag_nearest_correlation_h_weight (g02ajc)

1  Purpose

nag_nearest_correlation_h_weight (g02ajc) computes the nearest correlation matrix, using element-wise weighting in the Frobenius norm and optionally with bounds on the eigenvalues, to a given square, input matrix.

2  Specification

 #include #include
 void nag_nearest_correlation_h_weight (double g[], Integer pdg, Integer n, double alpha, double h[], Integer pdh, double errtol, Integer maxit, double x[], Integer pdx, Integer *iter, double *norm, NagError *fail)

3  Description

nag_nearest_correlation_h_weight (g02ajc) finds the nearest correlation matrix, $X$, to an approximate correlation matrix, $G$, using element-wise weighting, this minimizes ${‖H\circ \left(G-X\right)‖}_{F}$, where $C=A\circ B$ denotes the matrix $C$ with elements ${C}_{ij}={A}_{ij}×{B}_{ij}$.
You can optionally specify a lower bound on the eigenvalues, $\alpha$, of the computed correlation matrix, forcing the matrix to be strictly positive definite, if $0<\alpha <1$.
Zero elements in $H$ should be used when you wish to put no emphasis on the corresponding element of $G$. The algorithm scales $H$ so that the maximum element is $1$. It is this scaled matrix that is used in computing the norm above and for the stopping criteria described in Section 7.
Note that if the elements in $H$ 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
Jiang K, Sun D and Toh K-C (To appear) An inexact accelerated proximal gradient method for large scale linearly constrained convex SDP
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:     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]$.
On entry: $G$, the initial matrix.
On exit: $G$ is overwritten.
2:     pdgIntegerInput
On entry: the stride separating matrix row elements in the array g.
Constraint: ${\mathbf{pdg}}\ge {\mathbf{n}}$.
3:     nIntegerInput
On entry: the order of the matrix $G$.
Constraint: ${\mathbf{n}}>0$.
On entry: the value of $\alpha$.
If ${\mathbf{alpha}}<0.0$, $0.0$ is used.
Constraint: ${\mathbf{alpha}}<1.0$.
5:     h[${\mathbf{pdh}}×{\mathbf{n}}$]doubleInput/Output
Note: the $\left(i,j\right)$th element of the matrix $H$ is stored in ${\mathbf{h}}\left[\left(j-1\right)×{\mathbf{pdh}}+i-1\right]$.
On entry: the matrix of weights $H$.
On exit: a symmetric matrix $\frac{1}{2}\left(H+{H}^{\mathrm{T}}\right)$ with its diagonal elements set to zero and the remaining elements scaled so that the maximum element is $1.0$.
Constraint: $\mathit{H}\left[\left(\mathit{j}-1\right)×{\mathbf{pdh}}+\mathit{i}-1\right]\ge 0.0$, for all $i$ and $j=1,2,\dots ,n$, $i\ne j$.
6:     pdhIntegerInput
On entry: the stride separating matrix row elements in the array h.
Constraint: ${\mathbf{pdh}}\ge {\mathbf{n}}$.
7:     errtoldoubleInput
On entry: the termination tolerance for the iteration. If ${\mathbf{errtol}}\le 0.0$ then  is used. See Section 7 for further details.
8:     maxitIntegerInput
On entry: specifies the maximum number of iterations to be used.
If ${\mathbf{maxit}}\le 0$, $200$ is used.
9:     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]$.
On exit: contains the nearest correlation matrix.
10:   pdxIntegerInput
On entry: the stride separating matrix row elements in the array x.
Constraint: ${\mathbf{pdx}}\ge {\mathbf{n}}$.
11:   iterInteger *Output
On exit: the number of iterations taken.
12:   normdouble *Output
On exit: the value of ${‖H\circ \left(G-X\right)‖}_{F}$ after the final iteration.
13:   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
Function fails to converge in $⟨\mathit{\text{value}}⟩$ iterations.
Increase maxit or check the call to the function.
NE_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{pdh}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdh}}\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: ${\mathbf{alpha}}<1.0$.
NE_WEIGHTS_NOT_POSITIVE
On entry, one or more of the off-diagonal elements of $H$ were negative.

7  Accuracy

The returned accuracy is controlled by errtol and limited by machine precision. If ${e}_{i}$ is the value of norm at the $i$th iteration, that is
 $ei = H∘G-XF ,$
where $H$ has been scaled as described above, then the algorithm terminates when:
 $ei-ei-1 1+ maxei,ei-1 ≤ errtol .$

8  Parallelism and Performance

nag_nearest_correlation_h_weight (g02ajc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_nearest_correlation_h_weight (g02ajc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Arrays are internally allocated by nag_nearest_correlation_h_weight (g02ajc). The total size of these arrays is $15×{\mathbf{n}}+5×{\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_h_weight (g02ajc).

10  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:
 $H = 0.0 10.0 0.0 0.0 10.0 0.0 1.5 1.5 0.0 1.5 0.0 0.0 0.0 1.5 0.0 0.0$
with minimum eigenvalue $0.04$.

10.1  Program Text

Program Text (g02ajce.c)

10.2  Program Data

Program Data (g02ajce.d)

10.3  Program Results

Program Results (g02ajce.r)