ctgsy2.f

Go to the documentation of this file.

*> \brief \b CTGSY2 solves the generalized Sylvester equation (unblocked algorithm).
*
*  =========== DOCUMENTATION ===========
*
* Online html documentation available at
*            http://www.netlib.org/lapack/explore-html/
*
*> \htmlonly
*> Download CTGSY2 + dependencies
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/ctgsy2.f">
*> [TGZ]</a>
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/ctgsy2.f">
*> [ZIP]</a>
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/ctgsy2.f">
*> [TXT]</a>
*> \endhtmlonly
*
*  Definition:
*  ===========
*
*       SUBROUTINE CTGSY2( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D,
*                          LDD, E, LDE, F, LDF, SCALE, RDSUM, RDSCAL,
*                          INFO )
*
*       .. Scalar Arguments ..
*       CHARACTER          TRANS
*       INTEGER            IJOB, INFO, LDA, LDB, LDC, LDD, LDE, LDF, M, N
*       REAL               RDSCAL, RDSUM, SCALE
*       ..
*       .. Array Arguments ..
*       COMPLEX            A( LDA, * ), B( LDB, * ), C( LDC, * ),
*      $                   D( LDD, * ), E( LDE, * ), F( LDF, * )
*       ..
*
*
*> \par Purpose:
*  =============
*>
*> \verbatim
*>
*> CTGSY2 solves the generalized Sylvester equation
*>
*>             A * R - L * B = scale *  C               (1)
*>             D * R - L * E = scale * F
*>
*> using Level 1 and 2 BLAS, where R and L are unknown M-by-N matrices,
*> (A, D), (B, E) and (C, F) are given matrix pairs of size M-by-M,
*> N-by-N and M-by-N, respectively. A, B, D and E are upper triangular
*> (i.e., (A,D) and (B,E) in generalized Schur form).
*>
*> The solution (R, L) overwrites (C, F). 0 <= SCALE <= 1 is an output
*> scaling factor chosen to avoid overflow.
*>
*> In matrix notation solving equation (1) corresponds to solve
*> Zx = scale * b, where Z is defined as
*>
*>        Z = [ kron(In, A)  -kron(B**H, Im) ]             (2)
*>            [ kron(In, D)  -kron(E**H, Im) ],
*>
*> Ik is the identity matrix of size k and X**H is the transpose of X.
*> kron(X, Y) is the Kronecker product between the matrices X and Y.
*>
*> If TRANS = 'C', y in the conjugate transposed system Z**H*y = scale*b
*> is solved for, which is equivalent to solve for R and L in
*>
*>             A**H * R  + D**H * L   = scale * C           (3)
*>             R  * B**H + L  * E**H  = scale * -F
*>
*> This case is used to compute an estimate of Dif[(A, D), (B, E)] =
*> = sigma_min(Z) using reverse communicaton with CLACON.
*>
*> CTGSY2 also (IJOB >= 1) contributes to the computation in CTGSYL
*> of an upper bound on the separation between to matrix pairs. Then
*> the input (A, D), (B, E) are sub-pencils of two matrix pairs in
*> CTGSYL.
*> \endverbatim
*
*  Arguments:
*  ==========
*
*> \param[in] TRANS
*> \verbatim
*>          TRANS is CHARACTER*1
*>          = 'N', solve the generalized Sylvester equation (1).
*>          = 'T': solve the 'transposed' system (3).
*> \endverbatim
*>
*> \param[in] IJOB
*> \verbatim
*>          IJOB is INTEGER
*>          Specifies what kind of functionality to be performed.
*>          =0: solve (1) only.
*>          =1: A contribution from this subsystem to a Frobenius
*>              norm-based estimate of the separation between two matrix
*>              pairs is computed. (look ahead strategy is used).
*>          =2: A contribution from this subsystem to a Frobenius
*>              norm-based estimate of the separation between two matrix
*>              pairs is computed. (SGECON on sub-systems is used.)
*>          Not referenced if TRANS = 'T'.
*> \endverbatim
*>
*> \param[in] M
*> \verbatim
*>          M is INTEGER
*>          On entry, M specifies the order of A and D, and the row
*>          dimension of C, F, R and L.
*> \endverbatim
*>
*> \param[in] N
*> \verbatim
*>          N is INTEGER
*>          On entry, N specifies the order of B and E, and the column
*>          dimension of C, F, R and L.
*> \endverbatim
*>
*> \param[in] A
*> \verbatim
*>          A is COMPLEX array, dimension (LDA, M)
*>          On entry, A contains an upper triangular matrix.
*> \endverbatim
*>
*> \param[in] LDA
*> \verbatim
*>          LDA is INTEGER
*>          The leading dimension of the matrix A. LDA >= max(1, M).
*> \endverbatim
*>
*> \param[in] B
*> \verbatim
*>          B is COMPLEX array, dimension (LDB, N)
*>          On entry, B contains an upper triangular matrix.
*> \endverbatim
*>
*> \param[in] LDB
*> \verbatim
*>          LDB is INTEGER
*>          The leading dimension of the matrix B. LDB >= max(1, N).
*> \endverbatim
*>
*> \param[in,out] C
*> \verbatim
*>          C is COMPLEX array, dimension (LDC, N)
*>          On entry, C contains the right-hand-side of the first matrix
*>          equation in (1).
*>          On exit, if IJOB = 0, C has been overwritten by the solution
*>          R.
*> \endverbatim
*>
*> \param[in] LDC
*> \verbatim
*>          LDC is INTEGER
*>          The leading dimension of the matrix C. LDC >= max(1, M).
*> \endverbatim
*>
*> \param[in] D
*> \verbatim
*>          D is COMPLEX array, dimension (LDD, M)
*>          On entry, D contains an upper triangular matrix.
*> \endverbatim
*>
*> \param[in] LDD
*> \verbatim
*>          LDD is INTEGER
*>          The leading dimension of the matrix D. LDD >= max(1, M).
*> \endverbatim
*>
*> \param[in] E
*> \verbatim
*>          E is COMPLEX array, dimension (LDE, N)
*>          On entry, E contains an upper triangular matrix.
*> \endverbatim
*>
*> \param[in] LDE
*> \verbatim
*>          LDE is INTEGER
*>          The leading dimension of the matrix E. LDE >= max(1, N).
*> \endverbatim
*>
*> \param[in,out] F
*> \verbatim
*>          F is COMPLEX array, dimension (LDF, N)
*>          On entry, F contains the right-hand-side of the second matrix
*>          equation in (1).
*>          On exit, if IJOB = 0, F has been overwritten by the solution
*>          L.
*> \endverbatim
*>
*> \param[in] LDF
*> \verbatim
*>          LDF is INTEGER
*>          The leading dimension of the matrix F. LDF >= max(1, M).
*> \endverbatim
*>
*> \param[out] SCALE
*> \verbatim
*>          SCALE is REAL
*>          On exit, 0 <= SCALE <= 1. If 0 < SCALE < 1, the solutions
*>          R and L (C and F on entry) will hold the solutions to a
*>          slightly perturbed system but the input matrices A, B, D and
*>          E have not been changed. If SCALE = 0, R and L will hold the
*>          solutions to the homogeneous system with C = F = 0.
*>          Normally, SCALE = 1.
*> \endverbatim
*>
*> \param[in,out] RDSUM
*> \verbatim
*>          RDSUM is REAL
*>          On entry, the sum of squares of computed contributions to
*>          the Dif-estimate under computation by CTGSYL, where the
*>          scaling factor RDSCAL (see below) has been factored out.
*>          On exit, the corresponding sum of squares updated with the
*>          contributions from the current sub-system.
*>          If TRANS = 'T' RDSUM is not touched.
*>          NOTE: RDSUM only makes sense when CTGSY2 is called by
*>          CTGSYL.
*> \endverbatim
*>
*> \param[in,out] RDSCAL
*> \verbatim
*>          RDSCAL is REAL
*>          On entry, scaling factor used to prevent overflow in RDSUM.
*>          On exit, RDSCAL is updated w.r.t. the current contributions
*>          in RDSUM.
*>          If TRANS = 'T', RDSCAL is not touched.
*>          NOTE: RDSCAL only makes sense when CTGSY2 is called by
*>          CTGSYL.
*> \endverbatim
*>
*> \param[out] INFO
*> \verbatim
*>          INFO is INTEGER
*>          On exit, if INFO is set to
*>            =0: Successful exit
*>            <0: If INFO = -i, input argument number i is illegal.
*>            >0: The matrix pairs (A, D) and (B, E) have common or very
*>                close eigenvalues.
*> \endverbatim
*
*  Authors:
*  ========
*
*> \author Univ. of Tennessee
*> \author Univ. of California Berkeley
*> \author Univ. of Colorado Denver
*> \author NAG Ltd.
*
*> \date December 2016
*
*> \ingroup complexSYauxiliary
*
*> \par Contributors:
*  ==================
*>
*>     Bo Kagstrom and Peter Poromaa, Department of Computing Science,
*>     Umea University, S-901 87 Umea, Sweden.
*
*  =====================================================================
      SUBROUTINE ctgsy2( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D,
     $                   LDD, E, LDE, F, LDF, SCALE, RDSUM, RDSCAL,
     $                   INFO )
