Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

?tgexc

Reorders the generalized Schur decomposition of a pair of matrices (A,B) so that one diagonal block of (A,B) moves to another row index.

Syntax

lapack_int LAPACKE_stgexc (int matrix_layout, lapack_logical wantq, lapack_logical wantz, lapack_int n, float* a, lapack_int lda, float* b, lapack_int ldb, float* q, lapack_int ldq, float* z, lapack_int ldz, lapack_int* ifst, lapack_int* ilst);

lapack_int LAPACKE_dtgexc (int matrix_layout, lapack_logical wantq, lapack_logical wantz, lapack_int n, double* a, lapack_int lda, double* b, lapack_int ldb, double* q, lapack_int ldq, double* z, lapack_int ldz, lapack_int* ifst, lapack_int* ilst);

lapack_int LAPACKE_ctgexc (int matrix_layout, lapack_logical wantq, lapack_logical wantz, lapack_int n, lapack_complex_float* a, lapack_int lda, lapack_complex_float* b, lapack_int ldb, lapack_complex_float* q, lapack_int ldq, lapack_complex_float* z, lapack_int ldz, lapack_int ifst, lapack_int ilst);

lapack_int LAPACKE_ztgexc (int matrix_layout, lapack_logical wantq, lapack_logical wantz, lapack_int n, lapack_complex_double* a, lapack_int lda, lapack_complex_double* b, lapack_int ldb, lapack_complex_double* q, lapack_int ldq, lapack_complex_double* z, lapack_int ldz, lapack_int ifst, lapack_int ilst);

Include Files

  • mkl.h

Description

The routine reorders the generalized real-Schur/Schur decomposition of a real/complex matrix pair (A,B) using an orthogonal/unitary equivalence transformation

(A,B) = Q*(A,B)*ZH,

so that the diagonal block of (A, B) with row index ifst is moved to row ilst. Matrix pair (A, B) must be in a generalized real-Schur/Schur canonical form (as returned by gges), that is, 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.

Qin*Ain*ZinT = Qout*Aout*ZoutT

Qin*Bin*ZinT = Qout*Bout*ZoutT.

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

wantq, wantz

If wantq = 1, update the left transformation matrix Q;

If wantq = 0, do not update Q;

If wantz = 1, update the right transformation matrix Z;

If wantz = 0, do not update Z.

n

The order of the matrices A and B (n 0).

a, b, q, z

Arrays:

a (size max(1, lda*n)) contains the matrix A.

b (size max(1, ldb*n)) contains the matrix B.

q (size at least 1 if wantq = 0 and at least max(1, ldq*n) if wantq = 1)

If wantq = 0, then q is not referenced.

If wantq = 1, then q must contain the orthogonal/unitary matrix Q.

z (size at least 1 if wantz = 0 and at least max(1, ldz*n) if wantz = 1)

If wantz = 0, then z is not referenced.

If wantz = 1, then z must contain the orthogonal/unitary matrix Z.

lda

The leading dimension of a; at least max(1, n).

ldb

The leading dimension of b; at least max(1, n).

ldq

The leading dimension of q;

If wantq = 0, then ldq 1.

If wantq = 1, then ldq max(1, n).

ldz

The leading dimension of z;

If wantz = 0, then ldz 1.

If wantz = 1, then ldz max(1, n).

ifst, ilst

Specify the reordering of the diagonal blocks of (A, B). The block with row index ifst is moved to row ilst, by a sequence of swapping between adjacent blocks. Constraint: 1 ifst, ilstn.

Output Parameters

a, b, q, z

Overwritten by the updated matrices A,B, Q, and Z respectively.

ifst, ilst

Overwritten for real flavors only.

If ifst pointed to the second row of a 2 by 2 block on entry, 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).

Return Values

This function returns a value info.

If info=0, the execution is successful.

If info = -i, the i-th parameter had an illegal value.

If info = 1, the transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned. (A, B) may have been partially reordered, and ilst points to the first row of the current position of the block being moved.