﻿ g02ae Method
g02ae computes the factor loading matrix associated with the nearest correlation matrix with $k$-factor structure, in the Frobenius norm, to a given square, input matrix.

# Syntax

C#
```public static void g02ae(
double[,] g,
int n,
int k,
double errtol,
int maxit,
double[,] x,
out int iter,
out int feval,
out double nrmpgd,
out int ifail
)```
Visual Basic
```Public Shared Sub g02ae ( _
g As Double(,), _
n As Integer, _
k As Integer, _
errtol As Double, _
maxit As Integer, _
x As Double(,), _
<OutAttribute> ByRef iter As Integer, _
<OutAttribute> ByRef feval As Integer, _
<OutAttribute> ByRef nrmpgd As Double, _
<OutAttribute> ByRef ifail As Integer _
)```
Visual C++
```public:
static void g02ae(
array<double,2>^ g,
int n,
int k,
double errtol,
int maxit,
array<double,2>^ x,
[OutAttribute] int% iter,
[OutAttribute] int% feval,
[OutAttribute] double% nrmpgd,
[OutAttribute] int% ifail
)```
F#
```static member g02ae :
g : float[,] *
n : int *
k : int *
errtol : float *
maxit : int *
x : float[,] *
iter : int byref *
feval : int byref *
nrmpgd : float byref *
ifail : int byref -> unit
```

#### Parameters

g
Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: $\mathrm{dim1}\ge {\mathbf{n}}$
On entry: $G$, the initial matrix.
On exit: a symmetric matrix $\frac{1}{2}\left(G+{G}^{\mathrm{T}}\right)$ with the diagonal elements set to unity.
n
Type: System..::..Int32
On entry: $n$, the order of the matrix $G$.
Constraint: ${\mathbf{n}}>0$.
k
Type: System..::..Int32
On entry: $k$, the number of factors and columns of $X$.
Constraint: $0<{\mathbf{k}}\le {\mathbf{n}}$.
errtol
Type: System..::..Double
On entry: the termination tolerance for the projected gradient norm. See references for further details. If ${\mathbf{errtol}}\le 0.0$ then $0.01$ is used. This is often a suitable default value.
maxit
Type: System..::..Int32
On entry: specifies the maximum number of iterations in the spectral projected gradient method.
If ${\mathbf{maxit}}\le 0$, $40000$ is used.
x
Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: $\mathrm{dim1}\ge {\mathbf{n}}$
On exit: contains the matrix $X$.
iter
Type: System..::..Int32%
On exit: the number of steps taken in the spectral projected gradient method.
feval
Type: System..::..Int32%
On exit: the number of evaluations of ${‖G-X{X}^{\mathrm{T}}+\mathrm{diag}\left(X{X}^{\mathrm{T}}-I\right)‖}_{F}$.
nrmpgd
Type: System..::..Double%
On exit: the norm of the projected gradient at the final iteration.
ifail
Type: System..::..Int32%
On exit: ${\mathbf{ifail}}={0}$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

# Description

A correlation matrix $C$ with $k$-factor structure may be characterised as a real square matrix that is symmetric, has a unit diagonal, is positive semidefinite and can be written as $C=X{X}^{\mathrm{T}}+\mathrm{diag}\left(I-X{X}^{\mathrm{T}}\right)$, where $I$ is the identity matrix and $X$ has $n$ rows and $k$ columns. $X$ is often referred to as the factor loading matrix.
g02ae applies a spectral projected gradient method to the modified problem ${\mathrm{min}\phantom{\rule{0.25em}{0ex}} ‖G-X{X}^{\mathrm{T}}+\mathrm{diag}\left(X{X}^{\mathrm{T}}-I\right)‖}_{F}$ such that ${‖{x}_{\mathit{i}}^{\mathrm{T}}‖}_{2}\le 1$, for $\mathit{i}=1,2,\dots ,n$, where ${x}_{i}$ is the $i$th row of the factor loading matrix, $X$, which gives us the solution.

# References

Birgin E G, Martínez J M and Raydan M (2001) Algorithm 813: SPG–software for convex-constrained optimization ACM Trans. Math. Software 27 340–349
Borsdorf R, Higham N J and Raydan M (2010) Computing a nearest correlation matrix with factor structure. SIAM J. Matrix Anal. Appl. 31(5) 2603–2622

# Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDG, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{k}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: $0<{\mathbf{k}}\le {\mathbf{n}}$.
On entry, ${\mathbf{ldg}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ldg}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{ldx}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}>0$.
${\mathbf{ifail}}=2$
Spectral gradient method fails to converge in $〈\mathit{\text{value}}〉$ iterations.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
${\mathbf{ifail}}=-9000$
An error occured, see message report.
${\mathbf{ifail}}=-6000$
Invalid Parameters $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-4000$
Invalid dimension for array $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-8000$
Negative dimension for array $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-6000$
Invalid Parameters $〈\mathit{\text{value}}〉$

# Accuracy

The returned accuracy is controlled by errtol and limited by machine precision.

# Parallelism and Performance

None.

Arrays are internally allocated by g02ae. The total size of these arrays is ${\mathbf{n}}×{\mathbf{n}}+4×{\mathbf{n}}×{\mathbf{k}}+\left(\mathit{nb}+3\right)×{\mathbf{n}}+{\mathbf{n}}+50$ real elements and $6×{\mathbf{n}}$ integer elements. Here $\mathit{nb}$ is the block size required for optimal performance by (F08FEF not in this release) (F08FGF not in this release) which are called internally. All allocated memory is freed before return of g02ae.
See (G03CAF not in this release) for constructing the factor loading matrix from a known correlation matrix.

# Example

This example finds the nearest correlation matrix with $k=2$ factor structure to:
 $G=2-100-12-100-12-100-12$

Example program (C#): g02aee.cs

Example program data: g02aee.d

Example program results: g02aee.r