Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_lapack_dsygvx (f08sb)

## Purpose

nag_lapack_dsygvx (f08sb) computes selected eigenvalues and, optionally, eigenvectors of a real generalized symmetric-definite eigenproblem, of the form
 $Az=λBz , ABz=λz or BAz=λz ,$
where $A$ and $B$ are symmetric and $B$ is also positive definite. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

## Syntax

[a, b, m, w, z, jfail, info] = f08sb(itype, jobz, range, uplo, a, b, vl, vu, il, iu, abstol, 'n', n)
[a, b, m, w, z, jfail, info] = nag_lapack_dsygvx(itype, jobz, range, uplo, a, b, vl, vu, il, iu, abstol, 'n', n)

## Description

nag_lapack_dsygvx (f08sb) first performs a Cholesky factorization of the matrix $B$ as $B={U}^{\mathrm{T}}U$, when ${\mathbf{uplo}}=\text{'U'}$ or $B=L{L}^{\mathrm{T}}$, when ${\mathbf{uplo}}=\text{'L'}$. The generalized problem is then reduced to a standard symmetric eigenvalue problem
 $Cx=λx ,$
which is solved for the desired eigenvalues and eigenvectors; the eigenvectors are then backtransformed to give the eigenvectors of the original problem.
For the problem $Az=\lambda Bz$, the eigenvectors are normalized so that the matrix of eigenvectors, $Z$, satisfies
 $ZT A Z = Λ and ZT B Z = I ,$
where $\Lambda$ is the diagonal matrix whose diagonal elements are the eigenvalues. For the problem $ABz=\lambda z$ we correspondingly have
 $Z-1 A Z-T = Λ and ZT B Z = I ,$
and for $BAz=\lambda z$ we have
 $ZT A Z = Λ and ZT B-1 Z = I .$

## References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Demmel J W and Kahan W (1990) Accurate singular values of bidiagonal matrices SIAM J. Sci. Statist. Comput. 11 873–912
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{itype}$int64int32nag_int scalar
Specifies the problem type to be solved.
${\mathbf{itype}}=1$
$Az=\lambda Bz$.
${\mathbf{itype}}=2$
$ABz=\lambda z$.
${\mathbf{itype}}=3$
$BAz=\lambda z$.
Constraint: ${\mathbf{itype}}=1$, $2$ or $3$.
2:     $\mathrm{jobz}$ – string (length ≥ 1)
Indicates whether eigenvectors are computed.
${\mathbf{jobz}}=\text{'N'}$
Only eigenvalues are computed.
${\mathbf{jobz}}=\text{'V'}$
Eigenvalues and eigenvectors are computed.
Constraint: ${\mathbf{jobz}}=\text{'N'}$ or $\text{'V'}$.
3:     $\mathrm{range}$ – string (length ≥ 1)
If ${\mathbf{range}}=\text{'A'}$, all eigenvalues will be found.
If ${\mathbf{range}}=\text{'V'}$, all eigenvalues in the half-open interval $\left({\mathbf{vl}},{\mathbf{vu}}\right]$ will be found.
If ${\mathbf{range}}=\text{'I'}$, the ilth to iuth eigenvalues will be found.
Constraint: ${\mathbf{range}}=\text{'A'}$, $\text{'V'}$ or $\text{'I'}$.
4:     $\mathrm{uplo}$ – string (length ≥ 1)
If ${\mathbf{uplo}}=\text{'U'}$, the upper triangles of $A$ and $B$ are stored.
If ${\mathbf{uplo}}=\text{'L'}$, the lower triangles of $A$ and $B$ are stored.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
5:     $\mathrm{a}\left(\mathit{lda},:\right)$ – double array
The first dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $n$ by $n$ symmetric matrix $A$.
• If ${\mathbf{uplo}}=\text{'U'}$, the upper triangular part of $a$ must be stored and the elements of the array below the diagonal are not referenced.
• If ${\mathbf{uplo}}=\text{'L'}$, the lower triangular part of $a$ must be stored and the elements of the array above the diagonal are not referenced.
6:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The $n$ by $n$ symmetric matrix $B$.
• If ${\mathbf{uplo}}=\text{'U'}$, the upper triangular part of $b$ must be stored and the elements of the array below the diagonal are not referenced.
• If ${\mathbf{uplo}}=\text{'L'}$, the lower triangular part of $b$ must be stored and the elements of the array above the diagonal are not referenced.
7:     $\mathrm{vl}$ – double scalar
8:     $\mathrm{vu}$ – double scalar
If ${\mathbf{range}}=\text{'V'}$, the lower and upper bounds of the interval to be searched for eigenvalues.
If ${\mathbf{range}}=\text{'A'}$ or $\text{'I'}$, vl and vu are not referenced.
Constraint: if ${\mathbf{range}}=\text{'V'}$, ${\mathbf{vl}}<{\mathbf{vu}}$.
9:     $\mathrm{il}$int64int32nag_int scalar
10:   $\mathrm{iu}$int64int32nag_int scalar
If ${\mathbf{range}}=\text{'I'}$, the indices (in ascending order) of the smallest and largest eigenvalues to be returned.
If ${\mathbf{range}}=\text{'A'}$ or $\text{'V'}$, il and iu are not referenced.
Constraints:
• if ${\mathbf{range}}=\text{'I'}$ and ${\mathbf{n}}=0$, ${\mathbf{il}}=1$ and ${\mathbf{iu}}=0$;
• if ${\mathbf{range}}=\text{'I'}$ and ${\mathbf{n}}>0$, $1\le {\mathbf{il}}\le {\mathbf{iu}}\le {\mathbf{n}}$.
11:   $\mathrm{abstol}$ – double scalar
The absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval $\left[a,b\right]$ of width less than or equal to
 $abstol+ε maxa,b ,$
