NAG Toolbox: nag_correg_corrmat_nearest_bounded (g02ab)

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.

2:     $\mathrm{opt}$ – string (length ≥ 1)

Indicates the problem to be solved.

$\mathbf{opt}=\text{'A'}$

The lower bound problem is solved.

$\mathbf{opt}=\text{'W'}$

The weighted norm problem is solved.

$\mathbf{opt}=\text{'B'}$

Both problems are solved.

Constraint: $\mathbf{opt}=\text{'A'}$, $\text{'W'}$ or $\text{'B'}$.

3:     $\mathrm{alpha}$ – double scalar

The value of $\alpha$.

If $\mathbf{opt}=\text{'W'}$, alpha need not be set.

Constraint: $0.0<\mathbf{alpha}<1.0$.

4:     $\mathrm{w}\left(\mathbf{n}\right)$ – double array

The square roots of the diagonal elements of $W$, that is the diagonal of $W^{\frac{1}{2}}$.

If $\mathbf{opt}=\text{'A'}$, w is not referenced and need not be set.

Constraint: $\mathbf{w}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,n$.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the array w and 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 order 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$ 

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\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

2:     $\mathrm{w}\left(\mathbf{n}\right)$ – double array

If $\mathbf{opt}=\text{'W'}$ or $\text{'B'}$, the array is scaled so $0<\mathbf{w}\left(\mathit{i}\right)\le 1$, for $\mathit{i}=1,2,\dots ,n$.

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

Contains the nearest correlation matrix.

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

The number of Newton steps taken.

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

The number of function evaluations of the dual problem.

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

The norm of the gradient of the last Newton step.

7:     $\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: $0.0<\mathbf{alpha}<1.0$.

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

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

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

On entry, all elements of w were not positive.

On entry, $\mathbf{opt}\ne \text{'A'}$, $\text{'W'}$ or $\text{'B'}$.

   $\mathbf{ifail}=2$

Newton iteration fails to converge in $\_$ iterations. Increase maxit or check the call to the function.

W  $\mathbf{ifail}=3$

The machine precision is limiting convergence. In this instance the returned value of x may be useful.

W  $\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: g02ab_example

function g02ab_example


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

opt = 'b';
alpha = 0.02;
g = [2, -1,  0,  0;
    -1,  2, -1,  0;
     0, -1,  2, -1;
     0,  0, -1,  2];
w = [100, 20, 20, 20];

% Calculate nearest correlation matrix
[g, w, x, iter, feval, nrmgrd, ifail] = ...
  g02ab(g, opt, alpha, w);

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);
fprintf('\n\n Alpha: %30.3f\n', alpha);

[x, eig, info] = f08fa('n', 'u', x);
fprintf('\n Eigenvalues of x:\n');
disp(transpose(eig));

g02ab example results


 Nearest Correlation Matrix:
    1.0000   -0.9187    0.0257    0.0086
   -0.9187    1.0000   -0.3008    0.2270
    0.0257   -0.3008    1.0000   -0.8859
    0.0086    0.2270   -0.8859    1.0000


 Number of Newton steps taken:   5
 Number of function evaluations: 6


 Alpha:                          0.020

 Eigenvalues of x:
    0.0392    0.1183    1.6515    2.1910