NAG Library Routine Document
f02wgf (real_gen_partialsvd)
1
Purpose
f02wgf returns leading terms in the singular value decomposition (SVD) of a real general matrix and computes the corresponding left and right singular vectors.
2
Specification
Fortran Interface
Subroutine f02wgf ( |
m, n, k, ncv, av, nconv, sigma, u, ldu, v, ldv, resid, iuser, ruser, ifail) |
Integer, Intent (In) | :: | m, n, k, ncv, ldu, ldv | Integer, Intent (Inout) | :: | iuser(*), ifail | Integer, Intent (Out) | :: | nconv | Real (Kind=nag_wp), Intent (Inout) | :: | u(ldu,ncv), v(ldv,ncv), ruser(*) | Real (Kind=nag_wp), Intent (Out) | :: | sigma(ncv), resid(ncv) | External | :: | av |
|
C Header Interface
#include <nagmk26.h>
void |
f02wgf_ (const Integer *m, const Integer *n, const Integer *k, const Integer *ncv, void (NAG_CALL *av)(Integer *iflag, const Integer *m, const Integer *n, const double x[], double ax[], Integer iuser[], double ruser[]), Integer *nconv, double sigma[], double u[], const Integer *ldu, double v[], const Integer *ldv, double resid[], Integer iuser[], double ruser[], Integer *ifail) |
|
3
Description
f02wgf computes a few,
, of the largest singular values and corresponding vectors of an
by
matrix
. The value of
should be small relative to
and
, for example
. The full singular value decomposition (SVD) of an
by
matrix
is given by
where
and
are orthogonal and
is an
by
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 routines from
Chapter F12. You should read the
F12 Chapter Introduction for full details of the method used here.
The real matrix
is not explicitly supplied to
f02wgf. Instead, you are required to supply a routine,
av, that must calculate one of the requested matrix-vector products
or
for a given real vector
(of length
or
respectively).
4
References
Wilkinson J H (1978) Singular Value Decomposition – Basic Aspects Numerical Software – Needs and Availability (ed D A H Jacobs) Academic Press
5
Arguments
- 1: – IntegerInput
-
On entry: , the number of rows of the matrix .
Constraint:
.
If , an immediate return is effected.
- 2: – IntegerInput
-
On entry: , the number of columns of the matrix .
Constraint:
.
If , an immediate return is effected.
- 3: – IntegerInput
-
On entry: , the number of singular values to be computed.
Constraint:
.
- 4: – IntegerInput
-
On entry: the dimension of the arrays
sigma and
resid and the second dimension of the arrays
u and
v as declared in the (sub)program from which
f02wgf is called.
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
ncv relative to
k. However, it is recommended that
. If many problems of the same type are to be solved, you should experiment with varying
ncv while keeping
k 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.
Constraint:
.
- 5: – Subroutine, supplied by the user.External Procedure
-
av must return the vector result of the matrix-vector product
or
, as indicated by the input value of
iflag, for the given vector
.
av is called from
f02wgf with the argument
iuser and
ruser as supplied to
f02wgf. You are free to use these arrays to supply information to
av.
The specification of
av is:
Fortran Interface
Integer, Intent (In) | :: | m, n | Integer, Intent (Inout) | :: | iflag, iuser(*) | Real (Kind=nag_wp), Intent (In) | :: | x(*) | Real (Kind=nag_wp), Intent (Inout) | :: | ax(*), ruser(*) |
|
C Header Interface
#include <nagmk26.h>
void |
av (Integer *iflag, const Integer *m, const Integer *n, const double x[], double ax[], Integer iuser[], double ruser[]) |
|
- 1: – IntegerInput/Output
-
On entry: if
,
ax must return the
-vector result of the matrix-vector product
.
If
,
ax must return the
-vector result of the matrix-vector product
.
On exit: may be used as a flag to indicate a failure in the computation of
or
. If
iflag is negative on exit from
av,
f02wgf will exit immediately with
ifail set to
iflag.
- 2: – IntegerInput
-
On entry: the number of rows of the matrix .
- 3: – IntegerInput
-
On entry: the number of columns of the matrix .
- 4: – Real (Kind=nag_wp) arrayInput
-
On entry: the vector to be pre-multiplied by the matrix or .
- 5: – Real (Kind=nag_wp) arrayOutput
-
On exit: if
, contains the
-vector result of the matrix-vector product
.
If , contains the -vector result of the matrix-vector product .
- 6: – Integer arrayUser Workspace
- 7: – Real (Kind=nag_wp) arrayUser Workspace
-
av is called with the arguments
iuser and
ruser as supplied to
f02wgf. You should use the arrays
iuser and
ruser to supply information to
av.
av must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
f02wgf is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: av should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by
f02wgf. If your code inadvertently
does return any NaNs or infinities,
f02wgf is likely to produce unexpected results.
- 6: – IntegerOutput
-
On exit: the number of converged singular values found.
- 7: – Real (Kind=nag_wp) arrayOutput
-
On exit: the
nconv converged singular values are stored in the first
nconv elements of
sigma.
- 8: – Real (Kind=nag_wp) arrayOutput
-
On exit: the left singular vectors corresponding to the singular values stored in
sigma.
The
th element of the th left singular vector is stored in , for and .
- 9: – IntegerInput
-
On entry: the first dimension of the array
u as declared in the (sub)program from which
f02wgf is called.
Constraint:
.
- 10: – Real (Kind=nag_wp) arrayOutput
-
On exit: the right singular vectors corresponding to the singular values stored in
sigma.
The
th element of the th right singular vector is stored in , for and .
- 11: – IntegerInput
-
On entry: the first dimension of the array
v as declared in the (sub)program from which
f02wgf is called.
Constraint:
.
- 12: – Real (Kind=nag_wp) arrayOutput
-
On exit: the residual , for , or , for , for each of the converged singular values and corresponding left and right singular vectors and .
- 13: – Integer arrayUser Workspace
- 14: – Real (Kind=nag_wp) arrayUser Workspace
-
iuser and
ruser are not used by
f02wgf, but are passed directly to
av and may be used to pass information to this routine.
- 15: – IntegerInput/Output
-
On entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
f02wgf returns with if at least singular values have converged and the corresponding left and right singular vectors have been computed.
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
-
On entry, .
Constraint: .
-
On entry, .
Constraint: .
-
On entry, .
Constraint: .
-
On entry, , , and .
Constraint: .
-
On entry, and .
Constraint: .
-
On entry, and .
Constraint: .
-
The maximum number of iterations has been reached. The maximum number of iterations . The number of converged eigenvalues .
-
No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.
-
Could not build a full Lanczos factorization.
-
The number of eigenvalues found to sufficient accuracy is zero.
-
An error occurred during an internal call. Consider increasing the size of
ncv relative to
k.
-
On output from user-defined routine
av,
iflag was set to a negative value,
.
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
See
Section 2.14.2 in the F08 Chapter Introduction.
8
Parallelism and Performance
f02wgf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f02wgf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
None.
10
Example
This example finds the four largest singular values (
) and corresponding right and left singular vectors for the matrix
, where
is the
by
real matrix derived from the simplest finite difference discretization of the two-dimensional kernel
where
10.1
Program Text
Program Text (f02wgfe.f90)
10.2
Program Data
Program Data (f02wgfe.d)
10.3
Program Results
Program Results (f02wgfe.r)