*> \brief \b CTGSJA * * =========== DOCUMENTATION =========== * * Online html documentation available at * http://www.netlib.org/lapack/explore-html/ * *> \htmlonly *> Download CTGSJA + dependencies *> *> [TGZ] *> *> [ZIP] *> *> [TXT] *> \endhtmlonly * * Definition: * =========== * * SUBROUTINE CTGSJA( JOBU, JOBV, JOBQ, M, P, N, K, L, A, LDA, B, * LDB, TOLA, TOLB, ALPHA, BETA, U, LDU, V, LDV, * Q, LDQ, WORK, NCYCLE, INFO ) * * .. Scalar Arguments .. * CHARACTER JOBQ, JOBU, JOBV * INTEGER INFO, K, L, LDA, LDB, LDQ, LDU, LDV, M, N, * $ NCYCLE, P * REAL TOLA, TOLB * .. * .. Array Arguments .. * REAL ALPHA( * ), BETA( * ) * COMPLEX A( LDA, * ), B( LDB, * ), Q( LDQ, * ), * $ U( LDU, * ), V( LDV, * ), WORK( * ) * .. * * *> \par Purpose: * ============= *> *> \verbatim *> *> CTGSJA computes the generalized singular value decomposition (GSVD) *> of two complex upper triangular (or trapezoidal) matrices A and B. *> *> On entry, it is assumed that matrices A and B have the following *> forms, which may be obtained by the preprocessing subroutine CGGSVP *> from a general M-by-N matrix A and P-by-N matrix B: *> *> N-K-L K L *> A = K ( 0 A12 A13 ) if M-K-L >= 0; *> L ( 0 0 A23 ) *> M-K-L ( 0 0 0 ) *> *> N-K-L K L *> A = K ( 0 A12 A13 ) if M-K-L < 0; *> M-K ( 0 0 A23 ) *> *> N-K-L K L *> B = L ( 0 0 B13 ) *> P-L ( 0 0 0 ) *> *> where the K-by-K matrix A12 and L-by-L matrix B13 are nonsingular *> upper triangular; A23 is L-by-L upper triangular if M-K-L >= 0, *> otherwise A23 is (M-K)-by-L upper trapezoidal. *> *> On exit, *> *> U**H *A*Q = D1*( 0 R ), V**H *B*Q = D2*( 0 R ), *> *> where U, V and Q are unitary matrices. *> R is a nonsingular upper triangular matrix, and D1 *> and D2 are ``diagonal'' matrices, which are of the following *> structures: *> *> If M-K-L >= 0, *> *> K L *> D1 = K ( I 0 ) *> L ( 0 C ) *> M-K-L ( 0 0 ) *> *> K L *> D2 = L ( 0 S ) *> P-L ( 0 0 ) *> *> N-K-L K L *> ( 0 R ) = K ( 0 R11 R12 ) K *> L ( 0 0 R22 ) L *> *> where *> *> C = diag( ALPHA(K+1), ... , ALPHA(K+L) ), *> S = diag( BETA(K+1), ... , BETA(K+L) ), *> C**2 + S**2 = I. *> *> R is stored in A(1:K+L,N-K-L+1:N) on exit. *> *> If M-K-L < 0, *> *> K M-K K+L-M *> D1 = K ( I 0 0 ) *> M-K ( 0 C 0 ) *> *> K M-K K+L-M *> D2 = M-K ( 0 S 0 ) *> K+L-M ( 0 0 I ) *> P-L ( 0 0 0 ) *> *> N-K-L K M-K K+L-M *> ( 0 R ) = K ( 0 R11 R12 R13 ) *> M-K ( 0 0 R22 R23 ) *> K+L-M ( 0 0 0 R33 ) *> *> where *> C = diag( ALPHA(K+1), ... , ALPHA(M) ), *> S = diag( BETA(K+1), ... , BETA(M) ), *> C**2 + S**2 = I. *> *> R = ( R11 R12 R13 ) is stored in A(1:M, N-K-L+1:N) and R33 is stored *> ( 0 R22 R23 ) *> in B(M-K+1:L,N+M-K-L+1:N) on exit. *> *> The computation of the unitary transformation matrices U, V or Q *> is optional. These matrices may either be formed explicitly, or they *> may be postmultiplied into input matrices U1, V1, or Q1. *> \endverbatim * * Arguments: * ========== * *> \param[in] JOBU *> \verbatim *> JOBU is CHARACTER*1 *> = 'U': U must contain a unitary matrix U1 on entry, and *> the product U1*U is returned; *> = 'I': U is initialized to the unit matrix, and the *> unitary matrix U is returned; *> = 'N': U is not computed. *> \endverbatim *> *> \param[in] JOBV *> \verbatim *> JOBV is CHARACTER*1 *> = 'V': V must contain a unitary matrix V1 on entry, and *> the product V1*V is returned; *> = 'I': V is initialized to the unit matrix, and the *> unitary matrix V is returned; *> = 'N': V is not computed. *> \endverbatim *> *> \param[in] JOBQ *> \verbatim *> JOBQ is CHARACTER*1 *> = 'Q': Q must contain a unitary matrix Q1 on entry, and *> the product Q1*Q is returned; *> = 'I': Q is initialized to the unit matrix, and the *> unitary matrix Q is returned; *> = 'N': Q is not computed. *> \endverbatim *> *> \param[in] M *> \verbatim *> M is INTEGER *> The number of rows of the matrix A. M >= 0. *> \endverbatim *> *> \param[in] P *> \verbatim *> P is INTEGER *> The number of rows of the matrix B. P >= 0. *> \endverbatim *> *> \param[in] N *> \verbatim *> N is INTEGER *> The number of columns of the matrices A and B. N >= 0. *> \endverbatim *> *> \param[in] K *> \verbatim *> K is INTEGER *> \endverbatim *> *> \param[in] L *> \verbatim *> L is INTEGER *> *> K and L specify the subblocks in the input matrices A and B: *> A23 = A(K+1:MIN(K+L,M),N-L+1:N) and B13 = B(1:L,,N-L+1:N) *> of A and B, whose GSVD is going to be computed by CTGSJA. *> See Further Details. *> \endverbatim *> *> \param[in,out] A *> \verbatim *> A is COMPLEX array, dimension (LDA,N) *> On entry, the M-by-N matrix A. *> On exit, A(N-K+1:N,1:MIN(K+L,M) ) contains the triangular *> matrix R or part of R. See Purpose for details. *> \endverbatim *> *> \param[in] LDA *> \verbatim *> LDA is INTEGER *> The leading dimension of the array A. LDA >= max(1,M). *> \endverbatim *> *> \param[in,out] B *> \verbatim *> B is COMPLEX array, dimension (LDB,N) *> On entry, the P-by-N matrix B. *> On exit, if necessary, B(M-K+1:L,N+M-K-L+1:N) contains *> a part of R. See Purpose for details. *> \endverbatim *> *> \param[in] LDB *> \verbatim *> LDB is INTEGER *> The leading dimension of the array B. LDB >= max(1,P). *> \endverbatim *> *> \param[in] TOLA *> \verbatim *> TOLA is REAL *> \endverbatim *> *> \param[in] TOLB *> \verbatim *> TOLB is REAL *> *> TOLA and TOLB are the convergence criteria for the Jacobi- *> Kogbetliantz iteration procedure. Generally, they are the *> same as used in the preprocessing step, say *> TOLA = MAX(M,N)*norm(A)*MACHEPS, *> TOLB = MAX(P,N)*norm(B)*MACHEPS. *> \endverbatim *> *> \param[out] ALPHA *> \verbatim *> ALPHA is REAL array, dimension (N) *> \endverbatim *> *> \param[out] BETA *> \verbatim *> BETA is REAL array, dimension (N) *> *> On exit, ALPHA and BETA contain the generalized singular *> value pairs of A and B; *> ALPHA(1:K) = 1, *> BETA(1:K) = 0, *> and if M-K-L >= 0, *> ALPHA(K+1:K+L) = diag(C), *> BETA(K+1:K+L) = diag(S), *> or if M-K-L < 0, *> ALPHA(K+1:M)= C, ALPHA(M+1:K+L)= 0 *> BETA(K+1:M) = S, BETA(M+1:K+L) = 1. *> Furthermore, if K+L < N, *> ALPHA(K+L+1:N) = 0 *> BETA(K+L+1:N) = 0. *> \endverbatim *> *> \param[in,out] U *> \verbatim *> U is COMPLEX array, dimension (LDU,M) *> On entry, if JOBU = 'U', U must contain a matrix U1 (usually *> the unitary matrix returned by CGGSVP). *> On exit, *> if JOBU = 'I', U contains the unitary matrix U; *> if JOBU = 'U', U contains the product U1*U. *> If JOBU = 'N', U is not referenced. *> \endverbatim *> *> \param[in] LDU *> \verbatim *> LDU is INTEGER *> The leading dimension of the array U. LDU >= max(1,M) if *> JOBU = 'U'; LDU >= 1 otherwise. *> \endverbatim *> *> \param[in,out] V *> \verbatim *> V is COMPLEX array, dimension (LDV,P) *> On entry, if JOBV = 'V', V must contain a matrix V1 (usually *> the unitary matrix returned by CGGSVP). *> On exit, *> if JOBV = 'I', V contains the unitary matrix V; *> if JOBV = 'V', V contains the product V1*V. *> If JOBV = 'N', V is not referenced. *> \endverbatim *> *> \param[in] LDV *> \verbatim *> LDV is INTEGER *> The leading dimension of the array V. LDV >= max(1,P) if *> JOBV = 'V'; LDV >= 1 otherwise. *> \endverbatim *> *> \param[in,out] Q *> \verbatim *> Q is COMPLEX array, dimension (LDQ,N) *> On entry, if JOBQ = 'Q', Q must contain a matrix Q1 (usually *> the unitary matrix returned by CGGSVP). *> On exit, *> if JOBQ = 'I', Q contains the unitary matrix Q; *> if JOBQ = 'Q', Q contains the product Q1*Q. *> If JOBQ = 'N', Q is not referenced. *> \endverbatim *> *> \param[in] LDQ *> \verbatim *> LDQ is INTEGER *> The leading dimension of the array Q. LDQ >= max(1,N) if *> JOBQ = 'Q'; LDQ >= 1 otherwise. *> \endverbatim *> *> \param[out] WORK *> \verbatim *> WORK is COMPLEX array, dimension (2*N) *> \endverbatim *> *> \param[out] NCYCLE *> \verbatim *> NCYCLE is INTEGER *> The number of cycles required for convergence. *> \endverbatim *> *> \param[out] INFO *> \verbatim *> INFO is INTEGER *> = 0: successful exit *> < 0: if INFO = -i, the i-th argument had an illegal value. *> = 1: the procedure does not converge after MAXIT cycles. *> \endverbatim * *> \par Internal Parameters: * ========================= *> *> \verbatim *> MAXIT INTEGER *> MAXIT specifies the total loops that the iterative procedure *> may take. If after MAXIT cycles, the routine fails to *> converge, we return INFO = 1. *> \endverbatim * * Authors: * ======== * *> \author Univ. of Tennessee *> \author Univ. of California Berkeley *> \author Univ. of Colorado Denver *> \author NAG Ltd. * *> \ingroup complexOTHERcomputational * *> \par Further Details: * ===================== *> *> \verbatim *> *> CTGSJA essentially uses a variant of Kogbetliantz algorithm to reduce *> min(L,M-K)-by-L triangular (or trapezoidal) matrix A23 and L-by-L *> matrix B13 to the form: *> *> U1**H *A13*Q1 = C1*R1; V1**H *B13*Q1 = S1*R1, *> *> where U1, V1 and Q1 are unitary matrix. *> C1 and S1 are diagonal matrices satisfying *> *> C1**2 + S1**2 = I, *> *> and R1 is an L-by-L nonsingular upper triangular matrix. *> \endverbatim *> * ===================================================================== SUBROUTINE CTGSJA( JOBU, JOBV, JOBQ, M, P, N, K, L, A, LDA, B, $ LDB, TOLA, TOLB, ALPHA, BETA, U, LDU, V, LDV, $ Q, LDQ, WORK, NCYCLE, INFO ) * * -- LAPACK computational routine -- * -- LAPACK is a software package provided by Univ. of Tennessee, -- * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..-- * * .. Scalar Arguments .. CHARACTER JOBQ, JOBU, JOBV INTEGER INFO, K, L, LDA, LDB, LDQ, LDU, LDV, M, N, $ NCYCLE, P REAL TOLA, TOLB * .. * .. Array Arguments .. REAL ALPHA( * ), BETA( * ) COMPLEX A( LDA, * ), B( LDB, * ), Q( LDQ, * ), $ U( LDU, * ), V( LDV, * ), WORK( * ) * .. * * ===================================================================== * * .. Parameters .. INTEGER MAXIT PARAMETER ( MAXIT = 40 ) REAL ZERO, ONE PARAMETER ( ZERO = 0.0E+0, ONE = 1.0E+0 ) COMPLEX CZERO, CONE PARAMETER ( CZERO = ( 0.0E+0, 0.0E+0 ), $ CONE = ( 1.0E+0, 0.0E+0 ) ) * .. * .. Local Scalars .. * LOGICAL INITQ, INITU, INITV, UPPER, WANTQ, WANTU, WANTV INTEGER I, J, KCYCLE REAL A1, A3, B1, B3, CSQ, CSU, CSV, ERROR, GAMMA, $ RWK, SSMIN COMPLEX A2, B2, SNQ, SNU, SNV * .. * .. External Functions .. LOGICAL LSAME EXTERNAL LSAME * .. * .. External Subroutines .. EXTERNAL CCOPY, CLAGS2, CLAPLL, CLASET, CROT, CSSCAL, $ SLARTG, XERBLA * .. * .. Intrinsic Functions .. INTRINSIC ABS, CONJG, MAX, MIN, REAL * .. * .. Executable Statements .. * * Decode and test the input parameters * INITU = LSAME( JOBU, 'I' ) WANTU = INITU .OR. LSAME( JOBU, 'U' ) * INITV = LSAME( JOBV, 'I' ) WANTV = INITV .OR. LSAME( JOBV, 'V' ) * INITQ = LSAME( JOBQ, 'I' ) WANTQ = INITQ .OR. LSAME( JOBQ, 'Q' ) * INFO = 0 IF( .NOT.( INITU .OR. WANTU .OR. LSAME( JOBU, 'N' ) ) ) THEN INFO = -1 ELSE IF( .NOT.( INITV .OR. WANTV .OR. LSAME( JOBV, 'N' ) ) ) THEN INFO = -2 ELSE IF( .NOT.( INITQ .OR. WANTQ .OR. LSAME( JOBQ, 'N' ) ) ) THEN INFO = -3 ELSE IF( M.LT.0 ) THEN INFO = -4 ELSE IF( P.LT.0 ) THEN INFO = -5 ELSE IF( N.LT.0 ) THEN INFO = -6 ELSE IF( LDA.LT.MAX( 1, M ) ) THEN INFO = -10 ELSE IF( LDB.LT.MAX( 1, P ) ) THEN INFO = -12 ELSE IF( LDU.LT.1 .OR. ( WANTU .AND. LDU.LT.M ) ) THEN INFO = -18 ELSE IF( LDV.LT.1 .OR. ( WANTV .AND. LDV.LT.P ) ) THEN INFO = -20 ELSE IF( LDQ.LT.1 .OR. ( WANTQ .AND. LDQ.LT.N ) ) THEN INFO = -22 END IF IF( INFO.NE.0 ) THEN CALL XERBLA( 'CTGSJA', -INFO ) RETURN END IF * * Initialize U, V and Q, if necessary * IF( INITU ) $ CALL CLASET( 'Full', M, M, CZERO, CONE, U, LDU ) IF( INITV ) $ CALL CLASET( 'Full', P, P, CZERO, CONE, V, LDV ) IF( INITQ ) $ CALL CLASET( 'Full', N, N, CZERO, CONE, Q, LDQ ) * * Loop until convergence * UPPER = .FALSE. DO 40 KCYCLE = 1, MAXIT * UPPER = .NOT.UPPER * DO 20 I = 1, L - 1 DO 10 J = I + 1, L * A1 = ZERO A2 = CZERO A3 = ZERO IF( K+I.LE.M ) $ A1 = REAL( A( K+I, N-L+I ) ) IF( K+J.LE.M ) $ A3 = REAL( A( K+J, N-L+J ) ) * B1 = REAL( B( I, N-L+I ) ) B3 = REAL( B( J, N-L+J ) ) * IF( UPPER ) THEN IF( K+I.LE.M ) $ A2 = A( K+I, N-L+J ) B2 = B( I, N-L+J ) ELSE IF( K+J.LE.M ) $ A2 = A( K+J, N-L+I ) B2 = B( J, N-L+I ) END IF * CALL CLAGS2( UPPER, A1, A2, A3, B1, B2, B3, CSU, SNU, $ CSV, SNV, CSQ, SNQ ) * * Update (K+I)-th and (K+J)-th rows of matrix A: U**H *A * IF( K+J.LE.M ) $ CALL CROT( L, A( K+J, N-L+1 ), LDA, A( K+I, N-L+1 ), $ LDA, CSU, CONJG( SNU ) ) * * Update I-th and J-th rows of matrix B: V**H *B * CALL CROT( L, B( J, N-L+1 ), LDB, B( I, N-L+1 ), LDB, $ CSV, CONJG( SNV ) ) * * Update (N-L+I)-th and (N-L+J)-th columns of matrices * A and B: A*Q and B*Q * CALL CROT( MIN( K+L, M ), A( 1, N-L+J ), 1, $ A( 1, N-L+I ), 1, CSQ, SNQ ) * CALL CROT( L, B( 1, N-L+J ), 1, B( 1, N-L+I ), 1, CSQ, $ SNQ ) * IF( UPPER ) THEN IF( K+I.LE.M ) $ A( K+I, N-L+J ) = CZERO B( I, N-L+J ) = CZERO ELSE IF( K+J.LE.M ) $ A( K+J, N-L+I ) = CZERO B( J, N-L+I ) = CZERO END IF * * Ensure that the diagonal elements of A and B are real. * IF( K+I.LE.M ) $ A( K+I, N-L+I ) = REAL( A( K+I, N-L+I ) ) IF( K+J.LE.M ) $ A( K+J, N-L+J ) = REAL( A( K+J, N-L+J ) ) B( I, N-L+I ) = REAL( B( I, N-L+I ) ) B( J, N-L+J ) = REAL( B( J, N-L+J ) ) * * Update unitary matrices U, V, Q, if desired. * IF( WANTU .AND. K+J.LE.M ) $ CALL CROT( M, U( 1, K+J ), 1, U( 1, K+I ), 1, CSU, $ SNU ) * IF( WANTV ) $ CALL CROT( P, V( 1, J ), 1, V( 1, I ), 1, CSV, SNV ) * IF( WANTQ ) $ CALL CROT( N, Q( 1, N-L+J ), 1, Q( 1, N-L+I ), 1, CSQ, $ SNQ ) * 10 CONTINUE 20 CONTINUE * IF( .NOT.UPPER ) THEN * * The matrices A13 and B13 were lower triangular at the start * of the cycle, and are now upper triangular. * * Convergence test: test the parallelism of the corresponding * rows of A and B. * ERROR = ZERO DO 30 I = 1, MIN( L, M-K ) CALL CCOPY( L-I+1, A( K+I, N-L+I ), LDA, WORK, 1 ) CALL CCOPY( L-I+1, B( I, N-L+I ), LDB, WORK( L+1 ), 1 ) CALL CLAPLL( L-I+1, WORK, 1, WORK( L+1 ), 1, SSMIN ) ERROR = MAX( ERROR, SSMIN ) 30 CONTINUE * IF( ABS( ERROR ).LE.MIN( TOLA, TOLB ) ) $ GO TO 50 END IF * * End of cycle loop * 40 CONTINUE * * The algorithm has not converged after MAXIT cycles. * INFO = 1 GO TO 100 * 50 CONTINUE * * If ERROR <= MIN(TOLA,TOLB), then the algorithm has converged. * Compute the generalized singular value pairs (ALPHA, BETA), and * set the triangular matrix R to array A. * DO 60 I = 1, K ALPHA( I ) = ONE BETA( I ) = ZERO 60 CONTINUE * DO 70 I = 1, MIN( L, M-K ) * A1 = REAL( A( K+I, N-L+I ) ) B1 = REAL( B( I, N-L+I ) ) * IF( A1.NE.ZERO ) THEN GAMMA = B1 / A1 * IF( GAMMA.LT.ZERO ) THEN CALL CSSCAL( L-I+1, -ONE, B( I, N-L+I ), LDB ) IF( WANTV ) $ CALL CSSCAL( P, -ONE, V( 1, I ), 1 ) END IF * CALL SLARTG( ABS( GAMMA ), ONE, BETA( K+I ), ALPHA( K+I ), $ RWK ) * IF( ALPHA( K+I ).GE.BETA( K+I ) ) THEN CALL CSSCAL( L-I+1, ONE / ALPHA( K+I ), A( K+I, N-L+I ), $ LDA ) ELSE CALL CSSCAL( L-I+1, ONE / BETA( K+I ), B( I, N-L+I ), $ LDB ) CALL CCOPY( L-I+1, B( I, N-L+I ), LDB, A( K+I, N-L+I ), $ LDA ) END IF * ELSE ALPHA( K+I ) = ZERO BETA( K+I ) = ONE CALL CCOPY( L-I+1, B( I, N-L+I ), LDB, A( K+I, N-L+I ), $ LDA ) END IF 70 CONTINUE * * Post-assignment * DO 80 I = M + 1, K + L ALPHA( I ) = ZERO BETA( I ) = ONE 80 CONTINUE * IF( K+L.LT.N ) THEN DO 90 I = K + L + 1, N ALPHA( I ) = ZERO BETA( I ) = ZERO 90 CONTINUE END IF * 100 CONTINUE NCYCLE = KCYCLE * RETURN * * End of CTGSJA * END