Actual source code: slepceps.h

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

      6:    This file is part of SLEPc.
      7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
      8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      9: */
     10: /*
     11:    User interface for the SLEPc linear eigenvalue solvers
     12: */

     14: #pragma once

     16: #include <slepcst.h>
     17: #include <slepcbv.h>
     18: #include <slepcds.h>
     19: #include <slepcrg.h>
     20: #include <slepclme.h>
     21: #include <petscsnes.h>

     23: /* SUBMANSEC = EPS */

     25: SLEPC_EXTERN PetscErrorCode EPSInitializePackage(void);
     26: SLEPC_EXTERN PetscErrorCode EPSFinalizePackage(void);

     28: /*S
     29:    EPS - SLEPc object that manages all the linear eigenvalue problem solvers.

     31:    Level: beginner

     33: .seealso: [](ch:eps), `EPSCreate()`, `ST`
     34: S*/
     35: typedef struct _p_EPS* EPS;

     37: /*J
     38:    EPSType - String with the name of a linear eigensolver.

     40:    Level: beginner

     42: .seealso: [](ch:eps), `EPSSetType()`, `EPS`
     43: J*/
     44: typedef const char *EPSType;
     45: #define EPSPOWER       "power"
     46: #define EPSSUBSPACE    "subspace"
     47: #define EPSARNOLDI     "arnoldi"
     48: #define EPSLANCZOS     "lanczos"
     49: #define EPSKRYLOVSCHUR "krylovschur"
     50: #define EPSGD          "gd"
     51: #define EPSJD          "jd"
     52: #define EPSRQCG        "rqcg"
     53: #define EPSLOBPCG      "lobpcg"
     54: #define EPSCISS        "ciss"
     55: #define EPSLYAPII      "lyapii"
     56: #define EPSLAPACK      "lapack"
     57: #define EPSARPACK      "arpack"
     58: #define EPSBLOPEX      "blopex"
     59: #define EPSPRIMME      "primme"
     60: #define EPSFEAST       "feast"
     61: #define EPSSCALAPACK   "scalapack"
     62: #define EPSELPA        "elpa"
     63: #define EPSELEMENTAL   "elemental"
     64: #define EPSEVSL        "evsl"
     65: #define EPSCHASE       "chase"

     67: /* Logging support */
     68: SLEPC_EXTERN PetscClassId EPS_CLASSID;

     70: /*E
     71:    EPSProblemType - Determines the type of eigenvalue problem.

     73:    Values:
     74: +  `EPS_HEP`    - Hermitian
     75: .  `EPS_GHEP`   - generalized Hermitian
     76: .  `EPS_NHEP`   - non-Hermitian
     77: .  `EPS_GNHEP`  - generalized non-Hermitian
     78: .  `EPS_PGNHEP` - generalized non-Hermitian with positive (semi-)definite $B$
     79: .  `EPS_GHIEP`  - generalized Hermitian-indefinite
     80: .  `EPS_BSE`    - structured Bethe-Salpeter
     81: -  `EPS_HAMILT` - structured Hamiltonian

     83:    Note:
     84:    In real scalars, one should read the term Hermitian as symmetric.

     86:    Level: intermediate

     88: .seealso: [](ch:eps), `EPSSetProblemType()`, `EPSGetProblemType()`
     89: E*/
     90: typedef enum { EPS_HEP    = 1,
     91:                EPS_GHEP   = 2,
     92:                EPS_NHEP   = 3,
     93:                EPS_GNHEP  = 4,
     94:                EPS_PGNHEP = 5,
     95:                EPS_GHIEP  = 6,
     96:                EPS_BSE    = 7,
     97:                EPS_HAMILT = 8 } EPSProblemType;

     99: /*MC
    100:    EPS_HEP - A Hermitian eigenvalue problem.

    102:    Note:
    103:    The problem is formulated as $Ax=\lambda x$, where $A$ is real symmetric
    104:    or complex Hermitian.

    106:    Level: intermediate

    108: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
    109: M*/

    111: /*MC
    112:    EPS_GHEP - A generalized Hermitian eigenvalue problem.

    114:    Note:
    115:    The problem is formulated as $Ax=\lambda Bx$, where $A$ and $B$ are real
    116:    symmetric or complex Hermitian, and $B$ is positive (semi-)definite.

    118:    Level: intermediate

    120: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
    121: M*/

    123: /*MC
    124:    EPS_NHEP - A non-Hermitian eigenvalue problem.

    126:    Note:
    127:    The problem is formulated as $Ax=\lambda x$, where $A$ is non-symmetric
    128:    (or non-Hermitian).

    130:    Level: intermediate

    132: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
    133: M*/

    135: /*MC
    136:    EPS_GNHEP - A generalized non-Hermitian eigenvalue problem.

    138:    Note:
    139:    The problem is formulated as $Ax=\lambda Bx$, where $A$ or $B$ are
    140:    non-symmetric (or non-Hermitian).

    142:    Level: intermediate

    144: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
    145: M*/

    147: /*MC
    148:    EPS_PGNHEP - A generalized non-Hermitian eigenvalue problem with positive
    149:    (semi-)definite $B$.

    151:    Notes:
    152:    The problem is formulated as $Ax=\lambda Bx$, where $A$ is non-symmetric
    153:    (or non-Hermitian), but $B$ is symmetric (or Hermitian) and positive
    154:    (semi-)definite.

    156:    The problem will be solved with a non-Hermitian solver, but using an
    157:    inner product induced by matrix $B$.

    159:    Level: intermediate

    161: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
    162: M*/

    164: /*MC
    165:    EPS_GHIEP - A generalized Hermitian-indefinite eigenvalue problem.

    167:    Notes:
    168:    The problem is formulated as $Ax=\lambda Bx$, where both $A$ and $B$ are
    169:    real symmetric or complex Hermitian, but $B$ is indefinite.

    171:    The solver will try to exploit the symmetry by using an indefinite
    172:    inner product, which may turn the computation numerically unstable.
    173:    To avoid this, solve the problem as non-Hermitian.

    175:    Level: intermediate

    177: .seealso: [](ch:eps), `EPSProblemType`, `EPSSetProblemType()`
    178: M*/

    180: /*MC
    181:    EPS_BSE - A structured Bethe-Salpeter eigenvalue problem.

    183:    Notes:
    184:    The problem is formulated as $Hx=\lambda x$, where $H$ has a Bethe-Salpeter
    185:    structure,
    186:      $$H = \begin{bmatrix}
    187:         R & C \\
    188:         -C^* & -R^T
    189:         \end{bmatrix},$$
    190:    where $R$ is Hermitian and $C$ is complex symmetric. Can also be used in
    191:    the case of real matrices.

    193:    A description of the properties of this problem can be found in {cite:p}`Alv25`
    194:    and references therein.

    196:    Level: intermediate

    198: .seealso: [](ch:eps), [](sec:structured), `EPSProblemType`, `EPSSetProblemType()`
    199: M*/

    201: /*MC
    202:    EPS_HAMILT - A structured Hamiltonian eigenvalue problem.

    204:    Note:
    205:    The problem is formulated as $Hx=\lambda x$, where $H$ has a Hamiltonian
    206:    structure,
    207:      $$H = \begin{bmatrix}
    208:         A & B \\
    209:         C & -A^*
    210:         \end{bmatrix},$$
    211:    where $A$, $B$ and $C$ are either real with $B=B^T$, $C=C^T$, or complex with
    212:    $B=B^*$, $C=C^*$.

    214:    Level: intermediate

    216: .seealso: [](ch:eps), [](sec:structured), `EPSProblemType`, `EPSSetProblemType()`
    217: M*/

    219: /*E
    220:    EPSExtraction - Determines the type of extraction technique employed
    221:    by the eigensolver.

    223:    Values:
    224: +  `EPS_RITZ`              - Rayleigh-Ritz extraction
    225: .  `EPS_HARMONIC`          - harmonic Ritz extraction
    226: .  `EPS_HARMONIC_RELATIVE` - harmonic Ritz extraction relative to the eigenvalue
    227: .  `EPS_HARMONIC_RIGHT`    - harmonic Ritz extraction for rightmost eigenvalues
    228: .  `EPS_HARMONIC_LARGEST`  - harmonic Ritz extraction for largest magnitude (without target)
    229: .  `EPS_REFINED`           - refined Ritz extraction
    230: -  `EPS_REFINED_HARMONIC`  - refined harmonic Ritz extraction

    232:    Level: advanced

    234: .seealso: [](ch:eps), `EPSSetExtraction()`, `EPSGetExtraction()`
    235: E*/
    236: typedef enum { EPS_RITZ,
    237:                EPS_HARMONIC,
    238:                EPS_HARMONIC_RELATIVE,
    239:                EPS_HARMONIC_RIGHT,
    240:                EPS_HARMONIC_LARGEST,
    241:                EPS_REFINED,
    242:                EPS_REFINED_HARMONIC } EPSExtraction;

    244: /*MC
    245:    EPS_RITZ - The standard Rayleigh-Ritz extraction.

    247:    Note:
    248:    This is the default way of computing eigenpair approximations from a
    249:    given subspace.

    251:    Level: advanced

    253: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
    254: M*/

    256: /*MC
    257:    EPS_HARMONIC - The harmonic Ritz extraction.

    259:    Notes:
    260:    This extraction method may provide better convergence when computing
    261:    interior eigenvalues close to a given target.

    263:    For the particular case of Krylov-Schur, a detailed description can
    264:    be found in {cite:p}`Rom09`.

    266:    Level: advanced

    268: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`, `EPSSetTarget()`
    269: M*/

    271: /*MC
    272:    EPS_HARMONIC_RELATIVE - The harmonic Ritz extraction relative to the eigenvalue.

    274:    Note:
    275:    This is a variation of `EPS_HARMONIC`, used in Davidson methods only.

    277:    Level: advanced

    279: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`, `EPSSetTarget()`
    280: M*/

    282: /*MC
    283:    EPS_HARMONIC_RIGHT - The harmonic Ritz extraction for rightmost eigenvalues.

    285:    Note:
    286:    This is a variation of `EPS_HARMONIC`, used in Davidson methods only.

    288:    Level: advanced

    290: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`, `EPSSetTarget()`
    291: M*/

    293: /*MC
    294:    EPS_HARMONIC_LARGEST - The harmonic Ritz extraction for largest magnitude
    295:    eigenvalues (without target).

    297:    Note:
    298:    This is a variation of `EPS_HARMONIC`, used in Davidson methods only.

    300:    Level: advanced

    302: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
    303: M*/

    305: /*MC
    306:    EPS_REFINED - The refined Ritz extraction method {cite:p}`Jia97`.

    308:    Note:
    309:    Currently implemented only in `EPSARNOLDI`.

    311:    Level: advanced

    313: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
    314: M*/

    316: /*MC
    317:    EPS_REFINED_HARMONIC - The refined harmonic Ritz extraction.

    319:    Note:
    320:    This is a combination of `EPS_HARMONIC` and `EPS_REFINED`.

    322:    Developer Note:
    323:    Currently not implemented, reserved for future use.

    325:    Level: advanced

    327: .seealso: [](ch:eps), `EPSExtraction`, `EPSSetExtraction()`
    328: M*/

    330: /*E
    331:    EPSWhich - Determines which part of the spectrum is requested.

    333:    Values:
    334: +  `EPS_LARGEST_MAGNITUDE`  - largest $|\lambda|$
    335: .  `EPS_SMALLEST_MAGNITUDE` - smallest $|\lambda|$
    336: .  `EPS_LARGEST_REAL`       - largest $\mathrm{Re}(\lambda)$
    337: .  `EPS_SMALLEST_REAL`      - smallest $\mathrm{Re}(\lambda)$
    338: .  `EPS_LARGEST_IMAGINARY`  - largest $\mathrm{Im}(\lambda)$
    339: .  `EPS_SMALLEST_IMAGINARY` - smallest $\mathrm{Im}(\lambda)$
    340: .  `EPS_TARGET_MAGNITUDE`   - smallest $|\lambda-\tau|$
    341: .  `EPS_TARGET_REAL`        - smallest $|\mathrm{Re}(\lambda-\tau)|$
    342: .  `EPS_TARGET_IMAGINARY`   - smallest $|\mathrm{Im}(\lambda-\tau)|$
    343: .  `EPS_ALL`                - all $\lambda\in[a,b]$ or $\lambda\in\Omega$
    344: -  `EPS_WHICH_USER`         - user-defined sorting criterion

    346:    Notes:
    347:    If SLEPc is compiled for real scalars `EPS_LARGEST_IMAGINARY` and
    348:    `EPS_SMALLEST_IMAGINARY` use the absolute value of the imaginary part
    349:    for eigenvalue selection.

    351:    The target $\tau$ is a scalar value provided with `EPSSetTarget()`.

    353:    The case `EPS_ALL` needs an interval $[a,b]$ given with `EPSSetInterval()`
    354:    or a region $\Omega$ specified with an `RG` object.

    356:    Level: intermediate

    358: .seealso: [](ch:eps), `EPSSetWhichEigenpairs()`, `EPSSetTarget()`, `EPSSetInterval()`
    359: E*/
    360: typedef enum { EPS_LARGEST_MAGNITUDE  = 1,
    361:                EPS_SMALLEST_MAGNITUDE = 2,
    362:                EPS_LARGEST_REAL       = 3,
    363:                EPS_SMALLEST_REAL      = 4,
    364:                EPS_LARGEST_IMAGINARY  = 5,
    365:                EPS_SMALLEST_IMAGINARY = 6,
    366:                EPS_TARGET_MAGNITUDE   = 7,
    367:                EPS_TARGET_REAL        = 8,
    368:                EPS_TARGET_IMAGINARY   = 9,
    369:                EPS_ALL                = 10,
    370:                EPS_WHICH_USER         = 11 } EPSWhich;

    372: /*E
    373:    EPSBalance - The type of balancing used for non-Hermitian problems.

    375:    Values:
    376: +  `EPS_BALANCE_NONE`    - no balancing matrix is used
    377: .  `EPS_BALANCE_ONESIDE` - balancing matrix $D$ is computed with a one-sided Krylov method
    378: .  `EPS_BALANCE_TWOSIDE` - balancing matrix $D$ is computed with a two-sided Krylov method
    379: -  `EPS_BALANCE_USER`    - use a balancing matrix $D$ provided by the user

    381:    Level: intermediate

    383: .seealso: [](ch:eps), [](sec:balancing), `EPSSetBalance()`
    384: E*/
    385: typedef enum { EPS_BALANCE_NONE,
    386:                EPS_BALANCE_ONESIDE,
    387:                EPS_BALANCE_TWOSIDE,
    388:                EPS_BALANCE_USER } EPSBalance;
    389: SLEPC_EXTERN const char *EPSBalanceTypes[];

    391: /*E
    392:    EPSErrorType - The error type used to assess the accuracy of computed solutions.

    394:    Values:
    395: +  `EPS_ERROR_ABSOLUTE` - compute error bound as $\|r\|$
    396: .  `EPS_ERROR_RELATIVE` - compute error bound as $\|r\|/|\lambda|$
    397: -  `EPS_ERROR_BACKWARD` - compute error bound as $\|r\|/(\|A\|+|\lambda|\|B\|)$

    399:    Level: intermediate

    401: .seealso: [](ch:eps), `EPSComputeError()`
    402: E*/
    403: typedef enum { EPS_ERROR_ABSOLUTE,
    404:                EPS_ERROR_RELATIVE,
    405:                EPS_ERROR_BACKWARD } EPSErrorType;
    406: SLEPC_EXTERN const char *EPSErrorTypes[];

    408: /*E
    409:    EPSConv - The convergence criterion to be used by the solver.

    411:    Values:
    412: +  `EPS_CONV_ABS`  - absolute convergence criterion, $\|r\|$
    413: .  `EPS_CONV_REL`  - convergence criterion relative to eigenvalue, $\|r\|/|\lambda|$
    414: .  `EPS_CONV_NORM` - convergence criterion relative to matrix norms, $\|r\|/(\|A\|+|\lambda|\|B\|)$
    415: -  `EPS_CONV_USER` - convergence dictated by user-provided function

    417:    Level: intermediate

    419: .seealso: [](ch:eps), `EPSSetConvergenceTest()`, `EPSSetConvergenceTestFunction()`
    420: E*/
    421: typedef enum { EPS_CONV_ABS,
    422:                EPS_CONV_REL,
    423:                EPS_CONV_NORM,
    424:                EPS_CONV_USER } EPSConv;

    426: /*E
    427:    EPSStop - The stopping test to decide the termination of the outer loop
    428:    of the eigensolver.

    430:    Values:
    431: +  `EPS_STOP_BASIC`     - default stopping test
    432: .  `EPS_STOP_USER`      - user-provided stopping test
    433: -  `EPS_STOP_THRESHOLD` - threshold stopping test

    435:    Level: advanced

    437: .seealso: [](ch:eps), `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
    438: E*/
    439: typedef enum { EPS_STOP_BASIC,
    440:                EPS_STOP_USER,
    441:                EPS_STOP_THRESHOLD } EPSStop;

    443: /*MC
    444:    EPS_STOP_BASIC - The default stopping test.

    446:    Note:
    447:    By default, the termination of the outer loop is decided by calling
    448:    `EPSStoppingBasic()`, which will stop if all requested eigenvalues are converged,
    449:    or if the maximum number of iterations has been reached.

    451:    Level: advanced

    453: .seealso: [](ch:eps), `EPSStop`, `EPSSetStoppingTest()`, `EPSStoppingBasic()`
    454: M*/

    456: /*MC
    457:    EPS_STOP_USER - The user-provided stopping test.

    459:    Note:
    460:    Customized stopping test using the user-provided function given with
    461:    `EPSSetStoppingTestFunction()`.

    463:    Level: advanced

    465: .seealso: [](ch:eps), `EPSStop`, `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
    466: M*/

    468: /*MC
    469:    EPS_STOP_THRESHOLD - The threshold stopping test.

    471:    Note:
    472:    When a threshold has been provided with `EPSSetThreshold()`, the termination
    473:    of the outer loop is decided by calling `EPSStoppingThreshold()`, which will
    474:    stop when one of the computed eigenvalues is not above/below the threshold.
    475:    If a number of wanted eigenvalues has been specified via `EPSSetDimensions()`
    476:    then it is also taken into account, and the solver will stop when one of the
    477:    two conditions (threshold or number of converged values) is met.

    479:    Level: advanced

    481: .seealso: [](ch:eps), `EPSStop`, `EPSSetStoppingTest()`, `EPSStoppingThreshold()`, `EPSSetThreshold()`, `EPSSetDimensions()`
    482: M*/

    484: /*E
    485:    EPSConvergedReason - Reason an eigensolver was determined to have converged
    486:    or diverged.

    488:    Values:
    489: +  `EPS_CONVERGED_TOL`          - converged up to tolerance
    490: .  `EPS_CONVERGED_USER`         - converged due to a user-defined condition
    491: .  `EPS_DIVERGED_ITS`           - exceeded the maximum number of allowed iterations
    492: .  `EPS_DIVERGED_BREAKDOWN`     - generic breakdown in method
    493: .  `EPS_DIVERGED_SYMMETRY_LOST` - pseudo-Lanczos was not able to keep symmetry
    494: -  `EPS_CONVERGED_ITERATING`    - the solver is still running

    496:    Level: intermediate

    498: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSSetTolerances()`
    499: E*/
    500: typedef enum {/* converged */
    501:               EPS_CONVERGED_TOL                =  1,
    502:               EPS_CONVERGED_USER               =  2,
    503:               /* diverged */
    504:               EPS_DIVERGED_ITS                 = -1,
    505:               EPS_DIVERGED_BREAKDOWN           = -2,
    506:               EPS_DIVERGED_SYMMETRY_LOST       = -3,
    507:               EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;
    508: SLEPC_EXTERN const char *const*EPSConvergedReasons;

    510: /*MC
    511:    EPS_CONVERGED_TOL - The computed error estimates, based on residual norms,
    512:    for all requested eigenvalues are below the tolerance.

    514:    Level: intermediate

    516: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
    517: M*/

    519: /*MC
    520:    EPS_CONVERGED_USER - The solver was declared converged due to a user-defined condition.

    522:    Note:
    523:    This happens only when a user-defined stopping test has been set with
    524:    `EPSSetStoppingTestFunction()`.

    526:    Level: intermediate

    528: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`, `EPSSetStoppingTestFunction()`
    529: M*/

    531: /*MC
    532:    EPS_DIVERGED_ITS - Exceeded the maximum number of allowed iterations
    533:    before the convergence criterion was satisfied.

    535:    Level: intermediate

    537: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
    538: M*/

    540: /*MC
    541:    EPS_DIVERGED_BREAKDOWN - A breakdown in the solver was detected so the
    542:    method could not continue.

    544:    Level: intermediate

    546: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
    547: M*/

    549: /*MC
    550:    EPS_DIVERGED_SYMMETRY_LOST - The selected solver uses a pseudo-Lanczos recurrence,
    551:    which is numerically unstable, and a symmetry test revealed that instability
    552:    had appeared so the solver could not continue.

    554:    Level: intermediate

    556: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
    557: M*/

    559: /*MC
    560:    EPS_CONVERGED_ITERATING - This value is returned if `EPSGetConvergedReason()` is called
    561:    while `EPSSolve()` is still running.

    563:    Level: intermediate

    565: .seealso: [](ch:eps), `EPSSolve()`, `EPSGetConvergedReason()`, `EPSConvergedReason`
    566: M*/

    568: /*S
    569:    EPSStoppingCtx - Data structure (C struct) to hold additional information to
    570:    be used in some stopping test functions.

    572:    Level: advanced

    574: .seealso: [](ch:eps), `EPSSetStoppingTestFunction()`
    575: S*/
    576: struct _n_EPSStoppingCtx {
    577:   PetscReal firstev;    /* the (absolute) value of the first converged eigenvalue */
    578:   PetscReal lastev;     /* the (absolute) value of the last converged eigenvalue */
    579:   PetscReal thres;      /* threshold set with EPSSetThreshold() */
    580:   PetscBool threlative; /* threshold is relative */
    581:   EPSWhich  which;      /* which eigenvalues are being computed */
    582: };
    583: typedef struct _n_EPSStoppingCtx* EPSStoppingCtx;

    585: SLEPC_EXTERN PetscErrorCode EPSCreate(MPI_Comm,EPS*);
    586: SLEPC_EXTERN PetscErrorCode EPSDestroy(EPS*);
    587: SLEPC_EXTERN PetscErrorCode EPSReset(EPS);
    588: SLEPC_EXTERN PetscErrorCode EPSSetType(EPS,EPSType);
    589: SLEPC_EXTERN PetscErrorCode EPSGetType(EPS,EPSType*);
    590: SLEPC_EXTERN PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);
    591: SLEPC_EXTERN PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);
    592: SLEPC_EXTERN PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);
    593: SLEPC_EXTERN PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);
    594: SLEPC_EXTERN PetscErrorCode EPSSetBalance(EPS,EPSBalance,PetscInt,PetscReal);
    595: SLEPC_EXTERN PetscErrorCode EPSGetBalance(EPS,EPSBalance*,PetscInt*,PetscReal*);
    596: SLEPC_EXTERN PetscErrorCode EPSSetOperators(EPS,Mat,Mat);
    597: SLEPC_EXTERN PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);
    598: SLEPC_EXTERN PetscErrorCode EPSSetFromOptions(EPS);
    599: SLEPC_EXTERN PetscErrorCode EPSSetDSType(EPS);
    600: SLEPC_EXTERN PetscErrorCode EPSSetUp(EPS);
    601: SLEPC_EXTERN PetscErrorCode EPSSolve(EPS);
    602: SLEPC_EXTERN PetscErrorCode EPSView(EPS,PetscViewer);
    603: SLEPC_EXTERN PetscErrorCode EPSViewFromOptions(EPS,PetscObject,const char[]);
    604: SLEPC_EXTERN PetscErrorCode EPSErrorView(EPS,EPSErrorType,PetscViewer);
    605: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSErrorView()", ) static inline PetscErrorCode EPSPrintSolution(EPS eps,PetscViewer v) {return EPSErrorView(eps,EPS_ERROR_RELATIVE,v);}
    606: SLEPC_EXTERN PetscErrorCode EPSErrorViewFromOptions(EPS);
    607: SLEPC_EXTERN PetscErrorCode EPSConvergedReasonView(EPS,PetscViewer);
    608: SLEPC_EXTERN PetscErrorCode EPSConvergedReasonViewFromOptions(EPS);
    609: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "EPSConvergedReasonView()", ) static inline PetscErrorCode EPSReasonView(EPS eps,PetscViewer v) {return EPSConvergedReasonView(eps,v);}
    610: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "EPSConvergedReasonViewFromOptions()", ) static inline PetscErrorCode EPSReasonViewFromOptions(EPS eps) {return EPSConvergedReasonViewFromOptions(eps);}
    611: SLEPC_EXTERN PetscErrorCode EPSValuesView(EPS,PetscViewer);
    612: SLEPC_EXTERN PetscErrorCode EPSValuesViewFromOptions(EPS);
    613: SLEPC_EXTERN PetscErrorCode EPSVectorsView(EPS,PetscViewer);
    614: SLEPC_EXTERN PetscErrorCode EPSVectorsViewFromOptions(EPS);

    616: SLEPC_EXTERN PetscErrorCode EPSSetTarget(EPS,PetscScalar);
    617: SLEPC_EXTERN PetscErrorCode EPSGetTarget(EPS,PetscScalar*);
    618: SLEPC_EXTERN PetscErrorCode EPSSetInterval(EPS,PetscReal,PetscReal);
    619: SLEPC_EXTERN PetscErrorCode EPSGetInterval(EPS,PetscReal*,PetscReal*);
    620: SLEPC_EXTERN PetscErrorCode EPSSetST(EPS,ST);
    621: SLEPC_EXTERN PetscErrorCode EPSGetST(EPS,ST*);
    622: SLEPC_EXTERN PetscErrorCode EPSSetBV(EPS,BV);
    623: SLEPC_EXTERN PetscErrorCode EPSGetBV(EPS,BV*);
    624: SLEPC_EXTERN PetscErrorCode EPSSetRG(EPS,RG);
    625: SLEPC_EXTERN PetscErrorCode EPSGetRG(EPS,RG*);
    626: SLEPC_EXTERN PetscErrorCode EPSSetDS(EPS,DS);
    627: SLEPC_EXTERN PetscErrorCode EPSGetDS(EPS,DS*);
    628: SLEPC_EXTERN PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);
    629: SLEPC_EXTERN PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);
    630: SLEPC_EXTERN PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
    631: SLEPC_EXTERN PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

    633: SLEPC_EXTERN PetscErrorCode EPSGetConvergedReason(EPS,EPSConvergedReason*);

    635: SLEPC_EXTERN PetscErrorCode EPSGetConverged(EPS,PetscInt*);
    636: SLEPC_EXTERN PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
    637: SLEPC_EXTERN PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);
    638: SLEPC_EXTERN PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);
    639: SLEPC_EXTERN PetscErrorCode EPSGetLeftEigenvector(EPS,PetscInt,Vec,Vec);

    641: SLEPC_EXTERN PetscErrorCode EPSComputeError(EPS,PetscInt,EPSErrorType,PetscReal*);
    642: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSComputeError()", ) static inline PetscErrorCode EPSComputeRelativeError(EPS eps,PetscInt i,PetscReal *r) {return EPSComputeError(eps,i,EPS_ERROR_RELATIVE,r);}
    643: PETSC_DEPRECATED_FUNCTION(3, 6, 0, "EPSComputeError() with EPS_ERROR_ABSOLUTE", ) static inline PetscErrorCode EPSComputeResidualNorm(EPS eps,PetscInt i,PetscReal *r) {return EPSComputeError(eps,i,EPS_ERROR_ABSOLUTE,r);}
    644: SLEPC_EXTERN PetscErrorCode EPSGetInvariantSubspace(EPS,Vec[]);
    645: SLEPC_EXTERN PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);
    646: SLEPC_EXTERN PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);

    648: SLEPC_EXTERN PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);
    649: SLEPC_EXTERN PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);
    650: SLEPC_EXTERN PetscErrorCode EPSSetThreshold(EPS,PetscReal,PetscBool);
    651: SLEPC_EXTERN PetscErrorCode EPSGetThreshold(EPS,PetscReal*,PetscBool*);
    652: SLEPC_EXTERN PetscErrorCode EPSSetTwoSided(EPS,PetscBool);
    653: SLEPC_EXTERN PetscErrorCode EPSGetTwoSided(EPS,PetscBool*);
    654: SLEPC_EXTERN PetscErrorCode EPSSetTrueResidual(EPS,PetscBool);
    655: SLEPC_EXTERN PetscErrorCode EPSGetTrueResidual(EPS,PetscBool*);
    656: SLEPC_EXTERN PetscErrorCode EPSSetPurify(EPS,PetscBool);
    657: SLEPC_EXTERN PetscErrorCode EPSGetPurify(EPS,PetscBool*);
    658: SLEPC_EXTERN PetscErrorCode EPSIsGeneralized(EPS,PetscBool*);
    659: SLEPC_EXTERN PetscErrorCode EPSIsHermitian(EPS,PetscBool*);
    660: SLEPC_EXTERN PetscErrorCode EPSIsPositive(EPS,PetscBool*);
    661: SLEPC_EXTERN PetscErrorCode EPSIsStructured(EPS,PetscBool*);

    663: SLEPC_EXTERN PetscErrorCode EPSSetTrackAll(EPS,PetscBool);
    664: SLEPC_EXTERN PetscErrorCode EPSGetTrackAll(EPS,PetscBool*);

    666: SLEPC_EXTERN PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec[]);
    667: SLEPC_EXTERN PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec[]);
    668: SLEPC_EXTERN PetscErrorCode EPSSetLeftInitialSpace(EPS,PetscInt,Vec[]);

    670: /*S
    671:    EPSMonitorFn - A function prototype for functions provided to `EPSMonitorSet()`.

    673:    Calling Sequence:
    674: +  eps    - the linear eigensolver context
    675: .  its    - iteration number
    676: .  nconv  - number of converged eigenpairs
    677: .  eigr   - real part of the eigenvalues
    678: .  eigi   - imaginary part of the eigenvalues
    679: .  errest - relative error estimates for each eigenpair
    680: .  nest   - number of error estimates
    681: -  ctx    - optional monitoring context, as provided with `EPSMonitorSet()`

    683:    Level: intermediate

    685: .seealso: [](ch:eps), `EPSMonitorSet()`
    686: S*/
    687: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar eigr[],PetscScalar eigi[],PetscReal errest[],PetscInt nest,void *ctx);

    689: /*S
    690:    EPSMonitorRegisterFn - A function prototype for functions provided to `EPSMonitorRegister()`.

    692:    Calling Sequence:
    693: +  eps    - the linear eigensolver context
    694: .  its    - iteration number
    695: .  nconv  - number of converged eigenpairs
    696: .  eigr   - real part of the eigenvalues
    697: .  eigi   - imaginary part of the eigenvalues
    698: .  errest - relative error estimates for each eigenpair
    699: .  nest   - number of error estimates
    700: -  ctx    - `PetscViewerAndFormat` object

    702:    Level: advanced

    704:    Note:
    705:    This is an `EPSMonitorFn` specialized for a context of `PetscViewerAndFormat`.

    707: .seealso: [](ch:eps), `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterCreateFn`, `EPSMonitorRegisterDestroyFn`
    708: S*/
    709: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterFn(EPS eps,PetscInt its,PetscInt nconv,PetscScalar eigr[],PetscScalar eigi[],PetscReal errest[],PetscInt nest,PetscViewerAndFormat *ctx);

    711: /*S
    712:    EPSMonitorRegisterCreateFn - A function prototype for functions that do the
    713:    creation when provided to `EPSMonitorRegister()`.

    715:    Calling Sequence:
    716: +  viewer - the viewer to be used with the `EPSMonitorRegisterFn`
    717: .  format - the format of the viewer
    718: .  ctx    - a context for the monitor
    719: -  result - a `PetscViewerAndFormat` object

    721:    Level: advanced

    723: .seealso: [](ch:eps), `EPSMonitorRegisterFn`, `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterDestroyFn`
    724: S*/
    725: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);

    727: /*S
    728:    EPSMonitorRegisterDestroyFn - A function prototype for functions that do the after
    729:    use destruction when provided to `EPSMonitorRegister()`.

    731:    Calling Sequence:
    732: .  vf - a `PetscViewerAndFormat` object to be destroyed, including any context

    734:    Level: advanced

    736: .seealso: [](ch:eps), `EPSMonitorRegisterFn`, `EPSMonitorSet()`, `EPSMonitorRegister()`, `EPSMonitorFn`, `EPSMonitorRegisterCreateFn`
    737: S*/
    738: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSMonitorRegisterDestroyFn(PetscViewerAndFormat **result);

    740: SLEPC_EXTERN PetscErrorCode EPSMonitor(EPS,PetscInt,PetscInt,PetscScalar[],PetscScalar[],PetscReal[],PetscInt);
    741: SLEPC_EXTERN PetscErrorCode EPSMonitorSet(EPS,EPSMonitorFn,void*,PetscCtxDestroyFn*);
    742: SLEPC_EXTERN PetscErrorCode EPSMonitorCancel(EPS);
    743: SLEPC_EXTERN PetscErrorCode EPSGetMonitorContext(EPS,void*);

    745: SLEPC_EXTERN PetscErrorCode EPSMonitorSetFromOptions(EPS,const char[],const char[],void*,PetscBool);
    746: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorFirst;
    747: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorFirstDrawLG;
    748: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorFirstDrawLGCreate;
    749: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorAll;
    750: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorAllDrawLG;
    751: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorAllDrawLGCreate;
    752: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorConverged;
    753: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorConvergedCreate;
    754: SLEPC_EXTERN EPSMonitorRegisterFn        EPSMonitorConvergedDrawLG;
    755: SLEPC_EXTERN EPSMonitorRegisterCreateFn  EPSMonitorConvergedDrawLGCreate;
    756: SLEPC_EXTERN EPSMonitorRegisterDestroyFn EPSMonitorConvergedDestroy;

    758: SLEPC_EXTERN PetscErrorCode EPSSetOptionsPrefix(EPS,const char[]);
    759: SLEPC_EXTERN PetscErrorCode EPSAppendOptionsPrefix(EPS,const char[]);
    760: SLEPC_EXTERN PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

    762: SLEPC_EXTERN PetscFunctionList EPSList;
    763: SLEPC_EXTERN PetscFunctionList EPSMonitorList;
    764: SLEPC_EXTERN PetscFunctionList EPSMonitorCreateList;
    765: SLEPC_EXTERN PetscFunctionList EPSMonitorDestroyList;
    766: SLEPC_EXTERN PetscErrorCode EPSRegister(const char[],PetscErrorCode(*)(EPS));
    767: SLEPC_EXTERN PetscErrorCode EPSMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,EPSMonitorRegisterFn*,EPSMonitorRegisterCreateFn*,EPSMonitorRegisterDestroyFn*);

    769: SLEPC_EXTERN PetscErrorCode EPSSetWorkVecs(EPS,PetscInt);
    770: SLEPC_EXTERN PetscErrorCode EPSAllocateSolution(EPS,PetscInt);
    771: SLEPC_EXTERN PetscErrorCode EPSReallocateSolution(EPS,PetscInt);

    773: /*S
    774:    EPSConvergenceTestFn - A prototype of an `EPS` convergence test function that
    775:    would be passed to `EPSSetConvergenceTestFunction()`.

    777:    Calling Sequence:
    778: +  eps    - the linear eigensolver context
    779: .  eigr   - real part of the eigenvalue
    780: .  eigi   - imaginary part of the eigenvalue
    781: .  res    - residual norm associated to the eigenpair
    782: .  errest - [output] computed error estimate
    783: -  ctx    - optional convergence context, as set by `EPSSetConvergenceTestFunction()`

    785:    Level: advanced

    787: .seealso: [](ch:eps), `EPSSetConvergenceTest()`, `EPSSetConvergenceTestFunction()`
    788: S*/
    789: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSConvergenceTestFn(EPS eps,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx);

    791: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTest(EPS,EPSConv);
    792: SLEPC_EXTERN PetscErrorCode EPSGetConvergenceTest(EPS,EPSConv*);
    793: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedAbsolute;
    794: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedRelative;
    795: SLEPC_EXTERN EPSConvergenceTestFn EPSConvergedNorm;
    796: SLEPC_EXTERN PetscErrorCode EPSSetConvergenceTestFunction(EPS,EPSConvergenceTestFn*,void*,PetscCtxDestroyFn*);

    798: /*S
    799:    EPSStoppingTestFn - A prototype of an `EPS` stopping test function that would
    800:    be passed to `EPSSetStoppingTestFunction()`.

    802:    Calling Sequence:
    803: +  eps    - the linear eigensolver context
    804: .  its    - current number of iterations
    805: .  max_it - maximum number of iterations
    806: .  nconv  - number of currently converged eigenpairs
    807: .  nev    - number of requested eigenpairs
    808: .  reason - [output] result of the stopping test
    809: -  ctx    - optional stopping context, as set by `EPSSetStoppingTestFunction()`

    811:    Note:
    812:    A positive value of `reason` indicates that the iteration has finished successfully
    813:    (converged), and a negative value indicates an error condition (diverged). If
    814:    the iteration needs to be continued, `reason` must be set to `EPS_CONVERGED_ITERATING`
    815:    (zero).

    817:    Level: advanced

    819: .seealso: [](ch:eps), `EPSSetStoppingTest()`, `EPSSetStoppingTestFunction()`
    820: S*/
    821: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode EPSStoppingTestFn(EPS eps,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,EPSConvergedReason *reason,void *ctx);

    823: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTest(EPS,EPSStop);
    824: SLEPC_EXTERN PetscErrorCode EPSGetStoppingTest(EPS,EPSStop*);
    825: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingBasic;
    826: SLEPC_EXTERN EPSStoppingTestFn EPSStoppingThreshold;
    827: SLEPC_EXTERN PetscErrorCode EPSSetStoppingTestFunction(EPS,EPSStoppingTestFn*,void*,PetscCtxDestroyFn*);

    829: SLEPC_EXTERN PetscErrorCode EPSSetEigenvalueComparison(EPS,SlepcEigenvalueComparisonFn*,void*);
    830: SLEPC_EXTERN PetscErrorCode EPSSetArbitrarySelection(EPS,SlepcArbitrarySelectionFn*,void*);

    832: /* --------- options specific to particular eigensolvers -------- */

    834: /*E
    835:    EPSPowerShiftType - The type of shift used in the Power iteration solver.

    837:    Values:
    838: +  `EPS_POWER_SHIFT_CONSTANT`  - constant shift
    839: .  `EPS_POWER_SHIFT_RAYLEIGH`  - variable shift using Rayleigh quotient
    840: -  `EPS_POWER_SHIFT_WILKINSON` - variable shift using Wilkinson's approach

    842:    Note:
    843:    Details of the three variants can be found in {cite:p}`Her05`.

    845:    Level: advanced

    847: .seealso: [](ch:eps), `EPSPowerSetShiftType()`, `EPSPowerGetShiftType()`
    848: E*/
    849: typedef enum { EPS_POWER_SHIFT_CONSTANT,
    850:                EPS_POWER_SHIFT_RAYLEIGH,
    851:                EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;
    852: SLEPC_EXTERN const char *EPSPowerShiftTypes[];

    854: /*MC
    855:    EPS_POWER_SHIFT_CONSTANT - The power iteration will use a constant shift.

    857:    Note:
    858:    Together with `STSINVERT`, the `EPSPOWER` solver implements the inverse iteration
    859:    method, i.e., it will apply $(A-\sigma I)^{-1}$ at each iteration, by solving
    860:    a linear system. By default, the shift $\sigma$ is constant and given by the
    861:    user with `EPSSetTarget()`.

    863:    Details of the three variants can be found in {cite:p}`Her05`.

    865:    Level: advanced

    867: .seealso: [](ch:eps), `EPSPowerShiftType`, `EPSPowerSetShiftType()`, `STSetShift()`, `EPSSetTarget()`, `EPS_POWER_SHIFT_RAYLEIGH`, `EPS_POWER_SHIFT_WILKINSON`
    868: M*/

    870: /*MC
    871:    EPS_POWER_SHIFT_RAYLEIGH - The power iteration will use a variable shift
    872:    computed with the Rayleigh quotient.

    874:    Notes:
    875:    Together with `STSINVERT`, the `EPSPOWER` solver implements the inverse iteration
    876:    method, i.e., it will apply $(A-\sigma I)^{-1}$ at each iteration, by solving
    877:    a linear system. With this strategy, the value of the shift will be updated at
    878:    each iteration as $\sigma=\frac{x^*Ax}{x^*x}$, where $x$ is the current eigenvector
    879:    approximation. The resulting iteration is the RQI method.

    881:    Updating the shift may involve a high computational cost if the linear solve
    882:    is done via a factorization.

    884:    Details of the three variants can be found in {cite:p}`Her05`.

    886:    Level: advanced

    888: .seealso: [](ch:eps), `EPSPowerShiftType`, `EPSPowerSetShiftType()`, `STSetShift()`, `EPSSetTarget()`, `EPS_POWER_SHIFT_CONSTANT`, `EPS_POWER_SHIFT_WILKINSON`
    889: M*/

    891: /*MC
    892:    EPS_POWER_SHIFT_WILKINSON - The power iteration will use a variable shift
    893:    computed with Wilkinson's approach.

    895:    Note:
    896:    Together with `STSINVERT`, the `EPSPOWER` solver implements the inverse iteration
    897:    method, i.e., it will apply $(A-\sigma I)^{-1}$ at each iteration, by solving
    898:    a linear system. With this strategy, the value of the shift will be updated at
    899:    each iteration as proposed by Wilkinson, see {cite:p}`Par80{8.10}`.

    901:    Updating the shift may involve a high computational cost if the linear solve
    902:    is done via a factorization.

    904:    Details of the three variants can be found in {cite:p}`Her05`.

    906:    Level: advanced

    908: .seealso: [](ch:eps), `EPSPowerShiftType`, `EPSPowerSetShiftType()`, `STSetShift()`, `EPSSetTarget()`, `EPS_POWER_SHIFT_CONSTANT`, `EPS_POWER_SHIFT_RAYLEIGH`
    909: M*/

    911: SLEPC_EXTERN PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);
    912: SLEPC_EXTERN PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);
    913: SLEPC_EXTERN PetscErrorCode EPSPowerSetNonlinear(EPS,PetscBool);
    914: SLEPC_EXTERN PetscErrorCode EPSPowerGetNonlinear(EPS,PetscBool*);
    915: SLEPC_EXTERN PetscErrorCode EPSPowerSetUpdate(EPS,PetscBool);
    916: SLEPC_EXTERN PetscErrorCode EPSPowerGetUpdate(EPS,PetscBool*);
    917: SLEPC_EXTERN PetscErrorCode EPSPowerSetSignNormalization(EPS,PetscBool);
    918: SLEPC_EXTERN PetscErrorCode EPSPowerGetSignNormalization(EPS,PetscBool*);
    919: SLEPC_EXTERN PetscErrorCode EPSPowerSetSNES(EPS,SNES);
    920: SLEPC_EXTERN PetscErrorCode EPSPowerGetSNES(EPS,SNES*);

    922: SLEPC_EXTERN PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscBool);
    923: SLEPC_EXTERN PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscBool*);

    925: /*E
    926:    EPSKrylovSchurBSEType - The method to be used in the Krylov-Schur solver
    927:    for the case of BSE structured eigenproblems.

    929:    Values:
    930: +  `EPS_KRYLOVSCHUR_BSE_SHAO`         - a Lanczos method proposed by Shao and coauthors
    931: .  `EPS_KRYLOVSCHUR_BSE_GRUNING`      - a Lanczos method proposed by Gruning and coauthors
    932: -  `EPS_KRYLOVSCHUR_BSE_PROJECTEDBSE` - a Lanczos method resulting is a projected problem with BSE structure

    934:    Note:
    935:    All variants are implemented in combination with a thick restart, see
    936:    the details in {cite:p}`Alv25`.

    938:    Level: advanced

    940: .seealso: [](ch:eps), `EPSKrylovSchurSetBSEType()`, `EPSKrylovSchurGetBSEType()`
    941: E*/
    942: typedef enum { EPS_KRYLOVSCHUR_BSE_SHAO,
    943:                EPS_KRYLOVSCHUR_BSE_GRUNING,
    944:                EPS_KRYLOVSCHUR_BSE_PROJECTEDBSE } EPSKrylovSchurBSEType;
    945: SLEPC_EXTERN const char *EPSKrylovSchurBSETypes[];

    947: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetBSEType(EPS,EPSKrylovSchurBSEType);
    948: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetBSEType(EPS,EPSKrylovSchurBSEType*);
    949: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetRestart(EPS,PetscReal);
    950: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetRestart(EPS,PetscReal*);
    951: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetLocking(EPS,PetscBool);
    952: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetLocking(EPS,PetscBool*);
    953: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetPartitions(EPS,PetscInt);
    954: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetPartitions(EPS,PetscInt*);
    955: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDetectZeros(EPS,PetscBool);
    956: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDetectZeros(EPS,PetscBool*);
    957: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetDimensions(EPS,PetscInt,PetscInt,PetscInt);
    958: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);
    959: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurSetSubintervals(EPS,PetscReal[]);
    960: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubintervals(EPS,PetscReal*[]);
    961: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetInertias(EPS,PetscInt*,PetscReal*[],PetscInt*[]);
    962: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommInfo(EPS,PetscInt*,PetscInt*,Vec*);
    963: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommPairs(EPS,PetscInt,PetscScalar*,Vec);
    964: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetSubcommMats(EPS,Mat*,Mat*);
    965: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurUpdateSubcommMats(EPS,PetscScalar,PetscScalar,Mat,PetscScalar,PetscScalar, Mat,MatStructure,PetscBool);
    966: SLEPC_EXTERN PetscErrorCode EPSKrylovSchurGetKSP(EPS,KSP*);

    968: /*E
    969:    EPSLanczosReorthogType - The type of reorthogonalization used in `EPSLANCZOS`.

    971:    Values:
    972: +  `EPS_LANCZOS_REORTHOG_LOCAL`     - local orthogonalization, only involves previous two vectors
    973: .  `EPS_LANCZOS_REORTHOG_FULL`      - full orthogonalization against all previous vectors
    974: .  `EPS_LANCZOS_REORTHOG_SELECTIVE` - selective reorthogonalization against nearly converged Ritz vectors
    975: .  `EPS_LANCZOS_REORTHOG_PERIODIC`  - periodic reorthogonalization against all previous vectors
    976: .  `EPS_LANCZOS_REORTHOG_PARTIAL`   - partial reorthogonalization against as subset of previous vectors
    977: -  `EPS_LANCZOS_REORTHOG_DELAYED`   - full orthogonalization with delayed reorthogonalization

    979:    Note:
    980:    Details of the different reorthogonalization strategies can be found in
    981:    {cite:p}`Her06`.

    983:    Level: advanced

    985: .seealso: [](ch:eps), `EPSLanczosSetReorthog()`, `EPSLanczosGetReorthog()`
    986: E*/
    987: typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,
    988:                EPS_LANCZOS_REORTHOG_FULL,
    989:                EPS_LANCZOS_REORTHOG_SELECTIVE,
    990:                EPS_LANCZOS_REORTHOG_PERIODIC,
    991:                EPS_LANCZOS_REORTHOG_PARTIAL,
    992:                EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;
    993: SLEPC_EXTERN const char *EPSLanczosReorthogTypes[];

    995: SLEPC_EXTERN PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);
    996: SLEPC_EXTERN PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

    998: /*E
    999:    EPSPRIMMEMethod - The method selected in the PRIMME library.

    1001:    Note:
    1002:    See the documentation of PRIMME {cite:p}`Sta10` for a description of the methods.

    1004:    Level: advanced

    1006: .seealso: [](ch:eps), `EPSPRIMMESetMethod()`, `EPSPRIMMEGetMethod()`
    1007: E*/
    1008: typedef enum { EPS_PRIMME_DYNAMIC             = 1,
    1009:                EPS_PRIMME_DEFAULT_MIN_TIME    = 2,
    1010:                EPS_PRIMME_DEFAULT_MIN_MATVECS = 3,
    1011:                EPS_PRIMME_ARNOLDI             = 4,
    1012:                EPS_PRIMME_GD                  = 5,
    1013:                EPS_PRIMME_GD_PLUSK            = 6,
    1014:                EPS_PRIMME_GD_OLSEN_PLUSK      = 7,
    1015:                EPS_PRIMME_JD_OLSEN_PLUSK      = 8,
    1016:                EPS_PRIMME_RQI                 = 9,
    1017:                EPS_PRIMME_JDQR                = 10,
    1018:                EPS_PRIMME_JDQMR               = 11,
    1019:                EPS_PRIMME_JDQMR_ETOL          = 12,
    1020:                EPS_PRIMME_SUBSPACE_ITERATION  = 13,
    1021:                EPS_PRIMME_LOBPCG_ORTHOBASIS   = 14,
    1022:                EPS_PRIMME_LOBPCG_ORTHOBASISW  = 15 } EPSPRIMMEMethod;
    1023: SLEPC_EXTERN const char *EPSPRIMMEMethods[];

    1025: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetBlockSize(EPS,PetscInt);
    1026: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetBlockSize(EPS,PetscInt*);
    1027: SLEPC_EXTERN PetscErrorCode EPSPRIMMESetMethod(EPS,EPSPRIMMEMethod);
    1028: SLEPC_EXTERN PetscErrorCode EPSPRIMMEGetMethod(EPS,EPSPRIMMEMethod*);

    1030: SLEPC_EXTERN PetscErrorCode EPSGDSetKrylovStart(EPS,PetscBool);
    1031: SLEPC_EXTERN PetscErrorCode EPSGDGetKrylovStart(EPS,PetscBool*);
    1032: SLEPC_EXTERN PetscErrorCode EPSGDSetBlockSize(EPS,PetscInt);
    1033: SLEPC_EXTERN PetscErrorCode EPSGDGetBlockSize(EPS,PetscInt*);
    1034: SLEPC_EXTERN PetscErrorCode EPSGDSetRestart(EPS,PetscInt,PetscInt);
    1035: SLEPC_EXTERN PetscErrorCode EPSGDGetRestart(EPS,PetscInt*,PetscInt*);
    1036: SLEPC_EXTERN PetscErrorCode EPSGDSetInitialSize(EPS,PetscInt);
    1037: SLEPC_EXTERN PetscErrorCode EPSGDGetInitialSize(EPS,PetscInt*);
    1038: SLEPC_EXTERN PetscErrorCode EPSGDSetBOrth(EPS,PetscBool);
    1039: SLEPC_EXTERN PetscErrorCode EPSGDGetBOrth(EPS,PetscBool*);
    1040: SLEPC_EXTERN PetscErrorCode EPSGDSetDoubleExpansion(EPS,PetscBool);
    1041: SLEPC_EXTERN PetscErrorCode EPSGDGetDoubleExpansion(EPS,PetscBool*);

    1043: SLEPC_EXTERN PetscErrorCode EPSJDSetKrylovStart(EPS,PetscBool);
    1044: SLEPC_EXTERN PetscErrorCode EPSJDGetKrylovStart(EPS,PetscBool*);
    1045: SLEPC_EXTERN PetscErrorCode EPSJDSetBlockSize(EPS,PetscInt);
    1046: SLEPC_EXTERN PetscErrorCode EPSJDGetBlockSize(EPS,PetscInt*);
    1047: SLEPC_EXTERN PetscErrorCode EPSJDSetRestart(EPS,PetscInt,PetscInt);
    1048: SLEPC_EXTERN PetscErrorCode EPSJDGetRestart(EPS,PetscInt*,PetscInt*);
    1049: SLEPC_EXTERN PetscErrorCode EPSJDSetInitialSize(EPS,PetscInt);
    1050: SLEPC_EXTERN PetscErrorCode EPSJDGetInitialSize(EPS,PetscInt*);
    1051: SLEPC_EXTERN PetscErrorCode EPSJDSetFix(EPS,PetscReal);
    1052: SLEPC_EXTERN PetscErrorCode EPSJDGetFix(EPS,PetscReal*);
    1053: SLEPC_EXTERN PetscErrorCode EPSJDSetConstCorrectionTol(EPS,PetscBool);
    1054: SLEPC_EXTERN PetscErrorCode EPSJDGetConstCorrectionTol(EPS,PetscBool*);
    1055: SLEPC_EXTERN PetscErrorCode EPSJDSetBOrth(EPS,PetscBool);
    1056: SLEPC_EXTERN PetscErrorCode EPSJDGetBOrth(EPS,PetscBool*);

    1058: SLEPC_EXTERN PetscErrorCode EPSRQCGSetReset(EPS,PetscInt);
    1059: SLEPC_EXTERN PetscErrorCode EPSRQCGGetReset(EPS,PetscInt*);

    1061: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetBlockSize(EPS,PetscInt);
    1062: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetBlockSize(EPS,PetscInt*);
    1063: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetRestart(EPS,PetscReal);
    1064: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetRestart(EPS,PetscReal*);
    1065: SLEPC_EXTERN PetscErrorCode EPSLOBPCGSetLocking(EPS,PetscBool);
    1066: SLEPC_EXTERN PetscErrorCode EPSLOBPCGGetLocking(EPS,PetscBool*);

    1068: /*E
    1069:    EPSCISSQuadRule - The quadrature rule used in the `EPSCISS` solver.

    1071:    Values:
    1072: +  `EPS_CISS_QUADRULE_TRAPEZOIDAL` - trapezoidal rule
    1073: -  `EPS_CISS_QUADRULE_CHEBYSHEV`   - Gauss quadrature on Chebyshev points

    1075:    Note:
    1076:    For a detailed description see {cite:p}`Mae16`.

    1078:    Level: advanced

    1080: .seealso: [](ch:eps), `EPSCISSSetQuadRule()`, `EPSCISSGetQuadRule()`
    1081: E*/
    1082: typedef enum { EPS_CISS_QUADRULE_TRAPEZOIDAL = 1,
    1083:                EPS_CISS_QUADRULE_CHEBYSHEV   = 2 } EPSCISSQuadRule;
    1084: SLEPC_EXTERN const char *EPSCISSQuadRules[];

    1086: /*E
    1087:    EPSCISSExtraction - The extraction technique used in the `EPSCISS` solver.

    1089:    Values:
    1090: +  `EPS_CISS_EXTRACTION_RITZ`   - Ritz approximations from Rayleigh-Ritz projection
    1091: -  `EPS_CISS_EXTRACTION_HANKEL` - use Hankel pencil as in the original Sakurai-Sugiura method

    1093:    Note:
    1094:    For a detailed description see {cite:p}`Mae16`.

    1096:    Level: advanced

    1098: .seealso: [](ch:eps), `EPSCISSSetExtraction()`, `EPSCISSGetExtraction()`
    1099: E*/
    1100: typedef enum { EPS_CISS_EXTRACTION_RITZ,
    1101:                EPS_CISS_EXTRACTION_HANKEL } EPSCISSExtraction;
    1102: SLEPC_EXTERN const char *EPSCISSExtractions[];

    1104: SLEPC_EXTERN PetscErrorCode EPSCISSSetExtraction(EPS,EPSCISSExtraction);
    1105: SLEPC_EXTERN PetscErrorCode EPSCISSGetExtraction(EPS,EPSCISSExtraction*);
    1106: SLEPC_EXTERN PetscErrorCode EPSCISSSetQuadRule(EPS,EPSCISSQuadRule);
    1107: SLEPC_EXTERN PetscErrorCode EPSCISSGetQuadRule(EPS,EPSCISSQuadRule*);
    1108: SLEPC_EXTERN PetscErrorCode EPSCISSSetSizes(EPS,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscBool);
    1109: SLEPC_EXTERN PetscErrorCode EPSCISSGetSizes(EPS,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscInt*,PetscBool*);
    1110: SLEPC_EXTERN PetscErrorCode EPSCISSSetThreshold(EPS,PetscReal,PetscReal);
    1111: SLEPC_EXTERN PetscErrorCode EPSCISSGetThreshold(EPS,PetscReal*,PetscReal*);
    1112: SLEPC_EXTERN PetscErrorCode EPSCISSSetRefinement(EPS,PetscInt,PetscInt);
    1113: SLEPC_EXTERN PetscErrorCode EPSCISSGetRefinement(EPS,PetscInt*,PetscInt*);
    1114: SLEPC_EXTERN PetscErrorCode EPSCISSSetUseST(EPS,PetscBool);
    1115: SLEPC_EXTERN PetscErrorCode EPSCISSGetUseST(EPS,PetscBool*);
    1116: SLEPC_EXTERN PetscErrorCode EPSCISSGetKSPs(EPS,PetscInt*,KSP*[]);

    1118: SLEPC_EXTERN PetscErrorCode EPSLyapIISetLME(EPS,LME);
    1119: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetLME(EPS,LME*);
    1120: SLEPC_EXTERN PetscErrorCode EPSLyapIISetRanks(EPS,PetscInt,PetscInt);
    1121: SLEPC_EXTERN PetscErrorCode EPSLyapIIGetRanks(EPS,PetscInt*,PetscInt*);

    1123: SLEPC_EXTERN PetscErrorCode EPSBLOPEXSetBlockSize(EPS,PetscInt);
    1124: SLEPC_EXTERN PetscErrorCode EPSBLOPEXGetBlockSize(EPS,PetscInt*);

    1126: /*E
    1127:    EPSEVSLDOSMethod - The method to approximate the density of states (DOS)
    1128:    in the `EPSEVSL` solver.

    1130:    Values:
    1131: +  `EPS_EVSL_DOS_KPM`     - Kernel Polynomial Method
    1132: -  `EPS_EVSL_DOS_LANCZOS` - Lanczos method

    1134:    Note:
    1135:    See the documentation of EVSL {cite:p}`Li19` for an explanation.

    1137:    Level: advanced

    1139: .seealso: [](ch:eps), `EPSEVSLSetDOSParameters()`, `EPSEVSLGetDOSParameters()`
    1140: E*/
    1141: typedef enum { EPS_EVSL_DOS_KPM,
    1142:                EPS_EVSL_DOS_LANCZOS } EPSEVSLDOSMethod;
    1143: SLEPC_EXTERN const char *EPSEVSLDOSMethods[];

    1145: /*E
    1146:    EPSEVSLDamping - The damping type used in the `EPSEVSL` solver.

    1148:    Values:
    1149: +  `EPS_EVSL_DAMPING_NONE`    - no damping
    1150: .  `EPS_EVSL_DAMPING_JACKSON` - Jackson damping
    1151: -  `EPS_EVSL_DAMPING_SIGMA`   - Lanczos damping

    1153:    Note:
    1154:    See the documentation of EVSL {cite:p}`Li19` for an explanation.

    1156:    Level: advanced

    1158: .seealso: [](ch:eps), `EPSEVSLSetDOSParameters()`, `EPSEVSLGetDOSParameters()`
    1159: E*/
    1160: typedef enum { EPS_EVSL_DAMPING_NONE,
    1161:                EPS_EVSL_DAMPING_JACKSON,
    1162:                EPS_EVSL_DAMPING_SIGMA } EPSEVSLDamping;
    1163: SLEPC_EXTERN const char *EPSEVSLDampings[];

    1165: SLEPC_EXTERN PetscErrorCode EPSEVSLSetRange(EPS,PetscReal,PetscReal);
    1166: SLEPC_EXTERN PetscErrorCode EPSEVSLGetRange(EPS,PetscReal*,PetscReal*);
    1167: SLEPC_EXTERN PetscErrorCode EPSEVSLSetSlices(EPS,PetscInt);
    1168: SLEPC_EXTERN PetscErrorCode EPSEVSLGetSlices(EPS,PetscInt*);
    1169: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDOSParameters(EPS,EPSEVSLDOSMethod,PetscInt,PetscInt,PetscInt,PetscInt);
    1170: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDOSParameters(EPS,EPSEVSLDOSMethod*,PetscInt*,PetscInt*,PetscInt*,PetscInt*);
    1171: SLEPC_EXTERN PetscErrorCode EPSEVSLSetPolParameters(EPS,PetscInt,PetscReal);
    1172: SLEPC_EXTERN PetscErrorCode EPSEVSLGetPolParameters(EPS,PetscInt*,PetscReal*);
    1173: SLEPC_EXTERN PetscErrorCode EPSEVSLSetDamping(EPS,EPSEVSLDamping);
    1174: SLEPC_EXTERN PetscErrorCode EPSEVSLGetDamping(EPS,EPSEVSLDamping*);

    1176: SLEPC_EXTERN PetscErrorCode EPSFEASTSetNumPoints(EPS,PetscInt);
    1177: SLEPC_EXTERN PetscErrorCode EPSFEASTGetNumPoints(EPS,PetscInt*);

    1179: SLEPC_EXTERN PetscErrorCode EPSCHASESetDegree(EPS,PetscInt,PetscBool);
    1180: SLEPC_EXTERN PetscErrorCode EPSCHASEGetDegree(EPS,PetscInt*,PetscBool*);