NAG FL Interface
g02abf (corrmat_nearest_bounded)
1
Purpose
g02abf computes the nearest correlation matrix, in the Frobenius norm or weighted Frobenius norm, and optionally with bounds on the eigenvalues, to a given square, input matrix.
2
Specification
Fortran Interface
Subroutine g02abf ( |
g, ldg, n, opt, alpha, w, errtol, maxits, maxit, x, ldx, iter, feval, nrmgrd, ifail) |
Integer, Intent (In) |
:: |
ldg, n, maxits, maxit, ldx |
Integer, Intent (Inout) |
:: |
ifail |
Integer, Intent (Out) |
:: |
iter, feval |
Real (Kind=nag_wp), Intent (In) |
:: |
alpha, errtol |
Real (Kind=nag_wp), Intent (Inout) |
:: |
g(ldg,n), w(n), x(ldx,n) |
Real (Kind=nag_wp), Intent (Out) |
:: |
nrmgrd |
Character (1), Intent (In) |
:: |
opt |
|
C Header Interface
#include <nag.h>
void |
g02abf_ (double g[], const Integer *ldg, const Integer *n, const char *opt, const double *alpha, double w[], const double *errtol, const Integer *maxits, const Integer *maxit, double x[], const Integer *ldx, Integer *iter, Integer *feval, double *nrmgrd, Integer *ifail, const Charlen length_opt) |
|
C++ Header Interface
#include <nag.h> extern "C" {
void |
g02abf_ (double g[], const Integer &ldg, const Integer &n, const char *opt, const double &alpha, double w[], const double &errtol, const Integer &maxits, const Integer &maxit, double x[], const Integer &ldx, Integer &iter, Integer &feval, double &nrmgrd, Integer &ifail, const Charlen length_opt) |
}
|
The routine may be called by the names g02abf or nagf_correg_corrmat_nearest_bounded.
3
Description
Finds the nearest correlation matrix by minimizing where is an approximate correlation matrix.
The norm can either be the Frobenius norm or the weighted Frobenius norm .
You can optionally specify a lower bound on the eigenvalues, , of the computed correlation matrix, forcing the matrix to be positive definite, .
Note that if the weights 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
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:
– Real (Kind=nag_wp) array
Input/Output
-
On entry: , the initial matrix.
On exit: is overwritten.
-
2:
– Integer
Input
-
On entry: the first dimension of the array
g as declared in the (sub)program from which
g02abf is called.
Constraint:
.
-
3:
– Integer
Input
-
On entry: the order of the matrix .
Constraint:
.
-
4:
– Character(1)
Input
-
On entry: indicates the problem to be solved.
- The lower bound problem is solved.
- The weighted norm problem is solved.
- Both problems are solved.
Constraint:
, or .
-
5:
– Real (Kind=nag_wp)
Input
-
On entry: the value of
.
If
,
alpha need not be set.
Constraint:
.
-
6:
– Real (Kind=nag_wp) array
Input/Output
-
On entry: the square roots of the diagonal elements of
, that is the diagonal of
.
If
,
w is not referenced and need not be set.
On exit: if or , the array is scaled so
, for .
Constraint:
, for .
-
7:
– Real (Kind=nag_wp)
Input
-
On entry: the termination tolerance for the Newton iteration. If , is used.
-
8:
– Integer
Input
-
On entry: specifies the maximum number of iterations to be used by the iterative scheme to solve the linear algebraic equations at each Newton step.
If , is used.
-
9:
– Integer
Input
-
On entry: specifies the maximum number of Newton iterations.
If , is used.
-
10:
– Real (Kind=nag_wp) array
Output
-
On exit: contains the nearest correlation matrix.
-
11:
– Integer
Input
-
On entry: the first dimension of the array
x as declared in the (sub)program from which
g02abf is called.
Constraint:
.
-
12:
– Integer
Output
-
On exit: the number of Newton steps taken.
-
13:
– Integer
Output
-
On exit: the number of function evaluations of the dual problem.
-
14:
– Real (Kind=nag_wp)
Output
-
On exit: the norm of the gradient of the last Newton step.
-
15:
– Integer
Input/Output
-
On entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
-
On entry, all elements of
w were not positive.
Constraint:
, for all
.
On entry, .
Constraint: .
On entry, and .
Constraint: .
On entry, and .
Constraint: .
On entry, .
Constraint: .
On entry, the value of
opt is invalid.
Constraint:
,
or
.
-
Newton iteration fails to converge in
iterations. Increase
maxit or check the call to the routine.
-
The
machine precision is limiting convergence. In this instance the returned value of
x may be useful.
-
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.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
The returned accuracy is controlled by
errtol and limited by
machine precision.
8
Parallelism and Performance
g02abf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02abf 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.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
Arrays are internally allocated by g02abf. The total size of these arrays is real elements and integer elements. All allocated memory is freed before return of g02abf.
10
Example
This example finds the nearest correlation matrix to:
weighted by
with minimum eigenvalue
.
10.1
Program Text
10.2
Program Data
10.3
Program Results