SGEGV(l)	     LAPACK driver routine (version 1.1)	     SGEGV(l)

NAME
  SGEGV	- a pair of N-by-N real	nonsymmetric matrices A, B

SYNOPSIS

  SUBROUTINE SGEGV( JOBVL, JOBVR, N, A,	LDA, B,	LDB, ALPHAR, ALPHAI, BETA,
		    VL,	LDVL, VR, LDVR,	WORK, LWORK, INFO )

      CHARACTER	    JOBVL, JOBVR

      INTEGER	    INFO, LDA, LDB, LDVL, LDVR,	LWORK, N

      REAL	    A( LDA, * ), ALPHAI( * ), ALPHAR( *	), B( LDB, * ),	BETA(
		    * ), VL( LDVL, * ),	VR( LDVR, * ), WORK( * )

PURPOSE
  For a	pair of	N-by-N real nonsymmetric matrices A, B:

     compute the generalized eigenvalues (alphar +/- alphai*i, beta)
     compute the left and/or right generalized eigenvectors
	     (VL and VR)

  The second action is optional	-- see the description of JOBVL	and JOBVR
  below.

  A generalized	eigenvalue for a pair of matrices (A,B)	is, roughly speaking,
  a scalar w or	a ratio	 alpha/beta = w, such that  A -	w*B is singular.  It
  is usually represented as the	pair (alpha,beta), as there is a reasonable
  interpretation for beta=0, and even for both being zero.  A good beginning
  reference is the book, "Matrix Computations",	by G. Golub & C. van Loan
  (Johns Hopkins U. Press)

  A right generalized eigenvector corresponding	to a generalized eigenvalue
  w  for a pair	of matrices (A,B) is a vector  r  such that  (A	- w B) r = 0
  .  A left generalized	eigenvector is a vector
			 H
  l  such that	(A - w B) l = 0	.

  Note:	this routine performs "full balancing" on A and	B -- see "Further
  Details", below.

