NAG Toolbox: nag_eigen_real_gen_quad (f02jc)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{scal}$ – int64int32nag_int scalar

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}$ – string (length ≥ 1)

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}$ – string (length ≥ 1)

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}$ – int64int32nag_int scalar

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}$ – double scalar

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 function nag_machine_precision (x02aj). If tol is $-1.0$ on entry then no deflation is attempted. The recommended value for tol is zero.

6:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array

The first dimension of the array a must be at least $\mathbf{n}$.

The second dimension of the array a must be at least $\mathbf{n}$.

The $n$ by $n$ matrix $A$.

7:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array

The first dimension of the array b must be at least $\mathbf{n}$.

The second dimension of the array b must be at least $\mathbf{n}$.

The $n$ by $n$ matrix $B$.

8:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double array

The first dimension of the array c must be at least $\mathbf{n}$.

The second dimension of the array c must be at least $\mathbf{n}$.

The $n$ by $n$ matrix $C$.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the second dimension of the arrays a, b, c and the first dimension of the arrays a, b, c. (An error is raised if these dimensions are not equal.)

The order of the matrices $A$, $B$ and $C$.

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

Output Parameters

1:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array

The first dimension of the array a will be $\mathbf{n}$.

The second dimension of the array a will be $\mathbf{n}$.

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

2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array

The first dimension of the array b will be $\mathbf{n}$.

The second dimension of the array b will be $\mathbf{n}$.

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

3:     $\mathrm{c}\left(\mathit{ldc},:\right)$ – double array

The first dimension of the array c will be $\mathbf{n}$.

The second dimension of the array c will be $\mathbf{n}$.

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

4:     $\mathrm{alphar}\left(2\times \mathbf{n}\right)$ – double array

$\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.

5:     $\mathrm{alphai}\left(2\times \mathbf{n}\right)$ – double array

$\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.

6:     $\mathrm{beta}\left(2\times \mathbf{n}\right)$ – double array

$\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.

7:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – double array

The first dimension of the array vl will be $\mathbf{n}$.

The second dimension of the array vl will be $2\times \mathbf{n}$ if $\mathbf{jobvl}=\text{'V'}$.

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.

8:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – double array

The first dimension of the array vr will be $\mathbf{n}$.

The second dimension of the array vr will be $2\times \mathbf{n}$ if $\mathbf{jobvr}=\text{'V'}$.

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.

9:     $\mathrm{s}\left(:\right)$ – double array

The dimension of the array s will be $2\times \mathbf{n}$ if $\mathbf{sense}=1$, $5$, $6$ or $7$

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

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 double number (nag_machine_real_largest (x02al)).

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

10:   $\mathrm{bevl}\left(:\right)$ – double array

The dimension of the array bevl will be $2\times \mathbf{n}$ if $\mathbf{sense}=2$, $4$, $5$ or $7$

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.

11:   $\mathrm{bevr}\left(:\right)$ – double array

The dimension of the array bevr will be $2\times \mathbf{n}$ if $\mathbf{sense}=3$, $4$, $6$ or $7$

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.

12:   $\mathrm{iwarn}$ – int64int32nag_int scalar

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 nag_lapack_dgges (f08xa).

If $\mathbf{ifail}=\mathbf{3}$, iwarn returns the value of info from nag_lapack_dggev (f08wa).

13:   $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

The quadratic matrix polynomial is nonregular (singular).

   $\mathbf{ifail}=2$

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

   $\mathbf{ifail}=3$

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

   $\mathbf{ifail}=-1$

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

   $\mathbf{ifail}=-2$

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$.

On entry, $\mathbf{jobvl}=\_$.
Constraint: $\mathbf{jobvl}=\text{'N'}$ or $\text{'V'}$.

   $\mathbf{ifail}=-3$

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$.

On entry, $\mathbf{jobvr}=\_$.
Constraint: $\mathbf{jobvr}=\text{'N'}$ or $\text{'V'}$.

   $\mathbf{ifail}=-4$

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

   $\mathbf{ifail}=-6$

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

   $\mathbf{ifail}=-8$

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

   $\mathbf{ifail}=-10$

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

   $\mathbf{ifail}=-12$

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

   $\mathbf{ifail}=-17$

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

   $\mathbf{ifail}=-19$

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

   $\mathbf{ifail}=-99$

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

   $\mathbf{ifail}=-399$

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

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f02jc_example

function f02jc_example


fprintf('f02jc example results\n\n');

% Solve quadratic eigenvalue problem defined by A, B and C:

a = [ 1 2 2;
      3 1 1;
      3 2 1];

b = [ 3 2 1;
      2 1 3;
      1 3 2];

c = [ 1 1 2;
      2 3 1;
      3 1 2];

% Use default scaling and compute eigenvalue condition numbers and
% backward errors for both left and right eigenpairs
scal  = int64(1);
sense = int64(7);
tol   = 0;
[a, b, c, alphar, alphai, beta, vl, vr, s, bevl, bevr, iwarn, ifail] = ...
  f02jc(...
        scal, 'V', 'V', sense, tol, a, b, c);

eigv = complex(alphar+alphai*i)./beta;
disp('Eigenvalues:');
disp(eigv);
[ifail] = x04ca('General', ' ', vr, 'Right eigenvectors:');
disp(' ');
[ifail] = x04ca('General', ' ', vl, 'Left eigenvectors:');
disp(' ');
disp('Eigenvalue condition numbers:');
disp(s);
fprintf('\nMaximum backward errors for eigenvalues and\n');
fprintf('%30s eigenvectors: %7.2e\n', 'right', max(bevr));
fprintf('%30s eigenvectors: %7.2e\n', 'left', max(bevl));

f02jc example results

Eigenvalues:
  -3.8513 + 0.0000i
  -0.5922 + 0.8028i
  -0.5922 - 0.8028i
   0.5233 + 0.6225i
   0.5233 - 0.6225i
   0.7891 + 0.0000i

 Right eigenvectors:
          1       2       3       4       5       6
 1  -0.2108  0.3751 -0.1877 -0.6593  0.0424 -0.3478
 2   0.7695  0.5020 -0.2433  0.0302  0.0197  0.8277
 3  -0.6028  0.7162  0.0000  0.7498  0.0000 -0.4405
 
 Left eigenvectors:
          1       2       3       4       5       6
 1   0.1052  0.7816  0.0000  0.8079  0.0000  0.0358
 2   0.7381  0.5075 -0.1352 -0.1124 -0.0314  0.7072
 3  -0.6664  0.3202 -0.1038 -0.5704  0.0913 -0.7061
 
Eigenvalue condition numbers:
    2.3092
    0.7027
    0.7027
    2.7013
    2.7013
    2.0144


Maximum backward errors for eigenvalues and
                         right eigenvectors: 4.85e-16
                          left eigenvectors: 5.18e-16