Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 3/31/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

b?trexc

Reorders the Schur factorization of a general matrix.

Syntax

call bstrexc( n, t, ldt, ifst, ilst, nitraf, itraf, ndtraf, dtraf, work, info )

call bdtrexc( n, t, ldt, ifst, ilst, nitraf, itraf, ndtraf, dtraf, work, info )

Description

b?trexc reorders the real Schur factorization of a real matrix A = Q * T * QT, 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 transformation ZT * T * Z. In contrast to the LAPACK routine ?trexc, the orthogonal matrix Z is not explicitly constructed but represented by parameters contained in the arrays itraf and dtraf. See Application Notes for further details.

T must be in Schur canonical form (as returned by ?hseqr), 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-diagonal elements of opposite sign.

Input Parameters
n

INTEGER

The order of the matrix T. n 0.

t

REAL for bstrexc

DOUBLE PRECISION for bdtrexc

Array of size (ldt,n).

The upper quasi-triangular matrix T, in Schur canonical form.

ldt

INTEGER

The leading dimension of the array t. ldt max(1,n).

ifst, ilst

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.

nitraf

INTEGER

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|).

ndtraf

INTEGER

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|).

work

REAL for bstrexc

DOUBLE PRECISION for bdtrexc

(Workspace) array of size n.

OUTPUT Parameters
t

On exit, the reordered upper quasi-triangular matrix, in Schur canonical form.

ifst, ilst

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 ifstn; 1 ilstn.

nitraf

Actual length of the array itraf.

itraf

INTEGER array, length nitraf

List of parameters for representing the transformation matrix Z. See Application Notes for further details.

ndtraf

Actual length of the array dtraf.

dtraf

REAL for bstrexc

DOUBLE PRECISION for bdtrexc

Array, length ndtraf

List of parameters for representing the transformation matrix Z. See Application Notes for further details.

info

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.

Application Notes

The orthogonal transformation matrix Z is a product of nitraf elementary orthogonal transformations. The parameters defining these transformations 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

  • a Givens rotation with cosine c and sine s then

    itraf(i)= pos, dtraf(i) = c, dtraf(i+1) = s;
  • a Householder reflector H = I - t * v * v' with v = [ 1; v2; v3 ] then

    itraf(i) = n + pos, dtraf(i) = t, dtraf(i+1) = v2, dtraf(i+2) = v3;

  • a Householder reflector H = I - t* v * v' with v = [ v1; v2; 1 ] then

    itraf(i) = 2*n + pos, dtraf(i) = v1, dtraf(i+1) = v2, dtraf(i+2) = t;

Note that the parameters in dtraf are stored consecutively.

See Also