NAG Toolbox: nag_lapack_zggevx (f08wp)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{balanc}$ – string (length ≥ 1)

Specifies the balance option to be performed.

$\mathbf{balanc}=\text{'N'}$

Do not diagonally scale or permute.

$\mathbf{balanc}=\text{'P'}$

Permute only.

$\mathbf{balanc}=\text{'S'}$

Scale only.

$\mathbf{balanc}=\text{'B'}$

Both permute and scale.

Computed reciprocal condition numbers will be for the matrices after permuting and/or balancing. Permuting does not change condition numbers (in exact arithmetic), but balancing does. In the absence of other information, $\mathbf{balanc}=\text{'B'}$ is recommended.

Constraint: $\mathbf{balanc}=\text{'N'}$, $\text{'P'}$, $\text{'S'}$ or $\text{'B'}$.

2:     $\mathrm{jobvl}$ – string (length ≥ 1)

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

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

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

3:     $\mathrm{jobvr}$ – string (length ≥ 1)

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

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

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

4:     $\mathrm{sense}$ – string (length ≥ 1)

Determines which reciprocal condition numbers are computed.

$\mathbf{sense}=\text{'N'}$

None are computed.

$\mathbf{sense}=\text{'E'}$

Computed for eigenvalues only.

$\mathbf{sense}=\text{'V'}$

Computed for eigenvectors only.

$\mathbf{sense}=\text{'B'}$

Computed for eigenvalues and eigenvectors.

Constraint: $\mathbf{sense}=\text{'N'}$, $\text{'E'}$, $\text{'V'}$ or $\text{'B'}$.

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

The first dimension of the array a must be at least $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array a must be at least $\max \left(1,\mathbf{n}\right)$.

The matrix $A$ in the pair $\left(A,B\right)$.

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

The first dimension of the array b must be at least $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array b must be at least $\max \left(1,\mathbf{n}\right)$.

The matrix $B$ in the pair $\left(A,B\right)$.

Optional Input Parameters

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

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

$n$, the order of the matrices $A$ and $B$.

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 $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array a will be $\max \left(1,\mathbf{n}\right)$.

a has been overwritten. If $\mathbf{jobvl}=\text{'V'}$ or $\mathbf{jobvr}=\text{'V'}$ or both, then $A$ contains the first part of the Schur form of the ‘balanced’ versions of the input $A$ and $B$.

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

The first dimension of the array b will be $\max \left(1,\mathbf{n}\right)$.

The second dimension of the array b will be $\max \left(1,\mathbf{n}\right)$.

b has been overwritten.

3:     $\mathrm{alpha}\left(\mathbf{n}\right)$ – complex array

See the description of beta.

4:     $\mathrm{beta}\left(\mathbf{n}\right)$ – complex array

$\mathbf{alpha}\left(\mathit{j}\right)/\mathbf{beta}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,\mathbf{n}$, will be the generalized eigenvalues.

Note:  the quotients $\mathbf{alpha}\left(j\right)/\mathbf{beta}\left(j\right)$ may easily overflow or underflow, and $\mathbf{beta}\left(j\right)$ may even be zero. Thus, you should avoid naively computing the ratio ${\alpha }_j/{\beta }_j$. However, $\max \left|{\alpha }_j\right|$ will always be less than and usually comparable with ${‖\mathbf{a}‖}_2$ in magnitude, and $\max \left|{\beta }_j\right|$ will always be less than and usually comparable with ${‖\mathbf{b}‖}_2$.

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

The first dimension, $\mathit{ldvl}$, of the array vl will be

• if $\mathbf{jobvl}=\text{'V'}$, $\mathit{ldvl}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldvl}=1$.

The second dimension of the array vl will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{jobvl}=\text{'V'}$ and $1$ otherwise.

If $\mathbf{jobvl}=\text{'V'}$, the left generalized eigenvectors $u_j$ are stored one after another in the columns of vl, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have $\left|\text{real part}\right|+\left|\text{imag. part}\right|=1$.

If $\mathbf{jobvl}=\text{'N'}$, vl is not referenced.

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

The first dimension, $\mathit{ldvr}$, of the array vr will be

• if $\mathbf{jobvr}=\text{'V'}$, $\mathit{ldvr}=\max \left(1,\mathbf{n}\right)$;
• otherwise $\mathit{ldvr}=1$.

The second dimension of the array vr will be $\max \left(1,\mathbf{n}\right)$ if $\mathbf{jobvr}=\text{'V'}$ and $1$ otherwise.

If $\mathbf{jobvr}=\text{'V'}$, the right generalized eigenvectors $v_j$ are stored one after another in the columns of vr, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have $\left|\text{real part}\right|+\left|\text{imag. part}\right|=1$.

