NAG CL Interface
f12juc (feast_​poly_​symm_​solve)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{handle}$ – void * Input

On entry: the handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by f12jac. It must not be changed between calls to the NAG FEAST suite.

2: $\mathbf{irevcm}$ – Integer * Input/Output

On initial entry: $\mathbf{irevcm}=0$, otherwise an error condition will be raised.

On intermediate re-entry: must be unchanged from its previous exit value. Changing irevcm to any other value between calls will result in an error.

On intermediate exit: has the following meanings.

$\mathbf{irevcm}=1$

The calling program must compute a factorization of the matrix ${\sum }_{i=0}^p{\mathbf{ze}}^i{A}_i$ suitable for solving a linear system, for example using f11dnc which computes an incomplete $LU$ factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.

Note:  the factorization can be computed in single precision.

$\mathbf{irevcm}=2$

The calling program must compute the solution to the linear system $\left({\sum }_{i=0}^p{\mathbf{ze}}^i{A}_i\right)w=y$, overwriting $y$ with the result $w$. The matrix ${\sum }_{i=0}^p{\mathbf{ze}}^i{A}_i$ has previously been factorized (when $\mathbf{irevcm}=1$ was returned) and this factorization can be reused here.

Note:  the solve can be performed in single precision.

$\mathbf{irevcm}=3$

The calling program must compute $A_{k}z$, storing the result in $x$.

On final exit: $\mathbf{irevcm}=0$: f12juc has completed its tasks. The value of fail determines whether the iteration has been successfully completed, or whether errors have been detected.

Constraint: on initial entry, $\mathbf{irevcm}=0$; on re-entry irevcm must remain unchanged.

Note: the matrices $x$, $y$ and $z$ referred to in this section are all of size $\mathbf{n}\times \mathbf{m0}$ and are stored in the arrays x, y and z, respectively.

Note: any values you return to f12juc as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by f12juc. If your code inadvertently does return any NaNs or infinities, f12juc is likely to produce unexpected results.

3: $\mathbf{deg}$ – Integer Input

On entry: the degree, $p$, of the polynomial eigenvalue problem.

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

4: $\mathbf{ze}$ – Complex * Input/Output

On initial entry: need not be set.

On intermediate exit: contains the current point on the contour.

• If $\mathbf{irevcm}=1$, then this must be used by the calling program to form a factorization of the matrix ${\sum }_{i=0}^p{\mathbf{ze}}^i{A}_i$.

5: $\mathbf{n}$ – Integer Input

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}\ge 1$.

6: $\mathbf{x}\left[\mathit{dim}\right]$ – Complex Input/Output

Note: the dimension, dim, of the array x must be at least $\mathbf{pdx}\times \mathbf{m0}$.

The $(i,j)$th element of the matrix $X$ is stored in $\mathbf{x}\left[(j-1)\times \mathbf{pdx}+i-1\right]$.

On initial entry: need not be set.

On intermediate exit:

• if $\mathbf{irevcm}=3$, the calling program must compute $A_{k}z$, storing the result in $x$ prior to re-entry.

Note: the matrices $x$, $y$ and $z$ referred to in this section are all of size $\mathbf{n}\times \mathbf{m0}$ and are stored in the arrays x, y and z, respectively.

the matrices $x$ and $z$ are stored in the first m0 columns of the arrays x and z, respectively.

7: $\mathbf{pdx}$ – Integer Input

On entry: the stride separating matrix row elements in the array x.

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

8: $\mathbf{y}\left[\mathit{dim}\right]$ – Complex Input/Output

Note: the dimension, dim, of the array y must be at least $\mathbf{pdy}\times \mathbf{m0}$.

The $(i,j)$th element of the matrix $Y$ is stored in $\mathbf{y}\left[(j-1)\times \mathbf{pdy}+i-1\right]$.

On initial entry: need not be set.

On intermediate exit:

• if $\mathbf{irevcm}=2$, the calling program must compute the solution to the linear system $\left({\sum }_{i=0}^p{\mathbf{ze}}^i{A}_i\right)w=y$, overwriting $y$ with the result $w$, prior to re-entry. The linear system has m0 right-hand sides.

9: $\mathbf{pdy}$ – Integer Input

On entry: the stride separating matrix row elements in the array y.

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

10: $\mathbf{k}$ – Integer * Output

On intermediate exit:

• if $\mathbf{irevcm}=3$, denotes which of the coefficient matrices $A_k$ needs to be used to form $A_{k}z$.

11: $\mathbf{m0}$ – Integer * Input/Output

On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Section 9 for further details.

On intermediate re-entry: m0 must remain unchanged.

On exit: if the initial search subspace was found by f12juc to be too large, then a new smaller suitable choice is returned.

Constraint: $0<\mathbf{m0}\le \mathbf{n}$.

12: $\mathbf{nconv}$ – Integer * Output

On exit: the number of eigenvalues found within the search contour.

13: $\mathbf{d}\left[\mathit{dim}\right]$ – Complex Input/Output

