naginterfaces.library.eigen.real_​gen_​partialsvd

naginterfaces.library.eigen.real_gen_partialsvd(m, n, k, ncv, av, data=None, io_manager=None)[source]

real_gen_partialsvd returns leading terms in the singular value decomposition (SVD) of a real general matrix and computes the corresponding left and right singular vectors.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f02/f02wgf.html

Parameters
mint

, the number of rows of the matrix .

nint

, the number of columns of the matrix .

kint

, the number of singular values to be computed.

ncvint

This is the number of Lanczos basis vectors to use during the computation of the largest eigenvalues of () or ().

At present there is no a priori analysis to guide the selection of relative to .

However, it is recommended that .

If many problems of the same type are to be solved, you should experiment with varying while keeping fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the internal storage required to maintain the orthogonal basis vectors.

The optimal ‘cross-over’ with respect to CPU time is problem dependent and must be determined empirically.

avcallable (iflag, ax) = av(iflag, m, n, x, data=None)

must return the vector result of the matrix-vector product or , as indicated by the input value of , for the given vector .

Parameters
iflagint

If , must return the -vector result of the matrix-vector product .

If , must return the -vector result of the matrix-vector product .

mint

The number of rows of the matrix .

nint

The number of columns of the matrix .

xfloat, ndarray, shape

The vector to be pre-multiplied by the matrix or .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
iflagint

May be used as a flag to indicate a failure in the computation of or . If is negative on exit from , real_gen_partialsvd will exit immediately with set to .

axfloat, array-like, shape

If , contains the -vector result of the matrix-vector product .

If , contains the -vector result of the matrix-vector product .

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns
nconvint

The number of converged singular values found.

sigmafloat, ndarray, shape

The converged singular values are stored in the first elements of .

ufloat, ndarray, shape

The left singular vectors corresponding to the singular values stored in .

The th element of the th left singular vector is stored in , for , for .

vfloat, ndarray, shape

The right singular vectors corresponding to the singular values stored in .

The th element of the th right singular vector is stored in , for , for .

residfloat, ndarray, shape

The residual , for , or , for , for each of the converged singular values and corresponding left and right singular vectors and .

Raises
NagValueError
(errno )

On output from user-defined function , was set to a negative value, .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, , , and .

Constraint: .

(errno )

The maximum number of iterations has been reached. The maximum number of iterations . The number of converged eigenvalues .

(errno )

No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.

(errno )

Could not build a full Lanczos factorization.

(errno )

The number of eigenvalues found to sufficient accuracy is zero.

(errno )

An error occurred during an internal call. Consider increasing the size of relative to .

Notes

real_gen_partialsvd computes a few, , of the largest singular values and corresponding vectors of an matrix . The value of should be small relative to and , for example . The full singular value decomposition (SVD) of an matrix is given by

where and are orthogonal and is an diagonal matrix with real diagonal elements, , such that

The are the singular values of and the first columns of and are the left and right singular vectors of .

If , denote the leading columns of and respectively, and if denotes the leading principal submatrix of , then

is the best rank- approximation to in both the -norm and the Frobenius norm.

The singular values and singular vectors satisfy

where and are the th columns of and respectively.

Thus, for , the largest singular values and corresponding right singular vectors are computed by finding eigenvalues and eigenvectors for the symmetric matrix . For , the largest singular values and corresponding left singular vectors are computed by finding eigenvalues and eigenvectors for the symmetric matrix . These eigenvalues and eigenvectors are found using functions from submodule sparseig. You should read the F12 Introduction for full details of the method used here.

The real matrix is not explicitly supplied to real_gen_partialsvd. Instead, you are required to supply a function, , that must calculate one of the requested matrix-vector products or for a given real vector (of length or respectively).

References

Wilkinson, J H, 1978, Singular Value Decomposition – Basic Aspects, Numerical Software – Needs and Availability, (ed D A H Jacobs), Academic Press