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, * )


PURPOSE

       STGEX2 swaps adjacent diagonal blocks (A11, B11) and (A22,
       B22) of size 1-by-1 or 2-by-2 in an upper (quasi) triangu­
       lar matrix pair (A, B) by an orthogonal equivalence trans­
       formation.   (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 vec­
       tors 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


       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

       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 Eigenval­
       ues 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 Condi­
       tion
           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.


Man(1) output converted with man2html