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_zhegst (f08ss)

## Purpose

nag_lapack_zhegst (f08ss) reduces a complex Hermitian-definite generalized eigenproblem $Az=\lambda Bz$, $ABz=\lambda z$ or $BAz=\lambda z$ to the standard form $Cy=\lambda y$, where $A$ is a complex Hermitian matrix and $B$ has been factorized by nag_lapack_zpotrf (f07fr).

## Syntax

[a, info] = f08ss(itype, uplo, a, b, 'n', n)
[a, info] = nag_lapack_zhegst(itype, uplo, a, b, 'n', n)

## Description

To reduce the complex Hermitian-definite generalized eigenproblem $Az=\lambda Bz$, $ABz=\lambda z$ or $BAz=\lambda z$ to the standard form $Cy=\lambda y$, nag_lapack_zhegst (f08ss) must be preceded by a call to nag_lapack_zpotrf (f07fr) which computes the Cholesky factorization of $B$; $B$ must be positive definite.
The different problem types are specified by the argument itype, as indicated in the table below. The table shows how $C$ is computed by the function, and also how the eigenvectors $z$ of the original problem can be recovered from the eigenvectors of the standard form.
 itype Problem uplo $B$ $C$ $z$ $1$ $Az=\lambda Bz$ 'U' 'L' ${U}^{\mathrm{H}}U$  $L{L}^{\mathrm{H}}$ ${U}^{-\mathrm{H}}A{U}^{-1}$  ${L}^{-1}A{L}^{-\mathrm{H}}$ ${U}^{-1}y$  ${L}^{-\mathrm{H}}y$ $2$ $ABz=\lambda z$ 'U' 'L' ${U}^{\mathrm{H}}U$  $L{L}^{\mathrm{H}}$ $UA{U}^{\mathrm{H}}$  ${L}^{\mathrm{H}}AL$ ${U}^{-1}y$  ${L}^{-\mathrm{H}}y$ $3$ $BAz=\lambda z$ 'U' 'L' ${U}^{\mathrm{H}}U$  $L{L}^{\mathrm{H}}$ $UA{U}^{\mathrm{H}}$  ${L}^{\mathrm{H}}AL$ ${U}^{\mathrm{H}}y$  $Ly$

## References

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
Indicates how the standard form is computed.
${\mathbf{itype}}=1$
• if ${\mathbf{uplo}}=\text{'U'}$, $C={U}^{-\mathrm{H}}A{U}^{-1}$;
• if ${\mathbf{uplo}}=\text{'L'}$, $C={L}^{-1}A{L}^{-\mathrm{H}}$.
${\mathbf{itype}}=2$ or $3$
• if ${\mathbf{uplo}}=\text{'U'}$, $C=UA{U}^{\mathrm{H}}$;
• if ${\mathbf{uplo}}=\text{'L'}$, $C={L}^{\mathrm{H}}AL$.
Constraint: ${\mathbf{itype}}=1$, $2$ or $3$.
2:     $\mathrm{uplo}$ – string (length ≥ 1)
Indicates whether the upper or lower triangular part of $A$ is stored and how $B$ has been factorized.
${\mathbf{uplo}}=\text{'U'}$
The upper triangular part of $A$ is stored and $B={U}^{\mathrm{H}}U$.
${\mathbf{uplo}}=\text{'L'}$
The lower triangular part of $A$ is stored and $B=L{L}^{\mathrm{H}}$.
Constraint: ${\mathbf{uplo}}=\text{'U'}$ or $\text{'L'}$.
3:     $\mathrm{a}\left(\mathit{lda},:\right)$ – complex 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$ Hermitian 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.
4:     $\mathrm{b}\left(\mathit{ldb},:\right)$ – complex 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 Cholesky factor of $B$ as specified by uplo and returned by nag_lapack_zpotrf (f07fr).

### 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.
$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 $\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 upper or lower triangle of a stores the corresponding upper or lower triangle of $C$ as specified by itype and uplo.
2:     $\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: uplo, 3: n, 4: a, 5: lda, 6: b, 7: ldb, 8: 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.

## Accuracy

Forming the reduced matrix $C$ is a stable procedure. However it involves implicit multiplication by ${B}^{-1}$ (if ${\mathbf{itype}}=1$) or $B$ (if ${\mathbf{itype}}=2$ or $3$). When nag_lapack_zhegst (f08ss) is used as a step in the computation of eigenvalues and eigenvectors of the original problem, there may be a significant loss of accuracy if $B$ is ill-conditioned with respect to inversion. See the document for nag_lapack_zhegv (f08sn) for further details.

The total number of real floating-point operations is approximately $4{n}^{3}$.
The real analogue of this function is nag_lapack_dsygst (f08se).

## Example

This example computes all the eigenvalues of $Az=\lambda Bz$, where
 $A = -7.36+0.00i 0.77-0.43i -0.64-0.92i 3.01-6.97i 0.77+0.43i 3.49+0.00i 2.19+4.45i 1.90+3.73i -0.64+0.92i 2.19-4.45i 0.12+0.00i 2.88-3.17i 3.01+6.97i 1.90-3.73i 2.88+3.17i -2.54+0.00i$
and
 $B = 3.23+0.00i 1.51-1.92i 1.90+0.84i 0.42+2.50i 1.51+1.92i 3.58+0.00i -0.23+1.11i -1.18+1.37i 1.90-0.84i -0.23-1.11i 4.09+0.00i 2.33-0.14i 0.42-2.50i -1.18-1.37i 2.33+0.14i 4.29+0.00i .$
Here $B$ is Hermitian positive definite and must first be factorized by nag_lapack_zpotrf (f07fr). The program calls nag_lapack_zhegst (f08ss) to reduce the problem to the standard form $Cy=\lambda y$; then nag_lapack_zhetrd (f08fs) to reduce $C$ to tridiagonal form, and nag_lapack_dsterf (f08jf) to compute the eigenvalues.
```function f08ss_example

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

% Sove Az = lambda Bz
% A and B are the Hermitian positive definite matrices:
a = [-7.36 + 0.00i,  0.77 - 0.43i, -0.64 - 0.92i,  3.01 - 6.97i;
0.77 + 0.43i,  3.49 + 0.00i,  2.19 + 4.45i,  1.90 + 3.73i;
-0.64 + 0.92i,  2.19 - 4.45i,  0.12 + 0.00i,  2.88 - 3.17i;
3.01 + 6.97i,  1.90 - 3.73i,  2.88 + 3.17i, -2.54 + 0.00i];

b = [ 3.23 + 0.00i,  1.51 - 1.92i,  1.90 + 0.84i,  0.42 + 2.50i;
1.51 + 1.92i,  3.58 + 0.00i, -0.23 + 1.11i, -1.18 + 1.37i;
1.90 - 0.84i, -0.23 - 1.11i,  4.09 + 0.00i,  2.33 - 0.14i;
0.42 - 2.50i, -1.18 - 1.37i,  2.33 + 0.14i,  4.29 + 0.00i];

% Factorize B
uplo = 'L';
[bfac, info] = f07fr(uplo, b);

% Reduce problem to standard form Cy = lambda*y
itype = int64(1);
[c info] = f08ss(itype, uplo, a, bfac);

% Find eigenvalues lambda
jobz = 'No Vectors';
[~, w, info] = f08fn(jobz, uplo, c);

disp('Eigenvalues:');
disp(w');

```
```f08ss example results

Eigenvalues:
-5.9990   -2.9936    0.5047    3.9990

```