NAG Library Function Document

nag_complex_banded_eigensystem_solve (f12auc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     kl – IntegerInput

On entry: the number of subdiagonals of the matrices $A$ and $B$.

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

2:     ku – IntegerInput

On entry: the number of superdiagonals of the matrices $A$ and $B$.

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

3:     ab[$\mathit{dim}$] – const ComplexInput

Note: the dimension, dim, of the array ab must be at least $\mathbf{n}\times \left(2\times \mathbf{kl}+\mathbf{ku}+1\right)$ (see nag_complex_banded_eigensystem_init (f12atc)).

On entry: must contain the matrix $A$ in LAPACK column-ordered banded storage format for non-Hermitian matrices; that is, element $a_{ij}$ is stored in $\mathbf{ab}\left[\left(j-1\right)\times \left(2\times \mathbf{kl}+\mathbf{ku}+1\right)+\mathbf{kl}+\mathbf{ku}+i-j\right]$, which may be written as $\mathbf{ab}\left[\left(2\times j-1\right)\times \mathbf{kl}+j\times \mathbf{ku}+i-1\right]$, for $\max \left(1,j-\mathbf{ku}\right)\le i\le \min \left(n,j+\mathbf{kl}\right)$ and $j=1,2,\dots ,n$, (see Section 3.3.4 in the f07 Chapter Introduction).

4:     mb[$\mathit{dim}$] – const ComplexInput

Note: the dimension, dim, of the array mb must be at least $\mathbf{n}\times \left(2\times \mathbf{kl}+\mathbf{ku}+1\right)$ (see nag_complex_banded_eigensystem_init (f12atc)).

On entry: must contain the matrix $B$ in LAPACK column-ordered banded storage format for non-Hermitian matrices; that is, element $a_{ij}$ is stored in $\mathbf{mb}\left[\left(j-1\right)\times \left(2\times \mathbf{kl}+\mathbf{ku}+1\right)+\mathbf{kl}+\mathbf{ku}+i-j\right]$, which may be written as $\mathbf{mb}\left[\left(2\times j-1\right)\times \mathbf{kl}+j\times \mathbf{ku}+i-1\right]$, for $\max \left(1,j-\mathbf{ku}\right)\le i\le \min \left(n,j+\mathbf{kl}\right)$ and $j=1,2,\dots ,n$, (see Section 3.3.4 in the f07 Chapter Introduction).

5:     sigma – ComplexInput

On entry: if the $\mathbf{Shifted\; Inverse}$ mode (see nag_complex_sparse_eigensystem_option (f12arc)) has been selected then sigma must contain the shift used; otherwise sigma is not referenced. Section 4.2 in the f12 Chapter Introduction describes the use of shift and invert transformations.

6:     nconv – Integer *Output

On exit: the number of converged eigenvalues.

7:     d[nev] – ComplexOutput

On exit: the first nconv locations of the array d contain the converged approximate eigenvalues.

8:     z[$\mathit{dim}$] – ComplexOutput

Note: the dimension, dim, of the array z must be at least $\mathbf{n}\times \mathbf{nev}$ if the default option $\mathbf{Vectors}='\mathrm{RITZ}'$ (see nag_complex_sparse_eigensystem_option (f12arc)) has been selected (see nag_complex_banded_eigensystem_init (f12atc)).

On exit: if the default option $\mathbf{Vectors}='\mathrm{RITZ}'$ (see nag_complex_sparse_eigensystem_option (f12arc)) has been selected then z contains the final set of eigenvectors corresponding to the eigenvalues held in d, otherwise z is not referenced and may be NULL. The complex eigenvector associated with an eigenvalue $\mathbf{d}\left[j\right]$ is stored in the corresponding array section of z, namely $\mathbf{z}\left[\mathbf{n}\times \left(\mathit{j}-1\right)+\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$ and $\mathit{j}=1,2,\dots ,\mathbf{nconv}$.

9:     resid[n] – ComplexInput/Output

On entry: need not be set unless the option $\mathbf{Initial\; Residual}$ has been set in a prior call to nag_complex_sparse_eigensystem_option (f12arc) in which case resid must contain an initial residual vector.

On exit: contains the final residual vector. This can be used as the starting residual to improve convergence on the solution of a closely related eigenproblem. This has no relation to the error residual $Ax-\lambda x$ or $Ax-\lambda Bx$.

10:   v[$\mathbf{n}\times \mathbf{ncv}$] – ComplexOutput

On exit: if the option $\mathbf{Vectors}='\mathrm{SCHUR}'$ or $'\mathrm{RITZ}'$ (see nag_complex_sparse_eigensystem_option (f12arc)) has been set and a separate array z has been passed (i.e., z does not equal v), then the first nconv sections of v, of length $n$, will contain approximate Schur vectors that span the desired invariant subspace.

The $j$th Schur vector is stored in locations $\mathbf{v}\left[\mathbf{n}\times \left(\mathit{j}-1\right)+\mathit{i}-1\right]$, for $\mathit{j}=1,2,\dots ,\mathbf{nconv}$ and $\mathit{i}=1,2,\dots ,n$.

11:   comm[$60$] – ComplexCommunication Array

On entry: must remain unchanged from the prior call to nag_complex_sparse_eigensystem_option (f12arc) and nag_complex_banded_eigensystem_init (f12atc).

12:   icomm[$140$] – IntegerCommunication Array

On entry: must remain unchanged from the prior call to nag_complex_sparse_eigensystem_option (f12arc) and nag_complex_banded_eigensystem_init (f12atc).

13:   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_COMP_BAND_FAC

Failure during internal factorization of complex banded matrix. Please contact NAG.

NE_COMP_BAND_SOL

Failure during internal solution of complex banded matrix. Please contact NAG.

NE_EIGENVALUES

The number of eigenvalues found to sufficient accuracy is zero.

NE_INITIALIZATION

Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

NE_INT

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

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

NE_INTERNAL_EIGVAL_FAIL

Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG.

NE_INTERNAL_EIGVEC_FAIL

Error in internal call to compute eigenvectors. Please contact NAG.

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.

NE_INVALID_OPTION

On entry, $\mathbf{Vectors}=\text{Select}$, but this is not yet implemented.

The maximum number of iterations $\le 0$, the option $\mathbf{Iteration\; Limit}$ has been set to $⟨\mathit{\text{value}}⟩$.

NE_NO_ARNOLDI_FAC

Could not build an Arnoldi factorization. The size of the current Arnoldi factorization $=⟨\mathit{\text{value}}⟩$.

NE_NO_SHIFTS_APPLIED

No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.

NE_OPT_INCOMPAT

The options $\mathbf{Generalized}$ and $\mathbf{Regular}$ are incompatible.

NE_OVERFLOW

Overflow occurred during transformation of Ritz values to those of the original problem.

NE_REAL_BAND_FAC

Failure during internal factorization of real banded matrix. Please contact NAG.

NE_REAL_BAND_SOL

Failure during internal solution of real banded matrix. Please contact NAG.

NE_SCHUR_EIG_FAIL

During calculation of a Schur form, there was a failure to compute a number of eigenvalues Please contact NAG.

NE_SCHUR_REORDER

The computed Schur form could not be reordered by an internal call. Please contact NAG.

NE_TOO_MANY_ITER

The maximum number of iterations has been reached. The maximum number of $\text{iterations}=⟨\mathit{\text{value}}⟩$. The number of converged eigenvalues $=⟨\mathit{\text{value}}⟩$.

NE_ZERO_RESID

The option $\mathbf{Initial\; Residual}$ was selected but the starting vector held in resid is zero.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f12auce.c)

10.2  Program Data

Program Data (f12auce.d)

10.3  Program Results

Program Results (f12auce.r)