Purpose
=======
LA_GESVD and LA_GESDD compute the singular values and,
optionally, the left and/or right singular vectors from the singular
value decomposition (SVD) of a real or complex m by n matrix A. The
SVD of A is written
A = U * SIGMA * V^H
where SIGMA is an m by n matrix which is zero except for its
min(m, n) diagonal elements, U is an m by m orthogonal (unitary)
matrix, and V is an n by n orthogonal (unitary) matrix. The diagonal
elements of SIGMA , i.e., the values
sigma(i)= SIGMA(i,i), i = 1, 2,..., min(m, n)
are the singular values of A; they are real and non-negative, and are
returned in descending order. The first min(m, n) columns of U and V
are the left and right singular vectors of A, respectively.
LA_GESDD solves the same problem as LA_GESVD but uses a divide and
conquer method if singular vectors are desired. For large matrices it
is usually much faster than LA_GESVD when singular vectors are
desired, but uses more workspace.
Note: The routine returns V^H , not V .
========
SUBROUTINE LA_GESVD / LA_GESDD( A, S, U=u, VT=vt, &
WW=ww, JOB=job, INFO=info )
(), INTENT(INOUT) :: A(:,:)
REAL(), INTENT(OUT) :: S(:)
(), INTENT(OUT), OPTIONAL :: U(:,:), VT(:,:)
REAL(), INTENT(OUT), OPTIONAL :: WW(:)
CHARACTER(LEN=1), INTENT(IN), OPTIONAL :: JOB
INTEGER, INTENT(OUT), OPTIONAL :: INFO
where
::= REAL | COMPLEX
::= KIND(1.0) | KIND(1.0D0)
Arguments
=========
A (input/output) REAL or COMPLEX array, shape (:, :) with
size(A, 1) = m and size(A, 2) = n.
On entry, the matrix A.
On exit, if JOB = 'U' and U is not present, then A is
overwritten with the first min(m, n) columns of U (the left
singular vectors, stored columnwise).
If JOB = 'V' and VT is not present, then A is overwritten with
the first min(m, n) rows of V^H (the right singular vectors,
stored rowwise).
In all cases the original contents of A are destroyed.
S (output) REAL array, shape (:) with size(S) = min(m, n).
The singular values of A, sorted so that S(i) >= S(i+1).
U Optional (output) REAL or COMPLEX array, shape (:, :) with
size(U, 1) = m and size(U, 2) = m or min(m, n).
If size(U, 2) = m, U contains the m by m matrix U .
If size(U; 2) = min(m, n), U contains the first min(m, n)
columns of U (the left singular vectors, stored columnwise).
VT Optional (output) REAL or COMPLEX array, shape (:, :) with
size(VT, 1) = n or min(m, n) and size(VT, 2) = n.
If size(VT, 1) = n , VT contains the n by n matrix V^H .
If size(VT, 1) = min(m, n), VT contains the first min(m, n)
rows of V^H (the right singular vectors, stored rowwise).
WW Optional (output) REAL array, shape (:) with size(WW) =
min(m, n) - 1
If INFO > 0, WW contains the unconverged superdiagonal elements
of an upper bidiagonal matrix B whose diagonal is in SIGMA (not
necessarily sorted). B has the same singular values as A.
Note: WW is a dummy argument for LA_GESDD.
JOB Optional (input) CHARACTER(LEN=1).
= 'N': neither columns of U nor rows of V^H are returned in
array A.
= 'U': if U is not present, the first min(m, n) columns of U
(the left singular vectors) are returned in array A;
= 'V': if VT is not present, the first min(m, n) rows of V^H
(the right singular vectors) are returned in array A;
Default value: 'N'.
INFO Optional (output) INTEGER.
= 0: successful exit.
< 0: if INFO = -i, the i-th argument had an illegal value.
> 0: The algorithm did not converge.
If INFO is not present and an error occurs, then the program is
terminated with an error message.