slepc-3.21.1 2024-04-26
Report Typos and Errors

EPSSetArbitrarySelection

Specifies a function intended to look for eigenvalues according to an arbitrary selection criterion. This criterion can be based on a computation involving the current eigenvector approximation.

Synopsis

```#include "slepceps.h"
PetscErrorCode EPSSetArbitrarySelection(EPS eps,PetscErrorCode (*func)(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx),void* ctx)
```
Logically Collective

Input Parameters

 eps - eigensolver context obtained from EPSCreate() func - a pointer to the evaluation function ctx - a context pointer (the last parameter to the evaluation function)

Calling sequence of func

``` PetscErrorCode func(PetscScalar er,PetscScalar ei,Vec xr,Vec xi,PetscScalar *rr,PetscScalar *ri,void *ctx)
```
 er - real part of the current eigenvalue approximation ei - imaginary part of the current eigenvalue approximation xr - real part of the current eigenvector approximation xi - imaginary part of the current eigenvector approximation rr - result of evaluation (real part) ri - result of evaluation (imaginary part) ctx - optional context, as set by EPSSetArbitrarySelection()

Notes

This provides a mechanism to select eigenpairs by evaluating a user-defined function. When a function has been provided, the default selection based on sorting the eigenvalues is replaced by the sorting of the results of this function (with the same sorting criterion given in EPSSetWhichEigenpairs()).

For instance, suppose you want to compute those eigenvectors that maximize a certain computable expression. Then implement the computation using the arguments xr and xi, and return the result in rr. Then set the standard sorting by magnitude so that the eigenpair with largest value of rr is selected.

This evaluation function is collective, that is, all processes call it and it can use collective operations; furthermore, the computed result must be the same in all processes.

The result of func is expressed as a complex number so that it is possible to use the standard eigenvalue sorting functions, but normally only rr is used. Set ri to zero unless it is meaningful in your application.

EPSSetWhichEigenpairs()