--- 
:name: zhgeqz
:md5sum: abe28a9dc3cbffd9489f94d78eb0d905
:category: :subroutine
:arguments: 
- job: 
    :type: char
    :intent: input
- compq: 
    :type: char
    :intent: input
- compz: 
    :type: char
    :intent: input
- n: 
    :type: integer
    :intent: input
- ilo: 
    :type: integer
    :intent: input
- ihi: 
    :type: integer
    :intent: input
- h: 
    :type: doublecomplex
    :intent: input/output
    :dims: 
    - ldh
    - n
- ldh: 
    :type: integer
    :intent: input
- t: 
    :type: doublecomplex
    :intent: input/output
    :dims: 
    - ldt
    - n
- ldt: 
    :type: integer
    :intent: input
- alpha: 
    :type: doublecomplex
    :intent: output
    :dims: 
    - n
- beta: 
    :type: doublecomplex
    :intent: output
    :dims: 
    - n
- q: 
    :type: doublecomplex
    :intent: input/output
    :dims: 
    - ldq
    - n
- ldq: 
    :type: integer
    :intent: input
- z: 
    :type: doublecomplex
    :intent: input/output
    :dims: 
    - ldz
    - n
- ldz: 
    :type: integer
    :intent: input
- work: 
    :type: doublecomplex
    :intent: output
    :dims: 
    - MAX(1,lwork)
- lwork: 
    :type: integer
    :intent: input
    :option: true
    :default: n
- rwork: 
    :type: doublereal
    :intent: workspace
    :dims: 
    - n
- info: 
    :type: integer
    :intent: output
:substitutions: {}

