NAG FL Interface
g02asf (corrmat_​fixed)

1 Purpose

g02asf computes the nearest correlation matrix, in the Frobenius norm, while fixing elements and optionally with bounds on the eigenvalues, to a given square input matrix.

2 Specification

Fortran Interface
Subroutine g02asf ( g, ldg, n, alpha, h, ldh, errtol, maxit, m, x, ldx, its, fnorm, ifail)
Integer, Intent (In) :: ldg, n, h(ldh,n), ldh, maxit, m, ldx
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: its
Real (Kind=nag_wp), Intent (In) :: alpha, errtol
Real (Kind=nag_wp), Intent (Inout) :: g(ldg,n), x(ldx,n)
Real (Kind=nag_wp), Intent (Out) :: fnorm
C Header Interface
#include <nag.h>
void  g02asf_ (double g[], const Integer *ldg, const Integer *n, const double *alpha, const Integer h[], const Integer *ldh, const double *errtol, const Integer *maxit, const Integer *m, double x[], const Integer *ldx, Integer *its, double *fnorm, Integer *ifail)
The routine may be called by the names g02asf or nagf_correg_corrmat_fixed.

3 Description

g02asf finds the nearest correlation matrix, X, to a matrix, G, in the Frobenius norm. It uses an alternating projections algorithm with Anderson acceleration. Elements in the input matrix can be fixed by supplying the value 1 in the corresponding element of the matrix H. However, note that the algorithm may fail to converge if the fixed elements do not form part of a valid correlation matrix. You can optionally specify a lower bound, α, on the eigenvalues of the computed correlation matrix, forcing the matrix to be positive definite with 0α<1.

4 References

Anderson D G (1965) Iterative Procedures for Nonlinear Integral Equations J. Assoc. Comput. Mach. 12 547–560
Higham N J and Strabić N (2016) Anderson acceleration of the alternating projections method for computing the nearest correlation matrix Numer. Algor. 72 1021–1042

5 Arguments

1: gldgn Real (Kind=nag_wp) array Input/Output
On entry: G~, the initial matrix.
On exit: the symmetric matrix G=12G~+G~T with the diagonal elements set to 1.0.
2: ldg Integer Input
On entry: the first dimension of the array g as declared in the (sub)program from which g02asf is called.
Constraint: ldgn.
3: n Integer Input
On entry: the order of the matrix G.
Constraint: n>0.
4: alpha Real (Kind=nag_wp) Input
On entry: the value of α.
If alpha<0.0, a value of 0.0 is used.
Constraint: alpha<1.0.
5: hldhn Integer array Input
On entry: the symmetric matrix H. If an element of H is 1 then the corresponding element in G is fixed in the output X. Only the strictly lower triangular part of H need be set.
6: ldh Integer Input
On entry: the first dimension of the array h as declared in the (sub)program from which g02asf is called.
Constraint: ldhn.
7: errtol Real (Kind=nag_wp) Input
On entry: the termination tolerance for the iteration.
If errtol0.0, machine precision is used. See Section 7 for further details.
8: maxit Integer Input
On entry: specifies the maximum number of iterations.
If maxit0, a value of 200 is used.
9: m Integer Input
On entry: the number of previous iterates to use in the Anderson acceleration. If m=0, Anderson acceleration is not used. See Section 7 for further details.
If m<0, a value of 4 is used.
Constraint: mn×n.
10: xldxn Real (Kind=nag_wp) array Output
On exit: contains the matrix X.
11: ldx Integer Input
On entry: the first dimension of the array x as declared in the (sub)program from which g02asf is called.
Constraint: ldxn.
12: its Integer Output
On exit: the number of iterations taken.
13: fnorm Real (Kind=nag_wp) Output
On exit: the value of G-XF after the final iteration.
14: ifail Integer Input/Output
On entry: ifail must be set to 0, -1 or 1. 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 -1 or 1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry ifail=0 or -1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
On entry, n=value.
Constraint: n>0.
ifail=2
On entry, ldg=value and n=value.
Constraint: ldgn.
ifail=3
On entry, ldh=value and n=value.
Constraint: ldhn.
ifail=4
On entry, alpha=value.
Constraint: alpha<1.0.
ifail=5
On entry, m=value and n=value.
Constraint: mn×n.
ifail=6
On entry, ldx=value and n=value.
Constraint: ldxn.
ifail=7
Routine failed to converge in value iterations.
A solution may not exist, however, try increasing maxit.
ifail=8
Failure during Anderson acceleration.
Consider setting m=0 and recomputing.
ifail=9
The fixed element Gij, lies outside the interval -1,1, for i=value and j=value.
ifail=-99
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.
ifail=-399
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.
ifail=-999
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

Alternating projections is an iterative process where at each iteration the new iterate, Xk, can be improved by using Anderson acceleration to reduce the overall number of iterations. The alternating projections algorithm terminates at the kth iteration when
Xk - Yk F Xk F errtol  
where Yk is the result of the first of two projections computed at each step.
Without Anderson acceleration this algorithm is guaranteed to converge. There is no theoretical guarantee of convergence of Anderson acceleration and therefore, when it is used, no guarantee of convergence of g02asf. However, in practice it can be seen to significantly reduce the number of alternating projection iterations. Anderson acceleration is not used when m is set to zero. See c05mdf and Higham and Strabić (2016) and Anderson (1965) for further information.

8 Parallelism and Performance

g02asf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g02asf 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.

9 Further Comments

Arrays are internally allocated by g02asf. The total size of these arrays does not exceed 12×n2 real elements. All allocated memory is freed before return of g02asf.

10 Example

This example finds the nearest correlation matrix, X, to the input, G, whilst fixing two diagonal blocks as given by H. The minimum eigenvalue of X is stipulated to be 0.04.
G = 1.0000 -0.0991 0.5665 -0.5653 -0.3441 -0.0991 1.0000 -0.4273 0.8474 0.4975 0.5665 -0.4273 1.0000 -0.1837 -0.0585 -0.5653 0.8474 -0.1837 1.0000 -0.2713 -0.3441 0.4975 -0.0585 -0.2713 1.0000  
and
H = 1 1 0 0 0 1 1 0 0 0 0 0 1 0 0 0 0 0 1 1 0 0 0 1 1 .  
Only the strictly lower half of H is supplied in the example.

10.1 Program Text

Program Text (g02asfe.f90)

10.2 Program Data

Program Data (g02asfe.d)

10.3 Program Results

Program Results (g02asfe.r)