NAG CL Interface
f02jcc (real_​gen_​quad)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

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

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

$\mathbf{scal}=\mathrm{Nag\_NoScale}$

No scaling.

$\mathbf{scal}=\mathrm{Nag\_CondFanLinVanDooren}$ (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}=\mathrm{Nag\_FanLinVanDooren}$

Fan, Lin and Van Dooren scaling.

$\mathbf{scal}=\mathrm{Nag\_TropicalLargest}$

Tropical scaling with largest root.

$\mathbf{scal}=\mathrm{Nag\_TropicalSmallest}$

Tropical scaling with smallest root.

Constraint: $\mathbf{scal}=\mathrm{Nag\_NoScale}$, $\mathrm{Nag\_CondFanLinVanDooren}$, $\mathrm{Nag\_FanLinVanDooren}$, $\mathrm{Nag\_TropicalLargest}$ or $\mathrm{Nag\_TropicalSmallest}$.

2: $\mathbf{jobvl}$ – Nag_LeftVecsType Input

On entry: if $\mathbf{jobvl}=\mathrm{Nag\_NotLeftVecs}$, do not compute left eigenvectors.

If $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$, compute the left eigenvectors.

If $\mathbf{sense}=\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrLeft}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$, jobvl must be set to $\mathrm{Nag\_LeftVecs}$.

Constraint: $\mathbf{jobvl}=\mathrm{Nag\_NotLeftVecs}$ or $\mathrm{Nag\_LeftVecs}$.

3: $\mathbf{jobvr}$ – Nag_RightVecsType Input

On entry: if $\mathbf{jobvr}=\mathrm{Nag\_NotRightVecs}$, do not compute right eigenvectors.

If $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$, compute the right eigenvectors.

If $\mathbf{sense}=\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrRight}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$, jobvr must be set to $\mathrm{Nag\_RightVecs}$.

Constraint: $\mathbf{jobvr}=\mathrm{Nag\_NotRightVecs}$ or $\mathrm{Nag\_RightVecs}$.

4: $\mathbf{sense}$ – Nag_CondErrType Input

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

$\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$

Do not compute condition numbers, or backward errors.

$\mathbf{sense}=\mathrm{Nag\_CondOnly}$

Just compute condition numbers for the eigenvalues.

$\mathbf{sense}=\mathrm{Nag\_BackErrLeft}$

Just compute backward errors for the left eigenpairs.

$\mathbf{sense}=\mathrm{Nag\_BackErrRight}$

Just compute backward errors for the right eigenpairs.

$\mathbf{sense}=\mathrm{Nag\_BackErrBoth}$

Compute backward errors for the left and right eigenpairs.

$\mathbf{sense}=\mathrm{Nag\_CondBackErrLeft}$

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

$\mathbf{sense}=\mathrm{Nag\_CondBackErrRight}$

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

$\mathbf{sense}=\mathrm{Nag\_CondBackErrBoth}$

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

Constraint: $\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$, $\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrLeft}$, $\mathrm{Nag\_BackErrRight}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$.

5: $\mathbf{tol}$ – double 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 function X02AJC. 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[\mathit{dim}\right]$ – double Input/Output

Note: the dimension, dim, of the array a must be at least $\mathbf{pda}\times \mathbf{n}$.

The $\left(i,j\right)$th element of the matrix $A$ is stored in $\mathbf{a}\left[\left(j-1\right)\times \mathbf{pda}+i-1\right]$.

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

On exit: a is used as internal workspace, but if $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$ or $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$, a is restored on exit.

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

On entry: the stride separating matrix row elements in the array a.

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

9: $\mathbf{b}\left[\mathit{dim}\right]$ – double Input/Output

Note: the dimension, dim, of the array b must be at least $\mathbf{pdb}\times \mathbf{n}$.

The $\left(i,j\right)$th element of the matrix $B$ is stored in $\mathbf{b}\left[\left(j-1\right)\times \mathbf{pdb}+i-1\right]$.

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

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

10: $\mathbf{pdb}$ – Integer Input

On entry: the stride separating matrix row elements in the array b.

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

11: $\mathbf{c}\left[\mathit{dim}\right]$ – double Input/Output

Note: the dimension, dim, of the array c must be at least $\mathbf{pdc}\times \mathbf{n}$.

The $\left(i,j\right)$th element of the matrix $C$ is stored in $\mathbf{c}\left[\left(j-1\right)\times \mathbf{pdc}+i-1\right]$.

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

On exit: c is used as internal workspace, but if $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$ or $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$, c is restored on exit.

12: $\mathbf{pdc}$ – Integer Input

On entry: the stride separating matrix row elements in the array c.

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

13: $\mathbf{alphar}\left[2\times \mathbf{n}\right]$ – double Output

On exit: $\mathbf{alphar}\left[\mathit{j}-1\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]$ – double Output

On exit: $\mathbf{alphai}\left[\mathit{j}-1\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-1\right]$ is zero then the $j$th eigenvalue is real; if $\mathbf{alphai}\left[j-1\right]$ is positive then the $j$th and $\left(j+1\right)$th eigenvalues are a complex conjugate pair, with $\mathbf{alphai}\left[j\right]$ negative.

15: $\mathbf{beta}\left[2\times \mathbf{n}\right]$ – double Output

On exit: $\mathbf{beta}\left[\mathit{j}-1\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[\mathit{dim}\right]$ – double Output

Note: the dimension, dim, of the array vl must be at least $2\times \mathbf{n}$ when $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$.

where $\mathbf{VL}\left(i,j\right)$ appears in this document, it refers to the array element $\mathbf{vl}\left[\left(j-1\right)\times \mathbf{pdvl}+i-1\right]$.

On exit: if $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$, the left eigenvectors $y_j$ are stored one after another in 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}=\mathrm{Nag\_NotLeftVecs}$, vl is not referenced and may be NULL.

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

