CHSEIN(l)		LAPACK routine (version	1.1)		    CHSEIN(l)

NAME
  CHSEIN - use inverse iteration to find specified right and/or	left eigen-
  vectors of a complex upper Hessenberg	matrix H

SYNOPSIS

  SUBROUTINE CHSEIN( JOB, EIGSRC, INITV, SELECT, N, H, LDH, W, VL, LDVL, VR,
		     LDVR, MM, M, WORK,	RWORK, IFAILL, IFAILR, INFO )

      CHARACTER	     EIGSRC, INITV, JOB

      INTEGER	     INFO, LDH,	LDVL, LDVR, M, MM, N

      LOGICAL	     SELECT( * )

      INTEGER	     IFAILL( * ), IFAILR( * )

      REAL	     RWORK( * )

      COMPLEX	     H(	LDH, * ), VL( LDVL, * ), VR( LDVR, * ),	W( * ),	WORK(
		     * )

PURPOSE
  CHSEIN uses inverse iteration	to find	specified right	and/or left eigenvec-
  tors of a complex upper Hessenberg matrix H.

  The right eigenvector	x and the left eigenvector y of	the matrix H
  corresponding	to an eigenvalue w are defined by:

	       H x = w x,     y' H = w y'

  where	y' denotes the conjugate transpose of the vector y.

ARGUMENTS

  JOB	  (input) CHARACTER*1
	  = 'R': compute right eigenvectors only;
	  = 'L': compute left eigenvectors only;
	  = 'B': compute both right and	left eigenvectors.

  EIGSRC  (input) CHARACTER*1
	  Specifies the	source of eigenvalues supplied in W:
	  = 'Q': the eigenvalues were found using CHSEQR; thus,	if H has zero
	  subdiagonal elements,	and so is block-triangular, then the j-th
	  eigenvalue can be assumed to be an eigenvalue	of the block contain-
	  ing the j-th row/column.  This property allows CHSEIN	to perform
	  inverse iteration on just one	diagonal block.	 = 'N':	no assump-
	  tions	are made on the	correspondence between eigenvalues and diago-
	  nal blocks.  In this case, CHSEIN must always	perform	inverse
	  iteration using the whole matrix H.

  INITV	  (input) CHARACTER*1
	  = 'N': no initial vectors are	supplied;
	  = 'U': user-supplied initial vectors are stored in the arrays	VL
	  and/or VR.

  SELECT  (input) LOGICAL array, dimension (N)
	  Specifies the	eigenvectors to	be computed. To	select the
	  eigenvector corresponding to the eigenvalue W(j), SELECT(j) must be
	  set to .TRUE..

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

  H	  (input) COMPLEX array, dimension (LDH,N)
	  The upper Hessenberg matrix H.

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

  W	  (input/output) COMPLEX array,	dimension (N)
	  On entry, the	eigenvalues of H.  On exit, the	real parts of W	may
	  have been altered since close	eigenvalues are	perturbed slightly in
	  searching for	independent eigenvectors.

  VL	  (input/output) COMPLEX array,	dimension (LDVL,MM)
	  On entry, if INITV = 'U' and JOB = 'L' or 'B', VL must contain
	  starting vectors for the inverse iteration for the left eigenvec-
	  tors;	the starting vector for	each eigenvector must be in the	same
	  column in which the eigenvector will be stored.  On exit, if JOB =
	  'L' or 'B', the left eigenvectors specified by SELECT	will be
	  stored consecutively in the columns of VL, in	the same order as
	  their	eigenvalues.  If JOB = 'R', VL is not referenced.

  LDVL	  (input) INTEGER
	  The leading dimension	of the array VL.  LDVL >= max(1,N) if JOB =
	  'L' or 'B'; LDVL >= 1	otherwise.

  VR	  (input/output) COMPLEX array,	dimension (LDVR,MM)
	  On entry, if INITV = 'U' and JOB = 'R' or 'B', VR must contain
	  starting vectors for the inverse iteration for the right eigenvec-
	  tors;	the starting vector for	each eigenvector must be in the	same
	  column in which the eigenvector will be stored.  On exit, if JOB =
	  'R' or 'B', the right	eigenvectors specified by SELECT will be
	  stored consecutively in the columns of VR, in	the same order as
	  their	eigenvalues.  If JOB = 'L', VR is not referenced.

  LDVR	  (input) INTEGER
	  The leading dimension	of the array VR.  LDVR >= max(1,N) if JOB =
	  'R' or 'B'; LDVR >= 1	otherwise.

  MM	  (input) INTEGER
	  The number of	columns	in the arrays VL and/or	VR. MM >= M.

  M	  (output) INTEGER
	  The number of	columns	in the arrays VL and/or	VR required to store
	  the eigenvectors (= the number of .TRUE. elements in SELECT).

  WORK	  (workspace) COMPLEX array, dimension (N*N)

  RWORK	  (workspace) REAL array, dimension (N)

  IFAILL  (output) INTEGER array, dimension (MM)
	  If JOB = 'L' or 'B', IFAILL(i) = j > 0 if the	left eigenvector in
	  the i-th column of VL	(corresponding to the eigenvalue w(j)) failed
	  to converge; IFAILL(i) = 0 if	the eigenvector	converged satisfac-
	  torily.  If JOB = 'R', IFAILL	is not referenced.

  IFAILR  (output) INTEGER array, dimension (MM)
	  If JOB = 'R' or 'B', IFAILR(i) = j > 0 if the	right eigenvector in
	  the i-th column of VR	(corresponding to the eigenvalue w(j)) failed
	  to converge; IFAILR(i) = 0 if	the eigenvector	converged satisfac-
	  torily.  If JOB = 'L', IFAILR	is not referenced.

  INFO	  (output) INTEGER
	  = 0:	successful exit
	  < 0:	if INFO	= -i, the i-th argument	had an illegal value
	  > 0:	if INFO	= i, i is the number of	eigenvectors which failed to
	  converge; see	IFAILL and IFAILR for further details.

FURTHER	DETAILS
  Each eigenvector is normalized so that the element of	largest	magnitude has
  magnitude 1; here the	magnitude of a complex number (x,y) is taken to	be
  |x|+|y|.


Back to the listing of computational routines for eigenvalue problems