If $\mathbf{jobvr}=\text{'N'}$, vr is not referenced.

7:     $\mathrm{ilo}$ – int64int32nag_int scalar

8:     $\mathrm{ihi}$ – int64int32nag_int scalar

ilo and ihi are integer values such that $\mathbf{a}\left(i,j\right)=0$ and $\mathbf{b}\left(i,j\right)=0$ if $i>j$ and $j=1,2,\dots ,\mathbf{ilo}-1$ or $i=\mathbf{ihi}+1,\dots ,\mathbf{n}$.

If $\mathbf{balanc}=\text{'N'}$ or $\text{'S'}$, $\mathbf{ilo}=1$ and $\mathbf{ihi}=\mathbf{n}$.

9:     $\mathrm{lscale}\left(\mathbf{n}\right)$ – double array

Details of the permutations and scaling factors applied to the left side of $A$ and $B$.

If ${\mathit{pl}}_j$ is the index of the row interchanged with row $j$, and ${\mathit{dl}}_j$ is the scaling factor applied to row $j$, then:

• $\mathbf{lscale}\left(\mathit{j}\right)={\mathit{pl}}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,\mathbf{ilo}-1$;
• $\mathbf{lscale}={\mathit{dl}}_{\mathit{j}}$, for $\mathit{j}=\mathbf{ilo},\dots ,\mathbf{ihi}$;
• $\mathbf{lscale}={\mathit{pl}}_{\mathit{j}}$, for $\mathit{j}=\mathbf{ihi}+1,\dots ,\mathbf{n}$.

The order in which the interchanges are made is n to $\mathbf{ihi}+1$, then $1$ to $\mathbf{ilo}-1$.

10:   $\mathrm{rscale}\left(\mathbf{n}\right)$ – double array

Details of the permutations and scaling factors applied to the right side of $A$ and $B$.

If ${\mathit{pr}}_j$ is the index of the column interchanged with column $j$, and ${\mathit{dr}}_j$ is the scaling factor applied to column $j$, then:

• $\mathbf{rscale}\left(\mathit{j}\right)={\mathit{pr}}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,\mathbf{ilo}-1$;
• if $\mathbf{rscale}={\mathit{dr}}_{\mathit{j}}$, for $\mathit{j}=\mathbf{ilo},\dots ,\mathbf{ihi}$;
• if $\mathbf{rscale}={\mathit{pr}}_{\mathit{j}}$, for $\mathit{j}=\mathbf{ihi}+1,\dots ,\mathbf{n}$.

The order in which the interchanges are made is n to $\mathbf{ihi}+1$, then $1$ to $\mathbf{ilo}-1$.

11:   $\mathrm{abnrm}$ – double scalar

The $1$-norm of the balanced matrix $A$.

12:   $\mathrm{bbnrm}$ – double scalar

The $1$-norm of the balanced matrix $B$.

13:   $\mathrm{rconde}\left(:\right)$ – double array

The dimension of the array rconde will be $\max \left(1,\mathbf{n}\right)$

If $\mathbf{sense}=\text{'E'}$ or $\text{'B'}$, the reciprocal condition numbers of the eigenvalues, stored in consecutive elements of the array.

If $\mathbf{sense}=\text{'N'}$ or $\text{'V'}$, rconde is not referenced.

14:   $\mathrm{rcondv}\left(:\right)$ – double array

The dimension of the array rcondv will be $\max \left(1,\mathbf{n}\right)$

If $\mathbf{sense}=\text{'V'}$ or $\text{'B'}$, the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array.

If $\mathbf{sense}=\text{'N'}$ or $\text{'E'}$, rcondv is not referenced.

15:   $\mathrm{info}$ – int64int32nag_int scalar

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

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{info}=-i$

If $\mathbf{info}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:

1: balanc, 2: jobvl, 3: jobvr, 4: sense, 5: n, 6: a, 7: lda, 8: b, 9: ldb, 10: alpha, 11: beta, 12: vl, 13: ldvl, 14: vr, 15: ldvr, 16: ilo, 17: ihi, 18: lscale, 19: rscale, 20: abnrm, 21: bbnrm, 22: rconde, 23: rcondv, 24: work, 25: lwork, 26: rwork, 27: iwork, 28: bwork, 29: info.

It is possible that info refers to a parameter that is omitted from the MATLAB interface. This usually indicates that an error in one of the other input parameters has caused an incorrect value to be inferred.

W  $\mathbf{info}=1\hspace{0.17em}\text{to}\hspace{0.17em}\mathbf{n}$

The $QZ$ iteration failed. No eigenvectors have been calculated, but $\mathbf{alpha}\left(j\right)$ and $\mathbf{beta}\left(j\right)$ should be correct for $j=\mathbf{info}+1,\dots ,\mathbf{n}$.

   $\mathbf{info}=\mathbf{n}+1$

