NAG Library Routine Document

F02JQF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{SCAL}$ – INTEGERInput

On entry: determines the form of scaling to be performed on $A$, $B$ and $C$.

$\mathbf{SCAL}=0$

No scaling.

$\mathbf{SCAL}=1$ (the recommended value)

Fan, Lin and Van Dooren scaling if $\frac{‖B‖}{\sqrt{‖A‖\times ‖C‖}}<10$ and no scaling otherwise where $‖Z‖$ is the Frobenius norm of $Z$.

$\mathbf{SCAL}=2$

Fan, Lin and Van Dooren scaling.

$\mathbf{SCAL}=3$

Tropical scaling with largest root.

$\mathbf{SCAL}=4$

Tropical scaling with smallest root.

Constraint: $\mathbf{SCAL}=0$, $1$, $2$, $3$ or $4$.

2:     $\mathrm{JOBVL}$ – CHARACTER(1)Input

On entry: if $\mathbf{JOBVL}=\text{'N'}$, do not compute left eigenvectors.

If $\mathbf{JOBVL}=\text{'V'}$, compute the left eigenvectors.

If $\mathbf{SENSE}=1$, $2$, $4$, $5$, $6$ or $7$, JOBVL must be set to 'V'.

Constraint: $\mathbf{JOBVL}=\text{'N'}$ or $\text{'V'}$.

3:     $\mathrm{JOBVR}$ – CHARACTER(1)Input

On entry: if $\mathbf{JOBVR}=\text{'N'}$, do not compute right eigenvectors.

If $\mathbf{JOBVR}=\text{'V'}$, compute the right eigenvectors.

If $\mathbf{SENSE}=1$, $3$, $4$, $5$, $6$ or $7$, JOBVR must be set to 'V'.

Constraint: $\mathbf{JOBVR}=\text{'N'}$ or $\text{'V'}$.

4:     $\mathrm{SENSE}$ – INTEGERInput

On entry: determines whether, or not, condition numbers and backward errors are computed.

$\mathbf{SENSE}=0$

Do not compute condition numbers, or backward errors.

$\mathbf{SENSE}=1$

Just compute condition numbers for the eigenvalues.

$\mathbf{SENSE}=2$

Just compute backward errors for the left eigenpairs.

$\mathbf{SENSE}=3$

Just compute backward errors for the right eigenpairs.

$\mathbf{SENSE}=4$

Compute backward errors for the left and right eigenpairs.

$\mathbf{SENSE}=5$

Compute condition numbers for the eigenvalues and backward errors for the left eigenpairs.

$\mathbf{SENSE}=6$

Compute condition numbers for the eigenvalues and backward errors for the right eigenpairs.

$\mathbf{SENSE}=7$

Compute condition numbers for the eigenvalues and backward errors for the left and right eigenpairs.

Constraint: $\mathbf{SENSE}=0$, $1$, $2$, $3$, $4$, $5$, $6$ or $7$.

5:     $\mathrm{TOL}$ – REAL (KIND=nag_wp)Input

On entry: TOL is used as the tolerance for making decisions on rank in the deflation procedure. If TOL is zero on entry then $n\times \max \left(‖A‖,‖B‖,‖C‖\right)\times \mathit{machine precision}$ is used in place of TOL, where $‖Z‖$ is the Frobenius norm of the (scaled) matrix $Z$ and machine precision is as returned by routine X02AJF. If TOL is $-1.0$ on entry then no deflation is attempted. The recommended value for TOL is zero.

6:     $\mathrm{N}$ – INTEGERInput

On entry: the order of the matrices $A$, $B$ and $C$.

Constraint: $\mathbf{N}\ge 0$.

