f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_dtrsyl (f08qhc)

## 1  Purpose

nag_dtrsyl (f08qhc) solves the real quasi-triangular Sylvester matrix equation.

## 2  Specification

 #include #include
 void nag_dtrsyl (Nag_OrderType order, Nag_TransType trana, Nag_TransType tranb, Nag_SignType sign, Integer m, Integer n, const double a[], Integer pda, const double b[], Integer pdb, double c[], Integer pdc, double *scale, NagError *fail)

## 3  Description

nag_dtrsyl (f08qhc) solves the real Sylvester matrix equation
 $opAX ± XopB = αC ,$
where $\mathrm{op}\left(A\right)=A$ or ${A}^{\mathrm{T}}$, and the matrices $A$ and $B$ are upper quasi-triangular matrices in canonical Schur form (as returned by nag_dhseqr (f08pec)); $\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.

## 4  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

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     tranaNag_TransTypeInput
On entry: specifies the option $\mathrm{op}\left(A\right)$.
${\mathbf{trana}}=\mathrm{Nag_NoTrans}$
$\mathrm{op}\left(A\right)=A$.
${\mathbf{trana}}=\mathrm{Nag_Trans}$ or $\mathrm{Nag_ConjTrans}$
$\mathrm{op}\left(A\right)={A}^{\mathrm{T}}$.
Constraint: ${\mathbf{trana}}=\mathrm{Nag_NoTrans}$, $\mathrm{Nag_Trans}$ or $\mathrm{Nag_ConjTrans}$.
3:     tranbNag_TransTypeInput
On entry: specifies the option $\mathrm{op}\left(B\right)$.
${\mathbf{tranb}}=\mathrm{Nag_NoTrans}$
$\mathrm{op}\left(B\right)=B$.
${\mathbf{tranb}}=\mathrm{Nag_Trans}$ or $\mathrm{Nag_ConjTrans}$
$\mathrm{op}\left(B\right)={B}^{\mathrm{T}}$.
Constraint: ${\mathbf{tranb}}=\mathrm{Nag_NoTrans}$, $\mathrm{Nag_Trans}$ or $\mathrm{Nag_ConjTrans}$.
4:     signNag_SignTypeInput
On entry: indicates the form of the Sylvester equation.
${\mathbf{sign}}=\mathrm{Nag_Plus}$
The equation is of the form $\mathrm{op}\left(A\right)X+X\mathrm{op}\left(B\right)=\alpha C$.
${\mathbf{sign}}=\mathrm{Nag_Minus}$
The equation is of the form $\mathrm{op}\left(A\right)X-X\mathrm{op}\left(B\right)=\alpha C$.
Constraint: ${\mathbf{sign}}=\mathrm{Nag_Plus}$ or $\mathrm{Nag_Minus}$.
5:     mIntegerInput
On entry: $m$, the order of the matrix $A$, and the number of rows in the matrices $X$ and $C$.
Constraint: ${\mathbf{m}}\ge 0$.
6:     nIntegerInput
On entry: $n$, the order of the matrix $B$, and the number of columns in the matrices $X$ and $C$.
Constraint: ${\mathbf{n}}\ge 0$.
7:     a[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pda}}×{\mathbf{m}}\right)$.
The $\left(i,j\right)$th element of the matrix $A$ is stored in
• ${\mathbf{a}}\left[\left(j-1\right)×{\mathbf{pda}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{a}}\left[\left(i-1\right)×{\mathbf{pda}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $m$ by $m$ upper quasi-triangular matrix $A$ in canonical Schur form, as returned by nag_dhseqr (f08pec).
8:     pdaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array a.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
9:     b[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdb}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $B$ is stored in
• ${\mathbf{b}}\left[\left(j-1\right)×{\mathbf{pdb}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{b}}\left[\left(i-1\right)×{\mathbf{pdb}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $n$ by $n$ upper quasi-triangular matrix $B$ in canonical Schur form, as returned by nag_dhseqr (f08pec).
10:   pdbIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array b.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
11:   c[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array c must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdc}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pdc}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $C$ is stored in
• ${\mathbf{c}}\left[\left(j-1\right)×{\mathbf{pdc}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{c}}\left[\left(i-1\right)×{\mathbf{pdc}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the $m$ by $n$ right-hand side matrix $C$.
On exit: c is overwritten by the solution matrix $X$.
12:   pdcIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array c.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
13:   scaledouble *Output
On exit: the value of the scale factor $\alpha$.
14:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}\ge 0$.
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}>0$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}>0$.
On entry, ${\mathbf{pdc}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdc}}>0$.
NE_INT_2
On entry, ${\mathbf{pda}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pda}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
On entry, ${\mathbf{pdb}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdb}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdc}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
On entry, ${\mathbf{pdc}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdc}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_PERTURBED
$A$ and $B$ have common or close eigenvalues, perturbed values of which were used to solve the equation.

## 7  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 Section 8.

The total number of floating point operations is approximately $mn\left(m+n\right)$.
To solve the general real Sylvester equation
 $AX ± XB = C$
where $A$ and $B$ are general nonsymmetric matrices, $A$ and $B$ must first be reduced to Schur form :
 $A = Q1 A~ Q1T and B = Q2 B~ Q2T$
where $\stackrel{~}{A}$ and $\stackrel{~}{B}$ are upper quasi-triangular and ${Q}_{1}$ and ${Q}_{2}$ are orthogonal. The original equation may then be transformed to:
 $A~ X~ ± X~ B~ = C~$
where $\stackrel{~}{X}={Q}_{1}^{\mathrm{T}}X{Q}_{2}$ and $\stackrel{~}{C}={Q}_{1}^{\mathrm{T}}C{Q}_{2}$. $\stackrel{~}{C}$ may be computed by matrix multiplication; nag_dtrsyl (f08qhc) 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{T}}$.
The complex analogue of this function is nag_ztrsyl (f08qvc).

## 9  Example

This example solves the Sylvester equation $AX+XB=C$, where
 $A = 0.10 0.50 0.68 -0.21 -0.50 0.10 -0.24 0.67 0.00 0.00 0.19 -0.35 0.00 0.00 0.00 -0.72 ,$
 $B = -0.99 -0.17 0.39 0.58 0.00 0.48 -0.84 -0.15 0.00 0.00 0.75 0.25 0.00 0.00 -0.25 0.75$
and
 $C = 0.63 -0.56 0.08 -0.23 -0.45 -0.31 0.27 1.21 0.20 -0.35 0.41 0.84 0.49 -0.05 -0.52 -0.08 .$

### 9.1  Program Text

Program Text (f08qhce.c)

### 9.2  Program Data

Program Data (f08qhce.d)

### 9.3  Program Results

Program Results (f08qhce.r)