*
*  -- LAPACK auxiliary routine (version 3.7.0) --
*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
*     December 2016
*
*     .. Scalar Arguments ..
      CHARACTER          TRANS
      INTEGER            IJOB, INFO, LDA, LDB, LDC, LDD, LDE, LDF, M, N
      REAL               RDSCAL, RDSUM, SCALE
*     ..
*     .. Array Arguments ..
      COMPLEX            A( lda, * ), B( ldb, * ), C( ldc, * ),
     $                   d( ldd, * ), e( lde, * ), f( ldf, * )
*     ..
*
*  =====================================================================
*
*     .. Parameters ..
      REAL               ZERO, ONE
      INTEGER            LDZ
      parameter( zero = 0.0e+0, one = 1.0e+0, ldz = 2 )
*     ..
*     .. Local Scalars ..
      LOGICAL            NOTRAN
      INTEGER            I, IERR, J, K
      REAL               SCALOC
      COMPLEX            ALPHA
*     ..
*     .. Local Arrays ..
      INTEGER            IPIV( ldz ), JPIV( ldz )
      COMPLEX            RHS( ldz ), Z( ldz, ldz )
*     ..
*     .. External Functions ..
      LOGICAL            LSAME
      EXTERNAL           lsame
*     ..
*     .. External Subroutines ..
      EXTERNAL           caxpy, cgesc2, cgetc2, cscal, clatdf, xerbla
