NAG Toolbox: nag_lapack_zgeevx (f08np)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.

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

Do not diagonally scale or permute.

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

Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale.

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

Diagonally scale the matrix, i.e., replace $A$ by $DA{D}^{-1}$, where $D$ is a diagonal matrix chosen to make the rows and columns of $A$ more equal in norm. Do not permute.

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

Both diagonally scale and permute $A$.

Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting. Permuting does not change condition numbers (in exact arithmetic), but balancing does.

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

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

If $\mathbf{jobvl}=\text{'N'}$, the left eigenvectors of $A$ are not computed.

If $\mathbf{jobvl}=\text{'V'}$, the left eigenvectors of $A$ are computed.

If $\mathbf{sense}=\text{'E'}$ or $\text{'B'}$, jobvl must be set to $\mathbf{jobvl}=\text{'V'}$.

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

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

If $\mathbf{jobvr}=\text{'N'}$, the right eigenvectors of $A$ are not computed.

If $\mathbf{jobvr}=\text{'V'}$, the right eigenvectors of $A$ are computed.

If $\mathbf{sense}=\text{'E'}$ or $\text{'B'}$, jobvr must be set to $\mathbf{jobvr}=\text{'V'}$.

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 right eigenvectors only.

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

Computed for eigenvalues and right eigenvectors.

If $\mathbf{sense}=\text{'E'}$ or $\text{'B'}$, both left and right eigenvectors must also be computed ($\mathbf{jobvl}=\text{'V'}$ and $\mathbf{jobvr}=\text{'V'}$).

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 $n$ by $n$ matrix $A$.

Optional Input Parameters

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

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

$n$, the order of the matrix $A$.

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'}$, $A$ contains the Schur form of the balanced version of the matrix $A$.

2:     $\mathrm{w}\left(:\right)$ – complex array

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

Contains the computed eigenvalues.

3:     $\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 eigenvectors $u_j$ are stored one after another in the columns of vl, in the same order as their corresponding eigenvalues; that is $u_j=\mathbf{vl}\left(:,j\right)$, the $j$th column of vl.

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

4:     $\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 eigenvectors $v_j$ are stored one after another in the columns of vr, in the same order as their corresponding eigenvalues; that is $v_j=\mathbf{vr}\left(:,j\right)$, the $j$th column of vr.

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

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

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

ilo and ihi are integer values determined when $A$ was balanced. The balanced $A$ has $a_{ij}=0$ if $i>j$ and $j=1,2,\dots ,\mathbf{ilo}-1$ or $i=\mathbf{ihi}+1,\dots ,\mathbf{n}$.

7:     $\mathrm{scale}\left(:\right)$ – double array

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

Details of the permutations and scaling factors applied when balancing $A$.

If $p_j$ is the index of the row and column interchanged with row and column $j$, and $d_j$ is the scaling factor applied to row and column $j$, then

• $\mathbf{scale}\left(\mathit{j}\right)=p_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,\mathbf{ilo}-1$;
• $\mathbf{scale}\left(\mathit{j}\right)=d_{\mathit{j}}$, for $\mathit{j}=\mathbf{ilo},\dots ,\mathbf{ihi}$;
• $\mathbf{scale}\left(\mathit{j}\right)=p_{\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$.

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

The $1$-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).

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

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

$\mathbf{rconde}\left(j\right)$ is the reciprocal condition number of the $j$th eigenvalue.

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

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

$\mathbf{rcondv}\left(j\right)$ is the reciprocal condition number of the $j$th right eigenvector.

11:   $\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: w, 9: vl, 10: ldvl, 11: vr, 12: ldvr, 13: ilo, 14: ihi, 15: scale, 16: abnrm, 17: rconde, 18: rcondv, 19: work, 20: lwork, 21: rwork, 22: 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}>0$

If $\mathbf{info}=i$, the $QR$ algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements $1:\mathbf{ilo}-1$ and $i+1:\mathbf{n}$ of w contain eigenvalues which have converged.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08np_example

function f08np_example


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

% Complex matrix A
n = 4;
a = [-3.97 - 5.04i, -4.11 + 3.70i, -0.34 + 1.01i,  1.29 - 0.86i;
      0.34 - 1.50i,  1.52 - 0.43i,  1.88 - 5.38i,  3.36 + 0.65i;
      3.31 - 3.85i,  2.50 + 3.45i,  0.88 - 1.08i,  0.64 - 1.48i;
     -1.10 + 0.82i,  1.81 - 1.59i,  3.25 + 1.33i,  1.57 - 3.44i];

% Eigenvalues and left and right eigenvectors of A after matrix balancing
balanc = 'Balance';
jobvl = 'Vectors (left)';
jobvr = 'Vectors (right)';
sense = 'Both reciprocal condition numbers';
[a, w, vl, vr, ilo, ihi, scale, abnrm, rconde, rcondv, info] = ...
f08np( ...
       balanc, jobvl, jobvr, sense, a);

% Normalize eigenvectors: largest elements are real
for i = 1:n
  [~,k] = max(abs(real(vr(:,i)))+abs(imag(vr(:,i))));
  vr(:,i) = vr(:,i)*conj(vr(k,i))/abs(vr(k,i));
end

disp('Eigenvalues');
fprintf('\n        Eigenvalue                  rcond\n\n');
for j=1:n
  fprintf('%3d',j);
  if imag(w(j))<0
    fprintf('%15.4e - %10.4ei%10.4f\n',real(w(j)),abs(imag(w(j))),rconde(j));
  else
    fprintf('%15.4e + %10.4ei%10.4f\n',real(w(j)),imag(w(j)),rconde(j));
  end
end

fprintf('\nRight Eigenvectors\n\n');
fprintf('        Eigenvector                 rcond\n');
for j = 1:n
  fprintf('\n%3d',j);
  for l = 1:n
    if (l>1)
      fprintf('%3s', ' ');
    end
    if imag(vr(l,k))>0
      fprintf('%15.4e + %10.4ei', real(vr(l,k)), imag(vr(l,k)));
    else
      fprintf('%15.4e - %10.4ei', real(vr(l,k)), abs(imag(vr(l,k))));
    end
    if l==1
      fprintf('%10.4f', rcondv(j));
    end
    fprintf('\n');
  end
end

f08np example results

Eigenvalues

        Eigenvalue                  rcond

  1    -6.0004e+00 - 6.9998e+00i    0.9932
  2    -5.0000e+00 + 2.0060e+00i    0.9964
  3     7.9982e+00 - 9.9637e-01i    0.9814
  4     3.0023e+00 - 3.9998e+00i    0.9779

Right Eigenvectors

        Eigenvector                 rcond

  1    -3.5614e-02 - 1.7822e-01i    8.4011
        1.2637e-01 + 2.6663e-01i
        1.2933e-02 - 2.9657e-01i
        8.8982e-01 - 0.0000e+00i

  2    -3.5614e-02 - 1.7822e-01i    8.0214
        1.2637e-01 + 2.6663e-01i
        1.2933e-02 - 2.9657e-01i
        8.8982e-01 - 0.0000e+00i

  3    -3.5614e-02 - 1.7822e-01i    5.8292
        1.2637e-01 + 2.6663e-01i
        1.2933e-02 - 2.9657e-01i
        8.8982e-01 - 0.0000e+00i

  4    -3.5614e-02 - 1.7822e-01i    5.8292
        1.2637e-01 + 2.6663e-01i
        1.2933e-02 - 2.9657e-01i
        8.8982e-01 - 0.0000e+00i