NAG Toolbox: nag_correg_corrmat_nearest (g02aa)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{g}\left(\mathit{ldg},\mathbf{n}\right)$ – double array

ldg, the first dimension of the array, must satisfy the constraint $\mathit{ldg}\ge \mathbf{n}$.

$G$, the initial matrix.

Optional Input Parameters

1:     $\mathrm{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: $\mathbf{n}>0$.

2:     $\mathrm{errtol}$ – double scalar

Default: $0.0$ 

The termination tolerance for the Newton iteration. If $\mathbf{errtol}\le 0.0$ then $\mathbf{n}\times \sqrt{\mathit{machine precision}}$ is used.

3:     $\mathrm{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 $\mathbf{maxits}\le 0$, $2\times \mathbf{n}$ is used.

4:     $\mathrm{maxit}$ – int64int32nag_int scalar

Default: $0$ 

Specifies the maximum number of Newton iterations.

If $\mathbf{maxit}\le 0$, $200$ is used.

Output Parameters

1:     $\mathrm{g}\left(\mathit{ldg},\mathbf{n}\right)$ – double array

A symmetric matrix $\frac{1}{2}\left(G+G^{\mathrm{T}}\right)$ with the diagonal set to $I$.

2:     $\mathrm{x}\left(\mathit{ldx},\mathbf{n}\right)$ – double array

Contains the nearest correlation matrix.

3:     $\mathrm{iter}$ – int64int32nag_int scalar

The number of Newton steps taken.

4:     $\mathrm{feval}$ – int64int32nag_int scalar

The number of function evaluations of the dual problem.

5:     $\mathrm{nrmgrd}$ – double scalar

The norm of the gradient of the last Newton step.

6:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

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

   $\mathbf{ifail}=1$

Constraint: $\mathit{ldg}\ge \mathbf{n}$.

Constraint: $\mathit{ldx}\ge \mathbf{n}$.

Constraint: $\mathbf{n}>0$.

   $\mathbf{ifail}=2$

Newton iteration fails to converge in $\_$ iterations.

W  $\mathbf{ifail}=3$

Machine precision is limiting convergence.
The array returned in x may still be of interest.

   $\mathbf{ifail}=4$

An intermediate eigenproblem could not be solved. This should not occur. Please contact NAG with details of your call.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g02aa_example

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] = ...
  g02aa(g);

fprintf('\n     Nearest Correlation Matrix\n');
disp(x);
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);
end

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