Developer Reference

  • 0.10
  • 10/21/2020
  • Public Content
Contents

?tgsyl

Solves the generalized Sylvester equation.

Syntax

lapack_int LAPACKE_stgsyl
(
int
matrix_layout
,
char
trans
,
lapack_int
ijob
,
lapack_int
m
,
lapack_int
n
,
const float*
a
,
lapack_int
lda
,
const float*
b
,
lapack_int
ldb
,
float*
c
,
lapack_int
ldc
,
const float*
d
,
lapack_int
ldd
,
const float*
e
,
lapack_int
lde
,
float*
f
,
lapack_int
ldf
,
float*
scale
,
float*
dif
);
lapack_int LAPACKE_dtgsyl
(
int
matrix_layout
,
char
trans
,
lapack_int
ijob
,
lapack_int
m
,
lapack_int
n
,
const double*
a
,
lapack_int
lda
,
const double*
b
,
lapack_int
ldb
,
double*
c
,
lapack_int
ldc
,
const double*
d
,
lapack_int
ldd
,
const double*
e
,
lapack_int
lde
,
double*
f
,
lapack_int
ldf
,
double*
scale
,
double*
dif
);
lapack_int LAPACKE_ctgsyl
(
int
matrix_layout
,
char
trans
,
lapack_int
ijob
,
lapack_int
m
,
lapack_int
n
,
const lapack_complex_float*
a
,
lapack_int
lda
,
const lapack_complex_float*
b
,
lapack_int
ldb
,
lapack_complex_float*
c
,
lapack_int
ldc
,
const lapack_complex_float*
d
,
lapack_int
ldd
,
const lapack_complex_float*
e
,
lapack_int
lde
,
lapack_complex_float*
f
,
lapack_int
ldf
,
float*
scale
,
float*
dif
);
lapack_int LAPACKE_ztgsyl
(
int
matrix_layout
,
char
trans
,
lapack_int
ijob
,
lapack_int
m
,
lapack_int
n
,
const lapack_complex_double*
a
,
lapack_int
lda
,
const lapack_complex_double*
b
,
lapack_int
ldb
,
lapack_complex_double*
c
,
lapack_int
ldc
,
const lapack_complex_double*
d
,
lapack_int
ldd
,
const lapack_complex_double*
e
,
lapack_int
lde
,
lapack_complex_double*
f
,
lapack_int
ldf
,
double*
scale
,
double*
dif
);
Include Files
  • mkl.h
