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

NAME
  ZGEGV	- a pair of N-by-N complex nonsymmetric	matrices A, B

SYNOPSIS

  SUBROUTINE ZGEGV( JOBVL, JOBVR, N, A,	LDA, B,	LDB, ALPHA, BETA, VL, LDVL,
		    VR,	LDVR, WORK, LWORK, RWORK, INFO )

      CHARACTER	    JOBVL, JOBVR

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

      DOUBLE	    PRECISION RWORK( * )

      COMPLEX*16    A( LDA, * ), ALPHA(	* ), B(	LDB, * ), BETA(	* ), VL(
		    LDVL, * ), VR( LDVR, * ), WORK( * )

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

     compute the generalized eigenvalues (alpha, 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	l  such	that  (A - w B)**H 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) COMPLEX*16 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) COMPLEX*16 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).

  ALPHA	  (output) COMPLEX*16 array, dimension (N)
	  BETA	  (output) COMPLEX*16 array, dimension (N) On exit,
	  ALPHA(j)/BETA(j), j=1,...,N, will be the generalized eigenvalues.

	  Note:	the quotients ALPHA(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, ALPHA 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) COMPLEX*16 array, dimension (LDVL,N)
	  If JOBVL = 'V', the left generalized eigenvectors.  (See "Purpose",
	  above.) 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) COMPLEX*16 array, dimension (LDVR,N)
	  If JOBVL = 'V', the right generalized	eigenvectors.  (See "Pur-
	  pose", above.) Each eigenvector will be scaled so the	largest	com-
	  ponent 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) COMPLEX*16	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,2*N).  For good
	  performance, LWORK must generally be larger.	To compute the
	  optimal value	of LWORK, call ILAENV to get blocksizes	(for ZGEQRF,
	  ZUNMQR, and CUNGQR.)	Then compute: NB  -- MAX of the	blocksizes
	  for ZGEQRF, ZUNMQR, and CUNGQR; The optimal LWORK is	MAX( 2*N,
	  N*(NB+1) ).

  RWORK	  (workspace/output) DOUBLE PRECISION array, dimension (8*N)

  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 ALPHA(j)	and BETA(j) should be correct for
	  j=INFO+1,...,N.  > N:	 errors	that usually indicate LAPACK prob-
	  lems:
	  =N+1:	error return from ZGGBAL
	  =N+2:	error return from ZGEQRF
	  =N+3:	error return from ZUNMQR
	  =N+4:	error return from ZUNGQR
	  =N+5:	error return from ZGGHRD
	  =N+6:	error return from ZHGEQZ (other	than failed iteration) =N+7:
	  error	return from ZTGEVC
	  =N+8:	error return from ZGGBAK (computing VL)
	  =N+9:	error return from ZGGBAK (computing VR)
	  =N+10: error return from ZLASCL (various calls)

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

  This driver calls ZGGBAL 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, ZGGBAK 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 complex Schur form[*] of
  the "balanced" versions of A and B.  If no eigenvectors are computed,	then
  only the diagonal blocks will	be correct.

  [*] In other words, upper triangular form.