# naginterfaces.library.correg.corrmat_​nearest_​rank¶

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

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_28.5/flhtml/g02/g02akf.html

Parameters
gfloat, array-like, shape

, the initial matrix.

rankint

, the upper bound for the rank of .

errtolfloat, optional

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

If , then a value of is used.

See Algorithmic Details for further details.

ranktolfloat, optional

The feasibility tolerance for the rank constraint.

If , 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 , then a value of is used.

maxitint, optional

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

If , then a value of is used.

Returns
xfloat, ndarray, shape

, the nearest correlation matrix of rank .

ffloat

The difference between and given by .

rankerrfloat

The rank error of , defined as , given that denote eigenvalues of 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 )

On entry, .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

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

Warns
NagAlgorithmicWarning
(errno )

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

The array returned in may still be of interest.

Notes

corrmat_nearest_rank finds the nearest correlation matrix of maximum prescribed rank to an approximate correlation matrix 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 and . 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