nag_dtgsyl (f08yhc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_dtgsyl (f08yhc)

## 1  Purpose

nag_dtgsyl (f08yhc) solves the generalized real quasi-triangular Sylvester equations.

## 2  Specification

 #include #include
 void nag_dtgsyl (Nag_OrderType order, Nag_TransType trans, Integer ijob, Integer m, Integer n, const double a[], Integer pda, const double b[], Integer pdb, double c[], Integer pdc, const double d[], Integer pdd, const double e[], Integer pde, double f[], Integer pdf, double *scale, double *dif, NagError *fail)

## 3  Description

nag_dtgsyl (f08yhc) solves either the generalized real Sylvester equations
 $AR-LB =αC DR-LE =αF,$ (1)
or the equations
 $ATR+DTL =αC RBT+LET =-αF,$ (2)
where the pair $\left(A,D\right)$ are given $m$ by $m$ matrices in real generalized Schur form, $\left(B,E\right)$ are given $n$ by $n$ matrices in real generalized Schur form and $\left(C,F\right)$ are given $m$ by $n$ matrices. The pair $\left(R,L\right)$ are the $m$ by $n$ solution matrices, and $\alpha$ is an output scaling factor determined by the function to avoid overflow in computing $\left(R,L\right)$.
Equations (1) are equivalent to equations of the form
 $Zx=αb ,$
where
 $Z = I⊗A-BT⊗I I⊗D-ET⊗I$
and $\otimes$ is the Kronecker product. Equations (2) are then equivalent to
 $ZTy = αb .$
The pair $\left(S,T\right)$ are in real generalized Schur form if $S$ is block upper triangular with $1$ by $1$ and $2$ by $2$ diagonal blocks on the diagonal and $T$ is upper triangular as returned, for example, by nag_dgges (f08xac), or nag_dhgeqz (f08xec) with ${\mathbf{job}}=\mathrm{Nag_Schur}$.
Optionally, the function estimates $\mathrm{Dif}\left[\left(A,D\right),\left(B,E\right)\right]$, the separation between the matrix pairs $\left(A,D\right)$ and $\left(B,E\right)$, which is the smallest singular value of $Z$. The estimate can be based on either the Frobenius norm, or the $1$-norm. The $1$-norm estimate can be three to ten times more expensive than the Frobenius norm estimate, but makes the condition estimation uniform with the nonsymmetric eigenproblem. The Frobenius norm estimate provides a low cost, but equally reliable estimate. For more information see Sections 2.4.8.3 and 4.11.1.3 of Anderson et al. (1999) and Kågström and Poromaa (1996).

## 4  References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Kågström B (1994) A perturbation analysis of the generalized Sylvester equation $\left(AR-LB,DR-LE\right)=\left(c,F\right)$ SIAM J. Matrix Anal. Appl. 15 1045–1060
Kågström B and Poromaa P (1996) LAPACK-style algorithms and software for solving the generalized Sylvester equation and estimating the separation between regular matrix pairs ACM Trans. Math. Software 22 78–103

## 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:     transNag_TransTypeInput
On entry: if ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$, solve the generalized Sylvester equation (1).
If ${\mathbf{trans}}=\mathrm{Nag_Trans}$, solve the ‘transposed’ system (2).
Constraint: ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ or $\mathrm{Nag_Trans}$.
3:     ijobIntegerInput
On entry: specifies what kind of functionality is to be performed when ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$.
${\mathbf{ijob}}=0$
Solve (1) only.
${\mathbf{ijob}}=1$
The functionality of ${\mathbf{ijob}}=0$ and $3$.
${\mathbf{ijob}}=2$
The functionality of ${\mathbf{ijob}}=0$ and $4$.
${\mathbf{ijob}}=3$
Only an estimate of $\mathrm{Dif}\left[\left(A,D\right),\left(B,E\right)\right]$ is computed based on the Frobenius norm.
${\mathbf{ijob}}=4$
Only an estimate of $\mathrm{Dif}\left[\left(A,D\right),\left(B,E\right)\right]$ is computed based on the $1$-norm.
If ${\mathbf{trans}}=\mathrm{Nag_Trans}$, ijob is not referenced.
Constraint: if ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$, $0\le {\mathbf{ijob}}\le 4$.
4:     mIntegerInput
On entry: $m$, the order of the matrices $A$ and $D$, and the row dimension of the matrices $C$, $F$, $R$ and $L$.
Constraint: ${\mathbf{m}}\ge 0$.
5:     nIntegerInput
On entry: $n$, the order of the matrices $B$ and $E$, and the column dimension of the matrices $C$, $F$, $R$ and $L$.
Constraint: ${\mathbf{n}}\ge 0$.
6:     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 upper quasi-triangular matrix $A$.
7:     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)$.
8:     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 upper quasi-triangular matrix $B$.
9:     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)$.
10:   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: contains the right-hand-side matrix $C$.
On exit: if ${\mathbf{ijob}}=0$, $1$ or $2$, c is overwritten by the solution matrix $R$.
If ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ and ${\mathbf{ijob}}=3$ or $4$, c holds $R$, the solution achieved during the computation of the Dif estimate.
11:   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)$.
12:   d[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array d must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdd}}×{\mathbf{m}}\right)$.
The $\left(i,j\right)$th element of the matrix $D$ is stored in
• ${\mathbf{d}}\left[\left(j-1\right)×{\mathbf{pdd}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{d}}\left[\left(i-1\right)×{\mathbf{pdd}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the upper triangular matrix $D$.
13:   pddIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array d.
Constraint: ${\mathbf{pdd}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
14:   e[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array e must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pde}}×{\mathbf{n}}\right)$.
The $\left(i,j\right)$th element of the matrix $E$ is stored in
• ${\mathbf{e}}\left[\left(j-1\right)×{\mathbf{pde}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{e}}\left[\left(i-1\right)×{\mathbf{pde}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: the upper triangular matrix $E$.
15:   pdeIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array e.
Constraint: ${\mathbf{pde}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
16:   f[$\mathit{dim}$]doubleInput/Output
Note: the dimension, dim, of the array f must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdf}}×{\mathbf{n}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}×{\mathbf{pdf}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
The $\left(i,j\right)$th element of the matrix $F$ is stored in
• ${\mathbf{f}}\left[\left(j-1\right)×{\mathbf{pdf}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{f}}\left[\left(i-1\right)×{\mathbf{pdf}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On entry: contains the right-hand side matrix $F$.
On exit: if ${\mathbf{ijob}}=0$, $1$ or $2$, f is overwritten by the solution matrix $L$.
If ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$ and ${\mathbf{ijob}}=3$ or $4$, f holds $L$, the solution achieved during the computation of the Dif estimate.
17:   pdfIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array f.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdf}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdf}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
18:   scaledouble *Output
On exit: $\alpha$, the scaling factor in (1) or (2).
If $0<{\mathbf{scale}}<1$, c and f hold the solutions $R$ and $L$, respectively, to a slightly perturbed system but the input arrays a, b, d and e have not been changed.
If ${\mathbf{scale}}=0$, c and f hold the solutions $R$ and $L$, respectively, to the homogeneous system with $C=F=0$. In this case dif is not referenced.
Normally, ${\mathbf{scale}}=1$.
19:   difdouble *Output
On exit: the estimate of $\mathrm{Dif}$. If ${\mathbf{ijob}}=0$, dif is not referenced.
20:   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.
NE_BAD_PARAM
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_EIGENVALUES
$\left(A,D\right)$ and $\left(B,E\right)$ have common or close eigenvalues and so no solution could be computed.
NE_ENUM_INT
On entry, ${\mathbf{ijob}}=〈\mathit{\text{value}}〉$ and ${\mathbf{trans}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{trans}}=\mathrm{Nag_NoTrans}$, $0\le {\mathbf{ijob}}\le 4$.
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$.
On entry, ${\mathbf{pdd}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdd}}>0$.
On entry, ${\mathbf{pde}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pde}}>0$.
On entry, ${\mathbf{pdf}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdf}}>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)$.
On entry, ${\mathbf{pdd}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdd}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
On entry, ${\mathbf{pde}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pde}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
On entry, ${\mathbf{pdf}}=〈\mathit{\text{value}}〉$ and ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdf}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$.
On entry, ${\mathbf{pdf}}=〈\mathit{\text{value}}〉$ and ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdf}}\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.