Note: the dimension, dim, of the array d must be at least $\mathbf{m0}$.

On initial entry: if the option $\mathbf{Subspace}=\mathrm{Yes}$ was set using the option setting function f12jbc, then d should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by z), otherwise d need not be set.

On final exit: the first nconv entries in d contain the eigenvalues.

Note: if the option $\mathbf{Subspace}=\mathrm{Yes}$ was set using the option setting function f12jbc, then on final exit d contains an estimate of the eigenvalues after a single contour integral.

14: $\mathbf{z}\left[\mathit{dim}\right]$ – Complex Input/Output

Note: the dimension, dim, of the array z must be at least $\mathbf{pdz}\times \mathbf{m0}$.

The $(i,j)$th element of the matrix $Z$ is stored in $\mathbf{z}\left[(j-1)\times \mathbf{pdz}+i-1\right]$.

On initial entry: if the option $\mathbf{Subspace}=\mathrm{Yes}$ was set using the option setting function f12jbc, then z should contain an initial guess at the eigenvector search subspace, otherwise z need not be set.

On intermediate exit: must not be changed.

On final exit: the first nconv columns of z contain the eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option $\mathbf{Execution\; Mode}=\mathrm{Subspace}$ was set using the option setting function f12jbc, then on final exit columns $1:\mathbf{m0}$ of z contain the current search subspace after one contour integral.

15: $\mathbf{pdz}$ – Integer Input

On entry: the stride separating matrix row elements in the array z.

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

16: $\mathbf{eps}$ – double * Input/Output

On initial entry: need not be set.

On exit: the relative error on the trace. At iteration $k$, eps is given by the expression $|{\mathrm{trace}}_k-{\mathrm{trace}}_{k-1}|/(\left|E_{\mathrm{mid}}\right|+r)$, where ${\mathrm{trace}}_k$ is the sum of the eigenvalues found at the $k$th iteration, $E_{\mathrm{mid}}$ is the centre of mass of the contour and $r$ is the radius of the circle, centred at $E_{\mathrm{mid}}$ which just encloses the contour.

17: $\mathbf{iter}$ – Integer * Input/Output

On initial entry: need not be set.

On exit: the number of subspace iterations performed.

18: $\mathbf{resid}\left[\mathit{dim}\right]$ – double Input/Output

Note: the dimension, dim, of the array resid must be at least $\mathbf{m0}$.

On initial entry: need not be set.

On final exit: for $i=1,\dots ,\mathbf{nconv}$, $\mathbf{resid}\left[i-1\right]$ contains the relative residual, in the $1$-norm, of the $i$th eigenpair found, that is $\mathbf{resid}\left[i-1\right]=\Vert \left({\sum }_{j=0}^p{\lambda }_i^j{A}_j\right)z_i\Vert /(\Vert {\lambda }^p{A}_p{z}_i\Vert \times (\left|E_{\mathrm{mid}}\right|+r))$, where $E_{\mathrm{mid}}$ is the centre of mass of the contour and $r$ is the radius of the circle, centred at $E_{\mathrm{mid}}$ which just encloses the contour.

19: $\mathbf{fail}$ – NagError * Input/Output

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.

NE_BAD_PARAM

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

NE_EIGENVALUES

No eigenvalues were found within the search contour.

NE_HANDLE

Either the contour setting function f12jec has not been called prior to the first call of this function or the supplied handle has become corrupted.

NE_INT

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

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

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

On intermediate entry, $\mathbf{irevcm}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{irevcm}=1$, $2$, $3$, $4$, $5$ or $6$.

NE_INT_2

On entry, $\mathbf{m0}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $0<\mathbf{m0}\le \mathbf{n}$.

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

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

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

NE_INTERNAL_EIGVAL_FAIL

An internal error occurred in the reduced eigenvalue solver. 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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

NE_NO_SOLUTION

The optional parameter $\mathbf{Execution\; Mode}=\mathrm{Estimate}$ was set using f12jbc. nconv contains a stochastic estimate of the number of eigenvalues within the contour.

The optional parameter $\mathbf{Execution\; Mode}=\mathrm{Subspace}$ was set using f12jbc. Columns $1:\mathbf{m0}$ of z contain the search subspace after one contour integral and d contains an estimate of the eigenvalues.

NE_TOO_MANY_ITER

The function did not converge after the maximum number of iterations. The results returned may still be useful, however they might be improved by increasing the maximum number of iterations using the option setting routine f12jbc, increasing the size of the eigenvector search subspace, m0, or experimenting with the choice of contour. Note that the returned eigenvalues and eigenvectors, together with the returned value of m0, can be used as the initial estimates for a new iteration of the solver.

NE_TOO_SMALL

The size of the eigenvector search subspace, m0, is too small.

NE_ZERO_VALUE

The option $\mathbf{Subspace}=\mathrm{Yes}$ was set using the option setting function f12jbc but no nonzero elements were found in the supplied subspace.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Additional Licensor

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results