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_nearest_correlation_h_weight (g02aj)

Purpose

nag_nearest_correlation_h_weight (g02aj) 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.

Syntax

[g, h, x, iter, norm_p, ifail] = g02aj(g, alpha, h, 'n', n, 'errtol', errtol, 'maxit', maxit)
[g, h, x, iter, norm_p, ifail] = nag_nearest_correlation_h_weight(g, alpha, h, 'n', n, 'errtol', errtol, 'maxit', maxit)

Description

nag_nearest_correlation_h_weight (g02aj) finds the nearest correlation matrix, X X , to an approximate correlation matrix, G G , using element-wise weighting, this minimizes H(GX)F H (G-X) F , where C = AB C=AB  denotes the matrix C C  with elements Cij = Aij × Bij Cij=Aij×Bij .
You can optionally specify a lower bound on the eigenvalues, α α , of the computed correlation matrix, forcing the matrix to be strictly positive definite, if 0 < α < 1 0<α<1 .
Zero elements in H H  should be used when you wish to put no emphasis on the corresponding element of G G . The algorithm scales H H  so that the maximum element is 1 1 . It is this scaled matrix that is used in computing the norm above and for the stopping criteria described in Section [Accuracy].
Note that if the elements in H H  vary by several orders of magnitude from one another the algorithm may fail to converge.

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

Parameters

Compulsory Input Parameters

1:     g(ldg,n) – double array
ldg, the first dimension of the array, must satisfy the constraint ldgn ldgn .
G G , the initial matrix.
2:     alpha – double scalar
The value of α α .
If alpha < 0.0 alpha<0.0 , 0.0 0.0  is used.
Constraint: alpha < 1.0 alpha<1.0 .
3:     h(ldh,n) – double array
ldh, the first dimension of the array, must satisfy the constraint ldhn ldhn .
The matrix of weights H H .
Constraint: h(i,j)0.0 h (i,j) 0.0 , for all i i  and j = 1,2,,n j=1,2,,n , ij ij .

Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The first dimension of the arrays h, g and the second dimension of the arrays h, g. (An error is raised if these dimensions are not equal.)
The order of the matrix G G .
Constraint: n > 0 n>0 .
2:     errtol – double scalar
The termination tolerance for the iteration. If errtol0.0 errtol0.0  then n × sqrt(machine precision) n×machine precision  is used. See Section [Accuracy] for further details.
Default: 0.0 0.0  
3:     maxit – int64int32nag_int scalar
Specifies the maximum number of iterations to be used.
If maxit0 maxit0 , 200 200  is used.
Default: 0 0  

Input Parameters Omitted from the MATLAB Interface

ldg ldh ldx

Output Parameters

1:     g(ldg,n) – double array
ldgn ldgn .
A symmetric matrix (1/2)(G + GT) 12 (G+GT) with the diagonal set to I I .
2:     h(ldh,n) – double array
ldhn ldhn .
A symmetric matrix (1/2) (H + HT) 12 (H+HT) with its diagonal elements set to zero and the remaining elements scaled so that the maximum element is 1.0 1.0 .
3:     x(ldx,n) – double array
ldxn ldxn .
Contains the nearest correlation matrix.
4:     iter – int64int32nag_int scalar
The number of iterations taken.
5:     norm_p – double scalar
The value of H(GX)F H (G-X) F after the final iteration.
6:     ifail – int64int32nag_int scalar
ifail = 0 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.

  ifail = 1 ifail=1
Constraint: n > 0 n>0 .
  ifail = 2 ifail=2
Constraint: ldgn ldgn .
  ifail = 3 ifail=3
Constraint: ldhn ldhn .
  ifail = 4 ifail=4
Constraint: ldxn ldxn .
  ifail = 5 ifail=5
Constraint: alpha < 1.0 alpha<1.0 .
  ifail = 6 ifail=6
On entry, one or more of the off-diagonal elements of h were negative.
  ifail = 7 ifail=7
