naginterfaces.library.eigen.complex_​gen_​quad

naginterfaces.library.eigen.complex_gen_quad(scal, jobvl, jobvr, sense, tol, a, b, c)

complex_gen_quad solves the quadratic eigenvalue problem

$$({\lambda }^{2}A+\lambda B+C)x=0\text{,}$$

where $A$, $B$ and $C$ are complex $n\times n$ matrices.

The function returns the $2n$ eigenvalues, ${\lambda }_{\text{j}}$, for $\text{j}=1,2,\dots ,2n$, and can optionally return the corresponding right eigenvectors, $x_j$ and/or left eigenvectors, $y_j$ as well as estimates of the condition numbers of the computed eigenvalues and backward errors of the computed right and left eigenvectors. A left eigenvector satisfies the equation

$$y^H({\lambda }^{2}A+\lambda B+C)=0\text{,}$$

where $y^H$ is the complex conjugate transpose of $y$.

$\lambda$ is represented as the pair $(\alpha ,\beta )$, such that $\lambda =\alpha /\beta$. Note that the computation of $\alpha /\beta$ may overflow and indeed $\beta$ may be zero.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f02/f02jqf.html

Parameters

scalint

Determines the form of scaling to be performed on $A$, $B$ and $C$.

$scal=0$

No scaling.

$scal=1$ (the recommended value)

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

$scal=2$

Fan, Lin and Van Dooren scaling.

$scal=3$

Tropical scaling with largest root.

$scal=4$

Tropical scaling with smallest root.

jobvlstr, length 1

If $jobvl=\text{'N'}$, do not compute left eigenvectors.

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

If $sense=1$, $2$, $4$, $5$, $6$ or $7$, $jobvl$ must be set to ‘V’.

jobvrstr, length 1

If $jobvr=\text{'N'}$, do not compute right eigenvectors.

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

If $sense=1$, $3$, $4$, $5$, $6$ or $7$, $jobvr$ must be set to ‘V’.

senseint

Determines whether, or not, condition numbers and backward errors are computed.

$sense=0$

Do not compute condition numbers, or backward errors.

$sense=1$

Just compute condition numbers for the eigenvalues.

$sense=2$

Just compute backward errors for the left eigenpairs.

$sense=3$

Just compute backward errors for the right eigenpairs.

$sense=4$

Compute backward errors for the left and right eigenpairs.

$sense=5$

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

$sense=6$

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

$sense=7$

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

tolfloat

$tol$ is used as the tolerance for making decisions on rank in the deflation procedure. If $tol$ is zero on entry then $n\times \text{machine precision}$ is used in place of $tol$, where machine precision is as returned by function machine.precision. A diagonal element of a triangular matrix, $R$, is regarded as zero if $\left|r_{jj}\right|\le tol\times size\left(X\right)$, or $n\times \text{machine precision}\times size\left(X\right)$ when $tol$ is zero, where $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.

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

The $n\times n$ matrix $A$.

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

The $n\times n$ matrix $B$.

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

The $n\times n$ matrix $C$.

Returns

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

$a$ is used as internal workspace, but if $jobvl=\text{'V'}$ or $jobvr=\text{'V'}$, $a$ is restored on exit.

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

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

ccomplex, ndarray, shape $(n,n)$

$c$ is used as internal workspace, but if $jobvl=\text{'V'}$ or $jobvr=\text{'V'}$, $c$ is restored on exit.

alphacomplex, ndarray, shape $(2\times n)$

$alpha[\text{j}-1]$, for $\text{j}=1,2,\dots ,2n$, contains the first part of the $j$th eigenvalue pair $({\alpha }_j,{\beta }_j)$ of the quadratic eigenvalue problem.

betacomplex, ndarray, shape $(2\times n)$

$beta[\text{j}-1]$, for $\text{j}=1,2,\dots ,2n$, contains the second part of the $j$th eigenvalue pair $({\alpha }_j,{\beta }_j)$ 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.

vlNone or complex, ndarray, shape $(n,:)$

If $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 $jobvl=\text{'N'}$, $vl$ is not referenced.

vrNone or complex, ndarray, shape $(n,:)$

If $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 $jobvr=\text{'N'}$, $vr$ is not referenced.

sNone or float, ndarray, shape $(:)$

If $sense=1$, $5$, $6$ or $7$, $s[j-1]$ 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 (machine.real_largest).

If $sense=0$, $2$, $3$ or $4$, $s$ is not referenced.

bevlNone or float, ndarray, shape $(:)$

If $sense=2$, $4$, $5$ or $7$, $bevl[j-1]$ contains the backward error estimate for the computed left eigenpair $({\lambda }_j,y_j)$.

