NAG FL Interface
f02jcf (real_​gen_​quad)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{scal}$ – Integer Input

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: $\mathbf{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: $\mathbf{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: $\mathbf{sense}$ – Integer Input

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: $\mathbf{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 \mathit{machine precision}$ is used in place of tol, where machine precision is as returned by routine x02ajf. A diagonal element of a triangular matrix, $R$, is regarded as zero if $\left|r_{jj}\right|\le \mathbf{tol}\times \mathrm{size}\left(X\right)$, or $n\times \mathit{machine precision}\times \mathrm{size}\left(X\right)$ when tol is zero, where $\mathrm{size}\left(X\right)$ is based on the size of the absolute values of the elements of the matrix $X$ containing the matrix $R$. See Hammarling et al. (2013) for the motivation. If tol is $-1.0$ on entry then no deflation is attempted. The recommended value for tol is zero.

6: $\mathbf{n}$ – Integer Input

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

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

7: $\mathbf{a}\left(\mathbf{lda},*\right)$ – Real (Kind=nag_wp) array Input/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'}$, a is restored on exit.

8: $\mathbf{lda}$ – Integer Input

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

Constraint: $\mathbf{lda}\ge \mathbf{n}$.

9: $\mathbf{b}\left(\mathbf{ldb},*\right)$ – Real (Kind=nag_wp) array Input/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: $\mathbf{ldb}$ – Integer Input

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

Constraint: $\mathbf{ldb}\ge \mathbf{n}$.

11: $\mathbf{c}\left(\mathbf{ldc},*\right)$ – Real (Kind=nag_wp) array Input/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: $\mathbf{ldc}$ – Integer Input

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

Constraint: $\mathbf{ldc}\ge \mathbf{n}$.

13: $\mathbf{alphar}\left(2\times \mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

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

14: $\mathbf{alphai}\left(2\times \mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

On exit: $\mathbf{alphai}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,2n$, contains the imaginary part of ${\alpha }_j$ for the $j$th eigenvalue pair $\left({\alpha }_j,{\beta }_j\right)$ of the quadratic eigenvalue problem. If $\mathbf{alphai}\left(j\right)$ is zero then the $j$th eigenvalue is real; if $\mathbf{alphai}\left(j\right)$ is positive then the $j$th and $\left(j+1\right)$th eigenvalues are a complex conjugate pair, with $\mathbf{alphai}\left(j+1\right)$ negative.

15: $\mathbf{beta}\left(2\times \mathbf{n}\right)$ – Real (Kind=nag_wp) array Output

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, with ${\beta }_j\ge 0$. Infinite eigenvalues have ${\beta }_j$ set to zero.

16: $\mathbf{vl}\left(\mathbf{ldvl},*\right)$ – Real (Kind=nag_wp) array Output

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. If the $j$th eigenvalue is real, then $y_j=\mathbf{vl}\left(:,j\right)$, the $j$th column of vl. If the $j$th and $\left(j+1\right)$th eigenvalues form a complex conjugate pair, then $y_j=\mathbf{vl}\left(:,j\right)+i\times \mathbf{vl}\left(:,j+1\right)$ and $y_{j+1}=\mathbf{vl}\left(:,j\right)-i\times \mathbf{vl}\left(:,j+1\right)$. 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.

17: $\mathbf{ldvl}$ – Integer Input

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

Constraint: $\mathbf{ldvl}\ge \mathbf{n}$.

18: $\mathbf{vr}\left(\mathbf{ldvr},*\right)$ – Real (Kind=nag_wp) array Output

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. If the $j$th eigenvalue is real, then $x_j=\mathbf{vr}\left(:,j\right)$, the $j$th column of vr. If the $j$th and $\left(j+1\right)$th eigenvalues form a complex conjugate pair, then $x_j=\mathbf{vr}\left(:,j\right)+i\times \mathbf{vr}\left(:,j+1\right)$ and $x_{j+1}=\mathbf{vr}\left(:,j\right)-i\times \mathbf{vr}\left(:,j+1\right)$. 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.

19: $\mathbf{ldvr}$ – Integer Input

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

Constraint: $\mathbf{ldvr}\ge \mathbf{n}$.

20: $\mathbf{s}\left(*\right)$ – Real (Kind=nag_wp) array Output

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.

21: $\mathbf{bevl}\left(*\right)$ – Real (Kind=nag_wp) array Output

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.

22: $\mathbf{bevr}\left(*\right)$ – Real (Kind=nag_wp) array Output

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.

23: $\mathbf{iwarn}$ – Integer Output

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{iwarn}=4$, $‖\mathbf{b}‖\ge 10\sqrt{‖A‖·‖C‖}$ and backward stability cannot be guaranteed.

If $\mathbf{ifail}=\mathbf{2}$, iwarn returns the value of info from f08xaf.

If $\mathbf{ifail}=\mathbf{3}$, iwarn returns the value of info from f08waf.

24: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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 f08xaf.
iwarn returns the value of info returned by f08xaf. This failure is unlikely to happen, but if it does, please contact NAG.

$\mathbf{ifail}=3$

The $QZ$ iteration failed in f08waf.
iwarn returns the value of info returned by f08waf. 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}=-17$

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}=-19$

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 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results