Unexpected error returned from nag_lapack_zhgeqz (f08xs).

   $\mathbf{info}=\mathbf{n}+2$

Error returned from nag_lapack_ztgevc (f08yx).

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08wp_example

function f08wp_example


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

% Generalized eigenvalues and right eigenvectors of (A, B):
n = 4;
a = [ -21.10 - 22.50i,  53.5 - 50.5i, -34.5 + 127.5i,    7.5 +  0.5i;
       -0.46 -  7.78i,  -3.5 - 37.5i, -15.5 +  58.5i,  -10.5 -  1.5i;
        4.30 -  5.50i,  39.7 - 17.1i, -68.5 +  12.5i,   -7.5 -  3.5i;
        5.50 +  4.40i,  14.4 + 43.3i, -32.5 -  46.00i, -19.0 - 32.5i];
b = [   1    -  5i,      1.6 +  1.2i,  -3   +   0i,      0   -  1i;
        0.8  -  0.6i,    3   -  5i,    -4   +   3i,     -2.4 -  3.2i;
        1    +  0i,      2.4 +  1.8i,  -4   -   5i,      0   -  3i;
        0    +  1i,     -1.8 +  2.4i,   0   -   4i,      4   -  5i];

balanc = 'Balance';
jobvl = 'No left vectors';
jobvr = 'Vectors (right)';
sense = 'Both reciprocal condition numbers';
[~, ~, alpha, beta, ~, VR, ilo, ihi, lscale, rscale, abnrm, bbnrm, ...
	    rconde, rcondv, info] = ...
  f08wp( ...
	 balanc, jobvl, jobvr, sense, a, b);

epsilon = x02aj;
small = x02am;
absnrm = sqrt(abnrm^2+bbnrm^2);
tol = epsilon*absnrm;

for j=1:n

  % display information on the jth eigenvalue
  if (abs(alpha(j))*small >= abs(beta(j)))
    fprintf('\n%4d: Eigenvalue is numerically infinite or undetermined\n',j);
    fprintf('%4d: alpha = (%11.4e,%11.4e), beta = (%11.4e,%11.4e)\n', ...
            j, real(alpha(j)), imag(alpha(j)), real(beta(j)),imag(beta(j)));
  else
    fprintf('Eigenvalue  (%d)\n', j);
    disp(alpha(j)/beta(j));
  end

  if rconde(j) > 0
    fprintf(' Condition number            = %8.1e\n', 1/rconde(j));
    fprintf(' Error bound                 = %8.1e\n', tol/rconde(j));
  else
    fprintf(' Reciprocal condition number = %8.1e\n', rconde(j));
    fprintf(' Error bound is infinite\n');
  end

  fprintf('\nEigenvector (%d):\n', j);
  disp(VR(:, j));

  if rcondv(j) > 0
    fprintf(' Condition number            = %8.1e\n', 1/rcondv(j));
    fprintf(' Error bound                 = %8.1e\n\n', tol/rcondv(j));
  else
    fprintf(' Reciprocal condition number = %8.1e\n', rcondv(j));
    fprintf(' Error bound is infinite\n\n');
  end
end

f08wp example results

Eigenvalue  (1)
   3.0000 - 1.0000i

 Condition number            =  7.5e+00
 Error bound                 =  1.2e-14

Eigenvector (1):
  -0.7326 - 0.2674i
  -0.1493 + 0.0451i
  -0.1307 + 0.0851i
  -0.0851 - 0.1307i

 Condition number            =  7.8e+00
 Error bound                 =  1.2e-14

Eigenvalue  (2)
   2.0000 - 5.0000i

 Condition number            =  2.7e+00
 Error bound                 =  4.3e-15

Eigenvector (2):
  -0.5202 + 0.4798i
  -0.0007 + 0.0040i
  -0.0327 + 0.0302i
  -0.0302 - 0.0327i

 Condition number            =  1.7e+01
 Error bound                 =  2.7e-14

Eigenvalue  (3)
   3.0000 - 9.0000i

 Condition number            =  2.0e+00
 Error bound                 =  3.1e-15

Eigenvector (3):
  -0.3614 + 0.6386i
   0.0188 + 0.1455i
  -0.1455 + 0.0188i
  -0.0188 - 0.1455i

 Condition number            =  1.9e+01
 Error bound                 =  3.1e-14

Eigenvalue  (4)
   4.0000 - 5.0000i

 Condition number            =  1.6e+00
 Error bound                 =  2.6e-15

Eigenvector (4):
  -0.3660 + 0.6340i
   0.0010 + 0.0081i
   0.0122 - 0.0211i
  -0.0986 - 0.0569i

 Condition number            =  1.6e+01
 Error bound                 =  2.6e-14