Description
The routine solves the generalized Sylvester equation:
A
*
R
-
L
*
B
=
scale
*
C
D
*
R
-
L
*
E
=
scale
*
F
where
R
and
L
are unknown
m
-by-
n
matrices, (
A
,
D
), (
B
,
E
) and (
C
,
F
) are given matrix pairs of size
m
-by-
m
,
n
-by-
n
and
m
-by-
n
, respectively, with real/complex entries. (
A
,
D
) and (
B
,
E
) must be in generalized real-Schur/Schur canonical form, that is,
A
,
B
are upper quasi-triangular/triangular and
D
,
E
are upper triangular.
The solution (
R
,
L
) overwrites (
C
,
F
). The factor
scale
,
0
scale
1
, is an output scaling factor chosen to avoid overflow.
In matrix notation the above equation is equivalent to the following: solve
Z
*
x
=
scale
*
b
, where
Z
is defined as
Equation
Here
I
k
is the identity matrix of size
k
and
X
T
is the transpose/conjugate-transpose of
X
.
kron
(
X
,
Y
)
is the Kronecker product between the matrices
X
and
Y
.
If
trans
=
'T'
(for real flavors), or
trans
=
'C'
(for complex flavors), the routine
?tgsyl
solves the transposed/conjugate-transposed system
Z
T
*
y
=
scale
*
b
, which is equivalent to solve for
R
and
L
in
A
T
*
R
+
D
T
*
L
=
scale
*
C
R
*
B
T
+
L
*
E
T
=
scale
*(-
F
)
This case (
trans
=
'T'
for
stgsyl
/
dtgsyl
or
trans
=
'C'
for
ctgsyl
/
ztgsyl
) is used to compute an one-norm-based estimate of
Dif[(
A
,
D
), (
B
,
E
)]
, the separation between the matrix pairs (
A
,
D
) and (
B
,
E
).
If
ijob
≥ 1
,
?tgsyl
computes a Frobenius norm-based estimate of
Dif[(
A
,
D
), (
B
,
E
)]
. That is, the reciprocal of a lower bound on the reciprocal of the smallest singular value of
Z
. This is a level 3 BLAS algorithm.
Input Parameters
matrix_layout
Specifies whether matrix storage layout is row major (
LAPACK_ROW_MAJOR
) or column major (
LAPACK_COL_MAJOR
).
trans
Must be
'N'
,
'T'
, or
'C'
.
If
trans
=
'N'
, solve the generalized Sylvester equation.
If
trans
=
'T'
, solve the 'transposed' system (for real flavors only).
If
trans
=
'C'
, solve the ' conjugate transposed' system (for complex flavors only).
ijob
Specifies what kind of functionality to be performed:
If
ijob
=0
, solve the generalized Sylvester equation only;
If
ijob
=1
, perform the functionality of
ijob
=0
and
ijob
=3
;
If
ijob
=2
, perform the functionality of
ijob
=0
and
ijob
=4
;
If
ijob
=3
, only an estimate of Dif[(
A
,
D
), (
B
,
E
)] is computed (look ahead strategy is used);
If
ijob
=4
, only an estimate of Dif[(
A
,
D
), (
B
,
E
)] is computed (?gecon on sub-systems is used). If
trans
=
'T'
or
'C'
,
ijob
is not referenced.
m
The order of the matrices
A
and
D
, and the row dimension of the matrices
C
,
F
,
R
and
L
.
n
The order of the matrices
B
and
E
, and the column dimension of the matrices
C
,
F
,
R
and
L
.
a
,
b
,
c
,
d
,
e
,
f
Arrays:
a
(size max(1,
lda
*
m
))
contains the upper quasi-triangular (for real flavors) or upper triangular (for complex flavors) matrix
A
.
b
(size max(1,
ldb
*
n
))
contains the upper quasi-triangular (for real flavors) or upper triangular (for complex flavors) matrix
B
.
c
(size max(1,
ldc
*
n
) for column major layout and max(1,
ldc
*
m
) for row major layout)
contains the right-hand-side of the first matrix equation in the generalized Sylvester equation (as defined by
trans
)
d
(size max(1,
ldd
*
m
))
contains the upper triangular matrix
D
.
e
(size max(1,
lde
*
n
))
contains the upper triangular matrix
E
.
f
(size max(1,
ldf
*
n
) for column major layout and max(1,
ldf
*
m
) for row major layout)
contains the right-hand-side of the second matrix equation in the generalized Sylvester equation (as defined by
trans
)
lda
The leading dimension of
a
; at least max(1,
m
).
ldb
The leading dimension of
b
; at least max(1,
n
).
ldc
The leading dimension of
c
; at least max(1,
m
)
for column major layout and at least max(1,
n
) for row major layout
.
ldd
The leading dimension of
d
; at least max(1,
m
).
lde
The leading dimension of
e
; at least max(1,
n
).
ldf
The leading dimension of
f
; at least max(1,
m
)
for column major layout and at least max(1,
n
) for row major layout
.
Output Parameters
c
If
ijob
=0
, 1, or 2, overwritten by the solution
R
.
If
ijob
=3
or 4 and
trans
=
'N'
,
c
holds
R
, the solution achieved during the computation of the
Dif
-estimate.
f
If
ijob
=0
, 1, or 2, overwritten by the solution
L
.
If
ijob
=3
or 4 and
trans
=
'N'
,
f
holds
L
, the solution achieved during the computation of the
Dif
-estimate.
dif
On exit,
dif
is the reciprocal of a lower bound of the reciprocal of the Dif-function, that is,
dif
is an upper bound of
Dif[(
A
,
D
), (
B
,
E
)] = sigma_min(
Z
)
, where
Z
as defined in the description.
If
ijob
= 0
, or
trans
=
'T'
(for real flavors), or
trans
=
'C'
(for complex flavors),
dif
is not touched.
scale
On exit,
scale
is the scaling factor in the generalized Sylvester equation.
If
0 <
scale
< 1
,
c
and
f
hold the solutions
R
and
L
, respectively, to a slightly perturbed system but the input matrices
A
,
B
,
D
and
E
have not been changed.
If
scale
= 0
,
c
and
f
hold the solutions
R
and
L
, respectively, to the homogeneous system with
C
=
F
= 0
. Normally,
scale
= 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
> 0
, (
A
,
D
) and (
B
,
E
) have common or close eigenvalues.