naginterfaces.library.correg.corrmat_​fixed

naginterfaces.library.correg.corrmat_fixed(g, alpha, h, m, errtol=0.0, maxit=0)

corrmat_fixed 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.

For full information please refer to the NAG Library document for g02as

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g02/g02asf.html

Parameters

gfloat, array-like, shape $(n,n)$

$\tilde{G}$, the initial matrix.

alphafloat

The value of $\alpha$.

If $alpha<0.0$, a value of $0.0$ is used.

hint, array-like, shape $(n,n)$

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.

mint

The number of previous iterates to use in the Anderson acceleration. If $m=0$, Anderson acceleration is not used. See Accuracy for further details.

If $m<0$, a value of $4$ is used.

errtolfloat, optional

The termination tolerance for the iteration.

If $errtol\le 0.0$, $\sqrt{\text{machine precision}}$ is used.

See Accuracy for further details.

maxitint, optional

Specifies the maximum number of iterations.

If $maxit\le 0$, a value of $200$ is used.

Returns

xfloat, ndarray, shape $(n,n)$

Contains the matrix $X$.

itsint

The number of iterations taken.

fnormfloat

The value of ${\parallel G-X\parallel }_F$ after the final iteration.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $4$)

On entry, $alpha=⟨value⟩$.

Constraint: $alpha<1.0$.

(errno $5$)

On entry, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $m\le n\times n$.

(errno $7$)

Function failed to converge in $⟨value⟩$ iterations.

A solution may not exist, however, try increasing $maxit$.

(errno $8$)

Failure during Anderson acceleration.

Consider setting $m=0$ and recomputing.

(errno $9$)

The fixed element $G_{ij}$, lies outside the interval $[-1,1]$, for $i=⟨value⟩$ and $j=⟨value⟩$.

Notes

corrmat_fixed 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, $\alpha$, on the eigenvalues of the computed correlation matrix, forcing the matrix to be positive definite with $0\le \alpha <1$.

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