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

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: $dim1 \geq n$
On entry: $G$ , the initial matrix.
On exit: a symmetric matrix $\frac{1}{2} (G + G^{T})$ with the diagonal elements set to unity.

n: Type: System..::..Int32
On entry: $n$ , the order of the matrix $G$ .

Constraint: $n > 0$ .

k: Type: System..::..Int32
On entry: $k$ , the number of factors and columns of $X$ .

Constraint: $0 < k \leq n$ .

errtol: Type: System..::..Double
On entry: the termination tolerance for the projected gradient norm. See references for further details. If $errtol \leq 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 $maxit \leq 0$ , $40000$ is used.

x: Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: $dim1 \geq 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^{T} + diag (X X^{T} - I)‖}_{F}$ .

nrmpgd: Type: System..::..Double%
On exit: the norm of the projected gradient at the final iteration.

ifail: Type: System..::..Int32%
On exit: $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^{T} + diag (I - X X^{T})

, 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

{\min ‖G - X X^{T} + diag (X X^{T} - I)‖}_{F}

such that

{‖x_{i}^{T}‖}_{2} \leq 1

, for

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.

$ifail = 1$: On entry, $k = 〈value〉$ and $n = 〈value〉$ .
Constraint: $0 < k \leq n$ .

On entry, $ldg = 〈value〉$ and $n = 〈value〉$ .
Constraint: $ldg \geq n$ .

On entry, $ldx = 〈value〉$ and $n = 〈value〉$ .
Constraint: $ldx \geq n$ .

On entry, $n = 〈value〉$ .
Constraint: $n > 0$ .

$ifail = 2$: Spectral gradient method fails to converge in $〈value〉$ iterations.

$ifail = - 999$: Dynamic memory allocation failed.

$ifail = -9000$: An error occured, see message report.
$ifail = -6000$: Invalid Parameters $〈value〉$
$ifail = -4000$: Invalid dimension for array $〈value〉$
$ifail = -8000$: Negative dimension for array $〈value〉$
$ifail = -6000$: Invalid Parameters $〈value〉$

Accuracy

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

Parallelism and Performance

None.

Further Comments

Arrays are internally allocated by g02ae. The total size of these arrays is

n \times n + 4 \times n \times k + (nb + 3) \times n + n + 50

real elements and

6 \times n

integer elements. Here

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.