Actual source code: nepopts.c

      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:    NEP routines related to options that can be set via the command-line
     12:    or procedurally
     13: */

     15: #include <slepc/private/nepimpl.h>
     16: #include <petscdraw.h>

     18: /*@C
     19:    NEPMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
     20:    indicated by the user.

     22:    Collective

     24:    Input Parameters:
     25: +  nep      - the nonlinear eigensolver context
     26: .  opt      - the command line option for this monitor
     27: .  name     - the monitor type one is seeking
     28: .  ctx      - an optional user context for the monitor, or `NULL`
     29: -  trackall - whether this monitor tracks all eigenvalues or not

     31:    Level: developer

     33: .seealso: [](ch:nep), `NEPMonitorSet()`, `NEPSetTrackAll()`
     34: @*/
     35: PetscErrorCode NEPMonitorSetFromOptions(NEP nep,const char opt[],const char name[],void *ctx,PetscBool trackall)
     36: {
     37:   PetscErrorCode       (*mfunc)(NEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
     38:   PetscErrorCode       (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
     39:   PetscErrorCode       (*dfunc)(PetscViewerAndFormat**);
     40:   PetscViewerAndFormat *vf;
     41:   PetscViewer          viewer;
     42:   PetscViewerFormat    format;
     43:   PetscViewerType      vtype;
     44:   char                 key[PETSC_MAX_PATH_LEN];
     45:   PetscBool            flg;

     47:   PetscFunctionBegin;
     48:   PetscCall(PetscOptionsCreateViewer(PetscObjectComm((PetscObject)nep),((PetscObject)nep)->options,((PetscObject)nep)->prefix,opt,&viewer,&format,&flg));
     49:   if (!flg) PetscFunctionReturn(PETSC_SUCCESS);

     51:   PetscCall(PetscViewerGetType(viewer,&vtype));
     52:   PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
     53:   PetscCall(PetscFunctionListFind(NEPMonitorList,key,&mfunc));
     54:   PetscCheck(mfunc,PetscObjectComm((PetscObject)nep),PETSC_ERR_SUP,"Specified viewer and format not supported");
     55:   PetscCall(PetscFunctionListFind(NEPMonitorCreateList,key,&cfunc));
     56:   PetscCall(PetscFunctionListFind(NEPMonitorDestroyList,key,&dfunc));
     57:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
     58:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

     60:   PetscCall((*cfunc)(viewer,format,ctx,&vf));
     61:   PetscCall(PetscViewerDestroy(&viewer));
     62:   PetscCall(NEPMonitorSet(nep,mfunc,vf,(PetscCtxDestroyFn*)dfunc));
     63:   if (trackall) PetscCall(NEPSetTrackAll(nep,PETSC_TRUE));
     64:   PetscFunctionReturn(PETSC_SUCCESS);
     65: }

     67: /*@
     68:    NEPSetFromOptions - Sets `NEP` options from the options database.
     69:    This routine must be called before `NEPSetUp()` if the user is to be
     70:    allowed to configure the solver.

     72:    Collective

     74:    Input Parameter:
     75: .  nep - the nonlinear eigensolver context

     77:    Note:
     78:    To see all options, run your program with the `-help` option.

     80:    Level: beginner

     82: .seealso: [](ch:nep), `NEPSetOptionsPrefix()`
     83: @*/
     84: PetscErrorCode NEPSetFromOptions(NEP nep)
     85: {
     86:   char            type[256];
     87:   PetscBool       set,flg,flg1,flg2,flg3,flg4,flg5,bval;
     88:   PetscReal       r;
     89:   PetscScalar     s;
     90:   PetscInt        i,j,k;
     91:   NEPRefine       refine;
     92:   NEPRefineScheme scheme;

     94:   PetscFunctionBegin;
     96:   PetscCall(NEPRegisterAll());
     97:   PetscObjectOptionsBegin((PetscObject)nep);
     98:     PetscCall(PetscOptionsFList("-nep_type","Nonlinear eigensolver method","NEPSetType",NEPList,(char*)(((PetscObject)nep)->type_name?((PetscObject)nep)->type_name:NEPRII),type,sizeof(type),&flg));
     99:     if (flg) PetscCall(NEPSetType(nep,type));
    100:     else if (!((PetscObject)nep)->type_name) PetscCall(NEPSetType(nep,NEPRII));

    102:     PetscCall(PetscOptionsBoolGroupBegin("-nep_general","General nonlinear eigenvalue problem","NEPSetProblemType",&flg));
    103:     if (flg) PetscCall(NEPSetProblemType(nep,NEP_GENERAL));
    104:     PetscCall(PetscOptionsBoolGroupEnd("-nep_rational","Rational eigenvalue problem","NEPSetProblemType",&flg));
    105:     if (flg) PetscCall(NEPSetProblemType(nep,NEP_RATIONAL));

    107:     refine = nep->refine;
    108:     PetscCall(PetscOptionsEnum("-nep_refine","Iterative refinement method","NEPSetRefine",NEPRefineTypes,(PetscEnum)refine,(PetscEnum*)&refine,&flg1));
    109:     i = nep->npart;
    110:     PetscCall(PetscOptionsInt("-nep_refine_partitions","Number of partitions of the communicator for iterative refinement","NEPSetRefine",nep->npart,&i,&flg2));
    111:     r = nep->rtol;
    112:     PetscCall(PetscOptionsReal("-nep_refine_tol","Tolerance for iterative refinement","NEPSetRefine",nep->rtol==(PetscReal)PETSC_DETERMINE?SLEPC_DEFAULT_TOL/1000:nep->rtol,&r,&flg3));
    113:     j = nep->rits;
    114:     PetscCall(PetscOptionsInt("-nep_refine_its","Maximum number of iterations for iterative refinement","NEPSetRefine",nep->rits,&j,&flg4));
    115:     scheme = nep->scheme;
    116:     PetscCall(PetscOptionsEnum("-nep_refine_scheme","Scheme used for linear systems within iterative refinement","NEPSetRefine",NEPRefineSchemes,(PetscEnum)scheme,(PetscEnum*)&scheme,&flg5));
    117:     if (flg1 || flg2 || flg3 || flg4 || flg5) PetscCall(NEPSetRefine(nep,refine,i,r,j,scheme));

    119:     i = nep->max_it;
    120:     PetscCall(PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,&flg1));
    121:     r = nep->tol;
    122:     PetscCall(PetscOptionsReal("-nep_tol","Tolerance","NEPSetTolerances",SlepcDefaultTol(nep->tol),&r,&flg2));
    123:     if (flg1 || flg2) PetscCall(NEPSetTolerances(nep,r,i));

    125:     PetscCall(PetscOptionsBoolGroupBegin("-nep_conv_rel","Relative error convergence test","NEPSetConvergenceTest",&flg));
    126:     if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_REL));
    127:     PetscCall(PetscOptionsBoolGroup("-nep_conv_norm","Convergence test relative to the matrix norms","NEPSetConvergenceTest",&flg));
    128:     if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_NORM));
    129:     PetscCall(PetscOptionsBoolGroup("-nep_conv_abs","Absolute error convergence test","NEPSetConvergenceTest",&flg));
    130:     if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_ABS));
    131:     PetscCall(PetscOptionsBoolGroupEnd("-nep_conv_user","User-defined convergence test","NEPSetConvergenceTest",&flg));
    132:     if (flg) PetscCall(NEPSetConvergenceTest(nep,NEP_CONV_USER));

    134:     PetscCall(PetscOptionsBoolGroupBegin("-nep_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","NEPSetStoppingTest",&flg));
    135:     if (flg) PetscCall(NEPSetStoppingTest(nep,NEP_STOP_BASIC));
    136:     PetscCall(PetscOptionsBoolGroupEnd("-nep_stop_user","User-defined stopping test","NEPSetStoppingTest",&flg));
    137:     if (flg) PetscCall(NEPSetStoppingTest(nep,NEP_STOP_USER));

    139:     i = nep->nev;
    140:     PetscCall(PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,&flg1));
    141:     j = nep->ncv;
    142:     PetscCall(PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,&flg2));
    143:     k = nep->mpd;
    144:     PetscCall(PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,&flg3));
    145:     if (flg1 || flg2 || flg3) PetscCall(NEPSetDimensions(nep,i,j,k));

    147:     PetscCall(PetscOptionsBoolGroupBegin("-nep_largest_magnitude","Compute largest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg));
    148:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_LARGEST_MAGNITUDE));
    149:     PetscCall(PetscOptionsBoolGroup("-nep_smallest_magnitude","Compute smallest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg));
    150:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_SMALLEST_MAGNITUDE));
    151:     PetscCall(PetscOptionsBoolGroup("-nep_largest_real","Compute eigenvalues with largest real parts","NEPSetWhichEigenpairs",&flg));
    152:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_LARGEST_REAL));
    153:     PetscCall(PetscOptionsBoolGroup("-nep_smallest_real","Compute eigenvalues with smallest real parts","NEPSetWhichEigenpairs",&flg));
    154:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_SMALLEST_REAL));
    155:     PetscCall(PetscOptionsBoolGroup("-nep_largest_imaginary","Compute eigenvalues with largest imaginary parts","NEPSetWhichEigenpairs",&flg));
    156:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_LARGEST_IMAGINARY));
    157:     PetscCall(PetscOptionsBoolGroup("-nep_smallest_imaginary","Compute eigenvalues with smallest imaginary parts","NEPSetWhichEigenpairs",&flg));
    158:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_SMALLEST_IMAGINARY));
    159:     PetscCall(PetscOptionsBoolGroup("-nep_target_magnitude","Compute eigenvalues closest to target","NEPSetWhichEigenpairs",&flg));
    160:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE));
    161:     PetscCall(PetscOptionsBoolGroup("-nep_target_real","Compute eigenvalues with real parts closest to target","NEPSetWhichEigenpairs",&flg));
    162:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_REAL));
    163:     PetscCall(PetscOptionsBoolGroup("-nep_target_imaginary","Compute eigenvalues with imaginary parts closest to target","NEPSetWhichEigenpairs",&flg));
    164:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_IMAGINARY));
    165:     PetscCall(PetscOptionsBoolGroupEnd("-nep_all","Compute all eigenvalues in a region","NEPSetWhichEigenpairs",&flg));
    166:     if (flg) PetscCall(NEPSetWhichEigenpairs(nep,NEP_ALL));

    168:     PetscCall(PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg));
    169:     if (flg) {
    170:       if (nep->which!=NEP_TARGET_REAL && nep->which!=NEP_TARGET_IMAGINARY) PetscCall(NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE));
    171:       PetscCall(NEPSetTarget(nep,s));
    172:     }

    174:     PetscCall(PetscOptionsBool("-nep_two_sided","Use two-sided variant (to compute left eigenvectors)","NEPSetTwoSided",nep->twosided,&bval,&flg));
    175:     if (flg) PetscCall(NEPSetTwoSided(nep,bval));

    177:     /* -----------------------------------------------------------------------*/
    178:     /*
    179:       Cancels all monitors hardwired into code before call to NEPSetFromOptions()
    180:     */
    181:     PetscCall(PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",PETSC_FALSE,&flg,&set));
    182:     if (set && flg) PetscCall(NEPMonitorCancel(nep));
    183:     PetscCall(NEPMonitorSetFromOptions(nep,"-nep_monitor","first_approximation",NULL,PETSC_FALSE));
    184:     PetscCall(NEPMonitorSetFromOptions(nep,"-nep_monitor_all","all_approximations",NULL,PETSC_TRUE));
    185:     PetscCall(NEPMonitorSetFromOptions(nep,"-nep_monitor_conv","convergence_history",NULL,PETSC_FALSE));

    187:     /* -----------------------------------------------------------------------*/
    188:     PetscCall(PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",&set));
    189:     PetscCall(PetscOptionsName("-nep_view_vectors","View computed eigenvectors","NEPVectorsView",&set));
    190:     PetscCall(PetscOptionsName("-nep_view_values","View computed eigenvalues","NEPValuesView",&set));
    191:     PetscCall(PetscOptionsName("-nep_converged_reason","Print reason for convergence, and number of iterations","NEPConvergedReasonView",&set));
    192:     PetscCall(PetscOptionsName("-nep_error_absolute","Print absolute errors of each eigenpair","NEPErrorView",&set));
    193:     PetscCall(PetscOptionsName("-nep_error_relative","Print relative errors of each eigenpair","NEPErrorView",&set));

    195:     PetscTryTypeMethod(nep,setfromoptions,PetscOptionsObject);
    196:     PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)nep,PetscOptionsObject));
    197:   PetscOptionsEnd();

    199:   if (!nep->V) PetscCall(NEPGetBV(nep,&nep->V));
    200:   PetscCall(BVSetFromOptions(nep->V));
    201:   if (!nep->rg) PetscCall(NEPGetRG(nep,&nep->rg));
    202:   PetscCall(RGSetFromOptions(nep->rg));
    203:   if (nep->useds) {
    204:     if (!nep->ds) PetscCall(NEPGetDS(nep,&nep->ds));
    205:     PetscCall(NEPSetDSType(nep));
    206:     PetscCall(DSSetFromOptions(nep->ds));
    207:   }
    208:   if (!nep->refineksp) PetscCall(NEPRefineGetKSP(nep,&nep->refineksp));
    209:   PetscCall(KSPSetFromOptions(nep->refineksp));
    210:   if (nep->fui==NEP_USER_INTERFACE_SPLIT) for (i=0;i<nep->nt;i++) PetscCall(FNSetFromOptions(nep->f[i]));
    211:   PetscFunctionReturn(PETSC_SUCCESS);
    212: }

    214: /*@
    215:    NEPGetTolerances - Gets the tolerance and maximum iteration count used
    216:    by the `NEP` convergence tests.

    218:    Not Collective

    220:    Input Parameter:
    221: .  nep - the nonlinear eigensolver context

    223:    Output Parameters:
    224: +  tol - the convergence tolerance
    225: -  maxits - maximum number of iterations

    227:    Notes:
    228:    The user can specify `NULL` for any parameter that is not needed.

    230:    Level: intermediate

    232: .seealso: [](ch:nep), `NEPSetTolerances()`
    233: @*/
    234: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *tol,PetscInt *maxits)
    235: {
    236:   PetscFunctionBegin;
    238:   if (tol)    *tol    = nep->tol;
    239:   if (maxits) *maxits = nep->max_it;
    240:   PetscFunctionReturn(PETSC_SUCCESS);
    241: }

    243: /*@
    244:    NEPSetTolerances - Sets the tolerance and maximum iteration count used
    245:    by the `NEP` convergence tests.

    247:    Logically Collective

    249:    Input Parameters:
    250: +  nep    - the nonlinear eigensolver context
    251: .  tol    - the convergence tolerance
    252: -  maxits - maximum number of iterations to use

    254:    Options Database Keys:
    255: +  -nep_tol \<tol\>       - sets the convergence tolerance
    256: -  -nep_max_it \<maxits\> - sets the maximum number of iterations allowed

    258:    Note:
    259:    Use `PETSC_CURRENT` to retain the current value of any of the parameters.
    260:    Use `PETSC_DETERMINE` for either argument to assign a default value computed
    261:    internally (may be different in each solver).
    262:    For `maxits` use `PETSC_UNLIMITED` to indicate there is no upper bound on this value.

    264:    Level: intermediate

    266: .seealso: [](ch:nep), `NEPGetTolerances()`
    267: @*/
    268: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal tol,PetscInt maxits)
    269: {
    270:   PetscFunctionBegin;
    274:   if (tol == (PetscReal)PETSC_DETERMINE) {
    275:     nep->tol   = PETSC_DETERMINE;
    276:     nep->state = NEP_STATE_INITIAL;
    277:   } else if (tol != (PetscReal)PETSC_CURRENT) {
    278:     PetscCheck(tol>0.0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    279:     nep->tol = tol;
    280:   }
    281:   if (maxits == PETSC_DETERMINE) {
    282:     nep->max_it = PETSC_DETERMINE;
    283:     nep->state  = NEP_STATE_INITIAL;
    284:   } else if (maxits == PETSC_UNLIMITED) {
    285:     nep->max_it = PETSC_INT_MAX;
    286:   } else if (maxits != PETSC_CURRENT) {
    287:     PetscCheck(maxits>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
    288:     nep->max_it = maxits;
    289:   }
    290:   PetscFunctionReturn(PETSC_SUCCESS);
    291: }

    293: /*@
    294:    NEPGetDimensions - Gets the number of eigenvalues to compute
    295:    and the dimension of the subspace.

    297:    Not Collective

    299:    Input Parameter:
    300: .  nep - the nonlinear eigensolver context

    302:    Output Parameters:
    303: +  nev - number of eigenvalues to compute
    304: .  ncv - the maximum dimension of the subspace to be used by the solver
    305: -  mpd - the maximum dimension allowed for the projected problem

    307:    Note:
    308:    The user can specify `NULL` for any parameter that is not needed.

    310:    Level: intermediate

    312: .seealso: [](ch:nep), `NEPSetDimensions()`
    313: @*/
    314: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
    315: {
    316:   PetscFunctionBegin;
    318:   if (nev) *nev = nep->nev;
    319:   if (ncv) *ncv = nep->ncv;
    320:   if (mpd) *mpd = nep->mpd;
    321:   PetscFunctionReturn(PETSC_SUCCESS);
    322: }

    324: /*@
    325:    NEPSetDimensions - Sets the number of eigenvalues to compute
    326:    and the dimension of the subspace.

    328:    Logically Collective

    330:    Input Parameters:
    331: +  nep - the nonlinear eigensolver context
    332: .  nev - number of eigenvalues to compute
    333: .  ncv - the maximum dimension of the subspace to be used by the solver
    334: -  mpd - the maximum dimension allowed for the projected problem

    336:    Options Database Keys:
    337: +  -nep_nev \<nev\> - sets the number of eigenvalues
    338: .  -nep_ncv \<ncv\> - sets the dimension of the subspace
    339: -  -nep_mpd \<mpd\> - sets the maximum projected dimension

    341:    Notes:
    342:    Use `PETSC_DETERMINE` for `ncv` and `mpd` to assign a reasonably good value, which is
    343:    dependent on the solution method. For any of the arguments, use `PETSC_CURRENT`
    344:    to preserve the current value.

    346:    The parameters `ncv` and `mpd` are intimately related, so that the user is advised
    347:    to set one of them at most. Normal usage is\:

    349:     1. in cases where `nev` is small, the user sets `ncv` (a reasonable default is `2*nev`).
    350:     2. in cases where `nev` is large, the user sets `mpd`.

    352:    The value of `ncv` should always be between `nev` and `(nev+mpd)`, typically
    353:    `ncv=nev+mpd`. If `nev` is not too large, `mpd=nev` is a reasonable choice, otherwise
    354:    a smaller value should be used.

    356:    Level: intermediate

    358: .seealso: [](ch:nep), `NEPGetDimensions()`
    359: @*/
    360: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)
    361: {
    362:   PetscFunctionBegin;
    367:   if (nev != PETSC_CURRENT) {
    368:     PetscCheck(nev>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
    369:     nep->nev = nev;
    370:   }
    371:   if (ncv == PETSC_DETERMINE) {
    372:     nep->ncv = PETSC_DETERMINE;
    373:   } else if (ncv != PETSC_CURRENT) {
    374:     PetscCheck(ncv>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    375:     nep->ncv = ncv;
    376:   }
    377:   if (mpd == PETSC_DETERMINE) {
    378:     nep->mpd = PETSC_DETERMINE;
    379:   } else if (mpd != PETSC_CURRENT) {
    380:     PetscCheck(mpd>0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
    381:     nep->mpd = mpd;
    382:   }
    383:   nep->state = NEP_STATE_INITIAL;
    384:   PetscFunctionReturn(PETSC_SUCCESS);
    385: }

    387: /*@
    388:    NEPSetWhichEigenpairs - Specifies which portion of the spectrum is
    389:    to be sought.

    391:    Logically Collective

    393:    Input Parameters:
    394: +  nep   - the nonlinear eigensolver context
    395: -  which - the portion of the spectrum to be sought, see `NEPWhich` for possible values

    397:    Options Database Keys:
    398: +  -nep_largest_magnitude  - sets largest eigenvalues in magnitude
    399: .  -nep_smallest_magnitude - sets smallest eigenvalues in magnitude
    400: .  -nep_largest_real       - sets largest real parts
    401: .  -nep_smallest_real      - sets smallest real parts
    402: .  -nep_largest_imaginary  - sets largest imaginary parts
    403: .  -nep_smallest_imaginary - sets smallest imaginary parts
    404: .  -nep_target_magnitude   - sets eigenvalues closest to target
    405: .  -nep_target_real        - sets real parts closest to target
    406: .  -nep_target_imaginary   - sets imaginary parts closest to target
    407: -  -nep_all                - sets all eigenvalues in a region

    409:    Notes:
    410:    Not all eigensolvers implemented in `NEP` account for all the possible values
    411:    of `which`. Also, some values make sense only for certain types of
    412:    problems. If SLEPc is compiled for real numbers `NEP_LARGEST_IMAGINARY`
    413:    and `NEP_SMALLEST_IMAGINARY` use the absolute value of the imaginary part
    414:    for eigenvalue selection.

    416:    The target is a scalar value provided with `NEPSetTarget()`.

    418:    The criterion `NEP_TARGET_IMAGINARY` is available only in case PETSc and
    419:    SLEPc have been built with complex scalars.

    421:    `NEP_ALL` is intended for use in the context of the `NEPCISS` solver for
    422:    computing all eigenvalues in a region.

    424:    Level: intermediate

    426: .seealso: [](ch:nep), `NEPGetWhichEigenpairs()`, `NEPSetTarget()`, `NEPSetDimensions()`, `NEPSetEigenvalueComparison()`, `NEPWhich`
    427: @*/
    428: PetscErrorCode NEPSetWhichEigenpairs(NEP nep,NEPWhich which)
    429: {
    430:   PetscFunctionBegin;
    433:   switch (which) {
    434:     case NEP_LARGEST_MAGNITUDE:
    435:     case NEP_SMALLEST_MAGNITUDE:
    436:     case NEP_LARGEST_REAL:
    437:     case NEP_SMALLEST_REAL:
    438:     case NEP_LARGEST_IMAGINARY:
    439:     case NEP_SMALLEST_IMAGINARY:
    440:     case NEP_TARGET_MAGNITUDE:
    441:     case NEP_TARGET_REAL:
    442: #if defined(PETSC_USE_COMPLEX)
    443:     case NEP_TARGET_IMAGINARY:
    444: #endif
    445:     case NEP_ALL:
    446:     case NEP_WHICH_USER:
    447:       if (nep->which != which) {
    448:         nep->state = NEP_STATE_INITIAL;
    449:         nep->which = which;
    450:       }
    451:       break;
    452: #if !defined(PETSC_USE_COMPLEX)
    453:     case NEP_TARGET_IMAGINARY:
    454:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_SUP,"NEP_TARGET_IMAGINARY can be used only with complex scalars");
    455: #endif
    456:     default:
    457:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
    458:   }
    459:   PetscFunctionReturn(PETSC_SUCCESS);
    460: }

    462: /*@
    463:     NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
    464:     sought.

    466:     Not Collective

    468:     Input Parameter:
    469: .   nep - the nonlinear eigensolver context

    471:     Output Parameter:
    472: .   which - the portion of the spectrum to be sought

    474:     Level: intermediate

    476: .seealso: [](ch:nep), `NEPSetWhichEigenpairs()`, `NEPWhich`
    477: @*/
    478: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)
    479: {
    480:   PetscFunctionBegin;
    482:   PetscAssertPointer(which,2);
    483:   *which = nep->which;
    484:   PetscFunctionReturn(PETSC_SUCCESS);
    485: }

    487: /*@C
    488:    NEPSetEigenvalueComparison - Specifies the eigenvalue comparison function
    489:    when `NEPSetWhichEigenpairs()` is set to `NEP_WHICH_USER`.

    491:    Logically Collective

    493:    Input Parameters:
    494: +  nep  - the nonlinear eigensolver context
    495: .  comp - a pointer to the comparison function, see `SlepcEigenvalueComparisonFn` for the calling sequence
    496: -  ctx  - a context pointer (the last parameter to the comparison function)

    498:    Level: advanced

    500: .seealso: [](ch:nep), `NEPSetWhichEigenpairs()`, `NEPWhich`
    501: @*/
    502: PetscErrorCode NEPSetEigenvalueComparison(NEP nep,SlepcEigenvalueComparisonFn *comp,void *ctx)
    503: {
    504:   PetscFunctionBegin;
    506:   nep->sc->comparison    = comp;
    507:   nep->sc->comparisonctx = ctx;
    508:   nep->which             = NEP_WHICH_USER;
    509:   PetscFunctionReturn(PETSC_SUCCESS);
    510: }

    512: /*@
    513:    NEPSetProblemType - Specifies the type of the nonlinear eigenvalue problem.

    515:    Logically Collective

    517:    Input Parameters:
    518: +  nep  - the nonlinear eigensolver context
    519: -  type - a known type of nonlinear eigenvalue problem

    521:    Options Database Keys:
    522: +  -nep_general  - general problem with no particular structure
    523: -  -nep_rational - a rational eigenvalue problem defined in split form with all $f_i$ rational

    525:    Notes:
    526:    See `NEPProblemType` for possible problem types.

    528:    This function is used to provide a hint to the `NEP` solver to exploit certain
    529:    properties of the nonlinear eigenproblem. This hint may be used or not,
    530:    depending on the solver. By default, no particular structure is assumed.

    532:    Level: intermediate

    534: .seealso: [](ch:nep), `NEPSetType()`, `NEPGetProblemType()`, `NEPProblemType`
    535: @*/
    536: PetscErrorCode NEPSetProblemType(NEP nep,NEPProblemType type)
    537: {
    538:   PetscFunctionBegin;
    541:   PetscCheck(type==NEP_GENERAL || type==NEP_RATIONAL,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
    542:   if (type != nep->problem_type) {
    543:     nep->problem_type = type;
    544:     nep->state = NEP_STATE_INITIAL;
    545:   }
    546:   PetscFunctionReturn(PETSC_SUCCESS);
    547: }

    549: /*@
    550:    NEPGetProblemType - Gets the problem type from the `NEP` object.

    552:    Not Collective

    554:    Input Parameter:
    555: .  nep - the nonlinear eigensolver context

    557:    Output Parameter:
    558: .  type - the problem type

    560:    Level: intermediate

    562: .seealso: [](ch:nep), `NEPSetProblemType()`, `NEPProblemType`
    563: @*/
    564: PetscErrorCode NEPGetProblemType(NEP nep,NEPProblemType *type)
    565: {
    566:   PetscFunctionBegin;
    568:   PetscAssertPointer(type,2);
    569:   *type = nep->problem_type;
    570:   PetscFunctionReturn(PETSC_SUCCESS);
    571: }

    573: /*@
    574:    NEPSetTwoSided - Sets the solver to use a two-sided variant so that left
    575:    eigenvectors are also computed.

    577:    Logically Collective

    579:    Input Parameters:
    580: +  nep      - the nonlinear eigensolver context
    581: -  twosided - whether the two-sided variant is to be used or not

    583:    Options Database Key:
    584: .  -nep_two_sided - toggles the twosided flag

    586:    Notes:
    587:    If the user sets `twosided`=`PETSC_TRUE` then the solver uses a variant of
    588:    the algorithm that computes both right and left eigenvectors. This is
    589:    usually much more costly. This option is not available in all solvers,
    590:    see table [](#tab:solversn).

    592:    When using two-sided solvers, the problem matrices must have both the
    593:    `MATOP_MULT` and `MATOP_MULT_TRANSPOSE` operations defined.

    595:    Level: advanced

    597: .seealso: [](ch:nep), `NEPGetTwoSided()`, `NEPGetLeftEigenvector()`
    598: @*/
    599: PetscErrorCode NEPSetTwoSided(NEP nep,PetscBool twosided)
    600: {
    601:   PetscFunctionBegin;
    604:   if (twosided!=nep->twosided) {
    605:     nep->twosided = twosided;
    606:     nep->state    = NEP_STATE_INITIAL;
    607:   }
    608:   PetscFunctionReturn(PETSC_SUCCESS);
    609: }

    611: /*@
    612:    NEPGetTwoSided - Returns the flag indicating whether a two-sided variant
    613:    of the algorithm is being used or not.

    615:    Not Collective

    617:    Input Parameter:
    618: .  nep - the nonlinear eigensolver context

    620:    Output Parameter:
    621: .  twosided - the returned flag

    623:    Level: advanced

    625: .seealso: [](ch:nep), `NEPSetTwoSided()`
    626: @*/
    627: PetscErrorCode NEPGetTwoSided(NEP nep,PetscBool *twosided)
    628: {
    629:   PetscFunctionBegin;
    631:   PetscAssertPointer(twosided,2);
    632:   *twosided = nep->twosided;
    633:   PetscFunctionReturn(PETSC_SUCCESS);
    634: }

    636: /*@C
    637:    NEPSetConvergenceTestFunction - Sets a function to compute the error estimate
    638:    used in the convergence test.

    640:    Logically Collective

    642:    Input Parameters:
    643: +  nep     - the nonlinear eigensolver context
    644: .  conv    - convergence test function, see `NEPConvergenceTestFn` for the calling sequence
    645: .  ctx     - context for private data for the convergence routine (may be `NULL`)
    646: -  destroy - a routine for destroying the context (may be `NULL`), see `PetscCtxDestroyFn`
    647:              for the calling sequence

    649:    Notes:
    650:    When this is called with a user-defined function, then the convergence
    651:    criterion is set to `NEP_CONV_USER`, see `NEPSetConvergenceTest()`.

    653:    If the error estimate returned by the convergence test function is less than
    654:    the tolerance, then the eigenvalue is accepted as converged.

    656:    Level: advanced

    658: .seealso: [](ch:nep), `NEPSetConvergenceTest()`, `NEPSetTolerances()`
    659: @*/
    660: PetscErrorCode NEPSetConvergenceTestFunction(NEP nep,NEPConvergenceTestFn *conv,void *ctx,PetscCtxDestroyFn *destroy)
    661: {
    662:   PetscFunctionBegin;
    664:   if (nep->convergeddestroy) PetscCall((*nep->convergeddestroy)(&nep->convergedctx));
    665:   nep->convergeduser    = conv;
    666:   nep->convergeddestroy = destroy;
    667:   nep->convergedctx     = ctx;
    668:   if (conv == NEPConvergedRelative) nep->conv = NEP_CONV_REL;
    669:   else if (conv == NEPConvergedNorm) nep->conv = NEP_CONV_NORM;
    670:   else if (conv == NEPConvergedAbsolute) nep->conv = NEP_CONV_ABS;
    671:   else {
    672:     nep->conv      = NEP_CONV_USER;
    673:     nep->converged = nep->convergeduser;
    674:   }
    675:   PetscFunctionReturn(PETSC_SUCCESS);
    676: }

    678: /*@
    679:    NEPSetConvergenceTest - Specifies how to compute the error estimate
    680:    used in the convergence test.

    682:    Logically Collective

    684:    Input Parameters:
    685: +  nep  - the nonlinear eigensolver context
    686: -  conv - the type of convergence test, see `NEPConv` for possible values

    688:    Options Database Keys:
    689: +  -nep_conv_abs  - sets the absolute convergence test
    690: .  -nep_conv_rel  - sets the convergence test relative to the eigenvalue
    691: .  -nep_conv_norm - sets the convergence test relative to the matrix norms
    692: -  -nep_conv_user - selects the user-defined convergence test

    694:    Level: intermediate

    696: .seealso: [](ch:nep), `NEPGetConvergenceTest()`, `NEPSetConvergenceTestFunction()`, `NEPSetStoppingTest()`, `NEPConv`
    697: @*/
    698: PetscErrorCode NEPSetConvergenceTest(NEP nep,NEPConv conv)
    699: {
    700:   PetscFunctionBegin;
    703:   switch (conv) {
    704:     case NEP_CONV_ABS:  nep->converged = NEPConvergedAbsolute; break;
    705:     case NEP_CONV_REL:  nep->converged = NEPConvergedRelative; break;
    706:     case NEP_CONV_NORM: nep->converged = NEPConvergedNorm; break;
    707:     case NEP_CONV_USER:
    708:       PetscCheck(nep->convergeduser,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetConvergenceTestFunction() first");
    709:       nep->converged = nep->convergeduser;
    710:       break;
    711:     default:
    712:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
    713:   }
    714:   nep->conv = conv;
    715:   PetscFunctionReturn(PETSC_SUCCESS);
    716: }

    718: /*@
    719:    NEPGetConvergenceTest - Gets the method used to compute the error estimate
    720:    used in the convergence test.

    722:    Not Collective

    724:    Input Parameter:
    725: .  nep   - the nonlinear eigensolver context

    727:    Output Parameter:
    728: .  conv  - the type of convergence test

    730:    Level: intermediate

    732: .seealso: [](ch:nep), `NEPSetConvergenceTest()`, `NEPConv`
    733: @*/
    734: PetscErrorCode NEPGetConvergenceTest(NEP nep,NEPConv *conv)
    735: {
    736:   PetscFunctionBegin;
    738:   PetscAssertPointer(conv,2);
    739:   *conv = nep->conv;
    740:   PetscFunctionReturn(PETSC_SUCCESS);
    741: }

    743: /*@C
    744:    NEPSetStoppingTestFunction - Sets a function to decide when to stop the outer
    745:    iteration of the eigensolver.

    747:    Logically Collective

    749:    Input Parameters:
    750: +  nep     - the nonlinear eigensolver context
    751: .  stop    - the stopping test function, see `NEPStoppingTestFn` for the calling sequence
    752: .  ctx     - context for private data for the stopping routine (may be `NULL`)
    753: -  destroy - a routine for destroying the context (may be `NULL`), see `PetscCtxDestroyFn`
    754:              for the calling sequence

    756:    Note:
    757:    When implementing a function for this, normal usage is to first call the
    758:    default routine `NEPStoppingBasic()` and then set `reason` to `NEP_CONVERGED_USER`
    759:    if some user-defined conditions have been met. To let the eigensolver continue
    760:    iterating, the result must be left as `NEP_CONVERGED_ITERATING`.

    762:    Level: advanced

    764: .seealso: [](ch:nep), `NEPSetStoppingTest()`, `NEPStoppingBasic()`
    765: @*/
    766: PetscErrorCode NEPSetStoppingTestFunction(NEP nep,NEPStoppingTestFn *stop,void *ctx,PetscCtxDestroyFn *destroy)
    767: {
    768:   PetscFunctionBegin;
    770:   if (nep->stoppingdestroy) PetscCall((*nep->stoppingdestroy)(&nep->stoppingctx));
    771:   nep->stoppinguser    = stop;
    772:   nep->stoppingdestroy = destroy;
    773:   nep->stoppingctx     = ctx;
    774:   if (stop == NEPStoppingBasic) nep->stop = NEP_STOP_BASIC;
    775:   else {
    776:     nep->stop     = NEP_STOP_USER;
    777:     nep->stopping = nep->stoppinguser;
    778:   }
    779:   PetscFunctionReturn(PETSC_SUCCESS);
    780: }

    782: /*@
    783:    NEPSetStoppingTest - Specifies how to decide the termination of the outer
    784:    loop of the eigensolver.

    786:    Logically Collective

    788:    Input Parameters:
    789: +  nep  - the nonlinear eigensolver context
    790: -  stop - the type of stopping test, see `NEPStop`

    792:    Options Database Keys:
    793: +  -nep_stop_basic - sets the default stopping test
    794: -  -nep_stop_user  - selects the user-defined stopping test

    796:    Level: advanced

    798: .seealso: [](ch:nep), `NEPGetStoppingTest()`, `NEPSetStoppingTestFunction()`, `NEPSetConvergenceTest()`, `NEPStop`
    799: @*/
    800: PetscErrorCode NEPSetStoppingTest(NEP nep,NEPStop stop)
    801: {
    802:   PetscFunctionBegin;
    805:   switch (stop) {
    806:     case NEP_STOP_BASIC: nep->stopping = NEPStoppingBasic; break;
    807:     case NEP_STOP_USER:
    808:       PetscCheck(nep->stoppinguser,PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetStoppingTestFunction() first");
    809:       nep->stopping = nep->stoppinguser;
    810:       break;
    811:     default:
    812:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
    813:   }
    814:   nep->stop = stop;
    815:   PetscFunctionReturn(PETSC_SUCCESS);
    816: }

    818: /*@
    819:    NEPGetStoppingTest - Gets the method used to decide the termination of the outer
    820:    loop of the eigensolver.

    822:    Not Collective

    824:    Input Parameter:
    825: .  nep   - the nonlinear eigensolver context

    827:    Output Parameter:
    828: .  stop  - the type of stopping test

    830:    Level: advanced

    832: .seealso: [](ch:nep), `NEPSetStoppingTest()`, `NEPStop`
    833: @*/
    834: PetscErrorCode NEPGetStoppingTest(NEP nep,NEPStop *stop)
    835: {
    836:   PetscFunctionBegin;
    838:   PetscAssertPointer(stop,2);
    839:   *stop = nep->stop;
    840:   PetscFunctionReturn(PETSC_SUCCESS);
    841: }

    843: /*@
    844:    NEPSetTrackAll - Specifies if the solver must compute the residual of all
    845:    approximate eigenpairs or not.

    847:    Logically Collective

    849:    Input Parameters:
    850: +  nep      - the nonlinear eigensolver context
    851: -  trackall - whether compute all residuals or not

    853:    Notes:
    854:    If the user sets `trackall`=`PETSC_TRUE` then the solver explicitly computes
    855:    the residual for each eigenpair approximation. Computing the residual is
    856:    usually an expensive operation and solvers commonly compute the associated
    857:    residual to the first unconverged eigenpair.

    859:    The option `-nep_monitor_all` automatically activates this option.

    861:    Level: developer

    863: .seealso: [](ch:nep), `NEPGetTrackAll()`
    864: @*/
    865: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)
    866: {
    867:   PetscFunctionBegin;
    870:   nep->trackall = trackall;
    871:   PetscFunctionReturn(PETSC_SUCCESS);
    872: }

    874: /*@
    875:    NEPGetTrackAll - Returns the flag indicating whether all residual norms must
    876:    be computed or not.

    878:    Not Collective

    880:    Input Parameter:
    881: .  nep - the nonlinear eigensolver context

    883:    Output Parameter:
    884: .  trackall - the returned flag

    886:    Level: developer

    888: .seealso: [](ch:nep), `NEPSetTrackAll()`
    889: @*/
    890: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)
    891: {
    892:   PetscFunctionBegin;
    894:   PetscAssertPointer(trackall,2);
    895:   *trackall = nep->trackall;
    896:   PetscFunctionReturn(PETSC_SUCCESS);
    897: }

    899: /*@
    900:    NEPSetRefine - Specifies the refinement type (and options) to be used
    901:    after the solve.

    903:    Logically Collective

    905:    Input Parameters:
    906: +  nep    - the nonlinear eigensolver context
    907: .  refine - refinement type, see `NEPRefine` for possible values
    908: .  npart  - number of partitions of the communicator
    909: .  tol    - the convergence tolerance
    910: .  its    - maximum number of refinement iterations
    911: -  scheme - which scheme to be used for solving the involved linear systems, see `NEPRefineScheme`
    912:             for possible values

    914:    Options Database Keys:
    915: +  -nep_refine \<refine\>           - set the refinement type, one of `none`,`simple`,`multiple`
    916: .  -nep_refine_partitions \<npart\> - set the number of partitions
    917: .  -nep_refine_tol \<tol\>          - set the tolerance
    918: .  -nep_refine_its \<its\>          - set the number of iterations
    919: -  -nep_refine_scheme \<scheme\>    - set the scheme for the linear solves, `schur`,`mbe`, or `explicit`

    921:    Notes:
    922:    This function configures the parameters of Newton iterative refinement,
    923:    see section [](#sec:refine) for a discussion of the different strategies
    924:    in the context of polynomial eigenproblems.

    926:    By default, iterative refinement is disabled, since it may be very
    927:    costly. There are two possible refinement strategies, simple and multiple.
    928:    The simple approach performs iterative refinement on each of the
    929:    converged eigenpairs individually, whereas the multiple strategy works
    930:    with the invariant pair as a whole, refining all eigenpairs simultaneously.
    931:    The latter may be required for the case of multiple eigenvalues.

    933:    In some cases, especially when using direct solvers within the
    934:    iterative refinement method, it may be helpful for improved scalability
    935:    to split the communicator in several partitions. The `npart` parameter
    936:    indicates how many partitions to use (defaults to 1).

    938:    The `tol` and `its` parameters specify the stopping criterion. In the simple
    939:    method, refinement continues until the residual of each eigenpair is
    940:    below the tolerance (`tol` defaults to the `NEP` tolerance, but may be set to a
    941:    different value). In contrast, the multiple method simply performs its
    942:    refinement iterations (just one by default).

    944:    The `scheme` argument is used to change the way in which linear systems are
    945:    solved. Possible choices are explicit, mixed block elimination (MBE),
    946:    and Schur complement.

    948:    Use `PETSC_CURRENT` to retain the current value of `npart`, `tol` or `its`. Use
    949:    `PETSC_DETERMINE` to assign a default value.

    951:    Level: intermediate

    953: .seealso: [](ch:nep), [](#sec:refine), `NEPGetRefine()`
    954: @*/
    955: PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its,NEPRefineScheme scheme)
    956: {
    957:   PetscMPIInt    size;

    959:   PetscFunctionBegin;
    966:   nep->refine = refine;
    967:   if (refine) {  /* process parameters only if not REFINE_NONE */
    968:     if (npart!=nep->npart) {
    969:       PetscCall(PetscSubcommDestroy(&nep->refinesubc));
    970:       PetscCall(KSPDestroy(&nep->refineksp));
    971:     }
    972:     if (npart == PETSC_DETERMINE) {
    973:       nep->npart = 1;
    974:     } else if (npart != PETSC_CURRENT) {
    975:       PetscCallMPI(MPI_Comm_size(PetscObjectComm((PetscObject)nep),&size));
    976:       PetscCheck(npart>0 && npart<=size,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
    977:       nep->npart = npart;
    978:     }
    979:     if (tol == (PetscReal)PETSC_DETERMINE) {
    980:       nep->rtol = PETSC_DETERMINE;
    981:     } else if (tol != (PetscReal)PETSC_CURRENT) {
    982:       PetscCheck(tol>0.0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    983:       nep->rtol = tol;
    984:     }
    985:     if (its==PETSC_DETERMINE) {
    986:       nep->rits = PETSC_DETERMINE;
    987:     } else if (its != PETSC_CURRENT) {
    988:       PetscCheck(its>=0,PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
    989:       nep->rits = its;
    990:     }
    991:     nep->scheme = scheme;
    992:   }
    993:   nep->state = NEP_STATE_INITIAL;
    994:   PetscFunctionReturn(PETSC_SUCCESS);
    995: }

    997: /*@
    998:    NEPGetRefine - Gets the refinement strategy used by the `NEP` object, and the
    999:    associated parameters.

    1001:    Not Collective

    1003:    Input Parameter:
    1004: .  nep - the nonlinear eigensolver context

    1006:    Output Parameters:
    1007: +  refine - refinement type
    1008: .  npart  - number of partitions of the communicator
    1009: .  tol    - the convergence tolerance
    1010: .  its    - maximum number of refinement iterations
    1011: -  scheme - the scheme used for solving linear systems

    1013:    Level: intermediate

    1015:    Note:
    1016:    The user can specify `NULL` for any parameter that is not needed.

    1018: .seealso: [](ch:nep), `NEPSetRefine()`
    1019: @*/
    1020: PetscErrorCode NEPGetRefine(NEP nep,NEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its,NEPRefineScheme *scheme)
    1021: {
    1022:   PetscFunctionBegin;
    1024:   if (refine) *refine = nep->refine;
    1025:   if (npart)  *npart  = nep->npart;
    1026:   if (tol)    *tol    = nep->rtol;
    1027:   if (its)    *its    = nep->rits;
    1028:   if (scheme) *scheme = nep->scheme;
    1029:   PetscFunctionReturn(PETSC_SUCCESS);
    1030: }

    1032: /*@
    1033:    NEPSetOptionsPrefix - Sets the prefix used for searching for all
    1034:    `NEP` options in the database.

    1036:    Logically Collective

    1038:    Input Parameters:
    1039: +  nep    - the nonlinear eigensolver context
    1040: -  prefix - the prefix string to prepend to all `NEP` option requests

    1042:    Notes:
    1043:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1044:    The first character of all runtime options is AUTOMATICALLY the
    1045:    hyphen.

    1047:    For example, to distinguish between the runtime options for two
    1048:    different `NEP` contexts, one could call
    1049: .vb
    1050:    NEPSetOptionsPrefix(nep1,"neig1_")
    1051:    NEPSetOptionsPrefix(nep2,"neig2_")
    1052: .ve

    1054:    Level: advanced

    1056: .seealso: [](ch:nep), `NEPAppendOptionsPrefix()`, `NEPGetOptionsPrefix()`
    1057: @*/
    1058: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char prefix[])
    1059: {
    1060:   PetscFunctionBegin;
    1062:   if (!nep->V) PetscCall(NEPGetBV(nep,&nep->V));
    1063:   PetscCall(BVSetOptionsPrefix(nep->V,prefix));
    1064:   if (!nep->ds) PetscCall(NEPGetDS(nep,&nep->ds));
    1065:   PetscCall(DSSetOptionsPrefix(nep->ds,prefix));
    1066:   if (!nep->rg) PetscCall(NEPGetRG(nep,&nep->rg));
    1067:   PetscCall(RGSetOptionsPrefix(nep->rg,prefix));
    1068:   PetscCall(PetscObjectSetOptionsPrefix((PetscObject)nep,prefix));
    1069:   PetscFunctionReturn(PETSC_SUCCESS);
    1070: }

    1072: /*@
    1073:    NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
    1074:    `NEP` options in the database.

    1076:    Logically Collective

    1078:    Input Parameters:
    1079: +  nep    - the nonlinear eigensolver context
    1080: -  prefix - the prefix string to prepend to all `NEP` option requests

    1082:    Notes:
    1083:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1084:    The first character of all runtime options is AUTOMATICALLY the hyphen.

    1086:    Level: advanced

    1088: .seealso: [](ch:nep), `NEPSetOptionsPrefix()`, `NEPGetOptionsPrefix()`
    1089: @*/
    1090: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char prefix[])
    1091: {
    1092:   PetscFunctionBegin;
    1094:   if (!nep->V) PetscCall(NEPGetBV(nep,&nep->V));
    1095:   PetscCall(BVAppendOptionsPrefix(nep->V,prefix));
    1096:   if (!nep->ds) PetscCall(NEPGetDS(nep,&nep->ds));
    1097:   PetscCall(DSAppendOptionsPrefix(nep->ds,prefix));
    1098:   if (!nep->rg) PetscCall(NEPGetRG(nep,&nep->rg));
    1099:   PetscCall(RGAppendOptionsPrefix(nep->rg,prefix));
    1100:   PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix));
    1101:   PetscFunctionReturn(PETSC_SUCCESS);
    1102: }

    1104: /*@
    1105:    NEPGetOptionsPrefix - Gets the prefix used for searching for all
    1106:    `NEP` options in the database.

    1108:    Not Collective

    1110:    Input Parameter:
    1111: .  nep - the nonlinear eigensolver context

    1113:    Output Parameter:
    1114: .  prefix - pointer to the prefix string used is returned

    1116:    Level: advanced

    1118: .seealso: [](ch:nep), `NEPSetOptionsPrefix()`, `NEPAppendOptionsPrefix()`
    1119: @*/
    1120: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])
    1121: {
    1122:   PetscFunctionBegin;
    1124:   PetscAssertPointer(prefix,2);
    1125:   PetscCall(PetscObjectGetOptionsPrefix((PetscObject)nep,prefix));
    1126:   PetscFunctionReturn(PETSC_SUCCESS);
    1127: }