LSVCR

Computes the singular value decomposition of a complex matrix.

Required Arguments

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)

Optional Arguments

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 matrix, NRA by NRA if I = 1, or NRA by min(NRA, NCA) if I = 2, containing the left singular vectors of A. (Output)
U will not be referenced if I is equal to zero. If NRA ≤ 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).

FORTRAN 90 Interface

Generic: CALL LSVCR (A, IPATH, S [, …])

Specific: The specific interface names are S_LSVCR and D_LSVCR.

FORTRAN 77 Interface

Single: CALL LSVCR (NRA, NCA, A, LDA, IPATH, TOL, IRANK, S, U, LDU, V, LDV)

Double: The double precision name is DLSVCR.

Description

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

Comments

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	Description
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.

Example

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)

! Set values for A

! A = ( 1+2i 3+2i 1-4i )

! ( 3-2i 2-4i 1+3i )

! ( 4+3i -2+1i 1+4i )

! ( 2-1i 3+0i 3-1i )

! ( 1-5i 2-5i 2+2i )

! ( 1+2i 4-2i 2-3i )

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

IPATH = 11

TOL = AMACH(4)

TOL = 10. * TOL

CALL LSVCR(A, IPATH, S, TOL = TOL, IRANK=IRANK, U=U, V=V)

! Print results

CALL UMACH (2, NOUT)

WRITE (NOUT, *) ’IRANK = ’, IRANK

CALL WRCRN (’U’, U, NRA, NCA)

CALL WRCRN (’S’, S, 1, NCA, 1)

CALL WRCRN (’V’, V)

END

Output

IRANK = 3

1 2 3

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)

1 2 3

( 11.77, 0.00) ( 9.30, 0.00) ( 4.99, 0.00)

1 2 3

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)