Routine fails to converge in _ _  iterations.
Increase maxit or check the call to the function.
W ifail = 8 ifail=8
Failure to solve intermediate eigenproblem. This should not occur. Please contact NAG with details of your call.
  ifail = 999 ifail=-999
Dynamic memory allocation failed.

Accuracy

The returned accuracy is controlled by errtol and limited by machine precision. If ei ei  is the value of norm_p at the i i th iteration, that is
ei = H(GX)F ,
ei = H (G-X) F ,
where H H  has been scaled as described above, then the algorithm terminates when:
(|eiei1|)/( 1 + max (ei,ei1) ) errtol .
|ei-ei-1| 1+ max (ei,ei-1) errtol .

Further Comments

Arrays are internally allocated by nag_nearest_correlation_h_weight (g02aj). The total size of these arrays is 15 × n + 5 × n × n + max (2 × n × n + 6 × n + 1,120 + 9 × n) 15×n+5×n×n+max (2×n×n+6×n+1,120+9×n)  double elements and 5 × n + 3 5×n+3  integer elements. All allocated memory is freed before return of nag_nearest_correlation_h_weight (g02aj).

Example

function nag_nearest_correlation_h_weight_example
g = [ 2, -1,  0,  0;
     -1,  2, -1,  0;
      0, -1,  2, -1;
      0,  0, -1,  2];
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];
alpha = 0.04;
[g, h, x, iter, norm_p, ifail] = nag_nearest_correlation_h_weight(g, alpha, h);

if (ifail == 0)
  fprintf('\nReturned H Matrix\n');
  disp(h);
  fprintf('Nearest Correlation Matrix\n');
  disp(x);
  fprintf('Number of iterations taken:     %d\n', iter);
  fprintf('Norm value: %26.4f\n', norm_p);
  fprintf('Alpha:      %26.4f\n', alpha);

  [~, w, info] = nag_lapack_dsyev('n', 'u', x);
  fprintf('\nEigenvalues of X\n');
  disp(w');
end
 

Returned H Matrix
         0    1.0000         0         0
    1.0000         0    0.1500    0.1500
         0    0.1500         0         0
         0    0.1500         0         0

Nearest Correlation Matrix
    1.0000   -0.9229    0.7734    0.0026
   -0.9229    1.0000   -0.7843   -0.0000
    0.7734   -0.7843    1.0000   -0.0615
    0.0026   -0.0000   -0.0615    1.0000

Number of iterations taken:     66
Norm value:                     0.1183
Alpha:                          0.0400

Eigenvalues of X
    0.0769    0.2637    1.0031    2.6563


function g02aj_example
g = [ 2, -1,  0,  0;
     -1,  2, -1,  0;
      0, -1,  2, -1;
      0,  0, -1,  2];
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];
alpha = 0.04;
[g, h, x, iter, norm_p, ifail] = g02aj(g, alpha, h);

if (ifail == 0)
  fprintf('\nReturned H Matrix\n');
  disp(h);
  fprintf('Nearest Correlation Matrix\n');
  disp(x);
  fprintf('Number of iterations taken:     %d\n', iter);
  fprintf('Norm value: %26.4f\n', norm_p);
  fprintf('Alpha:      %26.4f\n', alpha);

  [~, w, info] = f08fa('n', 'u', x);
  fprintf('\nEigenvalues of X\n');
  disp(w');
end
 

Returned H Matrix
         0    1.0000         0         0
    1.0000         0    0.1500    0.1500
         0    0.1500         0         0
         0    0.1500         0         0

Nearest Correlation Matrix
    1.0000   -0.9229    0.7734    0.0026
   -0.9229    1.0000   -0.7843   -0.0000
    0.7734   -0.7843    1.0000   -0.0615
    0.0026   -0.0000   -0.0615    1.0000

Number of iterations taken:     66
Norm value:                     0.1183
Alpha:                          0.0400

Eigenvalues of X
    0.0769    0.2637    1.0031    2.6563



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–2013