On entry: the stride separating matrix row elements in the array vl.

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

18: $\mathbf{vr}\left[\mathit{dim}\right]$ – double Output

Note: the dimension, dim, of the array vr must be at least $2\times \mathbf{n}$ when $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$.

where $\mathbf{VR}\left(i,j\right)$ appears in this document, it refers to the array element $\mathbf{vr}\left[\left(j-1\right)\times \mathbf{pdvr}+i-1\right]$.

On exit: if $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$, the right eigenvectors $x_j$ are stored one after another in 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}=\mathrm{Nag\_NotRightVecs}$, vr is not referenced and may be NULL.

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

On entry: the stride separating matrix row elements in the array vr.

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

20: $\mathbf{s}\left[\mathit{dim}\right]$ – double Output

Note: the dimension, dim, of the array s must be at least

• $2\times \mathbf{n}$ when $\mathbf{sense}=\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$.

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

On exit: if $\mathbf{sense}=\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$, $\mathbf{s}\left[j-1\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 double number (X02ALC).

If $\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$, $\mathrm{Nag\_BackErrLeft}$, $\mathrm{Nag\_BackErrRight}$ or $\mathrm{Nag\_BackErrBoth}$, s is not referenced and may be NULL.

21: $\mathbf{bevl}\left[\mathit{dim}\right]$ – double Output

Note: the dimension, dim, of the array bevl must be at least

• $2\times \mathbf{n}$ when $\mathbf{sense}=\mathrm{Nag\_BackErrLeft}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$ or $\mathrm{Nag\_CondBackErrBoth}$.

On exit: if $\mathbf{sense}=\mathrm{Nag\_BackErrLeft}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$ or $\mathrm{Nag\_CondBackErrBoth}$, $\mathbf{bevl}\left[j-1\right]$ contains the backward error estimate for the computed left eigenpair $\left({\lambda }_j,y_j\right)$.

If $\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$, $\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrRight}$ or $\mathrm{Nag\_CondBackErrRight}$, bevl is not referenced and may be NULL.

22: $\mathbf{bevr}\left[\mathit{dim}\right]$ – double Output

Note: the dimension, dim, of the array bevr must be at least

• $2\times \mathbf{n}$ when $\mathbf{sense}=\mathrm{Nag\_BackErrRight}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$.

On exit: if $\mathbf{sense}=\mathrm{Nag\_BackErrRight}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$, $\mathbf{bevr}\left[j-1\right]$ contains the backward error estimate for the computed right eigenpair $\left({\lambda }_j,x_j\right)$.

If $\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$, $\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrLeft}$ or $\mathrm{Nag\_CondBackErrLeft}$, bevr is not referenced and may be NULL.

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

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

If $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_NOERROR 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{fail}\mathbf{.}\mathbf{code}=$ NE_ITERATIONS_QZ, f08xac has flagged that iwarn eigenvalues are invalid.

If $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_ITERATIONS_QZ, f08wac has flagged that iwarn eigenvalues are invalid.

24: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.

NE_ARRAY_SIZE

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

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

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

On entry, $\mathbf{pdvl}=〈\mathit{\text{value}}〉$, $\mathbf{n}=〈\mathit{\text{value}}〉$ and $\mathbf{jobvl}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$, $\mathbf{pdvl}\ge \mathbf{n}$.

On entry, $\mathbf{pdvr}=〈\mathit{\text{value}}〉$, $\mathbf{n}=〈\mathit{\text{value}}〉$ and $\mathbf{jobvr}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$, $\mathbf{pdvr}\ge \mathbf{n}$.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_INT

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

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.

NE_INVALID_VALUE

On entry, $\mathbf{sense}=〈\mathit{\text{value}}〉$ and $\mathbf{jobvl}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{jobvl}=\mathrm{Nag\_NotLeftVecs}$, $\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$ or $\mathrm{Nag\_BackErrRight}$,
when $\mathbf{jobvl}=\mathrm{Nag\_LeftVecs}$, $\mathbf{sense}=\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrLeft}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$.

On entry, $\mathbf{sense}=〈\mathit{\text{value}}〉$ and $\mathbf{jobvr}=〈\mathit{\text{value}}〉$.
Constraint: when $\mathbf{jobvr}=\mathrm{Nag\_NotRightVecs}$, $\mathbf{sense}=\mathrm{Nag\_NoCondBackErr}$ or $\mathrm{Nag\_BackErrLeft}$,
when $\mathbf{jobvr}=\mathrm{Nag\_RightVecs}$, $\mathbf{sense}=\mathrm{Nag\_CondOnly}$, $\mathrm{Nag\_BackErrRight}$, $\mathrm{Nag\_BackErrBoth}$, $\mathrm{Nag\_CondBackErrLeft}$, $\mathrm{Nag\_CondBackErrRight}$ or $\mathrm{Nag\_CondBackErrBoth}$.

NE_ITERATIONS_QZ

The $QZ$ iteration failed in f08wac.
iwarn returns the value of info returned by f08wac. This failure is unlikely to happen, but if it does, please contact NAG.

The $QZ$ iteration failed in f08xac.
iwarn returns the value of info returned by f08xac. This failure is unlikely to happen, but if it does, please contact NAG.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

NE_SINGULAR

The quadratic matrix polynomial is nonregular (singular).

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results