--- 
:name: dgges
:md5sum: 3eca96ecb9c176b7624b865b6032c1e7
:category: :subroutine
:arguments: 
- jobvsl: 
    :type: char
    :intent: input
- jobvsr: 
    :type: char
    :intent: input
- sort: 
    :type: char
    :intent: input
- selctg: 
    :intent: external procedure
    :block_type: logical
    :block_arg_num: 3
    :block_arg_type: doublereal
- n: 
    :type: integer
    :intent: input
- a: 
    :type: doublereal
    :intent: input/output
    :dims: 
    - lda
    - n
- lda: 
    :type: integer
    :intent: input
- b: 
    :type: doublereal
    :intent: input/output
    :dims: 
    - ldb
    - n
- ldb: 
    :type: integer
    :intent: input
- sdim: 
    :type: integer
    :intent: output
- alphar: 
    :type: doublereal
    :intent: output
    :dims: 
    - n
- alphai: 
    :type: doublereal
    :intent: output
    :dims: 
    - n
- beta: 
    :type: doublereal
    :intent: output
    :dims: 
    - n
- vsl: 
    :type: doublereal
    :intent: output
    :dims: 
    - ldvsl
    - n
- ldvsl: 
    :type: integer
    :intent: input
- vsr: 
    :type: doublereal
    :intent: output
    :dims: 
    - ldvsr
    - n
- ldvsr: 
    :type: integer
    :intent: input
- work: 
    :type: doublereal
    :intent: output
    :dims: 
    - MAX(1,lwork)
- lwork: 
    :type: integer
    :intent: input
    :option: true
    :default: MAX(8*n,6*n+16)
- bwork: 
    :type: logical
    :intent: workspace
    :dims: 
    - "lsame_(&sort,\"N\") ? 0 : n"
- info: 
    :type: integer
    :intent: output
:substitutions: 
  ldvsl: "lsame_(&jobvsl,\"V\") ? n : 1"
  ldvsr: "lsame_(&jobvsr,\"V\") ? n : 1"
