ztgsy2(3S)

NAME
     ZTGSY2 - solve 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,

SYNOPSIS
     SUBROUTINE ZTGSY2( TRANS, IJOB, M, N, A, LDA, B, LDB, C, LDC, D, LDD, E,
                        LDE, F, LDF, SCALE, RDSUM, RDSCAL, INFO )

         CHARACTER      TRANS

         INTEGER        IJOB, INFO, LDA, LDB, LDC, LDD, LDE, LDF, M, N

         DOUBLE         PRECISION RDSCAL, RDSUM, SCALE

         COMPLEX*16     A( LDA, * ), B( LDB, * ), C( LDC, * ), D( LDD, * ), E(
                        LDE, * ), F( LDF, * )

IMPLEMENTATION
     These routines are part of the SCSL Scientific Library and can be loaded
     using either the -lscs or the -lscs_mp option.  The -lscs_mp option
     directs the linker to use the multi-processor version of the library.

     When linking to SCSL with -lscs or -lscs_mp, the default integer size is
     4 bytes (32 bits). Another version of SCSL is available in which integers
     are 8 bytes (64 bits).  This version allows the user access to larger
     memory sizes and helps when porting legacy Cray codes.  It can be loaded
     by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
     only one of the two versions; 4-byte integer and 8-byte integer library
     calls cannot be mixed.

PURPOSE
     ZTGSY2 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', Im) ]             (2)
                [ kron(In, D)  -kron(E', Im) ],

     Ik is the identity matrix of size k and X' 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'y = scale*b is
     solved for, which is equivalent to solve for R and L in
                 A' * R  + D' * L   = scale *  C           (3)
                 R  * B' + L  * E'  = scale * -F

     This case is used to compute an estimate of Dif[(A, D), (B, E)] = =
     sigma_min(Z) using reverse communicaton with ZLACON.

     ZTGSY2 also (IJOB >= 1) contributes to the computation in ZTGSYL 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 ZTGSYL.


ARGUMENTS
     TRANS   (input) CHARACTER
             = 'N', solve the generalized Sylvester equation (1).  = 'T':
             solve the 'transposed' system (3).

     IJOB    (input) 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. (DGECON on sub-systems is
             used.)  Not referenced if TRANS = 'T'.

     M       (input) INTEGER
             On entry, M specifies the order of A and D, and the row dimension
             of C, F, R and L.

     N       (input) INTEGER
             On entry, N specifies the order of B and E, and the column
             dimension of C, F, R and L.

     A       (input) COMPLEX*16 array, dimension (LDA, M)
             On entry, A contains an upper triangular matrix.

     LDA     (input) INTEGER
             The leading dimension of the matrix A. LDA >= max(1, M).

     B       (input) COMPLEX*16 array, dimension (LDB, N)
             On entry, B contains an upper triangular matrix.

     LDB     (input) INTEGER
             The leading dimension of the matrix B. LDB >= max(1, N).

     C       (input/ output) COMPLEX*16 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.

     LDC     (input) INTEGER
             The leading dimension of the matrix C. LDC >= max(1, M).

     D       (input) COMPLEX*16 array, dimension (LDD, M)
             On entry, D contains an upper triangular matrix.

     LDD     (input) INTEGER
             The leading dimension of the matrix D. LDD >= max(1, M).

     E       (input) COMPLEX*16 array, dimension (LDE, N)
             On entry, E contains an upper triangular matrix.

     LDE     (input) INTEGER
             The leading dimension of the matrix E. LDE >= max(1, N).

     F       (input/ output) COMPLEX*16 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.

     LDF     (input) INTEGER
             The leading dimension of the matrix F. LDF >= max(1, M).

     SCALE   (output) DOUBLE PRECISION
             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.

     RDSUM   (input/output) DOUBLE PRECISION
             On entry, the sum of squares of computed contributions to the
             Dif-estimate under computation by ZTGSYL, 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 ZTGSY2 is called by ZTGSYL.

     RDSCAL  (input/output) DOUBLE PRECISION
             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 ZTGSY2 is called by ZTGSYL.

     INFO    (output) 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.

FURTHER DETAILS
     Based on contributions by
        Bo Kagstrom and Peter Poromaa, Department of Computing Science,
        Umea University, S-901 87 Umea, Sweden.


SEE ALSO
     INTRO_LAPACK(3S), INTRO_SCSL(3S)

     This man page is available only online.