TG01PD - SLICOT Library Routine Documentation

## TG01PD

### Bi-domain spectral splitting of a subpencil of a descriptor system

[Specification] [Arguments] [Method] [References] [Comments] [Example]

Purpose

      To compute orthogonal transformation matrices Q and Z which
      reduce the regular pole pencil A-lambda*E of the descriptor system
      (A-lambda*E,B,C) to the generalized real Schur form with ordered
      generalized eigenvalues. The pair (A,E) is reduced to the form

                 ( *  *  *  * )             ( *  *  *  * )
                 (            )             (            )
                 ( 0  A1 *  * )             ( 0  E1 *  * )
        Q'*A*Z = (            ) ,  Q'*E*Z = (            ) ,
                 ( 0  0  A2 * )             ( 0  0  E2 * )
                 (            )             (            )
                 ( 0  0  0  * )             ( 0  0  0  * )

      where the subpencil A1-lambda*E1 contains the eigenvalues which
      belong to a suitably defined domain of interest and the subpencil
      A2-lambda*E2 contains the eigenvalues which are outside of the
      domain of interest.
      If JOBAE = 'S', the pair (A,E) is assumed to be already in a
      generalized real Schur form and the reduction is performed only
      on the subpencil A12 - lambda*E12 defined by rows and columns
      NLOW to NSUP of A - lambda*E.

Specification

          SUBROUTINE TG01PD( DICO, STDOM, JOBAE, COMPQ, COMPZ, N, M, P,
         $                   NLOW, NSUP, ALPHA, A, LDA, E, LDE, B, LDB,
         $                   C, LDC, Q, LDQ, Z, LDZ, NDIM, ALPHAR, ALPHAI,
         $                   BETA, DWORK, LDWORK, INFO )
    C     .. Scalar Arguments ..
          CHARACTER        COMPQ, COMPZ, DICO, JOBAE, STDOM
          INTEGER          INFO, LDA, LDB, LDC, LDE, LDQ, LDWORK, LDZ, M, N,
         $                 NDIM, NLOW, NSUP, P
          DOUBLE PRECISION ALPHA
    C     .. Array Arguments ..
          DOUBLE PRECISION A(LDA,*), ALPHAI(*), ALPHAR(*), B(LDB,*),
         $                 BETA(*),  C(LDC,*),  DWORK(*),  E(LDE,*),
         $                 Q(LDQ,*), Z(LDZ,*)

Arguments

Mode Parameters

      DICO    CHARACTER*1
              Specifies the type of the descriptor system as follows:
              = 'C':  continuous-time system;
              = 'D':  discrete-time system.

      STDOM   CHARACTER*1
              Specifies whether the domain of interest is of stability
              type (left part of complex plane or inside of a circle)
              or of instability type (right part of complex plane or
              outside of a circle) as follows:
              = 'S':  stability type domain;
              = 'U':  instability type domain.

      JOBAE   CHARACTER*1
              Specifies the shape of the matrix pair (A,E) on entry
              as follows:
              = 'S':  (A,E) is in a generalized real Schur form;
              = 'G':  A and E are general square dense matrices.

      COMPQ   CHARACTER*1
              = 'I':  Q is initialized to the unit matrix, and the
                      orthogonal matrix Q is returned;
              = 'U':  Q must contain an orthogonal matrix Q1 on entry,
                      and the product Q1*Q is returned.
                      This option can not be used when JOBAE = 'G'.

      COMPZ   CHARACTER*1
              = 'I':  Z is initialized to the unit matrix, and the
                      orthogonal matrix Z is returned;
              = 'U':  Z must contain an orthogonal matrix Z1 on entry,
                      and the product Z1*Z is returned.
                      This option can not be used when JOBAE = 'G'.

