stgex2(3S)

NAME
     STGEX2 - swap adjacent diagonal blocks (A11, B11) and (A22, B22) of size
     1-by-1 or 2-by-2 in an upper (quasi) triangular matrix pair (A, B) by an
     orthogonal equivalence transformation

SYNOPSIS
     SUBROUTINE STGEX2( WANTQ, WANTZ, N, A, LDA, B, LDB, Q, LDQ, Z, LDZ, J1,
                        N1, N2, WORK, LWORK, INFO )

         LOGICAL        WANTQ, WANTZ

         INTEGER        INFO, J1, LDA, LDB, LDQ, LDZ, LWORK, N, N1, N2

         REAL           A( LDA, * ), B( LDB, * ), Q( LDQ, * ), WORK( * ), Z(
                        LDZ, * )

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
     STGEX2 swaps adjacent diagonal blocks (A11, B11) and (A22, B22) of size
     1-by-1 or 2-by-2 in an upper (quasi) triangular matrix pair (A, B) by an
     orthogonal equivalence transformation. (A, B) must be in generalized real
     Schur canonical form (as returned by SGGES), i.e. A is block upper
     triangular with 1-by-1 and 2-by-2 diagonal blocks. B is upper triangular.

     Optionally, the matrices Q and Z of generalized Schur vectors are
     updated.

            Q(in) * A(in) * Z(in)' = Q(out) * A(out) * Z(out)'
            Q(in) * B(in) * Z(in)' = Q(out) * B(out) * Z(out)'



ARGUMENTS
     WANTQ   (input) LOGICAL

     WANTZ   (input) LOGICAL

     N       (input) INTEGER
             The order of the matrices A and B. N >= 0.

     A      (input/output) REAL arrays, dimensions (LDA,N)
            On entry, the matrix A in the pair (A, B).  On exit, the updated
            matrix A.

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

     B      (input/output) REAL arrays, dimensions (LDB,N)
            On entry, the matrix B in the pair (A, B).  On exit, the updated
            matrix B.

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

     Q       (input/output) REAL array, dimension (LDZ,N)
             On entry, if WANTQ = .TRUE., the orthogonal matrix Q.  On exit,
             the updated matrix Q.  Not referenced if WANTQ = .FALSE..

     LDQ     (input) INTEGER
             The leading dimension of the array Q. LDQ >= 1.  If WANTQ =
             .TRUE., LDQ >= N.

     Z       (input/output) REAL array, dimension (LDZ,N)
             On entry, if WANTZ =.TRUE., the orthogonal matrix Z.  On exit,
             the updated matrix Z.  Not referenced if WANTZ = .FALSE..

     LDZ     (input) INTEGER
             The leading dimension of the array Z. LDZ >= 1.  If WANTZ =
             .TRUE., LDZ >= N.

     J1      (input) INTEGER
             The index to the first block (A11, B11). 1 <= J1 <= N.

     N1      (input) INTEGER
             The order of the first block (A11, B11). N1 = 0, 1 or 2.

     N2      (input) INTEGER
             The order of the second block (A22, B22). N2 = 0, 1 or 2.

     WORK    (workspace) REAL array, dimension (LWORK).

     LWORK   (input) INTEGER
             The dimension of the array WORK.  LWORK >=  MAX( N*(N2+N1),
             (N2+N1)*(N2+N1)*2 )

     INFO    (output) INTEGER
             =0: Successful exit
             >0: If INFO = 1, the transformed matrix (A, B) would be too far
             from generalized Schur form; the blocks are not swapped and (A,
             B) and (Q, Z) are unchanged.  The problem of swapping is too
             ill-conditioned.  <0: If INFO = -16: LWORK is too small.
             Appropriate value for LWORK is returned in WORK(1).
FURTHER DETAILS
     Based on contributions by
        Bo Kagstrom and Peter Poromaa, Department of Computing Science,
        Umea University, S-901 87 Umea, Sweden.

     In the current code both weak and strong stability tests are performed.
     The user can omit the strong stability test by changing the internal
     logical parameter WANDS to .FALSE.. See ref. [2] for details.

     [1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the
         Generalized Real Schur Form of a Regular Matrix Pair (A, B), in
         M.S. Moonen et al (eds), Linear Algebra for Large Scale and
         Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.

     [2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified
         Eigenvalues of a Regular Matrix Pair (A, B) and Condition
         Estimation: Theory, Algorithms and Software,
         Report UMINF - 94.04, Department of Computing Science, Umea
         University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working
         Note 87. To appear in Numerical Algorithms, 1996.


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

     This man page is available only online.