NAG Library Function Document

nag_dsbevd (f08hcc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by $\mathbf{order}=\mathrm{Nag\_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint: $\mathbf{order}=\mathrm{Nag\_RowMajor}$ or Nag_ColMajor.

2:     job – Nag_JobTypeInput

On entry: indicates whether eigenvectors are computed.

$\mathbf{job}=\mathrm{Nag\_DoNothing}$

Only eigenvalues are computed.

$\mathbf{job}=\mathrm{Nag\_EigVecs}$

Eigenvalues and eigenvectors are computed.

Constraint: $\mathbf{job}=\mathrm{Nag\_DoNothing}$ or $\mathrm{Nag\_EigVecs}$.

3:     uplo – Nag_UploTypeInput

On entry: indicates whether the upper or lower triangular part of $A$ is stored.

$\mathbf{uplo}=\mathrm{Nag\_Upper}$

The upper triangular part of $A$ is stored.

$\mathbf{uplo}=\mathrm{Nag\_Lower}$

The lower triangular part of $A$ is stored.

Constraint: $\mathbf{uplo}=\mathrm{Nag\_Upper}$ or $\mathrm{Nag\_Lower}$.

4:     n – IntegerInput

On entry: $n$, the order of the matrix $A$.

Constraint: $\mathbf{n}\ge 0$.

5:     kd – IntegerInput

On entry: if $\mathbf{uplo}=\mathrm{Nag\_Upper}$, the number of superdiagonals, $k_d$, of the matrix $A$.

If $\mathbf{uplo}=\mathrm{Nag\_Lower}$, the number of subdiagonals, $k_d$, of the matrix $A$.

Constraint: $\mathbf{kd}\ge 0$.

6:     ab[$\mathit{dim}$] – doubleInput/Output

Note: the dimension, dim, of the array ab must be at least $\max \left(1,\mathbf{pdab}\times \mathbf{n}\right)$.

On entry: the upper or lower triangle of the $n$ by $n$ symmetric band matrix $A$.

This is stored as a notional two-dimensional array with row elements or column elements stored contiguously. The storage of elements of $A_{ij}$, depends on the order and uplo arguments as follows:

• if $\mathbf{order}=\mathrm{Nag\_ColMajor}$ and $\mathbf{uplo}=\mathrm{Nag\_Upper}$,
            $A_{ij}$ is stored in $\mathbf{ab}\left[k_d+i-j+\left(j-1\right)\times \mathbf{pdab}\right]$, for $j=1,\dots ,n$ and $i=\max \left(1,j-k_d\right),\dots ,j$;
• if $\mathbf{order}=\mathrm{Nag\_ColMajor}$ and $\mathbf{uplo}=\mathrm{Nag\_Lower}$,
            $A_{ij}$ is stored in $\mathbf{ab}\left[i-j+\left(j-1\right)\times \mathbf{pdab}\right]$, for $j=1,\dots ,n$ and $i=j,\dots ,\min \left(n,j+k_d\right)$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$ and $\mathbf{uplo}=\mathrm{Nag\_Upper}$,
            $A_{ij}$ is stored in $\mathbf{ab}\left[j-i+\left(i-1\right)\times \mathbf{pdab}\right]$, for $i=1,\dots ,n$ and $j=i,\dots ,\min \left(n,i+k_d\right)$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$ and $\mathbf{uplo}=\mathrm{Nag\_Lower}$,
            $A_{ij}$ is stored in $\mathbf{ab}\left[k_d+j-i+\left(i-1\right)\times \mathbf{pdab}\right]$, for $i=1,\dots ,n$ and $j=\max \left(1,i-k_d\right),\dots ,i$.

On exit: ab is overwritten by values generated during the reduction to tridiagonal form.

The first superdiagonal or subdiagonal and the diagonal of the tridiagonal matrix $T$ are returned in ab using the same storage format as described above.

7:     pdab – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) of the matrix $A$ in the array ab.

Constraint: $\mathbf{pdab}\ge \mathbf{kd}+1$.

8:     w[$\mathit{dim}$] – doubleOutput

Note: the dimension, dim, of the array w must be at least $\max \left(1,\mathbf{n}\right)$.

On exit: the eigenvalues of the matrix $A$ in ascending order.

9:     z[$\mathit{dim}$] – doubleOutput

Note: the dimension, dim, of the array z must be at least

• $\max \left(1,\mathbf{pdz}\times \mathbf{n}\right)$ when $\mathbf{job}=\mathrm{Nag\_EigVecs}$;
• $1$ when $\mathbf{job}=\mathrm{Nag\_DoNothing}$.

The $\left(i,j\right)$th element of the matrix $Z$ is stored in

• $\mathbf{z}\left[\left(j-1\right)\times \mathbf{pdz}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{z}\left[\left(i-1\right)\times \mathbf{pdz}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

On exit: if $\mathbf{job}=\mathrm{Nag\_EigVecs}$, z is overwritten by the orthogonal matrix $Z$ which contains the eigenvectors of $A$. The $i$th column of $Z$ contains the eigenvector which corresponds to the eigenvalue $\mathbf{w}\left[i-1\right]$.

If $\mathbf{job}=\mathrm{Nag\_DoNothing}$, z is not referenced.

10:   pdz – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array z.

Constraints:

• if $\mathbf{job}=\mathrm{Nag\_EigVecs}$, $\mathbf{pdz}\ge \max \left(1,\mathbf{n}\right)$;
• if $\mathbf{job}=\mathrm{Nag\_DoNothing}$, $\mathbf{pdz}\ge 1$.

11:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_CONVERGENCE

If $\mathbf{fail}\mathbf{.}\mathbf{errnum}=〈\mathit{\text{value}}〉$ and $\mathbf{job}=\mathrm{Nag\_DoNothing}$, the algorithm failed to converge; $〈\mathit{\text{value}}〉$ elements of an intermediate tridiagonal form did not converge to zero; if $\mathbf{fail}\mathbf{.}\mathbf{errnum}=〈\mathit{\text{value}}〉$ and $\mathbf{job}=\mathrm{Nag\_EigVecs}$, then the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and column $〈\mathit{\text{value}}〉/\left(\mathbf{n}+1\right)$ through $〈\mathit{\text{value}}〉\mathrm{ mod }\left(\mathbf{n}+1\right)$.

NE_ENUM_INT_2

On entry, $\mathbf{job}=〈\mathit{\text{value}}〉$, $\mathbf{pdz}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{job}=\mathrm{Nag\_EigVecs}$, $\mathbf{pdz}\ge \max \left(1,\mathbf{n}\right)$;
if $\mathbf{job}=\mathrm{Nag\_DoNothing}$, $\mathbf{pdz}\ge 1$.

NE_INT

On entry, $\mathbf{kd}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{kd}\ge 0$.

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 0$.

On entry, $\mathbf{pdab}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdab}>0$.

On entry, $\mathbf{pdz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdz}>0$.

NE_INT_2

On entry, $\mathbf{pdab}=〈\mathit{\text{value}}〉$ and $\mathbf{kd}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdab}\ge \mathbf{kd}+1$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (f08hcce.c)

9.2  Program Data

Program Data (f08hcce.d)

9.3  Program Results

Program Results (f08hcce.r)