Input/Output Parameters

      N       (input) INTEGER
              The number of rows of the matrix B, the number of columns
              of the matrix C, and the order of the square matrices A
              and E.  N >= 0.

      M       (input) INTEGER
              The number of columns of the matrix B.  M >= 0.

      P       (input) INTEGER
              The number of rows of the matrix C.  P >= 0.

      NLOW,   (input) INTEGER
      NSUP    (input) INTEGER
              NLOW and NSUP specify the boundary indices for the rows
              and columns of the principal subpencil of A - lambda*E
              whose diagonal blocks are to be reordered.
              0 <= NLOW <= NSUP <= N,       if JOBAE = 'S'.
              NLOW = MIN( 1, N ), NSUP = N, if JOBAE = 'G'.

      ALPHA   (input) DOUBLE PRECISION
              The boundary of the domain of interest for the generalized
              eigenvalues of the pair (A,E). For a continuous-time
              system (DICO = 'C'), ALPHA is the boundary value for the
              real parts of the generalized eigenvalues, while for a
              discrete-time system (DICO = 'D'), ALPHA >= 0 represents
              the boundary value for the moduli of the generalized
              eigenvalues.

      A       (input/output) DOUBLE PRECISION array, dimension (LDA,N)
              On entry, the leading N-by-N part of this array must
              contain the state dynamics matrix A.
              If JOBAE = 'S' then A must be a matrix in real Schur form.
              On exit, the leading N-by-N part of this array contains
              the matrix Q'*A*Z in real Schur form, with the elements
              below the first subdiagonal set to zero.
              The leading NDIM-by-NDIM part of the principal subpencil
              A12 - lambda*E12, defined by A12 := A(NLOW:NSUP,NLOW:NSUP)
              and E12 := E(NLOW:NSUP,NLOW:NSUP), has generalized
              eigenvalues in the domain of interest, and the trailing
              part of this subpencil has generalized eigenvalues outside
              the domain of interest.
              The domain of interest for eig(A12,E12), the generalized
              eigenvalues of the pair (A12,E12), is defined by the
              parameters ALPHA, DICO and STDOM as follows:
                For DICO = 'C':
                   Real(eig(A12,E12)) < ALPHA if STDOM = 'S';
                   Real(eig(A12,E12)) > ALPHA if STDOM = 'U'.
                For DICO = 'D':
                   Abs(eig(A12,E12)) < ALPHA if STDOM = 'S';
                   Abs(eig(A12,E12)) > ALPHA if STDOM = 'U'.

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

      E       (input/output) DOUBLE PRECISION array, dimension (LDE,N)
              On entry, the leading N-by-N part of this array must
              contain the descriptor matrix E.
              If JOBAE = 'S', then E must be an upper triangular matrix.
              On exit, the leading N-by-N part of this array contains an
              upper triangular matrix Q'*E*Z, with the elements below
              the diagonal set to zero.
              The leading NDIM-by-NDIM part of the principal subpencil
              A12 - lambda*E12 (see description of A) has generalized
              eigenvalues in the domain of interest, and the trailing
              part of this subpencil has generalized eigenvalues outside
              the domain of interest.

      LDE     INTEGER
              The leading dimension of the array E.  LDE >= MAX(1,N).

      B       (input/output) DOUBLE PRECISION array, dimension (LDB,M)
              On entry, the leading N-by-M part of this array must
              contain the input matrix B.
              On exit, the leading N-by-M part of this array contains
              the transformed input matrix Q'*B.

      LDB     INTEGER
              The leading dimension of the array B.  LDB >= MAX(1,N).

      C       (input/output) DOUBLE PRECISION array, dimension (LDC,N)
              On entry, the leading P-by-N part of this array must
              contain the output matrix C.
              On exit, the leading P-by-N part of this array contains
              the transformed output matrix C*Z.

      LDC     INTEGER
              The leading dimension of the array C.  LDC >= MAX(1,P).

      Q       (input/output) DOUBLE PRECISION array, dimension (LDQ,N)
              If COMPQ = 'I':  on entry, Q need not be set;
                               on exit, the leading N-by-N part of this
                               array contains the orthogonal matrix Q,
                               where Q' is the product of orthogonal
                               transformations which are applied to A,
                               E, and B on the left.
              If COMPQ = 'U':  on entry, the leading N-by-N part of this
                               array must contain an orthogonal matrix
                               Q1;
                               on exit, the leading N-by-N part of this
                               array contains the orthogonal matrix
                               Q1*Q.

      LDQ     INTEGER
              The leading dimension of the array Q. LDQ >= MAX(1,N).

      Z       (input/output) DOUBLE PRECISION array, dimension (LDZ,N)
              If COMPZ = 'I':  on entry, Z need not be set;
                               on exit, the leading N-by-N part of this
                               array contains the orthogonal matrix Z,
                               which is the product of orthogonal
                               transformations applied to A, E, and C
                               on the right.
              If COMPZ = 'U':  on entry, the leading N-by-N part of this
                               array must contain an orthogonal matrix
                               Z1;
                               on exit, the leading N-by-N part of this
                               array contains the orthogonal matrix
                               Z1*Z.

      LDZ     INTEGER
              The leading dimension of the array Z. LDZ >= MAX(1,N).

      NDIM    (output) INTEGER
              The number of generalized eigenvalues of the principal
              subpencil A12 - lambda*E12 (see description of A) lying
              inside the domain of interest for eigenvalues.

      ALPHAR  (output) DOUBLE PRECISION array, dimension (N)
      ALPHAI  (output) DOUBLE PRECISION array, dimension (N)
      BETA    (output) DOUBLE PRECISION array, dimension (N)
              On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N,
              are the generalized eigenvalues.
              ALPHAR(j) + ALPHAI(j)*i, and BETA(j), j = 1,...,N, are the
              diagonals of the complex Schur form (S,T) that would
              result if the 2-by-2 diagonal blocks of the real Schur
              form of (A,B) were further reduced to triangular form
              using 2-by-2 complex unitary transformations.
              If ALPHAI(j) is zero, then the j-th eigenvalue is real;
              if positive, then the j-th and (j+1)-st eigenvalues are a
              complex conjugate pair, with ALPHAI(j+1) negative.

