naginterfaces.library.lapackeig.dtgsyl

naginterfaces.library.lapackeig.dtgsyl(trans, ijob, a, b, c, d, e, f)

dtgsyl solves the generalized real quasi-triangular Sylvester equations.

For full information please refer to the NAG Library document for f08yh

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08yhf.html

Parameters

transstr, length 1

If $trans=\text{'N'}$, solve the generalized Sylvester equation (1).

If $trans=\text{'T'}$, solve the ‘transposed’ system (2).

ijobint

Specifies what kind of functionality is to be performed when $trans=\text{'N'}$.

$ijob=0$

Solve (1) only.

$ijob=1$

The functionality of $ijob=0$ or $3$.

$ijob=2$

The functionality of $ijob=0$ or $4$.

$ijob=3$

Only an estimate of $\text{Dif}[(A,D),(B,E)]$ is computed based on the Frobenius norm.

$ijob=4$

Only an estimate of $\text{Dif}[(A,D),(B,E)]$ is computed based on the $1$-norm.

If $trans=\text{'T'}$, $ijob$ is not referenced.

afloat, array-like, shape $(m,m)$

The upper quasi-triangular matrix $A$.

bfloat, array-like, shape $(n,n)$

The upper quasi-triangular matrix $B$.

cfloat, array-like, shape $(m,n)$

Contains the right-hand-side matrix $C$.

dfloat, array-like, shape $(m,m)$

The upper triangular matrix $D$.

efloat, array-like, shape $(n,n)$

The upper triangular matrix $E$.

ffloat, array-like, shape $(m,n)$

Contains the right-hand side matrix $F$.

Returns

cfloat, ndarray, shape $(m,n)$

If $ijob=0$, $1$ or $2$, $c$ is overwritten by the solution matrix $R$.

If $trans=\text{'N'}$ and $ijob=3$ or $4$, $c$ holds $R$, the solution achieved during the computation of the Dif estimate.

ffloat, ndarray, shape $(m,n)$

If $ijob=0$, $1$ or $2$, $f$ is overwritten by the solution matrix $L$.

If $trans=\text{'N'}$ and $ijob=3$ or $4$, $f$ holds $L$, the solution achieved during the computation of the Dif estimate.

scalefloat

$\alpha$, the scaling factor in (1) and (2).

If $0<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 $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, $scale=1$.

diffloat

The estimate of $Dif$. If $ijob=0$, $dif$ is not referenced.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $trans$.

Constraint: $trans=\text{'N'}$ or $\text{'T'}$.

(errno $-2$)

On entry, error in parameter $ijob$.

Constraint: $0\le ijob\le 4$.

(errno $-3$)

On entry, error in parameter $\text{m}$.

Constraint: $m>0$.

(errno $-4$)

On entry, error in parameter $\text{n}$.

Constraint: $n>0$.

(errno $i>0$)

$(A,D)$ and $(B,E)$ have common or close eigenvalues and so no solution could be computed.

Notes

dtgsyl solves either the generalized real Sylvester equations

$$\begin{array}{c}\begin{array}{cc}AR-LB& =\alpha C\\ DR-LE& =\alpha F\text{,}\end{array}\end{array}$$

or the equations

$$\begin{array}{c}\begin{array}{cc}{A}^{T}R+D^{T}L& =\alpha C\\ R{B}^T+L{E}^T& =-\alpha F\text{,}\end{array}\end{array}$$

where the pair $(A,D)$ are given $m\times m$ matrices in real generalized Schur form, $(B,E)$ are given $n\times n$ matrices in real generalized Schur form and $(C,F)$ are given $m\times n$ matrices. The pair $(R,L)$ are the $m\times n$ solution matrices, and $\alpha$ is an output scaling factor determined by the function to avoid overflow in computing $(R,L)$.

Equations (1) are equivalent to equations of the form

$$Zx=\alpha b\text{,}$$

where

$$\begin{array}{c}Z=\left(\begin{array}{c}I\otimes A-B^T\otimes I\\ I\otimes D-E^T\otimes I\end{array}\right)\end{array}$$

and $\otimes$ is the Kronecker product. Equations (2) are then equivalent to

$$Z^{T}y=\alpha b\text{.}$$

The pair $(S,T)$ are in real generalized Schur form if $S$ is block upper triangular with $1\times 1$ and $2\times 2$ diagonal blocks on the diagonal and $T$ is upper triangular as returned, for example, by dgges3(), or dhgeqz() with $\text{job}=\text{'S'}$.

Optionally, the function estimates $Dif[(A,D),(B,E)]$, the separation between the matrix pairs $(A,D)$ and $(B,E)$, 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).

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, https://www.netlib.org/lapack/lug

Kågström, B, 1994, A perturbation analysis of the generalized Sylvester equation $(AR-LB,DR-LE)=(c,F)$, 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