naginterfaces.library.lapackeig.dgghd3

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

dgghd3 reduces a pair of real matrices $(A,B)$, where $B$ is upper triangular, to the generalized upper Hessenberg form using orthogonal transformations.

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

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

Parameters

compqstr, length 1

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

$compq=\text{'N'}$

Do not compute $Q$.

$compq=\text{'I'}$

The orthogonal matrix $Q$ is returned.

$compq=\text{'V'}$

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

compzstr, length 1

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

$compz=\text{'N'}$

Do not compute $Z$.

$compz=\text{'I'}$

The orthogonal matrix $Z$ is returned.

$compz=\text{'V'}$

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

iloint

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

ihiint

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

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

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

bfloat, 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 dgeqrf().

qfloat, 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 an orthogonal matrix $Q_1$.

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

zfloat, 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 an orthogonal matrix $Z_1$.

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

Returns

afloat, ndarray, shape $(n,n)$

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

bfloat, ndarray, shape $(n,n)$

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

qfloat, ndarray, shape $(:,:)$

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

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

zfloat, ndarray, shape $(:,:)$

If $compz=\text{'I'}$, $z$ contains the orthogonal 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

dgghd3 is the third step in the solution of the real generalized eigenvalue problem

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

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

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

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

where $H$ is an upper Hessenberg matrix, $T$ is an upper triangular matrix and $Q$ and $Z$ are orthogonal 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^T=\left(Q_{1}Q\right)H{\left(Z_{1}Z\right)}^T\text{,}\\ Q_{1}B{Z}_1^T=\left(Q_{1}Q\right)T{\left(Z_{1}Z\right)}^T\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