NAG Toolbox: nag_lapack_dtgevc (f08yk)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Specifies the required sets of generalized eigenvectors.

$\mathbf{side}=\text{'R'}$

Only right eigenvectors are computed.

$\mathbf{side}=\text{'L'}$

Only left eigenvectors are computed.

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

Both left and right eigenvectors are computed.

Constraint: $\mathbf{side}=\text{'B'}$, $\text{'L'}$ or $\text{'R'}$.

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

Specifies further details of the required generalized eigenvectors.

$\mathbf{howmny}=\text{'A'}$

All right and/or left eigenvectors are computed.

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

All right and/or left eigenvectors are computed; they are backtransformed using the input matrices supplied in arrays vr and/or vl.

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

Selected right and/or left eigenvectors, defined by the array select, are computed.

Constraint: $\mathbf{howmny}=\text{'A'}$, $\text{'B'}$ or $\text{'S'}$.

3:     $\mathrm{select}\left(:\right)$ – logical array

The dimension of the array select must be at least $\max \left(1,\mathbf{n}\right)$ if $\mathbf{howmny}=\text{'S'}$, and at least $1$ otherwise

Specifies the eigenvectors to be computed if $\mathbf{howmny}=\text{'S'}$. To select the generalized eigenvector corresponding to the $j$th generalized eigenvalue, the $j$th element of select should be set to true; if the eigenvalue corresponds to a complex conjugate pair, then real and imaginary parts of eigenvectors corresponding to the complex conjugate eigenvalue pair will be computed.

If $\mathbf{howmny}=\text{'A'}$ or $\text{'B'}$, select is not referenced.

Constraint: if $\mathbf{howmny}=\text{'S'}$, $\mathbf{select}\left(\mathit{j}\right)=\mathit{true}$ or $\mathit{false}$, for $\mathit{j}=1,2,\dots ,n$.

4:     $\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 matrix pair $\left(A,B\right)$ must be in the generalized Schur form. Usually, this is the matrix $A$ returned by nag_lapack_dhgeqz (f08xe).

5:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double 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 pair $\left(A,B\right)$ must be in the generalized Schur form. If $A$ has a $2$ by $2$ diagonal block then the corresponding $2$ by $2$ block of $B$ must be diagonal with positive elements. Usually, this is the matrix $B$ returned by nag_lapack_dhgeqz (f08xe).

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

The first dimension, $\mathit{ldvl}$, of the array vl must satisfy

• if $\mathbf{side}=\text{'L'}$ or $\text{'B'}$, $\mathit{ldvl}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{side}=\text{'R'}$, $\mathit{ldvl}\ge 1$.

The second dimension of the array vl must be at least $\max \left(1,\mathbf{mm}\right)$ if $\mathbf{side}=\text{'L'}$ or $\text{'B'}$ and at least $1$ if $\mathbf{side}=\text{'R'}$.

If $\mathbf{howmny}=\text{'B'}$ and $\mathbf{side}=\text{'L'}$ or $\text{'B'}$, vl must be initialized to an $n$ by $n$ matrix $Q$. Usually, this is the orthogonal matrix $Q$ of left Schur vectors returned by nag_lapack_dhgeqz (f08xe).

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

The first dimension, $\mathit{ldvr}$, of the array vr must satisfy

• if $\mathbf{side}=\text{'R'}$ or $\text{'B'}$, $\mathit{ldvr}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{side}=\text{'L'}$, $\mathit{ldvr}\ge 1$.

The second dimension of the array vr must be at least $\max \left(1,\mathbf{mm}\right)$ if $\mathbf{side}=\text{'R'}$ or $\text{'B'}$ and at least $1$ if $\mathbf{side}=\text{'L'}$.

If $\mathbf{howmny}=\text{'B'}$ and $\mathbf{side}=\text{'R'}$ or $\text{'B'}$, vr must be initialized to an $n$ by $n$ matrix $Z$. Usually, this is the orthogonal matrix $Z$ of right Schur vectors returned by nag_lapack_dhgeqz (f08xe).

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

