NAG Toolbox: nag_eigen_complex_gen_quad (f02jq)

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)$ – complex 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)$ – complex 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)$ – complex 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)$ – complex 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)$ – complex 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)$ – complex 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{alpha}\left(2\times \mathbf{n}\right)$ – complex array

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

5:     $\mathrm{beta}\left(2\times \mathbf{n}\right)$ – complex 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. Although beta is declared complex, it is actually real and non-negative. Infinite eigenvalues have ${\beta }_j$ set to zero.

6:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – complex 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. 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.

7:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – complex 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. 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.

8:     $\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 real number (nag_machine_real_largest (x02al)).

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

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

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

11:   $\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_zgges (f08xn).

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

12:   $\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_zgges (f08xn).
iwarn returns the value of info returned by nag_lapack_zgges (f08xn). This failure is unlikely to happen, but if it does, please contact NAG.

   $\mathbf{ifail}=3$

The $QZ$ iteration failed in nag_lapack_zggev (f08wn).
iwarn returns the value of info returned by nag_lapack_zggev (f08wn). 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}=-16$

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

   $\mathbf{ifail}=-18$

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: f02jq_example

function f02jq_example


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

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

a = [ 2 4 4;
      6 2 2;
      6 4 2]*i;

b = [ 3 2 1;
      2 1 3;
      1 3 2]*(1+i);

c = complex([ 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, alpha, beta, vl, vr, s, bevl, bevr, iwarn, ifail] = ...
  f02jq(...
        scal, 'V', 'V', sense, tol, a, b, c);

eigv = alpha./beta;
disp('Eigenvalues:');
disp(eigv);
[ifail] = x04da('General', ' ', vr, 'Right eigenvectors:');
disp(' ');
[ifail] = x04da('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));

f02jq example results

Eigenvalues:
  -1.9256 + 1.9256i
  -0.6975 - 0.1053i
   0.1053 + 0.6975i
  -0.0496 - 0.5729i
   0.5729 + 0.0496i
   0.3945 - 0.3945i

 Right eigenvectors:
          1       2       3       4       5       6
 1  -0.2108  0.3751  0.3751 -0.6593 -0.6593 -0.3478
     0.0000  0.1877 -0.1877 -0.0424  0.0424  0.0000

 2   0.7695  0.5020  0.5020  0.0302  0.0302  0.8277
     0.0000  0.2433 -0.2433 -0.0197  0.0197  0.0000

 3  -0.6028  0.7162  0.7162  0.7498  0.7498 -0.4405
    -0.0000  0.0000  0.0000  0.0000  0.0000 -0.0000
 
 Left eigenvectors:
          1       2       3       4       5       6
 1   0.1052  0.7816  0.7816  0.8079  0.8079  0.0358
     0.0000  0.0000  0.0000  0.0000  0.0000  0.0000

 2   0.7381  0.5075  0.5075 -0.1124 -0.1124  0.7072
     0.0000  0.1352 -0.1352  0.0314 -0.0314  0.0000

 3  -0.6664  0.3202  0.3202 -0.5704 -0.5704 -0.7061
    -0.0000  0.1038 -0.1038 -0.0913  0.0913 -0.0000
 
Eigenvalue condition numbers:
    3.0717
    0.6620
    0.6620
    2.3848
    2.3848
    1.7625


Maximum backward errors for eigenvalues and
                         right eigenvectors: 4.41e-16
                          left eigenvectors: 5.30e-16