Developer Reference for Intel® oneAPI Math Kernel Library for C
?trsyl
Solves Sylvester equation for real quasi-triangular or complex triangular matrices.
Syntax
lapack_int LAPACKE_strsyl ( intmatrix_layout , chartrana , chartranb , lapack_intisgn , lapack_intm , lapack_intn , const float*a , lapack_intlda , const float*b , lapack_intldb , float*c , lapack_intldc , float*scale );
lapack_int LAPACKE_dtrsyl ( intmatrix_layout , chartrana , chartranb , lapack_intisgn , lapack_intm , lapack_intn , const double*a , lapack_intlda , const double*b , lapack_intldb , double*c , lapack_intldc , double*scale );
lapack_int LAPACKE_ctrsyl ( intmatrix_layout , chartrana , chartranb , lapack_intisgn , lapack_intm , lapack_intn , const lapack_complex_float*a , lapack_intlda , const lapack_complex_float*b , lapack_intldb , lapack_complex_float*c , lapack_intldc , float*scale );
lapack_int LAPACKE_ztrsyl ( intmatrix_layout , chartrana , chartranb , lapack_intisgn , lapack_intm , lapack_intn , const lapack_complex_double*a , lapack_intlda , const lapack_complex_double*b , lapack_intldb , lapack_complex_double*c , lapack_intldc , double*scale );
Include Files
mkl.h
Description
strsyl dtrsyl ctrsyl ztrsyl trsyl
The routine solves the Sylvester matrix equation op(A)*X±X*op(B) = α*C , where op(A) = A or A:code:`H` , and the matrices A and B are upper triangular (or, for real flavors, upper quasi-triangular in canonical Schur form); α≤ 1 is a scale factor determined by the routine to avoid overflow in X ; A is m -by- m , B is n -by- n , and C and X are both m -by- n . The matrix X is obtained by a straightforward process of back substitution.
The equation has a unique solution if and only if α_{i}±β_{i}≠ 0 , where { α i } and { \(\beta\)i } are the eigenvalues of A and B , respectively, and the sign (+ or -) is the same as that used in the equation to be solved.
Input Parameters
- matrix_layout
-
Specifies whether matrix storage layout is row major ( LAPACK_ROW_MAJOR ) or column major ( LAPACK_COL_MAJOR ).
trana
Must be ‘N’ or ‘T’ or ‘C’ .
If trana = 'N' , then op(A) = A . If trana = 'T' , then op(A) = A^{T} (real flavors only). If trana = 'C' then op(A) = A^{H} .
tranb
Must be ‘N’ or ‘T’ or ‘C’ .
If tranb = 'N' , then op(B) = B . If tranb = 'T' , then op(B) = B^{T} (real flavors only). If tranb = 'C' , then op(B) = B^{H} .
isgn
Indicates the form of the Sylvester equation.
If isgn = +1 , op(A)*X + X*op(B) = alpha*C . If isgn = -1 , op(A)*X - X*op(B) = alpha*C .
m
The order of A , and the number of rows in X and C ( m ≥ 0).
n
The order of B , and the number of columns in X and C ( n ≥ 0).
- a , b , c
-
REAL for strsyl DOUBLE PRECISION for dtrsyl COMPLEX for ctrsyl DOUBLE COMPLEX for ztrsyl . Arrays:
a (size max(1, lda * m )) contains the matrix A .
The second dimension of a must be at least max(1, m ).
b (size max(1, ldb * n )) contains the matrix B .
The second dimension of b must be at least max(1, n ).
c (size max(1, ldc * n ) for column major layout and max(1, ldc * m for row major layout) contains the matrix C .
The second dimension of c must be at least max(1, n ).
lda
The leading dimension of a ; at least max(1, m ) for column major layout and max(1, n ) for row major layout .
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 .
Output Parameters
- c
-
Overwritten by the solution matrix X .
- scale
-
REAL for single-precision flavors DOUBLE PRECISION for double-precision flavors. The value of the scale factor α .
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 , A and B have common or close eigenvalues; perturbed values were used to solve the equation.
LAPACK 95 Interface Notes
There exist FORTRAN 77 and FORTRAN 95 interfaces for this routine. See the Intel® oneMKL Fortran Developer Reference for details.
Application Notes
Let \(X\) be the exact, \(Y\) the corresponding computed solution, and \(R\) the residual matrix: \(R = C\) - ( AY ± YB ). Then the residual is always small:
\(||R||_{F} = O(\varepsilon) (||A||_{F} +||B||_{F}) ||Y||_{F}\) .
However, \(Y\) is not necessarily the exact solution of a slightly perturbed equation; in other words, the solution is not backwards stable.
For the forward error, the following bound holds:
\(||Y - X||_{F}\leq||R||_{F}/sep(A,B)\)
but this may be a considerable overestimate. See [Golub96] for a definition of sep( A , B ).
The approximate number of floating-point operations for real flavors is m*n*(m + n) . For complex flavors it is 4 times greater.