## MB03WA

### Swapping two adjacent diagonal blocks in a periodic real Schur canonical form

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

Purpose

      To swap adjacent diagonal blocks A11*B11 and A22*B22 of size
      1-by-1 or 2-by-2 in an upper (quasi) triangular matrix product
      A*B by an orthogonal equivalence transformation.

      (A, B) must be in periodic real Schur canonical form (as returned
      by SLICOT Library routine MB03XP), i.e., A is block upper
      triangular with 1-by-1 and 2-by-2 diagonal blocks, and B is upper
      triangular.

      Optionally, the matrices Q and Z of generalized Schur vectors are
      updated.

          Q(in) * A(in) * Z(in)' = Q(out) * A(out) * Z(out)',
          Z(in) * B(in) * Q(in)' = Z(out) * B(out) * Q(out)'.

      This routine is largely based on the LAPACK routine DTGEX2
      developed by Bo Kagstrom and Peter Poromaa.

Specification

          SUBROUTINE MB03WA( WANTQ, WANTZ, N1, N2, A, LDA, B, LDB, Q, LDQ,
         $                   Z, LDZ, INFO )
    C     .. Scalar Arguments ..
          LOGICAL            WANTQ, WANTZ
          INTEGER            INFO, LDA, LDB, LDQ, LDZ, N1, N2
    C     .. Array Arguments ..
          DOUBLE PRECISION   A(LDA,*), B(LDB,*), Q(LDQ,*), Z(LDZ,*)

Arguments

Mode Parameters

      WANTQ   LOGICAL
              Indicates whether or not the user wishes to accumulate
              the matrix Q as follows:
              = .TRUE. :  The matrix Q is updated;
              = .FALSE.:  the matrix Q is not required.

      WANTZ   LOGICAL
              Indicates whether or not the user wishes to accumulate
              the matrix Z as follows:
              = .TRUE. :  The matrix Z is updated;
              = .FALSE.:  the matrix Z is not required.

Input/Output Parameters

      N1      (input) INTEGER
              The order of the first block A11*B11. N1 = 0, 1 or 2.

      N2      (input) INTEGER
              The order of the second block A22*B22. N2 = 0, 1 or 2.

      A       (input/output) DOUBLE PRECISION array, dimension
              (LDA,N1+N2)
              On entry, the leading (N1+N2)-by-(N1+N2) part of this
              array must contain the matrix A.
              On exit, the leading (N1+N2)-by-(N1+N2) part of this array
              contains the matrix A of the reordered pair.

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

      B       (input/output) DOUBLE PRECISION array, dimension
              (LDB,N1+N2)
              On entry, the leading (N1+N2)-by-(N1+N2) part of this
              array must contain the matrix B.
              On exit, the leading (N1+N2)-by-(N1+N2) part of this array
              contains the matrix B of the reordered pair.

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

      Q       (input/output) DOUBLE PRECISION array, dimension
              (LDQ,N1+N2)
              On entry, if WANTQ = .TRUE., the leading
              (N1+N2)-by-(N1+N2) part of this array must contain the
              orthogonal matrix Q.
              On exit, the leading (N1+N2)-by-(N1+N2) part of this array
              contains the updated matrix Q. Q will be a rotation
              matrix for N1=N2=1.
              This array is not referenced if WANTQ = .FALSE..

      LDQ     INTEGER
              The leading dimension of the array Q. LDQ >= 1.
              If WANTQ = .TRUE., LDQ >= N1+N2.

      Z       (input/output) DOUBLE PRECISION array, dimension
              (LDZ,N1+N2)
              On entry, if WANTZ = .TRUE., the leading
              (N1+N2)-by-(N1+N2) part of this array must contain the
              orthogonal matrix Z.
              On exit, the leading (N1+N2)-by-(N1+N2) part of this array
              contains the updated matrix Z. Z will be a rotation
              matrix for N1=N2=1.
              This array is not referenced if WANTZ = .FALSE..

      LDZ     INTEGER
              The leading dimension of the array Z. LDZ >= 1.
              If WANTZ = .TRUE., LDZ >= N1+N2.

Error Indicator

      INFO    INTEGER
              = 0:  successful exit;
              = 1:  the transformed matrix (A, B) would be
                    too far from periodic Schur form; the blocks are
                    not swapped and (A,B) and (Q,Z) are unchanged.

Method

      In the current code both weak and strong stability tests are
      performed. The user can omit the strong stability test by changing
      the internal logical parameter WANDS to .FALSE.. See ref. [2] for
      details.

References

      [1] Kagstrom, B.
          A direct method for reordering eigenvalues in the generalized
          real Schur form of a regular matrix pair (A,B), in M.S. Moonen
          et al (eds.), Linear Algebra for Large Scale and Real-Time
          Applications, Kluwer Academic Publ., 1993, pp. 195-218.

      [2] Kagstrom, B., and Poromaa, P.
          Computing eigenspaces with specified eigenvalues of a regular
          matrix pair (A, B) and condition estimation: Theory,
          algorithms and software, Numer. Algorithms, 1996, vol. 12,
          pp. 369-407.

Further Comments

      None

Example

Program Text

      None

Program Data

      None

Program Results

      None

Return to Supporting Routines index