The number of columns in the arrays vl and/or vr.

Constraints:

• if $\mathbf{howmny}=\text{'A'}$ or $\text{'B'}$, $\mathbf{mm}\ge \mathbf{n}$;
• if $\mathbf{howmny}=\text{'S'}$, mm must not be less than the number of requested eigenvectors.

Optional Input Parameters

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

Default: the first dimension of the arrays vl, vr. (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{vl}\left(\mathit{ldvl},:\right)$ – double array

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

• if $\mathbf{side}=\text{'L'}$ or $\text{'B'}$, $\mathit{ldvl}=\max \left(1,\mathbf{n}\right)$;
• if $\mathbf{side}=\text{'R'}$, $\mathit{ldvl}=1$.

The second dimension of the array vl will be $\max \left(1,\mathbf{mm}\right)$ if $\mathbf{side}=\text{'L'}$ or $\text{'B'}$ and at least $1$ if $\mathbf{side}=\text{'R'}$.

If $\mathbf{side}=\text{'L'}$ or $\text{'B'}$, vl contains:

• if $\mathbf{howmny}=\text{'A'}$, the matrix $Y$ of left eigenvectors of $\left(A,B\right)$;
• if $\mathbf{howmny}=\text{'B'}$, the matrix $QY$;
• if $\mathbf{howmny}=\text{'S'}$, the left eigenvectors of $\left(A,B\right)$ specified by select, stored consecutively in the columns of the array vl, in the same order as their corresponding eigenvalues.

A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part.

If $\mathbf{side}=\text{'R'}$, vl is not referenced.

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

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

• if $\mathbf{side}=\text{'R'}$ or $\text{'B'}$, $\mathit{ldvr}=\max \left(1,\mathbf{n}\right)$;
• if $\mathbf{side}=\text{'L'}$, $\mathit{ldvr}=1$.

The second dimension of the array vr will be $\max \left(1,\mathbf{mm}\right)$ if $\mathbf{side}=\text{'R'}$ or $\text{'B'}$ and at least $1$ if $\mathbf{side}=\text{'L'}$.

If $\mathbf{side}=\text{'R'}$ or $\text{'B'}$, vr contains:

• if $\mathbf{howmny}=\text{'A'}$, the matrix $X$ of right eigenvectors of $\left(A,B\right)$;
• if $\mathbf{howmny}=\text{'B'}$, the matrix $ZX$;
• if $\mathbf{howmny}=\text{'S'}$, the right eigenvectors of $\left(A,B\right)$ specified by select, stored consecutively in the columns of the array vr, in the same order as their corresponding eigenvalues.

A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part.

If $\mathbf{side}=\text{'L'}$, vr is not referenced.

3:     $\mathrm{m}$ – int64int32nag_int scalar

The number of columns in the arrays vl and/or vr actually used to store the eigenvectors. If $\mathbf{howmny}=\text{'A'}$ or $\text{'B'}$, m is set to n. Each selected real eigenvector occupies one column and each selected complex eigenvector occupies two columns.

4:     $\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: side, 2: howmny, 3: select, 4: n, 5: a, 6: lda, 7: b, 8: ldb, 9: vl, 10: ldvl, 11: vr, 12: ldvr, 13: mm, 14: m, 15: work, 16: 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 $2$ by $2$ block $\left(\mathbf{info}:\mathbf{info}+1\right)$ does not have complex eigenvalues.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f08yk_example

function f08yk_example


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

n = 5;
a = [ 1.0   1.0    1.0    1.0     1.0;
      2.0   4.0    8.0   16.0    32.0;
      3.0   9.0   27.0   81.0   243.0;
      4.0  16.0   64.0  256.0  1024.0;
      5.0  25.0  125.0  625.0  3125.0];
b = transpose(a);

% Balance A and B
job = 'B';
[a, b, ilo, ihi, lscale, rscale, info] = ...
  f08wh(job, a, b);

bbal = b(ilo:ihi,ilo:ihi);
abal = a(ilo:ihi,ilo:ihi);

% QR factorize balanced B
[QR, tau, info] = f08ae(bbal);

% Perform C = Q^T*A
side = 'Left';
trans = 'Transpose';
[C, info] = f08ag( ...
                   side, trans, QR, tau, abal);

% Form Q explicitly and let Z = I.
[Q, info] = f08af(QR, tau);
Z         = eye(n);

% Generalized Hessenberg form (C,R) -> (H,T)
jlo       = int64(1);
jhi       = int64(ihi-ilo+1);
compq     = 'Vectors Q';
compz     = 'Vectors Z';
[H, T, Q, Z, info] = ...
  f08we( ...
         compq, compz, jlo, jhi, C, QR, Q, Z);

% Find eigenvalues of generalized Hessenberg form
%    = eigenvalues of (A,B).
% and return Schur form for computing eigenvectors
job = 'Schur form';
[HS, TS, alphar, alphai, beta, Q, Z, info] = ...
  f08xe(...
        job, compq, compz, jlo, jhi, H, T, Q, Z);

% Obtain scaled eigenvectors from Schur form
side = 'Both sides';
howmny = 'Backtransformed using Q and Z';
select = [false];
[Q, Z, m, info] = f08yk( ...
                         side, howmny, select, HS, TS, Q, Z, jhi);

% rescale to obtain left and right eigenvectors of (A,B)
job  = 'Back scale';
side = 'Left';
[VL, info] = f08wj( ...
                    job, side, jlo, jhi, lscale, rscale, Q);
side = 'Right';
[VR, info] = f08wj( ...
                    job, side, jlo, jhi, lscale, rscale, Z);

% Display eigensolution
w = complex(alphar+i*alphai);
w = w./beta;
[ifail] = x04db( ...
                 'Gen', ' ', w, 'B', 'F7.3', ...
                 'Generalized eigenvalues of (A,B):', 'Int', 'N', ...
                 int64(80), int64(0));
fprintf('\n');
[ifail] = x04ca( ...
                 'Gen', ' ', VR, 'Right Eigenvectors');
fprintf('\n');
[ifail] = x04ca( ...
                 'Gen', ' ', VL, 'Left Eigenvectors');

f08yk example results

 Generalized eigenvalues of (A,B):
 1  ( -2.437,  0.000)
 2  (  0.607,  0.795)
 3  (  0.607, -0.795)
 4  (  1.000,  0.000)
 5  ( -0.410,  0.000)

 Right Eigenvectors
               1            2            3            4            5
 1   -4.9374E-02  -2.0772E-01   2.5702E-02  -7.4074E-02  -6.9466E-02
 2    1.0606E-01   1.7848E-01   8.8325E-02   1.3545E-01   1.3605E-01
 3   -1.0000E-01  -5.3742E-02  -4.6258E-02  -1.0000E-01  -1.0000E-01
 4    4.3761E-02   8.0277E-03   1.3765E-02   2.6455E-02   3.1879E-02
 5   -7.0192E-03  -5.5974E-04  -2.0807E-03  -3.7037E-03  -3.5534E-03

 Left Eigenvectors
               1            2            3            4            5
 1   -6.9466E-02  -2.0922E-01  -5.2678E-03  -7.4074E-02   4.9374E-02
 2    1.3605E-01   1.6346E-01   1.1371E-01   1.3545E-01  -1.0606E-01
 3   -1.0000E-01  -4.6314E-02  -5.3686E-02  -1.0000E-01   1.0000E-01
 4    3.1879E-02   5.9054E-03   1.4799E-02   2.6455E-02  -4.3761E-02
 5   -3.5534E-03  -2.4617E-04  -2.1404E-03  -3.7037E-03   7.0192E-03