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://support.nag.com/numeric/nl/nagdoc_30.2/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 bywhere 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