7:     $\mathrm{A}\left(\mathbf{LDA},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array A must be at least $\mathbf{N}$.

On entry: the $n$ by $n$ matrix $A$.

On exit: A is used as internal workspace, but if $\mathbf{JOBVL}=\text{'V'}$ or $\mathbf{JOBVR}=\text{'V'}$, then A is restored on exit.

8:     $\mathrm{LDA}$ – INTEGERInput

On entry: the first dimension of the array A as declared in the (sub)program from which F02JQF is called.

Constraint: $\mathbf{LDA}\ge \mathbf{N}$.

9:     $\mathrm{B}\left(\mathbf{LDB},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array B must be at least $\mathbf{N}$.

On entry: the $n$ by $n$ matrix $B$.

On exit: B is used as internal workspace, but is restored on exit.

10:   $\mathrm{LDB}$ – INTEGERInput

On entry: the first dimension of the array B as declared in the (sub)program from which F02JQF is called.

Constraint: $\mathbf{LDB}\ge \mathbf{N}$.

11:   $\mathrm{C}\left(\mathbf{LDC},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array C must be at least $\mathbf{N}$.

On entry: the $n$ by $n$ matrix $C$.

On exit: C is used as internal workspace, but if $\mathbf{JOBVL}=\text{'V'}$ or $\mathbf{JOBVR}=\text{'V'}$, C is restored on exit.

12:   $\mathrm{LDC}$ – INTEGERInput

On entry: the first dimension of the array C as declared in the (sub)program from which F02JQF is called.

Constraint: $\mathbf{LDC}\ge \mathbf{N}$.

13:   $\mathrm{ALPHA}\left(2\times \mathbf{N}\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

On exit: $\mathbf{ALPHA}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,2n$, contains the first part of the the $j$th eigenvalue pair $\left({\alpha }_j,{\beta }_j\right)$ of the quadratic eigenvalue problem.

14:   $\mathrm{BETA}\left(2\times \mathbf{N}\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

On exit: $\mathbf{BETA}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,2n$, contains the second part of the $j$th eigenvalue pair $\left({\alpha }_j,{\beta }_j\right)$ of the quadratic eigenvalue problem. Although BETA is declared complex, it is actually real and non-negative. Infinite eigenvalues have ${\beta }_j$ set to zero.

15:   $\mathrm{VL}\left(\mathbf{LDVL},*\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

Note: the second dimension of the array VL must be at least $2\times \mathbf{N}$ if $\mathbf{JOBVL}=\text{'V'}$.

On exit: if $\mathbf{JOBVL}=\text{'V'}$, the left eigenvectors $y_j$ are stored one after another in the columns of VL, in the same order as the corresponding eigenvalues. Each eigenvector will be normalized with length unity and with the element of largest modulus real and positive.

If $\mathbf{JOBVL}=\text{'N'}$, VL is not referenced.

16:   $\mathrm{LDVL}$ – INTEGERInput

On entry: the first dimension of the array VL as declared in the (sub)program from which F02JQF is called.

Constraint: $\mathbf{LDVL}\ge \mathbf{N}$.

17:   $\mathrm{VR}\left(\mathbf{LDVR},*\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

Note: the second dimension of the array VR must be at least $2\times \mathbf{N}$ if $\mathbf{JOBVR}=\text{'V'}$.

On exit: if $\mathbf{JOBVR}=\text{'V'}$, the right eigenvectors $x_j$ are stored one after another in the columns of VR, in the same order as the corresponding eigenvalues. Each eigenvector will be normalized with length unity and with the element of largest modulus real and positive.

If $\mathbf{JOBVR}=\text{'N'}$, VR is not referenced.

18:   $\mathrm{LDVR}$ – INTEGERInput

On entry: the first dimension of the array VR as declared in the (sub)program from which F02JQF is called.

Constraint: $\mathbf{LDVR}\ge \mathbf{N}$.

19:   $\mathrm{S}\left(*\right)$ – REAL (KIND=nag_wp) arrayOutput

Note: the dimension of the array S must be at least $2\times \mathbf{N}$ if $\mathbf{SENSE}=1$, $5$, $6$ or $7$.

Also: computing the condition numbers of the eigenvalues requires that both the left and right eigenvectors be computed.

On exit: if $\mathbf{SENSE}=1$, $5$, $6$ or $7$, $\mathbf{S}\left(j\right)$ contains the condition number estimate for the $j$th eigenvalue (large condition numbers imply that the problem is near one with multiple eigenvalues). Infinite condition numbers are returned as the largest model real number (X02ALF).

If $\mathbf{SENSE}=0$, $2$, $3$ or $4$, S is not referenced.

20:   $\mathrm{BEVL}\left(*\right)$ – REAL (KIND=nag_wp) arrayOutput

Note: the dimension of the array BEVL must be at least $2\times \mathbf{N}$ if $\mathbf{SENSE}=2$, $4$, $5$ or $7$.

On exit: if $\mathbf{SENSE}=2$, $4$, $5$ or $7$, $\mathbf{BEVL}\left(j\right)$ contains the backward error estimate for the computed left eigenpair $\left({\lambda }_j,y_j\right)$.

If $\mathbf{SENSE}=0$, $1$, $3$ or $6$, BEVL is not referenced.

21:   $\mathrm{BEVR}\left(*\right)$ – REAL (KIND=nag_wp) arrayOutput

Note: the dimension of the array BEVR must be at least $2\times \mathbf{N}$ if $\mathbf{SENSE}=3$, $4$, $6$ or $7$.

On exit: if $\mathbf{SENSE}=3$, $4$, $6$ or $7$, $\mathbf{BEVR}\left(j\right)$ contains the backward error estimate for the computed right eigenpair $\left({\lambda }_j,x_j\right)$.

If $\mathbf{SENSE}=0$, $1$, $2$ or $5$, BEVR is not referenced.

22:   $\mathrm{IWARN}$ – INTEGEROutput

On exit: IWARN will be positive if there are warnings, otherwise IWARN will be $0$.

If $\mathbf{IFAIL}=\mathbf{0}$ then:

• if $\mathbf{IWARN}=1$ then one, or both, of the matrices $A$ and $C$ is zero. In this case no scaling is performed, even if $\mathbf{SCAL}>0$;
• if $\mathbf{IWARN}=2$ then the matrices $A$ and $C$ are singular, or nearly singular, so the problem is potentially ill-posed;
• if $\mathbf{IWARN}=3$ then both the conditions for $\mathbf{IWARN}=1$ and $\mathbf{IWARN}=2$ above, apply.

If $\mathbf{IFAIL}=\mathbf{2}$, IWARN returns the value of INFO from F08XNF (ZGGES).

If $\mathbf{IFAIL}=\mathbf{3}$, IWARN returns the value of INFO from F08WNF (ZGGEV).

23:   $\mathrm{IFAIL}$ – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

The quadratic matrix polynomial is nonregular (singular).

$\mathbf{IFAIL}=2$

The $QZ$ iteration failed in F08XNF (ZGGES).
IWARN returns the value of INFO returned by F08XNF (ZGGES). This failure is unlikely to happen, but if it does, please contact NAG.

$\mathbf{IFAIL}=3$

The $QZ$ iteration failed in F08WNF (ZGGEV).
IWARN returns the value of INFO returned by F08WNF (ZGGEV). This failure is unlikely to happen, but if it does, please contact NAG.

$\mathbf{IFAIL}=-1$

On entry, $\mathbf{SCAL}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{SCAL}=0$, $1$, $2$, $3$ or $4$.

$\mathbf{IFAIL}=-2$

On entry, $\mathbf{JOBVL}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{JOBVL}=\text{'N'}$ or $\text{'V'}$.

On entry, $\mathbf{SENSE}=〈\mathit{\text{value}}〉$ and $\mathbf{JOBVL}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{JOBVL}=\text{'N'}$, $\mathbf{SENSE}=0$ or $3$,
when $\mathbf{JOBVL}=\text{'V'}$, $\mathbf{SENSE}=1$, $2$, $4$, $5$, $6$ or $7$.

$\mathbf{IFAIL}=-3$

On entry, $\mathbf{JOBVR}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{JOBVR}=\text{'N'}$ or $\text{'V'}$.

On entry, $\mathbf{SENSE}=〈\mathit{\text{value}}〉$ and $\mathbf{JOBVR}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{JOBVR}=\text{'N'}$, $\mathbf{SENSE}=0$ or $2$,
when $\mathbf{JOBVR}=\text{'V'}$, $\mathbf{SENSE}=1$, $3$, $4$, $5$, $6$ or $7$.

$\mathbf{IFAIL}=-4$

On entry, $\mathbf{SENSE}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{SENSE}=0$, $1$, $2$, $3$, $4$, $5$, $6$ or $7$.

$\mathbf{IFAIL}=-6$

On entry, $\mathbf{N}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{N}\ge 0$.

$\mathbf{IFAIL}=-8$

On entry, $\mathbf{LDA}=〈\mathit{\text{value}}〉$ and $\mathbf{N}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{LDA}\ge \mathbf{N}$.

$\mathbf{IFAIL}=-10$

On entry, $\mathbf{LDB}=〈\mathit{\text{value}}〉$ and $\mathbf{N}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{LDB}\ge \mathbf{N}$.

$\mathbf{IFAIL}=-12$

On entry, $\mathbf{LDC}=〈\mathit{\text{value}}〉$ and $\mathbf{N}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{LDC}\ge \mathbf{N}$.

$\mathbf{IFAIL}=-16$

On entry, $\mathbf{LDVL}=〈\mathit{\text{value}}〉$, $\mathbf{N}=〈\mathit{\text{value}}〉$ and $\mathbf{JOBVL}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{JOBVL}=\text{'V'}$, $\mathbf{LDVL}\ge \mathbf{N}$.

$\mathbf{IFAIL}=-18$

On entry, $\mathbf{LDVR}=〈\mathit{\text{value}}〉$, $\mathbf{N}=〈\mathit{\text{value}}〉$ and $\mathbf{JOBVR}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{JOBVR}=\text{'V'}$, $\mathbf{LDVR}\ge \mathbf{N}$.

$\mathbf{IFAIL}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 3.8 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 3.7 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-999$

Dynamic memory allocation failed.

See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f02jqfe.f90)

10.2  Program Data

Program Data (f02jqfe.d)

10.3  Program Results

Program Results (f02jqfe.r)