naginterfaces.library.lapackeig.zgghd3

naginterfaces.library.lapackeig.zgghd3(compq, compz, ilo, ihi, a, b, q, z)

zgghd3 reduces a pair of complex matrices $(A,B)$, where $B$ is upper triangular, to the generalized upper Hessenberg form using unitary transformations.

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

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

Parameters

compqstr, length 1

Specifies the form of the computed unitary matrix $Q$.

$compq=\text{'N'}$

Do not compute $Q$.

$compq=\text{'I'}$

The unitary matrix $Q$ is returned.

$compq=\text{'V'}$

$q$ must contain a unitary matrix $Q_1$, and the product $Q_{1}Q$ is returned.

compzstr, length 1

Specifies the form of the computed unitary matrix $Z$.

$compz=\text{'N'}$

Do not compute $Z$.

$compz=\text{'V'}$

$z$ must contain a unitary matrix $Z_1$, and the product $Z_{1}Z$ is returned.

$compz=\text{'I'}$

The unitary matrix $Z$ is returned.

iloint

$i_{lo}$ and $i_{hi}$ as determined by a previous call to zggbal(). Otherwise, they should be set to $1$ and $n$, respectively.

ihiint

$i_{lo}$ and $i_{hi}$ as determined by a previous call to zggbal(). Otherwise, they should be set to $1$ and $n$, respectively.

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

The matrix $A$ of the matrix pair $(A,B)$. Usually, this is the matrix $A$ returned by zunmqr().

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

The upper triangular matrix $B$ of the matrix pair $(A,B)$. Usually, this is the matrix $B$ returned by the $QR$ factorization function zgeqrf().

qcomplex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $compq\text{in}(\text{'I'},\text{'V'})$: $n$; if $compq=\text{'N'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $compq\text{in}(\text{'I'},\text{'V'})$: $n$; if $compq=\text{'N'}$: $1$; otherwise: $0$.

If $compq=\text{'V'}$, $q$ must contain a unitary matrix $Q_1$.

If $compq=\text{'N'}$, $q$ is not referenced.

zcomplex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $compz\text{in}(\text{'V'},\text{'I'})$: $max(1,n)$; if $compz=\text{'N'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $compz\text{in}(\text{'V'},\text{'I'})$: $n$; if $compz=\text{'N'}$: $1$; otherwise: $0$.

If $compz=\text{'V'}$, $z$ must contain a unitary matrix $Z_1$.

If $compz=\text{'N'}$, $z$ is not referenced.

Returns

acomplex, ndarray, shape $(n,n)$

$a$ is overwritten by the upper Hessenberg matrix $H$.

bcomplex, ndarray, shape $(n,n)$

$b$ is overwritten by the upper triangular matrix $T$.

qcomplex, ndarray, shape $(:,:)$

If $compq=\text{'I'}$, $q$ contains the unitary matrix $Q$.

Iif $compq=\text{'V'}$, $q$ is overwritten by $Q_{1}Q$.

zcomplex, ndarray, shape $(:,:)$

If $compz=\text{'I'}$, $z$ contains the unitary matrix $Z$.

If $compz=\text{'V'}$, $z$ is overwritten by $Z_{1}Z$.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $compq$.

Constraint: $compq=\text{'N'}$, $\text{'I'}$ or $\text{'V'}$.

(errno $-2$)

On entry, error in parameter $compz$.

Constraint: $compz=\text{'N'}$, $\text{'V'}$ or $\text{'I'}$.

(errno $-3$)

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

Constraint: $n\ge 0$.

(errno $-4$)

On entry, error in parameter $ilo$.

Constraint: $ilo\ge 1$.

(errno $-5$)

On entry, error in parameter $ihi$.

Constraint: $1\le ilo\le ihi\le n$.

(errno $-5$)

On entry, error in parameter $ihi$.

Constraint: $ilo=1$ and $ihi=0$.

Notes

zgghd3 is usually the third step in the solution of the complex generalized eigenvalue problem

$$Ax=\lambda Bx\text{.}$$

The (optional) first step balances the two matrices using zggbal(). In the second step, matrix $B$ is reduced to upper triangular form using the $QR$ factorization function zgeqrf() and this unitary transformation $Q$ is applied to matrix $A$ by calling zunmqr(). The driver, zggev3(), solves the complex generalized eigenvalue problem by combining all the required steps including those just listed.

zgghd3 reduces a pair of complex matrices $(A,B)$, where $B$ is triangular, to the generalized upper Hessenberg form using unitary transformations. This two-sided transformation is of the form

$$\begin{array}{c}\begin{array}{c}{Q}^{H}AZ=H\text{,}\\ Q^{H}BZ=T\end{array}\end{array}$$

where $H$ is an upper Hessenberg matrix, $T$ is an upper triangular matrix and $Q$ and $Z$ are unitary matrices determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices $Q_1$ and $Z_1$, so that

$$\begin{array}{c}\begin{array}{c}{Q}_{1}A{Z}_1^H=\left(Q_{1}Q\right)H{\left(Z_{1}Z\right)}^H\text{,}\\ Q_{1}B{Z}_1^H=\left(Q_{1}Q\right)T{\left(Z_{1}Z\right)}^H\text{.}\end{array}\end{array}$$

References

Golub, G H and Van Loan, C F, 2012, Matrix Computations, (4th Edition), Johns Hopkins University Press, Baltimore

Moler, C B and Stewart, G W, 1973, An algorithm for generalized matrix eigenproblems, SIAM J. Numer. Anal. (10), 241–256