where $\epsilon$ is the machine precision. If abstol is less than or equal to zero, then $\epsilon {‖T‖}_{1}$ will be used in its place, where $T$ is the tridiagonal matrix obtained by reducing $C$ to tridiagonal form. Eigenvalues will be computed most accurately when abstol is set to twice the underflow threshold , not zero. If this function returns with ${\mathbf{info}}={\mathbf{1}} \text{to} {\mathbf{n}}$, indicating that some eigenvectors did not converge, try setting abstol to . See Demmel and Kahan (1990).

### 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)$ – double array
The first dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array a will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The lower triangle (if ${\mathbf{uplo}}=\text{'L'}$) or the upper triangle (if ${\mathbf{uplo}}=\text{'U'}$) of a, including the diagonal, is overwritten.
2:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – double array
The first dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The second dimension of the array b will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$.
The triangular factor $U$ or $L$ from the Cholesky factorization $B={U}^{\mathrm{T}}U$ or $B=L{L}^{\mathrm{T}}$.
3:     $\mathrm{m}$int64int32nag_int scalar
The total number of eigenvalues found. $0\le {\mathbf{m}}\le {\mathbf{n}}$.
If ${\mathbf{range}}=\text{'A'}$, ${\mathbf{m}}={\mathbf{n}}$.
If ${\mathbf{range}}=\text{'I'}$, ${\mathbf{m}}={\mathbf{iu}}-{\mathbf{il}}+1$.
4:     $\mathrm{w}\left({\mathbf{n}}\right)$ – double array
The first m elements contain the selected eigenvalues in ascending order.
5:     $\mathrm{z}\left(\mathit{ldz},:\right)$ – double array
The first dimension, $\mathit{ldz}$, of the array z will be
• if ${\mathbf{jobz}}=\text{'V'}$, $\mathit{ldz}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$;
• otherwise $\mathit{ldz}=1$.
The second dimension of the array z will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}\right)$ if ${\mathbf{jobz}}=\text{'V'}$ and $1$ otherwise.
If ${\mathbf{jobz}}=\text{'V'}$, then
• if ${\mathbf{info}}={\mathbf{0}}$, the first m columns of $Z$ contain the orthonormal eigenvectors of the matrix $A$ corresponding to the selected eigenvalues, with the $i$th column of $Z$ holding the eigenvector associated with ${\mathbf{w}}\left(i\right)$. The eigenvectors are normalized as follows:
• if ${\mathbf{itype}}=1$ or $2$, ${Z}^{\mathrm{T}}BZ=I$;
• if ${\mathbf{itype}}=3$, ${Z}^{\mathrm{T}}{B}^{-1}Z=I$;
• if an eigenvector fails to converge (${\mathbf{info}}={\mathbf{1}} \text{to} {\mathbf{n}}$), then that column of $Z$ contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in jfail.
If ${\mathbf{jobz}}=\text{'N'}$, z is not referenced.
6:     $\mathrm{jfail}\left(:\right)$int64int32nag_int array
The dimension of the array jfail will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}\right)$
If ${\mathbf{jobz}}=\text{'V'}$, then
• if ${\mathbf{info}}={\mathbf{0}}$, the first m elements of jfail are zero;
• if ${\mathbf{info}}={\mathbf{1}} \text{to} {\mathbf{n}}$, jfail contains the indices of the eigenvectors that failed to converge.
If ${\mathbf{jobz}}=\text{'N'}$, jfail is not referenced.
7:     $\mathrm{info}$int64int32nag_int scalar
${\mathbf{info}}=0$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