*     ..
*     .. Intrinsic Functions ..
      INTRINSIC          cmplx, conjg, max
*     ..
*     .. Executable Statements ..
*
*     Decode and test input parameters
*
      info = 0
      ierr = 0
      notran = lsame( trans, 'N' )
      IF( .NOT.notran .AND. .NOT.lsame( trans, 'C' ) ) THEN
         info = -1
      ELSE IF( notran ) THEN
         IF( ( ijob.LT.0 ) .OR. ( ijob.GT.2 ) ) THEN
            info = -2
         END IF
      END IF
      IF( info.EQ.0 ) THEN
         IF( m.LE.0 ) THEN
            info = -3
         ELSE IF( n.LE.0 ) THEN
            info = -4
         ELSE IF( lda.LT.max( 1, m ) ) THEN
            info = -6
         ELSE IF( ldb.LT.max( 1, n ) ) THEN
            info = -8
         ELSE IF( ldc.LT.max( 1, m ) ) THEN
            info = -10
         ELSE IF( ldd.LT.max( 1, m ) ) THEN
            info = -12
         ELSE IF( lde.LT.max( 1, n ) ) THEN
            info = -14
         ELSE IF( ldf.LT.max( 1, m ) ) THEN
            info = -16
         END IF
      END IF
      IF( info.NE.0 ) THEN
         CALL xerbla( 'CTGSY2', -info )
         RETURN
      END IF
*
      IF( notran ) THEN
*
*        Solve (I, J) - system
*           A(I, I) * R(I, J) - L(I, J) * B(J, J) = C(I, J)
*           D(I, I) * R(I, J) - L(I, J) * E(J, J) = F(I, J)
*        for I = M, M - 1, ..., 1; J = 1, 2, ..., N
*
         scale = one
         scaloc = one
         DO 30 j = 1, n
            DO 20 i = m, 1, -1
*
*              Build 2 by 2 system
*
               z( 1, 1 ) = a( i, i )
               z( 2, 1 ) = d( i, i )
               z( 1, 2 ) = -b( j, j )
               z( 2, 2 ) = -e( j, j )