:fortran_help: "      SUBROUTINE ZHGEQZ( JOB, COMPQ, COMPZ, N, ILO, IHI, H, LDH, T, LDT, ALPHA, BETA, Q, LDQ, Z, LDZ, WORK, LWORK, RWORK, INFO )\n\n\
  *  Purpose\n\
  *  =======\n\
  *\n\
  *  ZHGEQZ computes the eigenvalues of a complex matrix pair (H,T),\n\
  *  where H is an upper Hessenberg matrix and T is upper triangular,\n\
  *  using the single-shift QZ method.\n\
  *  Matrix pairs of this type are produced by the reduction to\n\
  *  generalized upper Hessenberg form of a complex matrix pair (A,B):\n\
  *  \n\
  *     A = Q1*H*Z1**H,  B = Q1*T*Z1**H,\n\
  *  \n\
  *  as computed by ZGGHRD.\n\
  *  \n\
  *  If JOB='S', then the Hessenberg-triangular pair (H,T) is\n\
  *  also reduced to generalized Schur form,\n\
  *  \n\
  *     H = Q*S*Z**H,  T = Q*P*Z**H,\n\
  *  \n\
  *  where Q and Z are unitary matrices and S and P are upper triangular.\n\
  *  \n\
  *  Optionally, the unitary matrix Q from the generalized Schur\n\
  *  factorization may be postmultiplied into an input matrix Q1, and the\n\
  *  unitary matrix Z may be postmultiplied into an input matrix Z1.\n\
  *  If Q1 and Z1 are the unitary matrices from ZGGHRD that reduced\n\
  *  the matrix pair (A,B) to generalized Hessenberg form, then the output\n\
  *  matrices Q1*Q and Z1*Z are the unitary factors from the generalized\n\
  *  Schur factorization of (A,B):\n\
  *  \n\
  *     A = (Q1*Q)*S*(Z1*Z)**H,  B = (Q1*Q)*P*(Z1*Z)**H.\n\
  *  \n\
  *  To avoid overflow, eigenvalues of the matrix pair (H,T)\n\
  *  (equivalently, of (A,B)) are computed as a pair of complex values\n\
  *  (alpha,beta).  If beta is nonzero, lambda = alpha / beta is an\n\
  *  eigenvalue of the generalized nonsymmetric eigenvalue problem (GNEP)\n\
  *     A*x = lambda*B*x\n\
  *  and if alpha is nonzero, mu = beta / alpha is an eigenvalue of the\n\
  *  alternate form of the GNEP\n\
  *     mu*A*y = B*y.\n\
  *  The values of alpha and beta for the i-th eigenvalue can be read\n\
  *  directly from the generalized Schur form:  alpha = S(i,i),\n\
  *  beta = P(i,i).\n\
  *\n\
  *  Ref: C.B. Moler & G.W. Stewart, \"An Algorithm for Generalized Matrix\n\
  *       Eigenvalue Problems\", SIAM J. Numer. Anal., 10(1973),\n\
  *       pp. 241--256.\n\
  *\n\n\
  *  Arguments\n\
  *  =========\n\
  *\n\
  *  JOB     (input) CHARACTER*1\n\
  *          = 'E': Compute eigenvalues only;\n\
  *          = 'S': Computer eigenvalues and the Schur form.\n\
  *\n\
  *  COMPQ   (input) CHARACTER*1\n\
  *          = 'N': Left Schur vectors (Q) are not computed;\n\
  *          = 'I': Q is initialized to the unit matrix and the matrix Q\n\
  *                 of left Schur vectors of (H,T) is returned;\n\
  *          = 'V': Q must contain a unitary matrix Q1 on entry and\n\
  *                 the product Q1*Q is returned.\n\
  *\n\
  *  COMPZ   (input) CHARACTER*1\n\
  *          = 'N': Right Schur vectors (Z) are not computed;\n\
  *          = 'I': Q is initialized to the unit matrix and the matrix Z\n\
  *                 of right Schur vectors of (H,T) is returned;\n\
  *          = 'V': Z must contain a unitary matrix Z1 on entry and\n\
  *                 the product Z1*Z is returned.\n\
  *\n\
  *  N       (input) INTEGER\n\
  *          The order of the matrices H, T, Q, and Z.  N >= 0.\n\
  *\n\
  *  ILO     (input) INTEGER\n\
  *  IHI     (input) INTEGER\n\
  *          ILO and IHI mark the rows and columns of H which are in\n\
  *          Hessenberg form.  It is assumed that A is already upper\n\
  *          triangular in rows and columns 1:ILO-1 and IHI+1:N.\n\
  *          If N > 0, 1 <= ILO <= IHI <= N; if N = 0, ILO=1 and IHI=0.\n\
  *\n\
  *  H       (input/output) COMPLEX*16 array, dimension (LDH, N)\n\
  *          On entry, the N-by-N upper Hessenberg matrix H.\n\
  *          On exit, if JOB = 'S', H contains the upper triangular\n\
  *          matrix S from the generalized Schur factorization.\n\
  *          If JOB = 'E', the diagonal of H matches that of S, but\n\
  *          the rest of H is unspecified.\n\
  *\n\
  *  LDH     (input) INTEGER\n\
  *          The leading dimension of the array H.  LDH >= max( 1, N ).\n\
  *\n\
  *  T       (input/output) COMPLEX*16 array, dimension (LDT, N)\n\
  *          On entry, the N-by-N upper triangular matrix T.\n\
  *          On exit, if JOB = 'S', T contains the upper triangular\n\
  *          matrix P from the generalized Schur factorization.\n\
  *          If JOB = 'E', the diagonal of T matches that of P, but\n\
  *          the rest of T is unspecified.\n\
  *\n\
  *  LDT     (input) INTEGER\n\
  *          The leading dimension of the array T.  LDT >= max( 1, N ).\n\
  *\n\
  *  ALPHA   (output) COMPLEX*16 array, dimension (N)\n\
  *          The complex scalars alpha that define the eigenvalues of\n\
  *          GNEP.  ALPHA(i) = S(i,i) in the generalized Schur\n\
  *          factorization.\n\
  *\n\
  *  BETA    (output) COMPLEX*16 array, dimension (N)\n\
  *          The real non-negative scalars beta that define the\n\
  *          eigenvalues of GNEP.  BETA(i) = P(i,i) in the generalized\n\
  *          Schur factorization.\n\
  *\n\
  *          Together, the quantities alpha = ALPHA(j) and beta = BETA(j)\n\
  *          represent the j-th eigenvalue of the matrix pair (A,B), in\n\
  *          one of the forms lambda = alpha/beta or mu = beta/alpha.\n\
  *          Since either lambda or mu may overflow, they should not,\n\
  *          in general, be computed.\n\
  *\n\
  *  Q       (input/output) COMPLEX*16 array, dimension (LDQ, N)\n\
  *          On entry, if COMPZ = 'V', the unitary matrix Q1 used in the\n\
  *          reduction of (A,B) to generalized Hessenberg form.\n\
  *          On exit, if COMPZ = 'I', the unitary matrix of left Schur\n\
  *          vectors of (H,T), and if COMPZ = 'V', the unitary matrix of\n\
  *          left Schur vectors of (A,B).\n\
  *          Not referenced if COMPZ = 'N'.\n\
  *\n\
  *  LDQ     (input) INTEGER\n\
  *          The leading dimension of the array Q.  LDQ >= 1.\n\
  *          If COMPQ='V' or 'I', then LDQ >= N.\n\
  *\n\
  *  Z       (input/output) COMPLEX*16 array, dimension (LDZ, N)\n\
  *          On entry, if COMPZ = 'V', the unitary matrix Z1 used in the\n\
  *          reduction of (A,B) to generalized Hessenberg form.\n\
  *          On exit, if COMPZ = 'I', the unitary matrix of right Schur\n\
  *          vectors of (H,T), and if COMPZ = 'V', the unitary matrix of\n\
  *          right Schur vectors of (A,B).\n\
  *          Not referenced if COMPZ = 'N'.\n\
  *\n\
  *  LDZ     (input) INTEGER\n\
  *          The leading dimension of the array Z.  LDZ >= 1.\n\
  *          If COMPZ='V' or 'I', then LDZ >= N.\n\
  *\n\
  *  WORK    (workspace/output) COMPLEX*16 array, dimension (MAX(1,LWORK))\n\
  *          On exit, if INFO >= 0, WORK(1) returns the optimal LWORK.\n\
  *\n\
  *  LWORK   (input) INTEGER\n\
  *          The dimension of the array WORK.  LWORK >= max(1,N).\n\
  *\n\
  *          If LWORK = -1, then a workspace query is assumed; the routine\n\
  *          only calculates the optimal size of the WORK array, returns\n\
  *          this value as the first entry of the WORK array, and no error\n\
  *          message related to LWORK is issued by XERBLA.\n\
  *\n\
  *  RWORK   (workspace) DOUBLE PRECISION array, dimension (N)\n\
  *\n\
  *  INFO    (output) INTEGER\n\
  *          = 0: successful exit\n\
  *          < 0: if INFO = -i, the i-th argument had an illegal value\n\
  *          = 1,...,N: the QZ iteration did not converge.  (H,T) is not\n\
  *                     in Schur form, but ALPHA(i) and BETA(i),\n\
  *                     i=INFO+1,...,N should be correct.\n\
  *          = N+1,...,2*N: the shift calculation failed.  (H,T) is not\n\
  *                     in Schur form, but ALPHA(i) and BETA(i),\n\
  *                     i=INFO-N+1,...,N should be correct.\n\
  *\n\n\
  *  Further Details\n\
  *  ===============\n\
  *\n\
  *  We assume that complex ABS works as long as its value is less than\n\
  *  overflow.\n\
  *\n\
  *  =====================================================================\n\
  *\n"