${\mathbf{info}}=-i$
If ${\mathbf{info}}=-i$, parameter $i$ had an illegal value on entry. The parameters are numbered as follows:
1: itype, 2: jobz, 3: range, 4: uplo, 5: n, 6: a, 7: lda, 8: b, 9: ldb, 10: vl, 11: vu, 12: il, 13: iu, 14: abstol, 15: m, 16: w, 17: z, 18: ldz, 19: work, 20: lwork, 21: iwork, 22: jfail, 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.
${\mathbf{info}}=1 \text{to} {\mathbf{n}}$
If ${\mathbf{info}}=i$, nag_lapack_dsyevx (f08fb) failed to converge; $i$ eigenvectors failed to converge. Their indices are stored in array jfail.
${\mathbf{info}}>{\mathbf{n}}$
nag_lapack_dpotrf (f07fd) returned an error code; i.e., if ${\mathbf{info}}={\mathbf{n}}+i$, for $1\le i\le {\mathbf{n}}$, then the leading minor of order $i$ of $B$ is not positive definite. The factorization of $B$ could not be completed and no eigenvalues or eigenvectors were computed.

## Accuracy

If $B$ is ill-conditioned with respect to inversion, then the error bounds for the computed eigenvalues and vectors may be large, although when the diagonal elements of $B$ differ widely in magnitude the eigenvalues and eigenvectors may be less sensitive than the condition of $B$ would suggest. See Section 4.10 of Anderson et al. (1999) for details of the error bounds.

The total number of floating-point operations is proportional to ${n}^{3}$.
The complex analogue of this function is nag_lapack_zhegvx (f08sp).

## Example

This example finds the eigenvalues in the half-open interval $\left(-1.0,1.0\right]$, and corresponding eigenvectors, of the generalized symmetric eigenproblem $Az=\lambda Bz$, where
 $A = 0.24 0.39 0.42 -0.16 0.39 -0.11 0.79 0.63 0.42 0.79 -0.25 0.48 -0.16 0.63 0.48 -0.03 and B= 4.16 -3.12 0.56 -0.10 -3.12 5.03 -0.83 1.09 0.56 -0.83 0.76 0.34 -0.10 1.09 0.34 1.18 .$
The example program for nag_lapack_dsygvd (f08sc) illustrates solving a generalized symmetric eigenproblem of the form $ABz=\lambda z$.
```function f08sb_example

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

% Upper triangular parts of symmetric matrix A and symmetric definite matrix B
uplo = 'Upper';
n = 4;
a = [0.24,  0.39,  0.42, -0.16;
0,    -0.11,  0.79,  0.63;
0,     0,    -0.25,  0.48;
0,     0,     0,    -0.03];
b = [4.16, -3.12,  0.56, -0.10;
0,     5.03, -0.83,  1.09;
0,     0,     0.76,  0.34;
0,     0,     0,     1.18];

% Generalized eigenvalues and eigenvectors for problem Az = lambda Bz
% Selecting eigenvalues in the range [-1,1]
itype = int64(1);
jobz  = 'Vectors';
range = 'Values in range';
[vl,vu] = deal(-1, 1);
[il,iu] = deal(int64(0), int64(0));
abstol = 0;
[~, ~, m, w, z, jfail, info] = ...
f08sb( ...
itype, jobz, range, uplo, a, b, vl, vu, il, iu, abstol);

% Normalize eigenvectors: largest element positive
for j = 1:m
[~,k] = max(abs(z(:,j)));
if z(k,j) < 0;
z(:,j) = -z(:,j);
end
end

disp('Selected Eigenvalues');
disp(w(1:m)');
disp('Corresponding eigenvectors');
disp(z);

```
```f08sb example results

Selected Eigenvalues
-0.4548    0.1001

Corresponding eigenvectors
-0.3080   -0.4469
-0.5329   -0.0371
0.3496    0.0505
0.6211    0.4743

```