Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_ztrsyl (f08qv)

## Purpose

nag_lapack_ztrsyl (f08qv) solves the complex triangular Sylvester matrix equation.

## Syntax

[c, scal, info] = f08qv(trana, tranb, isgn, a, b, c, 'm', m, 'n', n)
[c, scal, info] = nag_lapack_ztrsyl(trana, tranb, isgn, a, b, c, 'm', m, 'n', n)

## Description

nag_lapack_ztrsyl (f08qv) solves the complex Sylvester matrix equation
 $opAX ± XopB = αC ,$
where $\mathrm{op}\left(A\right)=A$ or ${A}^{\mathrm{H}}$, and the matrices $A$ and $B$ are upper triangular; $\alpha$ is a scale factor ($\text{}\le 1$) determined by the function to avoid overflow in $X$; $A$ is $m$ by $m$ and $B$ is $n$ by $n$ while the right-hand side matrix $C$ and the solution matrix $X$ are both $m$ by $n$. The matrix $X$ is obtained by a straightforward process of back-substitution (see Golub and Van Loan (1996)).
Note that the equation has a unique solution if and only if ${\alpha }_{i}±{\beta }_{j}\ne 0$, where $\left\{{\alpha }_{i}\right\}$ and $\left\{{\beta }_{j}\right\}$ are the eigenvalues of $A$ and $B$ respectively and the sign ($+$ or $-$) is the same as that used in the equation to be solved.

## References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (1992) Perturbation theory and backward error for $AX-XB=C$ Numerical Analysis Report University of Manchester

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{trana}$ – string (length ≥ 1)
Specifies the option $\mathrm{op}\left(A\right)$.
${\mathbf{trana}}=\text{'N'}$
$\mathrm{op}\left(A\right)=A$.
${\mathbf{trana}}=\text{'C'}$
$\mathrm{op}\left(A\right)={A}^{\mathrm{H}}$.
Constraint: ${\mathbf{trana}}=\text{'N'}$ or $\text{'C'}$.
2:     $\mathrm{tranb}$ – string (length ≥ 1)
Specifies the option $\mathrm{op}\left(B\right)$.
${\mathbf{tranb}}=\text{'N'}$
$\mathrm{op}\left(B\right)=B$.
${\mathbf{tranb}}=\text{'C'}$
$\mathrm{op}\left(B\right)={B}^{\mathrm{H}}$.
Constraint: ${\mathbf{tranb}}=\text{'N'}$ or $\text{'C'}$.
3:     $\mathrm{isgn}$int64int32nag_int scalar
Indicates the form of the Sylvester equation.
${\mathbf{isgn}}=+1$
The equation is of the form $\mathrm{op}\left(A\right)X+X\mathrm{op}\left(B\right)=\alpha C$.
${\mathbf{isgn}}=-1$
The equation is of the form $\mathrm{op}\left(A\right)X-X\mathrm{op}\left(B\right)=\alpha C$.
Constraint: ${\mathbf{isgn}}=+1$ or $-1$.
4:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The $m$ by $m$ upper triangular matrix $A$.
5:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $n$ by $n$ upper triangular matrix $B$.
6:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – complex array
The first dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array c must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $m$ by $n$ right-hand side matrix $C$.

### Optional Input Parameters

1:     $\mathrm{m}$int64int32nag_int scalar
Default: the first dimension of the array a and the second dimension of the array a. (An error is raised if these dimensions are not equal.)
$m$, the order of the matrix $A$, and the number of rows in the matrices $X$ and $C$.
Constraint: ${\mathbf{m}}\ge 0$.
2:     $\mathrm{n}$int64int32nag_int scalar
Default: the first dimension of the array b and the second dimension of the array b. (An error is raised if these dimensions are not equal.)
$n$, the order of the matrix $B$, and the number of columns in the matrices $X$ and $C$.
Constraint: ${\mathbf{n}}\ge 0$.

### Output Parameters

1:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – complex array
The first dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
The second dimension of the array c will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
c stores the solution matrix $X$.
2:     $\mathrm{scal}$ – double scalar
The value of the scale factor $\alpha$.
3:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: trana, 2: tranb, 3: isgn, 4: m, 5: n, 6: a, 7: lda, 8: b, 9: ldb, 10: c, 11: ldc, 12: scal, 13: info.
It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.
W  ${\mathbf{info}}=1$
$A$ and $B$ have common or close eigenvalues, perturbed values of which were used to solve the equation.

## Accuracy

Consider the equation $AX-XB=C$. (To apply the remarks to the equation $AX+XB=C$, simply replace $B$ by $-B$.)
Let $\stackrel{~}{X}$ be the computed solution and $R$ the residual matrix:
 $R = C - AX~ - X~B .$
Then the residual is always small:
 $RF = Oε AF + BF X~F .$
However, $\stackrel{~}{X}$ 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:
 $X~ - X F ≤ RF sep A,B$