ARGUMENTS

  JOBVL	  (input) CHARACTER*1
	  = 'N':  do not compute the left generalized eigenvectors;
	  = 'V':  compute the left generalized eigenvectors.

  JOBVR	  (input) CHARACTER*1
	  = 'N':  do not compute the right generalized eigenvectors;
	  = 'V':  compute the right generalized	eigenvectors.

  N	  (input) INTEGER
	  The number of	rows and columns in the	matrices A, B, VL, and VR.  N
	  >= 0.

  A	  (input/workspace) REAL array,	dimension (LDA,	N)
	  On entry, the	first of the pair of matrices whose generalized
	  eigenvalues and (optionally) generalized eigenvectors	are to be
	  computed.  On	exit, the contents will	have been destroyed.  (For a
	  description of the contents of A on exit, see	"Further Details",
	  below.)

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

  B	  (input/workspace) REAL array,	dimension (LDB,	N)
	  On entry, the	second of the pair of matrices whose generalized
	  eigenvalues and (optionally) generalized eigenvectors	are to be
	  computed.  On	exit, the contents will	have been destroyed.  (For a
	  description of the contents of B on exit, see	"Further Details",
	  below.)

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

  ALPHAR  (output) REAL	array, dimension (N)
	  ALPHAI  (output) REAL	array, dimension (N) BETA    (output) REAL
	  array, dimension (N)

	  On exit, (ALPHAR(j) +	ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the
	  generalized eigenvalues.  If ALPHAI(j) is zero, then the j-th
	  eigenvalue is	real; if positive, then	the j-th and (j+1)-st eigen-
	  values are a complex conjugate pair, with ALPHAI(j+1)	negative.

	  Note:	the quotients ALPHAR(j)/BETA(j)	and ALPHAI(j)/BETA(j) may
	  easily over- or underflow, and BETA(j) may even be zero.  Thus, the
	  user should avoid naively computing the ratio	alpha/beta.  However,
	  ALPHAR and ALPHAI will be always less	than and usually comparable
	  with norm(A) in magnitude, and BETA always less than and usually
	  comparable with norm(B).

  VL	  (output) REAL	array, dimension (LDVL,N)
	  If JOBVL = 'V', the left generalized eigenvectors.  (See "Purpose",
	  above.)  Real	eigenvectors take one column, complex take two
	  columns, the first for the real part and the second for the ima-
	  ginary part.	Complex	eigenvectors correspond	to an eigenvalue with
	  positive imaginary part.  Each eigenvector will be scaled so the
	  largest component will have abs(real part) + abs(imag. part) = 1,
	  *except* that	for eigenvalues	with alpha=beta=0, a zero vector will
	  be returned as the corresponding eigenvector.	 Not referenced	if
	  JOBVL	= 'N'.

  LDVL	  (input) INTEGER
	  The leading dimension	of the matrix VL. LDVL >= 1, and if JOBVL =
	  'V', LDVL >= N.

  VR	  (output) REAL	array, dimension (LDVR,N)
	  If JOBVL = 'V', the right generalized	eigenvectors.  (See "Pur-
	  pose", above.)  Real eigenvectors take one column, complex take two
	  columns, the first for the real part and the second for the ima-
	  ginary part.	Complex	eigenvectors correspond	to an eigenvalue with
	  positive imaginary part.  Each eigenvector will be scaled so the
	  largest component will have abs(real part) + abs(imag. part) = 1,
	  *except* that	for eigenvalues	with alpha=beta=0, a zero vector will
	  be returned as the corresponding eigenvector.	 Not referenced	if
	  JOBVR	= 'N'.

  LDVR	  (input) INTEGER
	  The leading dimension	of the matrix VR. LDVR >= 1, and if JOBVR =
	  'V', LDVR >= N.

  WORK	  (workspace/output) REAL array, dimension (LWORK)
	  On exit, if INFO = 0,	WORK(1)	returns	the optimal LWORK.

  LWORK	  (input) INTEGER
	  The dimension	of the array WORK.  LWORK >= max(1,8*N).  For good
	  performance, LWORK must generally be larger.	To compute the
	  optimal value	of LWORK, call ILAENV to get blocksizes	(for SGEQRF,
	  SORMQR, and SORGQR.)	Then compute: NB  -- MAX of the	blocksizes
	  for SGEQRF, SORMQR, and SORGQR; The optimal LWORK is:	2*N + MAX(
	  6*N, N*(NB+1)	).

  INFO	  (output) INTEGER
	  = 0:	successful exit
	  < 0:	if INFO	= -i, the i-th argument	had an illegal value.
	  = 1,...,N: The QZ iteration failed.  No eigenvectors have been cal-
	  culated, but ALPHAR(j), ALPHAI(j), and BETA(j) should	be correct
	  for j=INFO+1,...,N.  > N:  errors that usually indicate LAPACK
	  problems:
	  =N+1:	error return from SGGBAL
	  =N+2:	error return from SGEQRF
	  =N+3:	error return from SORMQR
	  =N+4:	error return from SORGQR
	  =N+5:	error return from SGGHRD
	  =N+6:	error return from SHGEQZ (other	than failed iteration) =N+7:
	  error	return from STGEVC
	  =N+8:	error return from SGGBAK (computing VL)
	  =N+9:	error return from SGGBAK (computing VR)
	  =N+10: error return from SLASCL (various calls)

FURTHER	DETAILS
  Balancing
  ---------

  This driver calls SGGBAL to both permute and scale rows and columns of A
  and B.  The permutations PL and PR are chosen	so that	PL*A*PR	and PL*B*R
  will be upper	triangular except for the diagonal blocks A(i:j,i:j) and
  B(i:j,i:j), with i and j as close together as	possible.  The diagonal	scal-
  ing matrices DL and DR are chosen so that the	pair  DL*PL*A*PR*DR,
  DL*PL*B*PR*DR	have entries close to one (except for the entries that start
  out zero.)

  After	the eigenvalues	and eigenvectors of the	balanced matrices have been
  computed, SGGBAK transforms the eigenvectors back to what they would have
  been (in perfect arithmetic) if they had not been balanced.

  Contents of A	and B on Exit
  -------- -- -	--- - -- ----

  If any eigenvectors are computed (either JOBVL='V' or	JOBVR='V' or both),
  then on exit the arrays A and	B will contain the real	Schur form[*] of the
  "balanced" versions of A and B.  If no eigenvectors are computed, then only
  the diagonal blocks will be correct.

  [*] See SHGEQZ, SGEGS, or read the book "Matrix Computations",
      by Golub & van Loan, pub.	by Johns Hopkins U. Press.