:fortran_help: "      SUBROUTINE DGGES( JOBVSL, JOBVSR, SORT, SELCTG, N, A, LDA, B, LDB, SDIM, ALPHAR, ALPHAI, BETA, VSL, LDVSL, VSR, LDVSR, WORK, LWORK, BWORK, INFO )\n\n\
  *  Purpose\n\
  *  =======\n\
  *\n\
  *  DGGES computes for a pair of N-by-N real nonsymmetric matrices (A,B),\n\
  *  the generalized eigenvalues, the generalized real Schur form (S,T),\n\
  *  optionally, the left and/or right matrices of Schur vectors (VSL and\n\
  *  VSR). This gives the generalized Schur factorization\n\
  *\n\
  *           (A,B) = ( (VSL)*S*(VSR)**T, (VSL)*T*(VSR)**T )\n\
  *\n\
  *  Optionally, it also orders the eigenvalues so that a selected cluster\n\
  *  of eigenvalues appears in the leading diagonal blocks of the upper\n\
  *  quasi-triangular matrix S and the upper triangular matrix T.The\n\
  *  leading columns of VSL and VSR then form an orthonormal basis for the\n\
  *  corresponding left and right eigenspaces (deflating subspaces).\n\
  *\n\
  *  (If only the generalized eigenvalues are needed, use the driver\n\
  *  DGGEV instead, which is faster.)\n\
  *\n\
  *  A generalized eigenvalue for a pair of matrices (A,B) is a scalar w\n\
  *  or a ratio alpha/beta = w, such that  A - w*B is singular.  It is\n\
  *  usually represented as the pair (alpha,beta), as there is a\n\
  *  reasonable interpretation for beta=0 or both being zero.\n\
  *\n\
  *  A pair of matrices (S,T) is in generalized real Schur form if T is\n\
  *  upper triangular with non-negative diagonal and S is block upper\n\
  *  triangular with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond\n\
  *  to real generalized eigenvalues, while 2-by-2 blocks of S will be\n\
  *  \"standardized\" by making the corresponding elements of T have the\n\
  *  form:\n\
  *          [  a  0  ]\n\
  *          [  0  b  ]\n\
  *\n\
  *  and the pair of corresponding 2-by-2 blocks in S and T will have a\n\
  *  complex conjugate pair of generalized eigenvalues.\n\
  *\n\
  *\n\n\
  *  Arguments\n\
  *  =========\n\
  *\n\
  *  JOBVSL  (input) CHARACTER*1\n\
  *          = 'N':  do not compute the left Schur vectors;\n\
  *          = 'V':  compute the left Schur vectors.\n\
  *\n\
  *  JOBVSR  (input) CHARACTER*1\n\
  *          = 'N':  do not compute the right Schur vectors;\n\
  *          = 'V':  compute the right Schur vectors.\n\
  *\n\
  *  SORT    (input) CHARACTER*1\n\
  *          Specifies whether or not to order the eigenvalues on the\n\
  *          diagonal of the generalized Schur form.\n\
  *          = 'N':  Eigenvalues are not ordered;\n\
  *          = 'S':  Eigenvalues are ordered (see SELCTG);\n\
  *\n\
  *  SELCTG  (external procedure) LOGICAL FUNCTION of three DOUBLE PRECISION arguments\n\
  *          SELCTG must be declared EXTERNAL in the calling subroutine.\n\
  *          If SORT = 'N', SELCTG is not referenced.\n\
  *          If SORT = 'S', SELCTG is used to select eigenvalues to sort\n\
  *          to the top left of the Schur form.\n\
  *          An eigenvalue (ALPHAR(j)+ALPHAI(j))/BETA(j) is selected if\n\
  *          SELCTG(ALPHAR(j),ALPHAI(j),BETA(j)) is true; i.e. if either\n\
  *          one of a complex conjugate pair of eigenvalues is selected,\n\
  *          then both complex eigenvalues are selected.\n\
  *\n\
  *          Note that in the ill-conditioned case, a selected complex\n\
  *          eigenvalue may no longer satisfy SELCTG(ALPHAR(j),ALPHAI(j),\n\
  *          BETA(j)) = .TRUE. after ordering. INFO is to be set to N+2\n\
  *          in this case.\n\
  *\n\
  *  N       (input) INTEGER\n\
  *          The order of the matrices A, B, VSL, and VSR.  N >= 0.\n\
  *\n\
  *  A       (input/output) DOUBLE PRECISION array, dimension (LDA, N)\n\
  *          On entry, the first of the pair of matrices.\n\
  *          On exit, A has been overwritten by its generalized Schur\n\
  *          form S.\n\
  *\n\
  *  LDA     (input) INTEGER\n\
  *          The leading dimension of A.  LDA >= max(1,N).\n\
  *\n\
  *  B       (input/output) DOUBLE PRECISION array, dimension (LDB, N)\n\
  *          On entry, the second of the pair of matrices.\n\
  *          On exit, B has been overwritten by its generalized Schur\n\
  *          form T.\n\
  *\n\
  *  LDB     (input) INTEGER\n\
  *          The leading dimension of B.  LDB >= max(1,N).\n\
  *\n\
  *  SDIM    (output) INTEGER\n\
  *          If SORT = 'N', SDIM = 0.\n\
  *          If SORT = 'S', SDIM = number of eigenvalues (after sorting)\n\
  *          for which SELCTG is true.  (Complex conjugate pairs for which\n\
  *          SELCTG is true for either eigenvalue count as 2.)\n\
  *\n\
  *  ALPHAR  (output) DOUBLE PRECISION array, dimension (N)\n\
  *  ALPHAI  (output) DOUBLE PRECISION array, dimension (N)\n\
  *  BETA    (output) DOUBLE PRECISION array, dimension (N)\n\
  *          On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will\n\
  *          be the generalized eigenvalues.  ALPHAR(j) + ALPHAI(j)*i,\n\
  *          and  BETA(j),j=1,...,N are the diagonals of the complex Schur\n\
  *          form (S,T) that would result if the 2-by-2 diagonal blocks of\n\
  *          the real Schur form of (A,B) were further reduced to\n\
  *          triangular form using 2-by-2 complex unitary transformations.\n\
  *          If ALPHAI(j) is zero, then the j-th eigenvalue is real; if\n\
  *          positive, then the j-th and (j+1)-st eigenvalues are a\n\
  *          complex conjugate pair, with ALPHAI(j+1) negative.\n\
  *\n\
  *          Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j)\n\
  *          may easily over- or underflow, and BETA(j) may even be zero.\n\
  *          Thus, the user should avoid naively computing the ratio.\n\
  *          However, ALPHAR and ALPHAI will be always less than and\n\
  *          usually comparable with norm(A) in magnitude, and BETA always\n\
  *          less than and usually comparable with norm(B).\n\
  *\n\
  *  VSL     (output) DOUBLE PRECISION array, dimension (LDVSL,N)\n\
  *          If JOBVSL = 'V', VSL will contain the left Schur vectors.\n\
  *          Not referenced if JOBVSL = 'N'.\n\
  *\n\
  *  LDVSL   (input) INTEGER\n\
  *          The leading dimension of the matrix VSL. LDVSL >=1, and\n\
  *          if JOBVSL = 'V', LDVSL >= N.\n\
  *\n\
  *  VSR     (output) DOUBLE PRECISION array, dimension (LDVSR,N)\n\
  *          If JOBVSR = 'V', VSR will contain the right Schur vectors.\n\
  *          Not referenced if JOBVSR = 'N'.\n\
  *\n\
  *  LDVSR   (input) INTEGER\n\
  *          The leading dimension of the matrix VSR. LDVSR >= 1, and\n\
  *          if JOBVSR = 'V', LDVSR >= N.\n\
  *\n\
  *  WORK    (workspace/output) DOUBLE PRECISION 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.\n\
  *          If N = 0, LWORK >= 1, else LWORK >= 8*N+16.\n\
  *          For good performance , LWORK must generally be larger.\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\
  *  BWORK   (workspace) LOGICAL array, dimension (N)\n\
  *          Not referenced if SORT = '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:\n\
  *                The QZ iteration failed.  (A,B) are not in Schur\n\
  *                form, but ALPHAR(j), ALPHAI(j), and BETA(j) should\n\
  *                be correct for j=INFO+1,...,N.\n\
  *          > N:  =N+1: other than QZ iteration failed in DHGEQZ.\n\
  *                =N+2: after reordering, roundoff changed values of\n\
  *                      some complex eigenvalues so that leading\n\
  *                      eigenvalues in the Generalized Schur form no\n\
  *                      longer satisfy SELCTG=.TRUE.  This could also\n\
  *                      be caused due to scaling.\n\
  *                =N+3: reordering failed in DTGSEN.\n\
  *\n\n\
  *  =====================================================================\n\
  *\n"