*
*              Set up right hand side(s)
*
               rhs( 1 ) = c( i, j )
               rhs( 2 ) = f( i, j )
*
*              Solve Z * x = RHS
*
               CALL cgetc2( ldz, z, ldz, ipiv, jpiv, ierr )
               IF( ierr.GT.0 )
     $            info = ierr
               IF( ijob.EQ.0 ) THEN
                  CALL cgesc2( ldz, z, ldz, rhs, ipiv, jpiv, scaloc )
                  IF( scaloc.NE.one ) THEN
                     DO 10 k = 1, n
                        CALL cscal( m, cmplx( scaloc, zero ), c( 1, k ),
     $                              1 )
                        CALL cscal( m, cmplx( scaloc, zero ), f( 1, k ),
     $                              1 )
   10                CONTINUE
                     scale = scale*scaloc
                  END IF
               ELSE
                  CALL clatdf( ijob, ldz, z, ldz, rhs, rdsum, rdscal,
     $                         ipiv, jpiv )
               END IF
*
*              Unpack solution vector(s)
*
               c( i, j ) = rhs( 1 )
               f( i, j ) = rhs( 2 )
*
*              Substitute R(I, J) and L(I, J) into remaining equation.
*
               IF( i.GT.1 ) THEN
                  alpha = -rhs( 1 )
                  CALL caxpy( i-1, alpha, a( 1, i ), 1, c( 1, j ), 1 )
                  CALL caxpy( i-1, alpha, d( 1, i ), 1, f( 1, j ), 1 )
               END IF
               IF( j.LT.n ) THEN
                  CALL caxpy( n-j, rhs( 2 ), b( j, j+1 ), ldb,
     $                        c( i, j+1 ), ldc )
                  CALL caxpy( n-j, rhs( 2 ), e( j, j+1 ), lde,
     $                        f( i, j+1 ), ldf )
               END IF
*
   20       CONTINUE
   30    CONTINUE
      ELSE
*
*        Solve transposed (I, J) - system:
*           A(I, I)**H * R(I, J) + D(I, I)**H * L(J, J) = C(I, J)
*           R(I, I) * B(J, J) + L(I, J) * E(J, J)   = -F(I, J)
*        for I = 1, 2, ..., M, J = N, N - 1, ..., 1
*
         scale = one
         scaloc = one
         DO 80 i = 1, m
            DO 70 j = n, 1, -1
*
*              Build 2 by 2 system Z**H
*
               z( 1, 1 ) = conjg( a( i, i ) )
               z( 2, 1 ) = -conjg( b( j, j ) )
               z( 1, 2 ) = conjg( d( i, i ) )
               z( 2, 2 ) = -conjg( e( j, j ) )
*
*
*              Set up right hand side(s)
*
               rhs( 1 ) = c( i, j )
               rhs( 2 ) = f( i, j )
*
*              Solve Z**H * x = RHS
*
               CALL cgetc2( ldz, z, ldz, ipiv, jpiv, ierr )
               IF( ierr.GT.0 )
     $            info = ierr
               CALL cgesc2( ldz, z, ldz, rhs, ipiv, jpiv, scaloc )
               IF( scaloc.NE.one ) THEN
                  DO 40 k = 1, n
                     CALL cscal( m, cmplx( scaloc, zero ), c( 1, k ),
     $                           1 )
                     CALL cscal( m, cmplx( scaloc, zero ), f( 1, k ),
     $                           1 )
   40             CONTINUE
                  scale = scale*scaloc
               END IF
*
*              Unpack solution vector(s)
*
               c( i, j ) = rhs( 1 )
               f( i, j ) = rhs( 2 )
*
*              Substitute R(I, J) and L(I, J) into remaining equation.
*
               DO 50 k = 1, j - 1
                  f( i, k ) = f( i, k ) + rhs( 1 )*conjg( b( k, j ) ) +
     $                        rhs( 2 )*conjg( e( k, j ) )
   50          CONTINUE
               DO 60 k = i + 1, m
                  c( k, j ) = c( k, j ) - conjg( a( i, k ) )*rhs( 1 ) -
     $                        conjg( d( i, k ) )*rhs( 2 )
   60          CONTINUE
*
   70       CONTINUE
   80    CONTINUE
      END IF
      RETURN
*
*     End of CTGSY2
*
      END