## 7  Accuracy

See Kågström (1994) for a perturbation analysis of the generalized Sylvester equation.

## 8  Further Comments

The total number of floating point operations needed to solve the generalized Sylvester equations is approximately $2mn\left(n+m\right)$. The Frobenius norm estimate of $\mathrm{Dif}$ does not require additional significant computation, but the $1$-norm estimate is typically five times more expensive.
The complex analogue of this function is nag_ztgsyl (f08yvc).

## 9  Example

This example solves the generalized Sylvester equations
 $AR-LB =αC DR-LE =αF,$
where
 $A = 4.0 1.0 1.0 2.0 0.0 3.0 4.0 1.0 0.0 1.0 3.0 1.0 0.0 0.0 0.0 6.0 , B= 1.0 1.0 1.0 1.0 0.0 3.0 4.0 1.0 0.0 1.0 3.0 1.0 0.0 0.0 0.0 4.0 ,$
 $D = 2.0 1.0 1.0 3.0 0.0 1.0 2.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0 2.0 , E= 1.0 1.0 1.0 2.0 0.0 1.0 4.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0 1.0 ,$
 $C = -4.0 7.0 1.0 12.0 -9.0 2.0 -2.0 -2.0 -4.0 2.0 -2.0 8.0 -7.0 7.0 -6.0 19.0 and F= -7.0 5.0 0.0 7.0 -5.0 1.0 -8.0 0.0 -1.0 2.0 -3.0 5.0 -3.0 2.0 0.0 5.0 .$

### 9.1  Program Text

Program Text (f08yhce.c)

### 9.2  Program Data

Program Data (f08yhce.d)

### 9.3  Program Results

Program Results (f08yhce.r)

nag_dtgsyl (f08yhc) (PDF version)
f08 Chapter Contents
f08 Chapter Introduction
NAG C Library Manual