Computes the singular value decomposition of a complex matrix.
A — Complex NRA by NCA matrix whose singular value decomposition is to be computed. (Input)
IPATH — Integer flag used to control the
computation of the singular vectors. (Input)
IPATH has the decimal
expansion IJ
such that:
I=0
means do not compute the left singular vectors;
I=1
means return the NCA
left singular vectors in U;
I=2 means return only the
min(NRA,
NCA)
left singular vectors in U;
J=0
means do not compute the right singular vectors;
J=1
means return the right singular vectors in V.
For example, IPATH = 20 means I = 2 and J = 0.
S — Complex vector of length min(NRA + 1, NCA) containing the singular values of A in descending order of magnitude in the first min(NRA, NCA) positions. (Output)
NRA — Number of rows in the matrix A.
(Input)
Default: NRA = size (A,1).
NCA — Number of columns in the matrix
A.
(Input)
Default: NCA = size (A,2).
LDA — Leading dimension of A exactly as specified
in the dimension statement of the calling program.
(Input)
Default: LDA = size (A,1).
TOL — Real scalar containing the tolerance
used to determine when a singular value is negligible. (Input)
If TOL is
positive, then a singular value SI is considered
negligible if SI
≤ TOL . If TOL is negative, then
a singular value SI is considered
negligible if
SI ≤ ǀTOLǀ*(Infinity norm of
A). In this case
ǀTOLǀ should generally contain an
estimate of the level of relative error in the data.
Default: TOL = 1.0e-5 for
single precision and 1.0d-10 for double precision.
IRANK — Integer scalar containing an estimate of the rank of A. (Output)
U — Complex NRA by NRA if I = 1 or NRA by min(NRA, NCA) if I = 2 matrix
containing the left singular vectors of A.
(Output)
U
will not be referenced if I is equal to zero. If
NRA is less than
or equal to NCA
or IPATH =
2, then U can
share the same storage locations as A.
LDU — Leading dimension of U exactly as specified
in the dimension statement of the calling program.
(Input)
Default: LDU = size (U,1).
V — Complex NCA by NCA matrix containing
the right singular vectors of A.
(Output)
V
will not be referenced if J is equal to zero. If
NCA is less than
or equal to NRA,
then V can share
the same storage locations as A; however U and V cannot both coincide
with A
simultaneously.
LDV — Leading dimension of V exactly as specified
in the dimension statement of the calling program.
(Input)
Default: LDV = size (V,1).
Generic: CALL LSVCR (A, IPATH, S [,…])
Specific: The specific interface names are S_LSVCR and D_LSVCR.
Single: CALL LSVCR (NRA, NCA, A, LDA, IPATH, TOL, IRANK, S, U, LDU, V, LDV)
Double: The double precision name is DLSVCR.
The underlying code of routine LSVCR is based on either LINPACK or LAPACK code depending upon which supporting libraries are used during linking. For a detailed explanation see “Using ScaLAPACK, LAPACK, LINPACK, and EISPACK” in the Introduction section of this manual.
Let n = NRA (the number of rows in A) and let p = NCA (the number of columns in A).For any n × p matrix A there exists an n × n orthogonal matrix U and a p × p orthogonal matrix V such that
where ∑ = diag(σ1, …, σm), and m = min(n, p). The scalars σ1 ≥ σ2 ≥ … ≥ 0 are called the singular values of A. The columns of U are called the left singular vectors of A. The columns of V are called the right singular vectors of A.
The estimated rank of A is the number of σk which are larger than a tolerance η. If τ is the parameter TOL in the program, then
1. Workspace may be explicitly provided, if desired, by use of L2VCR/DL2VCR. The reference is
CALL L2VCR (NRA, NCA, A, LDA, IPATH, TOL, IRANK, S, U, LDU, V, LDV,
ACOPY, WK)
The additional arguments are as follows:
ACOPY — NRA * NCA complex work array of length for the matrix A. If A is not needed, then A and ACOPY can share the same storage locations.
WK — Complex work vector of length NRA + NCA + max(NRA, NCA) 1.
2. Informational error
Type Code
4 1 Convergence cannot be achieved for all the singular values and their corresponding singular vectors.
3. When NRA is much greater than NCA, it might not be reasonable to store the whole matrix U. In this case IPATH with I = 2 allows a singular value factorization of A to be computed in which only the first NCA columns of U are computed, and in many applications those are all that are needed.
4. Integer Options with Chapter 11 Options Manager
16 This
option uses four values to solve memory bank conflict (access inefficiency)
problems. In routine L2VCR the leading
dimension of ACOPY is increased by
IVAL(3) when
N is a multiple
of IVAL(4). The
values IVAL(3)
and IVAL(4) are
temporarily replaced by IVAL(1) and IVAL(2), respectively, in
LSVCR.
Additional memory allocation for ACOPY and option value
restoration are done automatically in LSVCR. Users directly
calling L2VCR
can allocate additional space for ACOPY and set IVAL(3) and IVAL(4) so that memory
bank conflicts no longer cause inefficiencies. There is no requirement that
users change existing applications that use LSVCR or L2VCR. Default values
for the option are
IVAL(*) = 1, 16, 0, 1.
17 This option has two values that determine if the L1 condition number is to be computed. Routine LSVCR temporarily replaces IVAL(2) by IVAL(1). The routine L2CCG computes the condition number if IVAL(2) = 2. Otherwise L2CCG skips this computation. LSVCR restores the option. Default values for the option are IVAL(*) = 1, 2.
This example computes the singular value decomposition of a 6 × 3 matrix A. The matrices U and V containing the left and right singular vectors, respectively, and the diagonal of ∑, containing singular values, are printed. On some systems, the signs of some of the columns of U and V may be reversed.
USE
IMSL_LIBRARIES
!
Declare variables
PARAMETER (NRA=6, NCA=3, LDA=NRA, LDU=NRA, LDV=NCA)
COMPLEX A(LDA,NCA), U(LDU,NRA), V(LDV,NCA), S(NCA)
DATA A/(1.0,2.0), (3.0,-2.0), (4.0,3.0), (2.0,-1.0), (1.0,-5.0), &
(1.0,2.0), (3.0,2.0), (2.0,-4.0), (-2.0,1.0), (3.0,0.0), &
(2.0,-5.0), (4.0,-2.0), (1.0,-4.0), (1.0,3.0), (1.0,4.0), &
(3.0,-1.0), (2.0,2.0), (2.0,-3.0)/
! Compute all singular vectors
TOL =
AMACH(4)
TOL = 10. * TOL
CALL LSVCR(A, IPATH, S, TOL = TOL, IRANK=IRANK, U=U, V=V)
WRITE (NOUT, *) 'IRANK = ', IRANK
CALL WRCRN ('S', S, 1, NCA, 1)
1 ( 0.1968, 0.2186) ( 0.5011, 0.0217) (-0.2007,-0.1003)
2 ( 0.3443,-0.3542) (-0.2933, 0.0248) ( 0.1155,-0.2338)
3 ( 0.1457, 0.2307) (-0.5424, 0.1381) (-0.4361,-0.4407)
4 ( 0.3016,-0.0844) ( 0.2157, 0.2659) (-0.0523,-0.0894)
5 ( 0.2283,-0.6008) (-0.1325, 0.1433) ( 0.3152,-0.0090)
6 ( 0.2876,-0.0350) ( 0.4377,-0.0400) ( 0.0458,-0.6205)
( 11.77, 0.00) ( 9.30, 0.00) ( 4.99, 0.00)
1 ( 0.6616, 0.0000) (-0.2651, 0.0000) (-0.7014, 0.0000)
2 ( 0.7355, 0.0379) ( 0.3850,-0.0707) ( 0.5482, 0.0624)
3 ( 0.0507,-0.1317) ( 0.1724, 0.8642) (-0.0173,-0.4509)
Visual Numerics, Inc. PHONE: 713.784.3131 FAX:713.781.9260 |