BDTREXC(3)    ScaLAPACK routine of NEC Numeric Library Collection   BDTREXC(3)



NAME
       BDTREXC  -  reorders  the real Schur factorization of a real matrix A =
       Q*T*Q**T, so that the diagonal block of T with row index IFST is  moved
       to row ILST

SYNOPSIS
       SUBROUTINE BDTREXC( N,  T,  LDT,  IFST,  ILST,  NITRAF,  ITRAF, NDTRAF,
                           DTRAF, WORK, INFO )

           INTEGER         IFST, ILST, INFO, LDT, N, NDTRAF, NITRAF

           INTEGER         ITRAF( * )

           DOUBLE          PRECISION DTRAF( * ), T( LDT, * ), WORK( * )

PURPOSE
       BDTREXC reorders the real Schur factorization of  a  real  matrix  A  =
       Q*T*Q**T,  so that the diagonal block of T with row index IFST is moved
       to row ILST.

       The real Schur form T is reordered by an orthogonal  similarity  trans-
       formation  Z**T*T*Z.  In  contrast  to  the  LAPACK routine DTREXC, the
       orthogonal matrix Z is not explicitly constructed  but  represented  by
       paramaters  contained  in  the  arrays  ITRAF  and  DTRAF,  see further
       details.

       T must be in Schur canonical form (as returned  by  DHSEQR),  that  is,
       block  upper  triangular  with  1-by-1 and 2-by-2 diagonal blocks; each
       2-by-2 diagonal block has its diagonal elements equal and its off-diag-
       onal elements of opposite sign.


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

       T       (input/output) DOUBLE PRECISION array, dimension (LDT,N)
               On  entry,  the upper quasi-triangular matrix T, in Schur Schur
               canonical form.
               On exit, the reordered upper quasi-triangular matrix, again  in
               Schur canonical form.

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

       IFST    (input/output) INTEGER

       ILST    (input/output) INTEGER
               Specify the reordering of the diagonal blocks of T.
               The  block  with  row  index  IFST  is  moved to row ILST, by a
               sequence of transpositions between adjacent blocks.
               On exit, if IFST pointed on entry to the second row of a 2-by-2
               block,  it  is  changed  to point to the first row; ILST always
               points to the first row of the  block  in  its  final  position
               (which may differ from its input value by +1 or -1).
               1 <= IFST <= N; 1 <= ILST <= N.

       NITRAF  (input/output) INTEGER
               On entry, length of the array ITRAF.
               As a minimum requirement, NITRAF >= max(1,|ILST-IFST|).
               If  there  are 2-by-2 blocks in T then NITRAF must be larger; a
               safe choice is NITRAF >= max(1,2*|ILST-IFST|).
               On exit, actual length of the array ITRAF.

       ITRAF   (output) INTEGER array, length NITRAF
               List of parameters for representing the  transformation  matrix
               Z, see further details.

       NDTRAF  (input/output) INTEGER
               On entry, length of the array DTRAF.
               As a minimum requirement, NDTRAF >= max(1,2*|ILST-IFST|).
               If  there  are 2-by-2 blocks in T then NDTRAF must be larger; a
               safe choice is NDTRAF >= max(1,5*|ILST-IFST|).
               On exit, actual length of the array DTRAF.

       DTRAF   (output) DOUBLE PRECISION array, length NDTRAF
               List of parameters for representing the  transformation  matrix
               Z, see further details.

       WORK    (workspace) DOUBLE PRECISION array, dimension (N)

       INFO    (output) INTEGER
               = 0:  successful exit
               < 0:  if INFO = -i, the i-th argument had an illegal value
               = 1:  two adjacent blocks were too close to swap (the problem
                     is very ill-conditioned); T may have been partially
                     reordered, and ILST points to the first row of the
                     current position of the block being moved.
               = 2:  the 2 by 2 block to be reordered split into two 1 by 1
                     blocks and the second block failed to swap with an
                     adjacent block. ILST points to the first row of the
                     current position of the whole block being moved.

FURTHER DETAILS
       The  orthogonal  transformation matrix Z is a product of NITRAF elemen-
       tary orthogonal transformations. The parameters defining  these  trans-
       formations are stored in the arrays ITRAF and DTRAF as follows:

       Consider the i-th transformation acting on rows/columns POS, POS+1, ...
       If this transformation is

          (1) a Givens rotation with cosine C and sine S then

                ITRAF(i) = POS,
                DTRAF(j) = C,    DTRAF(j+1) = S;

          (2) a Householder reflector H = I - tau * v * v' with
              v = [ 1; v2; v3 ] then

                ITRAF(i) = N + POS,
                DTRAF(j) = tau,  DTRAF(j+1) = v2,  DTRAF(j+2) = v3;

          (3) a Householder reflector H = I - tau * v * v' with
              v = [ v1; v2; 1 ] then

                ITRAF(i) = 2*N + POS,
                DTRAF(j) = v1,  DTRAF(j+1) = v2,  DTRAF(j+2) = tau;

       Note that the parameters in DTRAF are stored consecutively.



ScaLAPACK routine               31 October 2017                     BDTREXC(3)