Workspace

      DWORK   DOUBLE PRECISION array, dimension (LDWORK)
              On exit, if INFO = 0, DWORK(1) returns the optimal value
              of LDWORK.

      LDWORK  INTEGER
              The length of the array DWORK.
              LDWORK >= 8*N+16, if JOBAE = 'G';
              LDWORK >= 4*N+16, if JOBAE = 'S'.
              For optimum performance LDWORK should be larger.

              If LDWORK = -1, then a workspace query is assumed; the
              routine only calculates the optimal size of the DWORK
              array, returns this value as the first entry of the DWORK
              array, and no error message related to LDWORK is issued by
              XERBLA.

Error Indicator

      INFO    INTEGER
              = 0:  successful exit;
              < 0:  if INFO = -i, the i-th argument had an illegal
                    value;
              = 1:  the QZ algorithm failed to compute all generalized
                    eigenvalues of the pair (A,E);
              = 2:  a failure occured during the ordering of the
                    generalized real Schur form of the pair (A,E).

Method

      If JOBAE = 'G', the pair (A,E) is reduced to an ordered
      generalized real Schur form using an orthogonal equivalence
      transformation A <-- Q'*A*Z and E <-- Q'*E*Z. This transformation
      is determined so that the leading diagonal blocks of the resulting
      pair (A,E) have generalized eigenvalues in a suitably defined
      domain of interest. Then, the transformations are applied to the
      matrices B and C: B <-- Q'*B and C <-- C*Z.
      If JOBAE = 'S', then the diagonal blocks of the subpencil
      A12 - lambda*E12, defined by A12 := A(NLOW:NSUP,NLOW:NSUP)
      and E12 := E(NLOW:NSUP,NLOW:NSUP), are reordered using orthogonal
      equivalence transformations, such that the leading blocks have
      generalized eigenvalues in a suitably defined domain of interest.

Numerical Aspects

                                      3
      The algorithm requires about 25N  floating point operations.

Further Comments

      None

Example

