NAG Library Function Document

nag_real_symm_sparse_eigensystem_init (f12fac)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     n – IntegerInput

On entry: the order of the matrix $A$ (and the order of the matrix $B$ for the generalized problem) that defines the eigenvalue problem.

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

2:     nev – IntegerInput

On entry: the number of eigenvalues to be computed.

Constraint: $0<\mathbf{nev}<\mathbf{n}-1$.

3:     ncv – IntegerInput

On entry: the number of Lanczos basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of ncv relative to nev. However, it is recommended that $\mathbf{ncv}\ge 2\times \mathbf{nev}+1$. If many problems of the same type are to be solved, you should experiment with increasing ncv while keeping nev fixed for a given test problem. This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors. The optimal ‘cross-over’ with respect to CPU time is problem dependent and must be determined empirically.

Constraint: $\mathbf{nev}<\mathbf{ncv}\le \mathbf{n}$.

4:     icomm[$\max \left(1,\mathbf{licomm}\right)$] – IntegerCommunication Array

On exit: contains data to be communicated to the other functions in the suite.

5:     licomm – IntegerInput

On entry: the dimension of the array icomm.

If $\mathbf{licomm}=-1$, a workspace query is assumed and the function only calculates the required dimensions of icomm and comm, which it returns in $\mathbf{icomm}\left[0\right]$ and $\mathbf{comm}\left[0\right]$ respectively.

Constraint: $\mathbf{licomm}\ge 140\text{ or }\mathbf{licomm}=-1$.

6:     comm[$\max \left(1,\mathbf{lcomm}\right)$] – doubleCommunication Array

On exit: contains data to be communicated to the other functions in the suite.

7:     lcomm – IntegerInput

On entry: the dimension of the array comm.

If $\mathbf{lcomm}=-1$, a workspace query is assumed and the function only calculates the dimensions of icomm and comm required by nag_real_symm_sparse_eigensystem_iter (f12fbc), which it returns in $\mathbf{icomm}\left[0\right]$ and $\mathbf{comm}\left[0\right]$ respectively.

Constraint: $\mathbf{lcomm}\ge 3\times \mathbf{n}+\mathbf{ncv}\times \mathbf{ncv}+8\times \mathbf{ncv}+60\text{ or }\mathbf{lcomm}=-1$.

8:     fail – NagError *Input/Output

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

6  Error Indicators and Warnings

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

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

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

NE_INT_2

The length of the integer array icomm is too small $\mathbf{licomm}=⟨\mathit{\text{value}}⟩$, but must be at least $⟨\mathit{\text{value}}⟩$.

NE_INT_3

On entry, $\mathbf{lcomm}=⟨\mathit{\text{value}}⟩$, $\mathbf{n}=⟨\mathit{\text{value}}⟩$ and $\mathbf{ncv}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lcomm}\ge 3\times \mathbf{n}+3\times \mathbf{ncv}\times \mathbf{ncv}+8\times \mathbf{ncv}+60$.

On entry, $\mathbf{ncv}=⟨\mathit{\text{value}}⟩$, $\mathbf{nev}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ncv}>\mathbf{nev}+1$ and $\mathbf{ncv}\le \mathbf{n}$.

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 (f12face.c)

10.2  Program Data

Program Data (f12face.d)

10.3  Program Results

Program Results (f12face.r)