but this may be a considerable over estimate. See Golub and Van Loan (1996) for a definition of $\mathit{sep}\left(A,B\right)$, and Higham (1992) for further details.
These remarks also apply to the solution of a general Sylvester equation, as described in Further Comments.

The total number of real floating-point operations is approximately $4mn\left(m+n\right)$.
To solve the general complex Sylvester equation
 $AX ± XB = C$
where $A$ and $B$ are general matrices, $A$ and $B$ must first be reduced to Schur form (by calling nag_lapack_zgees (f08pn), for example):
 $A = Q1 A~ Q1H and B = Q2 B~ Q2H$
where $\stackrel{~}{A}$ and $\stackrel{~}{B}$ are upper triangular and ${Q}_{1}$ and ${Q}_{2}$ are unitary. The original equation may then be transformed to:
 $A~ X~ ± X~ B~ = C~$
where $\stackrel{~}{X}={Q}_{1}^{\mathrm{H}}X{Q}_{2}$ and $\stackrel{~}{C}={Q}_{1}^{\mathrm{H}}C{Q}_{2}$. $\stackrel{~}{C}$ may be computed by matrix multiplication; nag_lapack_ztrsyl (f08qv) may be used to solve the transformed equation; and the solution to the original equation can be obtained as $X={Q}_{1}\stackrel{~}{X}{Q}_{2}^{\mathrm{H}}$.
The real analogue of this function is nag_lapack_dtrsyl (f08qh).

## Example

This example solves the Sylvester equation $AX+XB=C$, where
 $A = -6.00-7.00i 0.36-0.36i -0.19+0.48i 0.88-0.25i 0.00+0.00i -5.00+2.00i -0.03-0.72i -0.23+0.13i 0.00+0.00i 0.00+0.00i 8.00-1.00i 0.94+0.53i 0.00+0.00i 0.00+0.00i 0.00+0.00i 3.00-4.00i ,$
 $B = 0.50-0.20i -0.29-0.16i -0.37+0.84i -0.55+0.73i 0.00+0.00i -0.40+0.90i 0.06+0.22i -0.43+0.17i 0.00+0.00i 0.00+0.00i -0.90-0.10i -0.89-0.42i 0.00+0.00i 0.00+0.00i 0.00+0.00i 0.30-0.70i$
and
 $C = 0.63+0.35i 0.45-0.56i 0.08-0.14i -0.17-0.23i -0.17+0.09i -0.07-0.31i 0.27-0.54i 0.35+1.21i -0.93-0.44i -0.33-0.35i 0.41-0.03i 0.57+0.84i 0.54+0.25i -0.62-0.05i -0.52-0.13i 0.11-0.08i .$
```function f08qv_example

fprintf('f08qv example results\n\n');

% Quasi-triangular (Schur form) matrices A and B, and general matrix C
a = [-6    - 7i,     0.36 - 0.36i, -0.19 + 0.48i,  0.88 - 0.25i;
0    + 0i,    -5    + 2i,    -0.03 - 0.72i, -0.23 + 0.13i;
0    + 0i,     0    + 0i,     8    - 1i,     0.94 + 0.53i;
0    + 0i,     0    + 0i,     0    + 0i,     3    - 4i];
b = [ 0.5  - 0.2i,  -0.29 - 0.16i, -0.37 + 0.84i, -0.55 + 0.73i;
0    + 0i,    -0.4  + 0.9i,   0.06 + 0.22i, -0.43 + 0.17i;
0    + 0i,     0    + 0i,    -0.90 - 0.10i, -0.89 - 0.42i;
0    + 0i,     0    + 0i,     0    + 0i,     0.30 - 0.7i];
c = [ 0.63 + 0.35i,  0.45 - 0.56i,  0.08 - 0.14i, -0.17 - 0.23i;
-0.17 + 0.09i, -0.07 - 0.31i,  0.27 - 0.54i,  0.35 + 1.21i;
-0.93 - 0.44i, -0.33 - 0.35i,  0.41 - 0.03i,  0.57 + 0.84i;
0.54 + 0.25i, -0.62 - 0.05i, -0.52 - 0.13i,  0.11 - 0.08i];

% Solve Sylvester equation AX + XB = C for X
trana = 'No transpose';
tranb = 'No transpose';
isgn = int64(1);
[X, scal, info] = f08qv( ...
trana, tranb, isgn, a, b, c);

disp('Solution matrix');
disp(X);

```
```f08qv example results

Solution matrix
-0.0611 + 0.0249i  -0.0031 + 0.0798i  -0.0062 + 0.0165i   0.0054 - 0.0063i
0.0215 - 0.0003i  -0.0155 + 0.0570i  -0.0665 + 0.0718i   0.0290 - 0.2636i
-0.0949 - 0.0785i  -0.0415 - 0.0298i   0.0357 + 0.0244i   0.0284 + 0.1108i
0.0281 + 0.1052i  -0.0970 - 0.1214i  -0.0271 - 0.0940i   0.0402 + 0.0048i

```