naginterfaces.library.correg.corrmat_​nearest_​rank

naginterfaces.library.correg.corrmat_nearest_rank(g, rank, errtol=0.0, ranktol=0.0, maxits=0, maxit=0)

corrmat_nearest_rank computes the nearest correlation matrix of maximum prescribed rank, in the Frobenius norm, to a given square, input matrix.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/g02/g02akf.html

Parameters

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

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

rankint

$r$, the upper bound for the rank of $X$.

errtolfloat, optional

The termination tolerance for the convergence measure of the objective function value.

If $errtol\le 0.0$, then a value of $1.0e-5$ is used.

See Algorithmic Details for further details.

ranktolfloat, optional

The feasibility tolerance for the rank constraint.

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

See Algorithmic Details for further details.

maxitsint, optional

Specifies the maximum number of iterations used for the majorization approach to solve penalized problems at each level of penalty parameter.

If $maxits\le 0$, then a value of $100$ is used.

maxitint, optional

Specifies the maximum number of iterations for the penalty method, i.e., the maximum level of penalty parameter.

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

Returns

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

$X$, the nearest correlation matrix of rank $r$.

ffloat

The difference between $X$ and $G$ given by $\frac{1}{2}{\parallel X-G\parallel }_F^2$.

rankerrfloat

The rank error of $X$, defined as ${\sum }_{i=r+1}^n\left({\lambda }_i\right)$, given that ${\lambda }_i$ denote eigenvalues of $X$ sorted in non-increasing order.

nsubint

The total number of majorized problems that have been solved, i.e., the total number of calls for corrmat_nearest().

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $4$)

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

Constraint: $0<rank\le n$.

(errno $5$)

Majorized penalty approach fails to converge in $maxit$ level of penalty iterations.

Warns

NagAlgorithmicWarning

(errno $6$)

Convergence is limited by machine precision. The objective function value or rank is decreasing very slowly.

The array returned in $x$ may still be of interest.

Notes

corrmat_nearest_rank finds the nearest correlation matrix $X$ of maximum prescribed rank $r$ to an approximate correlation matrix $G$ in the Frobenius norm.

The solver is based on the Majorized Penalty Approach (MPA) proposed by Gao and Sun (2010). One of the key elements in this type of method is that the subproblems are similar to the nearest correlation matrix problem without rank constraint, and can be solved efficiently by corrmat_nearest(). The total number of subproblems solved is controlled by the arguments $maxit$ and $maxits$. The algorithm behaviour and solver accuracy can be modified by these and other input arguments. The default values for these arguments are chosen to work well in the general case but it is recommended that you tune them to your particular problem. For a detailed description of the algorithm see Algorithmic Details.

References

Bai, S, Qi, H–D and Xiu, N, 2015, Constrained best Euclidean distance embedding on a sphere: A matrix optimization approach, SIAM J. Optim. (25(1)), 439–467

Gao, Y and Sun, D, 2010, A majorized penalty approach for calibrating rank constrained correlation matrix problems, Technical report, Department of Mathematics, National University of Singapore

Qi, H–D and Yuan, X, 2014, Computing the nearest Euclidean distance matrix with low embedding dimensions, Mathematical Programming (147(1–2)), 351–389