hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_correg_corrmat_nearest (g02aa)


    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example


nag_correg_corrmat_nearest (g02aa) computes the nearest correlation matrix, in the Frobenius norm, to a given square, input matrix.


[g, x, iter, feval, nrmgrd, ifail] = g02aa(g, 'n', n, 'errtol', errtol, 'maxits', maxits, 'maxit', maxit)
[g, x, iter, feval, nrmgrd, ifail] = nag_correg_corrmat_nearest(g, 'n', n, 'errtol', errtol, 'maxits', maxits, 'maxit', maxit)
Note: the interface to this routine has changed since earlier releases of the toolbox:
At Mark 23: errtol, maxits and maxit were made optional


A correlation matrix may be characterised as a real square matrix that is symmetric, has a unit diagonal and is positive semidefinite.
nag_correg_corrmat_nearest (g02aa) applies an inexact Newton method to a dual formulation of the problem, as described by Qi and Sun (2006). It applies the improvements suggested by Borsdorf and Higham (2010).


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


Compulsory Input Parameters

1:     gldgn – double array
ldg, the first dimension of the array, must satisfy the constraint ldgn.
G, the initial matrix.

Optional Input Parameters

1:     n int64int32nag_int scalar
Default: the first dimension of the array g and the second dimension of the array g. (An error is raised if these dimensions are not equal.)
The size of the matrix G.
Constraint: n>0.
2:     errtol – double scalar
Default: 0.0 
The termination tolerance for the Newton iteration. If errtol0.0 then n×machine precision is used.
3:     maxits int64int32nag_int scalar
Default: 0 
maxits specifies the maximum number of iterations used for the iterative scheme used to solve the linear algebraic equations at each Newton step.
If maxits0, 2×n is used.
4:     maxit int64int32nag_int scalar
Default: 0 
Specifies the maximum number of Newton iterations.
If maxit0, 200 is used.

Output Parameters

1:     gldgn – double array
A symmetric matrix 12G+GT with the diagonal set to I.
2:     xldxn – double array
Contains the nearest correlation matrix.
3:     iter int64int32nag_int scalar
The number of Newton steps taken.
4:     feval int64int32nag_int scalar
The number of function evaluations of the dual problem.
5:     nrmgrd – double scalar
The norm of the gradient of the last Newton step.
6:     ifail int64int32nag_int scalar
ifail=0 unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

Constraint: ldgn.
Constraint: ldxn.
Constraint: n>0.
Newton iteration fails to converge in _ iterations.
W  ifail=3
Machine precision is limiting convergence.
The array returned in x may still be of interest.
An intermediate eigenproblem could not be solved. This should not occur. Please contact NAG with details of your call.
An unexpected error has been triggered by this routine. Please contact NAG.
Your licence key may have expired or may not have been installed correctly.
Dynamic memory allocation failed.


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

Further Comments

Arrays are internally allocated by nag_correg_corrmat_nearest (g02aa). The total size of these arrays is 11×n+3×n×n+max2×n×n+6×n+1,120+9×n real elements and 5×n+3 integer elements.


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  
function g02aa_example

fprintf('g02aa example results\n\n');

g = [ 2, -1,  0,  0;
     -1,  2, -1,  0;
      0, -1,  2, -1;
      0,  0, -1,  2];

[g, x, iter, feval, nrmgrd, ifail] = ...

fprintf('\n     Nearest Correlation Matrix\n');
fprintf('\n Number of Newton steps taken:   %d\n', iter);
fprintf(' Number of function evaluations: %d\n', feval);
if (nrmgrd > 4*x02aj)
  fprintf(' Norm of gradient of last Newton step: %6.4f\n', nrmgrd);

g02aa example results

     Nearest Correlation Matrix
    1.0000   -0.8084    0.1916    0.1068
   -0.8084    1.0000   -0.6562    0.1916
    0.1916   -0.6562    1.0000   -0.8084
    0.1068    0.1916   -0.8084    1.0000

 Number of Newton steps taken:   3
 Number of function evaluations: 4
 Norm of gradient of last Newton step: 0.0000

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015