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

?trsyl

Solves Sylvester equation for real quasi-triangular or complex triangular matrices.

Syntax

lapack_int LAPACKE_strsyl( int matrix_layout, char trana, char tranb, lapack_int isgn, lapack_int m, lapack_int n, const float* a, lapack_int lda, const float* b, lapack_int ldb, float* c, lapack_int ldc, float* scale );

lapack_int LAPACKE_dtrsyl( int matrix_layout, char trana, char tranb, lapack_int isgn, lapack_int m, lapack_int n, const double* a, lapack_int lda, const double* b, lapack_int ldb, double* c, lapack_int ldc, double* scale );

lapack_int LAPACKE_ctrsyl( int matrix_layout, char trana, char tranb, lapack_int isgn, 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, float* scale );

lapack_int LAPACKE_ztrsyl( int matrix_layout, char trana, char tranb, lapack_int isgn, 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, double* scale );

Include Files

  • mkl.h

Description

The routine solves the Sylvester matrix equation op(A)*X±X*op(B) = α*C, where op(A) = A or AH, 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 {β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) = AT (real flavors only).

If trana = 'C' then op(A) = AH.

tranb

Must be 'N' or 'T' or 'C'.

If tranb = 'N', then op(B) = B.

If tranb = 'T', then op(B) = BT (real flavors only).

If tranb = 'C', then op(B) = BH.

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

Arrays:

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

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

c(size max(1, ldc*n) for column major layout and max(1, ldc*m for row major layout) contains the matrix C.

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

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.

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(ε)*(||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||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.