Program Text

    *     TG01PD EXAMPLE PROGRAM TEXT
    *
    *     .. Parameters ..
          DOUBLE PRECISION ZERO
          PARAMETER        ( ZERO = 0.0D0 )
          INTEGER          NIN, NOUT
          PARAMETER        ( NIN = 5, NOUT = 6 )
          INTEGER          NMAX, MMAX, PMAX
          PARAMETER        ( NMAX = 20, MMAX = 20, PMAX = 20 )
          INTEGER          LDA, LDB, LDC, LDE, LDQ, LDZ
          PARAMETER        ( LDA = NMAX, LDB = NMAX, LDC = PMAX,
         $                   LDE = NMAX, LDQ = NMAX, LDZ = NMAX )
          INTEGER          LDWORK
          PARAMETER        ( LDWORK = 8*NMAX+16 )
    *     .. Local Scalars ..
          CHARACTER*1      COMPQ, COMPZ, DICO, JOBAE, STDOM
          INTEGER          I, INFO, J, M, N, NDIM, NLOW, NSUP, P
          DOUBLE PRECISION ALPHA, TOL
    *     .. Local Arrays ..
          DOUBLE PRECISION A(LDA,NMAX),  ALPHAI(NMAX), ALPHAR(NMAX),
         $                 B(LDB,MMAX),    BETA(NMAX), C(LDC,NMAX),
         $                 DWORK(LDWORK), E(LDE,NMAX), Q(LDQ,NMAX),
         $                 Z(LDZ,NMAX)
    *     .. External Functions ..
          LOGICAL          LSAME
          EXTERNAL         LSAME
    *     .. External Subroutines ..
          EXTERNAL         TG01PD
    *     .. Intrinsic Functions ..
          INTRINSIC        DCMPLX
    *     .. Executable Statements ..
    *
          WRITE ( NOUT, FMT = 99999 )
    *     Skip the heading in the data file and read the data.
          READ ( NIN, FMT = '()' )
          READ ( NIN, FMT = * ) N, M, P, DICO, STDOM, JOBAE, COMPQ, COMPZ,
         $                      NLOW, NSUP, ALPHA, TOL
          IF ( N.LT.0 .OR. N.GT.NMAX ) THEN
             WRITE ( NOUT, FMT = 99988 ) N
          ELSE
             READ ( NIN, FMT = * ) ( ( A(I,J), J = 1,N ), I = 1,N )
             READ ( NIN, FMT = * ) ( ( E(I,J), J = 1,N ), I = 1,N )
             IF ( M.LT.0 .OR. M.GT.MMAX ) THEN
                WRITE ( NOUT, FMT = 99987 ) M
             ELSE
                READ ( NIN, FMT = * ) ( ( B(I,J), J = 1,M ), I = 1,N )
                IF ( P.LT.0 .OR. P.GT.PMAX ) THEN
                   WRITE ( NOUT, FMT = 99986 ) P
                ELSE
                   READ ( NIN, FMT = * ) ( ( C(I,J), J = 1,N ), I = 1,P )
                   IF ( LSAME( COMPQ, 'U' ) )
         $            READ ( NIN, FMT = * ) ( ( Q(I,J), J = 1,N ), I = 1,N )
                   IF ( LSAME( COMPZ, 'U' ) )
         $            READ ( NIN, FMT = * ) ( ( Z(I,J), J = 1,N ), I = 1,N )
    *              Find the reduced descriptor system
    *              (A-lambda E,B,C).
                   CALL TG01PD( DICO, STDOM, JOBAE, COMPQ, COMPZ, N, M, P,
         $                      NLOW, NSUP, ALPHA, A, LDA, E, LDE, B, LDB,
         $                      C, LDC, Q, LDQ, Z, LDZ, NDIM, ALPHAR,
         $                      ALPHAI, BETA, DWORK, LDWORK, INFO )
    *
                   IF ( INFO.NE.0 ) THEN
                      WRITE ( NOUT, FMT = 99998 ) INFO
                   ELSE
                      WRITE ( NOUT, FMT = 99994 ) NDIM
                      WRITE ( NOUT, FMT = 99997 )
                      DO 10 I = 1, N
                         WRITE ( NOUT, FMT = 99995 ) ( A(I,J), J = 1,N )
       10             CONTINUE
                      WRITE ( NOUT, FMT = 99996 )
                      DO 20 I = 1, N
                         WRITE ( NOUT, FMT = 99995 ) ( E(I,J), J = 1,N )
       20             CONTINUE
                      WRITE ( NOUT, FMT = 99993 )
                      DO 30 I = 1, N
                         WRITE ( NOUT, FMT = 99995 ) ( B(I,J), J = 1,M )
       30             CONTINUE
                      WRITE ( NOUT, FMT = 99992 )
                      DO 40 I = 1, P
                         WRITE ( NOUT, FMT = 99995 ) ( C(I,J), J = 1,N )
       40             CONTINUE
                      WRITE ( NOUT, FMT = 99991 )
                      DO 50 I = 1, N
                         WRITE ( NOUT, FMT = 99995 ) ( Q(I,J), J = 1,N )
       50             CONTINUE
                      WRITE ( NOUT, FMT = 99990 )
                      DO 60 I = 1, N
                         WRITE ( NOUT, FMT = 99995 ) ( Z(I,J), J = 1,N )
       60             CONTINUE
                      WRITE ( NOUT, FMT = 99985 )
                      DO 70 I = 1, N
                         IF ( BETA(I).EQ.ZERO .OR. ALPHAI(I).EQ.ZERO ) THEN
                            WRITE ( NOUT, FMT = 99984 )
         $                     ALPHAR(I)/BETA(I)
                         ELSE
                            WRITE ( NOUT, FMT = 99984 )
         $                     DCMPLX( ALPHAR(I), ALPHAI(I) )/BETA(I)
                         END IF
       70             CONTINUE
                   END IF
                END IF
             END IF
          END IF
          STOP
    *
    99999 FORMAT (' TG01PD EXAMPLE PROGRAM RESULTS',/1X)
    99998 FORMAT (' INFO on exit from TG01PD = ',I2)
    99997 FORMAT (/' The transformed state dynamics matrix Q''*A*Z is ')
    99996 FORMAT (/' The transformed descriptor matrix Q''*E*Z is ')
    99995 FORMAT (20(1X,F8.4))
    99994 FORMAT (' Number of eigenvalues in the domain =', I5)
    99993 FORMAT (/' The transformed input/state matrix Q''*B is ')
    99992 FORMAT (/' The transformed state/output matrix C*Z is ')
    99991 FORMAT (/' The left transformation matrix Q is ')
    99990 FORMAT (/' The right transformation matrix Z is ')
    99988 FORMAT (/' N is out of range.',/' N = ',I5)
    99987 FORMAT (/' M is out of range.',/' M = ',I5)
    99986 FORMAT (/' P is out of range.',/' P = ',I5)
    99985 FORMAT (/' The finite generalized eigenvalues are '/
         $         ' real  part     imag  part ')
    99984 FORMAT (1X,F9.4,SP,F9.4,S,'i ')
          END

