NAG Toolbox: nag_lapack_dgeevx (f08nb)

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)$ – double 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)$ – double 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 real Schur form of the balanced version of the input matrix $A$.

2:     $\mathrm{wr}\left(:\right)$ – double array

3:     $\mathrm{wi}\left(:\right)$ – double array

The dimension of the arrays wr and wi will be $\max \left(1,\mathbf{n}\right)$

wr and wi contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.

4:     $\mathrm{vl}\left(\mathit{ldvl},:\right)$ – double 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. If the $j$th eigenvalue is real, then $u_j=\mathbf{vl}\left(:,j\right)$, the $j$th column of vl. If the $j$th and $\left(j+1\right)$st eigenvalues form a complex conjugate pair, then $u_j=\mathbf{vl}\left(:,j\right)+i\times \mathbf{vl}\left(:,j+1\right)$ and $u_{j+1}=\mathbf{vl}\left(:,j\right)-i\times \mathbf{vl}\left(:,j+1\right)$.

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

5:     $\mathrm{vr}\left(\mathit{ldvr},:\right)$ – double 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. If the $j$th eigenvalue is real, then $v_j=\mathbf{vr}\left(:,j\right)$, the $j$th column of vr. If the $j$th and $\left(j+1\right)$st eigenvalues form a complex conjugate pair, then $v_j=\mathbf{vr}\left(:,j\right)+i\times \mathbf{vr}\left(:,j+1\right)$ and $v_{j+1}=\mathbf{vr}\left(:,j\right)-i\times \mathbf{vr}\left(:,j+1\right)$.

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

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

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

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

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

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

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

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

12:   $\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: wr, 9: wi, 10: vl, 11: ldvl, 12: vr, 13: ldvr, 14: ilo, 15: ihi, 16: scale, 17: abnrm, 18: rconde, 19: rcondv, 20: work, 21: lwork, 22: iwork, 23: 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 wr and wi contain eigenvalues which have converged.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08nb_example

function f08nb_example


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

% Matrix A
n = 4;
a = [0.35,  0.45, -0.14, -0.17;
     0.09,  0.07, -0.54,  0.35;
    -0.44, -0.33, -0.03,  0.17;
     0.25, -0.32, -0.13,  0.11];


% 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, wr, wi, vl, vr, ilo, ihi, scale, abnrm, rconde, rcondv, info] = ...
f08nb( ...
       balanc, jobvl, jobvr, sense, a);

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

fprintf('\nEigenvectors\n\n');
fprintf('        Eigenvector                 rcond\n');
evecs = complex(zeros(n,n));
k = 1;
conjugating = false;
for j = 1:n
  fprintf('\n%3d',j);
  if wi(j)==0 && ~conjugating
    fprintf('%15.4e%24.4f\n',vr(1,k),rcondv(j));
    fprintf('%18.4e\n',vr(2:n,k));
    k = k + 1;
  else
    if conjugating
      pl = '-';
      mi = '+';
    else
      pl = '+';
      mi = '-';
    end
    for l = 1:n
      if (l>1)
        fprintf('%3s', ' ');
      end
      if vr(l,k+1)>0
        fprintf('%15.4e %s %10.4ei', vr(l,k), pl, vr(l,k+1));
      else
        fprintf('%15.4e %s %10.4ei', vr(l,k), mi, abs(vr(l,k+1)));
      end
      if l==1
        fprintf('%10.4f', rcondv(j));
      end
      fprintf('\n');
    end
    if conjugating    
      k = k + 2;
    end
    conjugating = ~conjugating;
  end
end

f08nb example results

Eigenvalues

        Eigenvalue                  rcond

  1     7.9948e-01                  0.9936
  2    -9.9412e-02 + 4.0079e-01i    0.7027
  3    -9.9412e-02 - 4.0079e-01i    0.7027
  4    -1.0066e-01                  0.5710

Eigenvectors

        Eigenvector                 rcond

  1    -6.5509e-01                  0.6252
       -5.2363e-01
        5.3622e-01
       -9.5607e-02

  2    -1.9330e-01 + 2.5463e-01i    0.3996
        2.5186e-01 - 5.2240e-01i
        9.7182e-02 - 3.0838e-01i
        6.7595e-01 - 0.0000e+00i

  3    -1.9330e-01 - 2.5463e-01i    0.3996
        2.5186e-01 + 5.2240e-01i
        9.7182e-02 + 3.0838e-01i
        6.7595e-01 + 0.0000e+00i

  4     1.2533e-01                  0.3125
        3.3202e-01
        5.9384e-01
        7.2209e-01