If $sense=0$, $1$, $3$ or $6$, $bevl$ is not referenced.

bevrNone or float, ndarray, shape $(:)$

If $sense=3$, $4$, $6$ or $7$, $bevr[j-1]$ contains the backward error estimate for the computed right eigenpair $({\lambda }_j,x_j)$.

If $sense=0$, $1$, $2$ or $5$, $bevr$ is not referenced.

iwarnint

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

If no exception or warning is raised then:

if $iwarn=1$ then one, or both, of the matrices $A$ and $C$ is zero. In this case no scaling is performed, even if $scal>0$;

if $iwarn=2$ then the matrices $A$ and $C$ are singular, or nearly singular, so the problem is potentially ill-posed;

if $iwarn=3$ then both the conditions for $iwarn=1$ and $iwarn=2$ above, apply. If $iwarn=4$, $\parallel b\parallel \ge 10\sqrt{\parallel A\parallel \cdot \parallel C\parallel }$ and backward stability cannot be guaranteed.

If $errno$ = 2, $iwarn$ returns the value of $\text{info}$ from lapackeig.zgges3.

If $errno$ = 3, $iwarn$ returns the value of $\text{info}$ from lapackeig.zggev3.

Raises

NagValueError

(errno $-18$)

On entry, $\text{ldvr}=⟨value⟩$, $n=⟨value⟩$ and $jobvr=⟨value⟩$.

Constraint: when $jobvr=\text{'V'}$, $\text{ldvr}\ge n$.

(errno $-16$)

On entry, $\text{ldvl}=⟨value⟩$, $n=⟨value⟩$ and $jobvl=⟨value⟩$.

Constraint: when $jobvl=\text{'V'}$, $\text{ldvl}\ge n$.

(errno $-6$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $-4$)

On entry, $sense=⟨value⟩$.

Constraint: $sense=0$, $1$, $2$, $3$, $4$, $5$, $6$ or $7$.

(errno $-3$)

On entry, $sense=⟨value⟩$ and $jobvr=⟨value⟩$.

Constraint: when $jobvr=\text{'N'}$, $sense=0$ or $2$,

when $jobvr=\text{'V'}$, $sense=1$, $3$, $4$, $5$, $6$ or $7$.

(errno $-3$)

On entry, $jobvr=⟨value⟩$.

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

(errno $-2$)

On entry, $sense=⟨value⟩$ and $jobvl=⟨value⟩$.

Constraint: when $jobvl=\text{'N'}$, $sense=0$ or $3$,

when $jobvl=\text{'V'}$, $sense=1$, $2$, $4$, $5$, $6$ or $7$.

(errno $-2$)

On entry, $jobvl=⟨value⟩$.

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

(errno $-1$)

On entry, $scal=⟨value⟩$.

Constraint: $scal=0$, $1$, $2$, $3$ or $4$.

(errno $1$)

The quadratic matrix polynomial is nonregular (singular).

(errno $2$)

The $QZ$ iteration failed in lapackeig.zgges3.

$iwarn$ returns the value of $\text{errno}$ returned by lapackeig.zgges3. This failure is unlikely to happen, but if it does, please contact NAG.

(errno $3$)

The $QZ$ iteration failed in lapackeig.zggev3.

$iwarn$ returns the value of $\text{errno}$ returned by lapackeig.zggev3. This failure is unlikely to happen, but if it does, please contact NAG.

Notes

The quadratic eigenvalue problem is solved by linearizing the problem and solving the resulting $2n\times 2n$ generalized eigenvalue problem. The linearization is chosen to have favourable conditioning and backward stability properties. An initial preprocessing step is performed that reveals and deflates the zero and infinite eigenvalues contributed by singular leading and trailing matrices.

The algorithm is backward stable for problems that are not too heavily damped, that is $\parallel B\parallel \le 10\sqrt{\parallel A\parallel \cdot \parallel C\parallel }$.

Further details on the algorithm are given in Hammarling et al. (2013).

References

Fan, H -Y, Lin, W.-W and Van Dooren, P., 2004, Normwise scaling of second order polynomial matrices, SIAM J. Matrix Anal. Appl. (26, 1), 252–256

Gaubert, S and Sharify, M, 2009, Tropical scaling of polynomial matrices, Lecture Notes in Control and Information Sciences Series (389), 291–303, Springer–Verlag

Hammarling, S, Munro, C J and Tisseur, F, 2013, An algorithm for the complete solution of quadratic eigenvalue problems, ACM Trans. Math. Software. (39(3):18:1–18:119), http://eprints.maths.manchester.ac.uk/2061/