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

NAME
  DGEES	- compute for an N-by-N	real nonsymmetric matrix A, the	eigenvalues,
  the real Schur form T, and, optionally, the matrix of	Schur vectors Z

SYNOPSIS

  SUBROUTINE DGEES( JOBVS, SORT, SELECT, N, A, LDA, SDIM, WR, WI, VS, LDVS,
		    WORK, LWORK, BWORK,	INFO )

      CHARACTER	    JOBVS, SORT

      INTEGER	    INFO, LDA, LDVS, LWORK, N, SDIM

      LOGICAL	    BWORK( * )

      DOUBLE	    PRECISION A( LDA, *	), VS( LDVS, * ), WI( *	), WORK( * ),
		    WR(	* )

      LOGICAL	    SELECT

      EXTERNAL	    SELECT

PURPOSE
  DGEES	computes for an	N-by-N real nonsymmetric matrix	A, the eigenvalues,
  the real Schur form T, and, optionally, the matrix of	Schur vectors Z.
  This gives the Schur factorization A = Z*T*(Z**T).

  Optionally, it also orders the eigenvalues on	the diagonal of	the real
  Schur	form so	that selected eigenvalues are at the top left.	The leading
  columns of Z then form an orthonormal	basis for the invariant	subspace
  corresponding	to the selected	eigenvalues.

  A matrix is in real Schur form if it is upper	quasi-triangular with 1-by-1
  and 2-by-2 blocks. 2-by-2 blocks will	be standardized	in the form
	  [  a	b  ]
	  [  c	a  ]

  where	b*c < 0. The eigenvalues of such a block are a +- sqrt(bc).

ARGUMENTS

  JOBVS	  (input) CHARACTER*1
	  = 'N': Schur vectors are not computed;
	  = 'V': Schur vectors are computed.

  SORT	  (input) CHARACTER*1
	  Specifies whether or not to order the	eigenvalues on the diagonal
	  of the Schur form.  =	'N': Eigenvalues are not ordered;
	  = 'S': Eigenvalues are ordered (see SELECT).

  SELECT  (input) LOGICAL FUNCTION of two DOUBLE PRECISION variables
	  SELECT must be declared EXTERNAL in the calling subroutine.  If
	  SORT = 'S', SELECT is	used to	select eigenvalues to sort to the top
	  left of the Schur form.  If SORT = 'N', SELECT is not	referenced.
	  An eigenvalue	WR(j)+sqrt(-1)*WI(j) is	selected if
	  SELECT(WR(j),WI(j)) is true; i.e., if	either one of a	complex	con-
	  jugate pair of eigenvalues is	selected, then both complex eigen-
	  values are selected.	Note that a selected complex eigenvalue	may
	  no longer satisfy SELECT(WR(j),WI(j))	= .TRUE. after ordering,
	  since	ordering may change the	value of complex eigenvalues (espe-
	  cially if the	eigenvalue is ill-conditioned);	in this	case INFO is
	  set to N+2 (see INFO below).

  N	  (input) INTEGER
	  The order of the matrix A. N >= 0.

  A	  (input/output) DOUBLE	PRECISION array, dimension (LDA,N)
	  On entry, the	N-by-N matrix A.  On exit, A has been overwritten by
	  its real Schur form T.

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

  SDIM	  (output) INTEGER
	  If SORT = 'N', SDIM =	0.  If SORT = 'S', SDIM	= number of eigen-
	  values (after	sorting) for which SELECT is true. (Complex conjugate
	  pairs	for which SELECT is true for either eigenvalue count as	2.)

  WR	  (output) DOUBLE PRECISION array, dimension (N)
	  WI	  (output) DOUBLE PRECISION array, dimension (N) WR and	WI
	  contain the real and imaginary parts,	respectively, of the computed
	  eigenvalues in the same order	that they appear on the	diagonal of
	  the output Schur form	T.  Complex conjugate pairs of eigenvalues
	  will appear consecutively with the eigenvalue	having the positive
	  imaginary part first.

  VS	  (output) DOUBLE PRECISION array, dimension (LDVS,N)
	  If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur vec-
	  tors.	 If JOBVS = 'N', VS is not referenced.

  LDVS	  (input) INTEGER
	  The leading dimension	of the array VS.  LDVS >= 1; if	JOBVS =	'V',
	  LDVS >= N.

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

  LWORK	  (input) INTEGER
	  The dimension	of the array WORK.  LWORK >= max(1,3*N).  For good
	  performance, LWORK must generally be larger.

  BWORK	  (workspace) LOGICAL array, dimension (N)
	  Not referenced if SORT = 'N'.

  INFO	  (output) INTEGER
	  = 0: successful exit
	  < 0: if INFO = -i, the i-th argument had an illegal value.
	  > 0: if INFO = i, and	i is
	  <= N:	the QR algorithm failed	to compute all the
	  eigenvalues; elements	1:ILO-1	and i+1:N of WR	and WI contain those
	  eigenvalues which have converged; if JOBVS = 'V', VS contains	the
	  matrix which reduces A to its	partially converged Schur form.	 =
	  N+1: the eigenvalues could not be reordered because some eigen-
	  values were too close	to separate (the problem is very ill-
	  conditioned);	= N+2: after reordering, roundoff changed values of
	  some complex eigenvalues so that leading eigenvalues in the Schur
	  form no longer satisfy SELECT=.TRUE.	This could also	be caused by
	  underflow due	to scaling.


Back to the listing of simple driver routines