Program Data

    TG01PD EXAMPLE PROGRAM DATA
      4     2     2     C     S     G     I     I     1     4     -1.E-7     0.0
        -1     0     0     3
         0     0     1     2
         1     1     0     4
         0     0     0     0
         1     2     0     0
         0     1     0     1
         3     9     6     3
         0     0     2     0
         1     0
         0     0
         0     1
         1     1
        -1     0     1     0
         0     1    -1     1

Program Results

     TG01PD EXAMPLE PROGRAM RESULTS

     Number of eigenvalues in the domain =    1

     The transformed state dynamics matrix Q'*A*Z is
      -1.6311   2.1641  -3.6829  -0.3369
       0.0000   0.4550  -1.9033   0.6425
       0.0000   0.0000   2.6950   0.6882
       0.0000   0.0000   0.0000   0.0000

     The transformed descriptor matrix Q'*E*Z is
       0.4484   9.6340  -1.2601  -5.6475
       0.0000   3.3099   0.6641  -1.4869
       0.0000   0.0000   0.0000  -1.3765
       0.0000   0.0000   0.0000   2.0000

     The transformed input/state matrix Q'*B is
       0.0232  -0.9413
      -0.7251  -0.2478
       0.6882  -0.2294
       1.0000   1.0000

     The transformed state/output matrix C*Z is
      -0.8621   0.3754   0.3405   1.0000
      -0.1511  -1.1192   0.8513  -1.0000

     The left transformation matrix Q is
       0.0232  -0.7251   0.6882   0.0000
      -0.3369   0.6425   0.6882   0.0000
      -0.9413  -0.2478  -0.2294   0.0000
       0.0000   0.0000   0.0000   1.0000

     The right transformation matrix Z is
       0.8621  -0.3754  -0.3405   0.0000
      -0.4258  -0.9008  -0.0851   0.0000
       0.0000   0.0000   0.0000   1.0000
       0.2748  -0.2184   0.9364   0.0000

     The finite generalized eigenvalues are
     real  part     imag  part
       -3.6375
        0.1375
      Infinity
        0.0000

Return to index