NAG Library Function Document

nag_dstev (f08jac)

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 $\mathrm{Nag\_ColMajor}$.

2:     job – Nag_JobTypeInput

On entry: indicates whether eigenvectors are computed.

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

Only eigenvalues are computed.

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

Eigenvalues and eigenvectors are computed.

Constraint: $\mathbf{job}=\mathrm{Nag\_EigVals}$ or $\mathrm{Nag\_DoBoth}$.

3:     n – IntegerInput

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

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

4:     d[$\mathit{dim}$] – doubleInput/Output

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

On entry: the $n$ diagonal elements of the tridiagonal matrix $A$.

On exit: if $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_NOERROR, the eigenvalues in ascending order.

5:     e[$\mathit{dim}$] – doubleInput/Output

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

On entry: the $\left(n-1\right)$ subdiagonal elements of the tridiagonal matrix $A$.

On exit: the contents of e are destroyed.

6:     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\_DoBoth}$;
• $1$ otherwise.

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\_DoBoth}$, then if $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_NOERROR, z contains the orthonormal eigenvectors of the matrix $A$, with the $i$th column of $Z$ holding the eigenvector associated with $\mathbf{d}\left[i-1\right]$.

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

7:     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\_DoBoth}$, $\mathbf{pdz}\ge \max \left(1,\mathbf{n}\right)$;
• otherwise $\mathbf{pdz}\ge 1$.

8:     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

The algorithm failed to converge; $⟨\mathit{\text{value}}⟩$ off-diagonal elements of e did not converge to zero.

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\_DoBoth}$, $\mathbf{pdz}\ge \max \left(1,\mathbf{n}\right)$;
otherwise $\mathbf{pdz}\ge 1$.

NE_INT

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

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

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  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f08jace.c)

10.2  Program Data

Program Data (f08jace.d)

10.3  Program Results

Program Results (f08jace.r)