redhat man page for stgex2

STGEX2(l)								 )								 STGEX2(l)

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

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  inter-
       nal 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.

LAPACK version 3.0						   15 June 2000 							 STGEX2(l)