Date: 2021-09-20T09:44:08+00:00

Actual source code: nepopts.c
slepc-3.15.2 2021-09-20
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2021, 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 on nep

     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: 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;
     46:   PetscErrorCode       ierr;

     49:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)nep),((PetscObject)nep)->options,((PetscObject)nep)->prefix,opt,&viewer,&format,&flg);
     50:   if (!flg) return(0);

     52:   PetscViewerGetType(viewer,&vtype);
     53:   SlepcMonitorMakeKey_Internal(name,vtype,format,key);
     54:   PetscFunctionListFind(NEPMonitorList,key,&mfunc);
     55:   PetscFunctionListFind(NEPMonitorCreateList,key,&cfunc);
     56:   PetscFunctionListFind(NEPMonitorDestroyList,key,&dfunc);
     57:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
     58:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

     60:   (*cfunc)(viewer,format,ctx,&vf);
     61:   PetscObjectDereference((PetscObject)viewer);
     62:   NEPMonitorSet(nep,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
     63:   if (trackall) {
     64:     NEPSetTrackAll(nep,PETSC_TRUE);
     65:   }
     66:   return(0);
     67: }

     69: /*@
     70:    NEPSetFromOptions - Sets NEP options from the options database.
     71:    This routine must be called before NEPSetUp() if the user is to be
     72:    allowed to set the solver type.

     74:    Collective on nep

     76:    Input Parameters:
     77: .  nep - the nonlinear eigensolver context

     79:    Notes:
     80:    To see all options, run your program with the -help option.

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

     97:   NEPRegisterAll();
     98:   PetscObjectOptionsBegin((PetscObject)nep);
     99:     PetscOptionsFList("-nep_type","Nonlinear eigensolver method","NEPSetType",NEPList,(char*)(((PetscObject)nep)->type_name?((PetscObject)nep)->type_name:NEPRII),type,sizeof(type),&flg);
    100:     if (flg) {
    101:       NEPSetType(nep,type);
    102:     } else if (!((PetscObject)nep)->type_name) {
    103:       NEPSetType(nep,NEPRII);
    104:     }

    106:     PetscOptionsBoolGroupBegin("-nep_general","General nonlinear eigenvalue problem","NEPSetProblemType",&flg);
    107:     if (flg) { NEPSetProblemType(nep,NEP_GENERAL); }
    108:     PetscOptionsBoolGroupEnd("-nep_rational","Rational eigenvalue problem","NEPSetProblemType",&flg);
    109:     if (flg) { NEPSetProblemType(nep,NEP_RATIONAL); }

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

    123:     i = nep->max_it;
    124:     PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,&flg1);
    125:     r = nep->tol;
    126:     PetscOptionsReal("-nep_tol","Tolerance","NEPSetTolerances",nep->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->tol,&r,&flg2);
    127:     if (flg1 || flg2) { NEPSetTolerances(nep,r,i); }

    129:     PetscOptionsBoolGroupBegin("-nep_conv_rel","Relative error convergence test","NEPSetConvergenceTest",&flg);
    130:     if (flg) { NEPSetConvergenceTest(nep,NEP_CONV_REL); }
    131:     PetscOptionsBoolGroup("-nep_conv_norm","Convergence test relative to the matrix norms","NEPSetConvergenceTest",&flg);
    132:     if (flg) { NEPSetConvergenceTest(nep,NEP_CONV_NORM); }
    133:     PetscOptionsBoolGroup("-nep_conv_abs","Absolute error convergence test","NEPSetConvergenceTest",&flg);
    134:     if (flg) { NEPSetConvergenceTest(nep,NEP_CONV_ABS); }
    135:     PetscOptionsBoolGroupEnd("-nep_conv_user","User-defined convergence test","NEPSetConvergenceTest",&flg);
    136:     if (flg) { NEPSetConvergenceTest(nep,NEP_CONV_USER); }

    138:     PetscOptionsBoolGroupBegin("-nep_stop_basic","Stop iteration if all eigenvalues converged or max_it reached","NEPSetStoppingTest",&flg);
    139:     if (flg) { NEPSetStoppingTest(nep,NEP_STOP_BASIC); }
    140:     PetscOptionsBoolGroupEnd("-nep_stop_user","User-defined stopping test","NEPSetStoppingTest",&flg);
    141:     if (flg) { NEPSetStoppingTest(nep,NEP_STOP_USER); }

    143:     i = nep->nev;
    144:     PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,&flg1);
    145:     j = nep->ncv;
    146:     PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,&flg2);
    147:     k = nep->mpd;
    148:     PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,&flg3);
    149:     if (flg1 || flg2 || flg3) {
    150:       NEPSetDimensions(nep,i,j,k);
    151:     }

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

    174:     PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg);
    175:     if (flg) {
    176:       if (nep->which!=NEP_TARGET_REAL && nep->which!=NEP_TARGET_IMAGINARY) {
    177:         NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE);
    178:       }
    179:       NEPSetTarget(nep,s);
    180:     }

    182:     PetscOptionsBool("-nep_two_sided","Use two-sided variant (to compute left eigenvectors)","NEPSetTwoSided",nep->twosided,&bval,&flg);
    183:     if (flg) { NEPSetTwoSided(nep,bval); }

    185:     /* -----------------------------------------------------------------------*/
    186:     /*
    187:       Cancels all monitors hardwired into code before call to NEPSetFromOptions()
    188:     */
    189:     PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",PETSC_FALSE,&flg,&set);
    190:     if (set && flg) { NEPMonitorCancel(nep); }
    191:     NEPMonitorSetFromOptions(nep,"-nep_monitor","first_approximation",NULL,PETSC_FALSE);
    192:     NEPMonitorSetFromOptions(nep,"-nep_monitor_all","all_approximations",NULL,PETSC_TRUE);
    193:     NEPMonitorSetFromOptions(nep,"-nep_monitor_conv","convergence_history",NULL,PETSC_FALSE);

    195:     /* -----------------------------------------------------------------------*/
    196:     PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",NULL);
    197:     PetscOptionsName("-nep_view_vectors","View computed eigenvectors","NEPVectorsView",NULL);
    198:     PetscOptionsName("-nep_view_values","View computed eigenvalues","NEPValuesView",NULL);
    199:     PetscOptionsName("-nep_converged_reason","Print reason for convergence, and number of iterations","NEPConvergedReasonView",NULL);
    200:     PetscOptionsName("-nep_error_absolute","Print absolute errors of each eigenpair","NEPErrorView",NULL);
    201:     PetscOptionsName("-nep_error_relative","Print relative errors of each eigenpair","NEPErrorView",NULL);

    203:     if (nep->ops->setfromoptions) {
    204:       (*nep->ops->setfromoptions)(PetscOptionsObject,nep);
    205:     }
    206:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)nep);
    207:   PetscOptionsEnd();

    209:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
    210:   BVSetFromOptions(nep->V);
    211:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
    212:   RGSetFromOptions(nep->rg);
    213:   if (nep->useds) {
    214:     if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    215:     DSSetFromOptions(nep->ds);
    216:   }
    217:   if (!nep->refineksp) { NEPRefineGetKSP(nep,&nep->refineksp); }
    218:   KSPSetFromOptions(nep->refineksp);
    219:   if (nep->fui==NEP_USER_INTERFACE_SPLIT) for (i=0;i<nep->nt;i++) {FNSetFromOptions(nep->f[i]);}
    220:   return(0);
    221: }

    223: /*@C
    224:    NEPGetTolerances - Gets the tolerance and maximum iteration count used
    225:    by the NEP convergence tests.

    227:    Not Collective

    229:    Input Parameter:
    230: .  nep - the nonlinear eigensolver context

    232:    Output Parameters:
    233: +  tol - the convergence tolerance
    234: -  maxits - maximum number of iterations

    236:    Notes:
    237:    The user can specify NULL for any parameter that is not needed.

    239:    Level: intermediate

    241: .seealso: NEPSetTolerances()
    242: @*/
    243: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *tol,PetscInt *maxits)
    244: {
    247:   if (tol)    *tol    = nep->tol;
    248:   if (maxits) *maxits = nep->max_it;
    249:   return(0);
    250: }

    252: /*@
    253:    NEPSetTolerances - Sets the tolerance and maximum iteration count used
    254:    by the NEP convergence tests.

    256:    Logically Collective on nep

    258:    Input Parameters:
    259: +  nep    - the nonlinear eigensolver context
    260: .  tol    - the convergence tolerance
    261: -  maxits - maximum number of iterations to use

    263:    Options Database Keys:
    264: +  -nep_tol <tol> - Sets the convergence tolerance
    265: -  -nep_max_it <maxits> - Sets the maximum number of iterations allowed

    267:    Notes:
    268:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

    270:    Level: intermediate

    272: .seealso: NEPGetTolerances()
    273: @*/
    274: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal tol,PetscInt maxits)
    275: {
    280:   if (tol == PETSC_DEFAULT) {
    281:     nep->tol   = PETSC_DEFAULT;
    282:     nep->state = NEP_STATE_INITIAL;
    283:   } else {
    284:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    285:     nep->tol = tol;
    286:   }
    287:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    288:     nep->max_it = PETSC_DEFAULT;
    289:     nep->state  = NEP_STATE_INITIAL;
    290:   } else {
    291:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
    292:     nep->max_it = maxits;
    293:   }
    294:   return(0);
    295: }

    297: /*@C
    298:    NEPGetDimensions - Gets the number of eigenvalues to compute
    299:    and the dimension of the subspace.

    301:    Not Collective

    303:    Input Parameter:
    304: .  nep - the nonlinear eigensolver context

    306:    Output Parameters:
    307: +  nev - number of eigenvalues to compute
    308: .  ncv - the maximum dimension of the subspace to be used by the solver
    309: -  mpd - the maximum dimension allowed for the projected problem

    311:    Notes:
    312:    The user can specify NULL for any parameter that is not needed.

    314:    Level: intermediate

    316: .seealso: NEPSetDimensions()
    317: @*/
    318: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
    319: {
    322:   if (nev) *nev = nep->nev;
    323:   if (ncv) *ncv = nep->ncv;
    324:   if (mpd) *mpd = nep->mpd;
    325:   return(0);
    326: }

    328: /*@
    329:    NEPSetDimensions - Sets the number of eigenvalues to compute
    330:    and the dimension of the subspace.

    332:    Logically Collective on nep

    334:    Input Parameters:
    335: +  nep - the nonlinear eigensolver context
    336: .  nev - number of eigenvalues to compute
    337: .  ncv - the maximum dimension of the subspace to be used by the solver
    338: -  mpd - the maximum dimension allowed for the projected problem

    340:    Options Database Keys:
    341: +  -nep_nev <nev> - Sets the number of eigenvalues
    342: .  -nep_ncv <ncv> - Sets the dimension of the subspace
    343: -  -nep_mpd <mpd> - Sets the maximum projected dimension

    345:    Notes:
    346:    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
    347:    dependent on the solution method.

    349:    The parameters ncv and mpd are intimately related, so that the user is advised
    350:    to set one of them at most. Normal usage is that
    351:    (a) in cases where nev is small, the user sets ncv (a reasonable default is 2*nev); and
    352:    (b) in cases where nev is large, the user sets mpd.

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

    358:    Level: intermediate

    360: .seealso: NEPGetDimensions()
    361: @*/
    362: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)
    363: {
    369:   if (nev<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
    370:   nep->nev = nev;
    371:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    372:     nep->ncv = PETSC_DEFAULT;
    373:   } else {
    374:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    375:     nep->ncv = ncv;
    376:   }
    377:   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
    378:     nep->mpd = PETSC_DEFAULT;
    379:   } else {
    380:     if (mpd<1) SETERRQ(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:   return(0);
    385: }

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

    391:     Logically Collective on nep

    393:     Input Parameters:
    394: +   nep   - eigensolver context obtained from NEPCreate()
    395: -   which - the portion of the spectrum to be sought

    397:     Possible values:
    398:     The parameter 'which' can have one of these values

    400: +     NEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
    401: .     NEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
    402: .     NEP_LARGEST_REAL - largest real parts
    403: .     NEP_SMALLEST_REAL - smallest real parts
    404: .     NEP_LARGEST_IMAGINARY - largest imaginary parts
    405: .     NEP_SMALLEST_IMAGINARY - smallest imaginary parts
    406: .     NEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
    407: .     NEP_TARGET_REAL - eigenvalues with real part closest to target
    408: .     NEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target
    409: .     NEP_ALL - all eigenvalues contained in a given region
    410: -     NEP_WHICH_USER - user defined ordering set with NEPSetEigenvalueComparison()

    412:     Options Database Keys:
    413: +   -nep_largest_magnitude - Sets largest eigenvalues in magnitude
    414: .   -nep_smallest_magnitude - Sets smallest eigenvalues in magnitude
    415: .   -nep_largest_real - Sets largest real parts
    416: .   -nep_smallest_real - Sets smallest real parts
    417: .   -nep_largest_imaginary - Sets largest imaginary parts
    418: .   -nep_smallest_imaginary - Sets smallest imaginary parts
    419: .   -nep_target_magnitude - Sets eigenvalues closest to target
    420: .   -nep_target_real - Sets real parts closest to target
    421: .   -nep_target_imaginary - Sets imaginary parts closest to target
    422: -   -nep_all - Sets all eigenvalues in a region

    424:     Notes:
    425:     Not all eigensolvers implemented in NEP account for all the possible values
    426:     stated above. If SLEPc is compiled for real numbers NEP_LARGEST_IMAGINARY
    427:     and NEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
    428:     for eigenvalue selection.

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

    432:     Level: intermediate

    434: .seealso: NEPGetWhichEigenpairs(), NEPSetTarget(), NEPSetEigenvalueComparison(), NEPWhich
    435: @*/
    436: PetscErrorCode NEPSetWhichEigenpairs(NEP nep,NEPWhich which)
    437: {
    441:   switch (which) {
    442:     case NEP_LARGEST_MAGNITUDE:
    443:     case NEP_SMALLEST_MAGNITUDE:
    444:     case NEP_LARGEST_REAL:
    445:     case NEP_SMALLEST_REAL:
    446:     case NEP_LARGEST_IMAGINARY:
    447:     case NEP_SMALLEST_IMAGINARY:
    448:     case NEP_TARGET_MAGNITUDE:
    449:     case NEP_TARGET_REAL:
    450: #if defined(PETSC_USE_COMPLEX)
    451:     case NEP_TARGET_IMAGINARY:
    452: #endif
    453:     case NEP_ALL:
    454:     case NEP_WHICH_USER:
    455:       if (nep->which != which) {
    456:         nep->state = NEP_STATE_INITIAL;
    457:         nep->which = which;
    458:       }
    459:       break;
    460: #if !defined(PETSC_USE_COMPLEX)
    461:     case NEP_TARGET_IMAGINARY:
    462:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_SUP,"NEP_TARGET_IMAGINARY can be used only with complex scalars");
    463: #endif
    464:     default:
    465:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
    466:   }
    467:   return(0);
    468: }

    470: /*@
    471:     NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
    472:     sought.

    474:     Not Collective

    476:     Input Parameter:
    477: .   nep - eigensolver context obtained from NEPCreate()

    479:     Output Parameter:
    480: .   which - the portion of the spectrum to be sought

    482:     Notes:
    483:     See NEPSetWhichEigenpairs() for possible values of 'which'.

    485:     Level: intermediate

    487: .seealso: NEPSetWhichEigenpairs(), NEPWhich
    488: @*/
    489: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)
    490: {
    494:   *which = nep->which;
    495:   return(0);
    496: }

    498: /*@C
    499:    NEPSetEigenvalueComparison - Specifies the eigenvalue comparison function
    500:    when NEPSetWhichEigenpairs() is set to NEP_WHICH_USER.

    502:    Logically Collective on nep

    504:    Input Parameters:
    505: +  nep  - eigensolver context obtained from NEPCreate()
    506: .  func - a pointer to the comparison function
    507: -  ctx  - a context pointer (the last parameter to the comparison function)

    509:    Calling Sequence of func:
    510: $   func(PetscScalar ar,PetscScalar ai,PetscScalar br,PetscScalar bi,PetscInt *res,void *ctx)

    512: +   ar     - real part of the 1st eigenvalue
    513: .   ai     - imaginary part of the 1st eigenvalue
    514: .   br     - real part of the 2nd eigenvalue
    515: .   bi     - imaginary part of the 2nd eigenvalue
    516: .   res    - result of comparison
    517: -   ctx    - optional context, as set by NEPSetEigenvalueComparison()

    519:    Note:
    520:    The returning parameter 'res' can be
    521: +  negative - if the 1st eigenvalue is preferred to the 2st one
    522: .  zero     - if both eigenvalues are equally preferred
    523: -  positive - if the 2st eigenvalue is preferred to the 1st one

    525:    Level: advanced

    527: .seealso: NEPSetWhichEigenpairs(), NEPWhich
    528: @*/
    529: PetscErrorCode NEPSetEigenvalueComparison(NEP nep,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void* ctx)
    530: {
    533:   nep->sc->comparison    = func;
    534:   nep->sc->comparisonctx = ctx;
    535:   nep->which             = NEP_WHICH_USER;
    536:   return(0);
    537: }

    539: /*@
    540:    NEPSetProblemType - Specifies the type of the nonlinear eigenvalue problem.

    542:    Logically Collective on nep

    544:    Input Parameters:
    545: +  nep  - the nonlinear eigensolver context
    546: -  type - a known type of nonlinear eigenvalue problem

    548:    Options Database Keys:
    549: +  -nep_general - general problem with no particular structure
    550: -  -nep_rational - a rational eigenvalue problem defined in split form with all f_i rational

    552:    Notes:
    553:    Allowed values for the problem type are: general (NEP_GENERAL), and rational
    554:    (NEP_RATIONAL).

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

    560:    Level: intermediate

    562: .seealso: NEPSetType(), NEPGetProblemType(), NEPProblemType
    563: @*/
    564: PetscErrorCode NEPSetProblemType(NEP nep,NEPProblemType type)
    565: {
    569:   if (type!=NEP_GENERAL && type!=NEP_RATIONAL) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_WRONG,"Unknown eigenvalue problem type");
    570:   if (type != nep->problem_type) {
    571:     nep->problem_type = type;
    572:     nep->state = NEP_STATE_INITIAL;
    573:   }
    574:   return(0);
    575: }

    577: /*@
    578:    NEPGetProblemType - Gets the problem type from the NEP object.

    580:    Not Collective

    582:    Input Parameter:
    583: .  nep - the nonlinear eigensolver context

    585:    Output Parameter:
    586: .  type - the problem type

    588:    Level: intermediate

    590: .seealso: NEPSetProblemType(), NEPProblemType
    591: @*/
    592: PetscErrorCode NEPGetProblemType(NEP nep,NEPProblemType *type)
    593: {
    597:   *type = nep->problem_type;
    598:   return(0);
    599: }

    601: /*@
    602:    NEPSetTwoSided - Sets the solver to use a two-sided variant so that left
    603:    eigenvectors are also computed.

    605:    Logically Collective on nep

    607:    Input Parameters:
    608: +  nep      - the eigensolver context
    609: -  twosided - whether the two-sided variant is to be used or not

    611:    Options Database Keys:
    612: .  -nep_two_sided <boolean> - Sets/resets the twosided flag

    614:    Notes:
    615:    If the user sets twosided=PETSC_TRUE then the solver uses a variant of
    616:    the algorithm that computes both right and left eigenvectors. This is
    617:    usually much more costly. This option is not available in all solvers.

    619:    When using two-sided solvers, the problem matrices must have both the
    620:    MatMult and MatMultTranspose operations defined.

    622:    Level: advanced

    624: .seealso: NEPGetTwoSided(), NEPGetLeftEigenvector()
    625: @*/
    626: PetscErrorCode NEPSetTwoSided(NEP nep,PetscBool twosided)
    627: {
    631:   if (twosided!=nep->twosided) {
    632:     nep->twosided = twosided;
    633:     nep->state    = NEP_STATE_INITIAL;
    634:   }
    635:   return(0);
    636: }

    638: /*@
    639:    NEPGetTwoSided - Returns the flag indicating whether a two-sided variant
    640:    of the algorithm is being used or not.

    642:    Not Collective

    644:    Input Parameter:
    645: .  nep - the eigensolver context

    647:    Output Parameter:
    648: .  twosided - the returned flag

    650:    Level: advanced

    652: .seealso: NEPSetTwoSided()
    653: @*/
    654: PetscErrorCode NEPGetTwoSided(NEP nep,PetscBool *twosided)
    655: {
    659:   *twosided = nep->twosided;
    660:   return(0);
    661: }

    663: /*@C
    664:    NEPSetConvergenceTestFunction - Sets a function to compute the error estimate
    665:    used in the convergence test.

    667:    Logically Collective on nep

    669:    Input Parameters:
    670: +  nep     - nonlinear eigensolver context obtained from NEPCreate()
    671: .  func    - a pointer to the convergence test function
    672: .  ctx     - context for private data for the convergence routine (may be null)
    673: -  destroy - a routine for destroying the context (may be null)

    675:    Calling Sequence of func:
    676: $   func(NEP nep,PetscScalar eigr,PetscScalar eigi,PetscReal res,PetscReal *errest,void *ctx)

    678: +   nep    - nonlinear eigensolver context obtained from NEPCreate()
    679: .   eigr   - real part of the eigenvalue
    680: .   eigi   - imaginary part of the eigenvalue
    681: .   res    - residual norm associated to the eigenpair
    682: .   errest - (output) computed error estimate
    683: -   ctx    - optional context, as set by NEPSetConvergenceTestFunction()

    685:    Note:
    686:    If the error estimate returned by the convergence test function is less than
    687:    the tolerance, then the eigenvalue is accepted as converged.

    689:    Level: advanced

    691: .seealso: NEPSetConvergenceTest(), NEPSetTolerances()
    692: @*/
    693: PetscErrorCode NEPSetConvergenceTestFunction(NEP nep,PetscErrorCode (*func)(NEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
    694: {

    699:   if (nep->convergeddestroy) {
    700:     (*nep->convergeddestroy)(nep->convergedctx);
    701:   }
    702:   nep->convergeduser    = func;
    703:   nep->convergeddestroy = destroy;
    704:   nep->convergedctx     = ctx;
    705:   if (func == NEPConvergedRelative) nep->conv = NEP_CONV_REL;
    706:   else if (func == NEPConvergedNorm) nep->conv = NEP_CONV_NORM;
    707:   else if (func == NEPConvergedAbsolute) nep->conv = NEP_CONV_ABS;
    708:   else {
    709:     nep->conv      = NEP_CONV_USER;
    710:     nep->converged = nep->convergeduser;
    711:   }
    712:   return(0);
    713: }

    715: /*@
    716:    NEPSetConvergenceTest - Specifies how to compute the error estimate
    717:    used in the convergence test.

    719:    Logically Collective on nep

    721:    Input Parameters:
    722: +  nep  - nonlinear eigensolver context obtained from NEPCreate()
    723: -  conv - the type of convergence test

    725:    Options Database Keys:
    726: +  -nep_conv_abs  - Sets the absolute convergence test
    727: .  -nep_conv_rel  - Sets the convergence test relative to the eigenvalue
    728: -  -nep_conv_user - Selects the user-defined convergence test

    730:    Note:
    731:    The parameter 'conv' can have one of these values
    732: +     NEP_CONV_ABS  - absolute error ||r||
    733: .     NEP_CONV_REL  - error relative to the eigenvalue l, ||r||/|l|
    734: .     NEP_CONV_NORM - error relative matrix norms, ||r||/sum_i(|f_i(l)|*||A_i||)
    735: -     NEP_CONV_USER - function set by NEPSetConvergenceTestFunction()

    737:    Level: intermediate

    739: .seealso: NEPGetConvergenceTest(), NEPSetConvergenceTestFunction(), NEPSetStoppingTest(), NEPConv
    740: @*/
    741: PetscErrorCode NEPSetConvergenceTest(NEP nep,NEPConv conv)
    742: {
    746:   switch (conv) {
    747:     case NEP_CONV_ABS:  nep->converged = NEPConvergedAbsolute; break;
    748:     case NEP_CONV_REL:  nep->converged = NEPConvergedRelative; break;
    749:     case NEP_CONV_NORM: nep->converged = NEPConvergedNorm; break;
    750:     case NEP_CONV_USER:
    751:       if (!nep->convergeduser) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetConvergenceTestFunction() first");
    752:       nep->converged = nep->convergeduser;
    753:       break;
    754:     default:
    755:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'conv' value");
    756:   }
    757:   nep->conv = conv;
    758:   return(0);
    759: }

    761: /*@
    762:    NEPGetConvergenceTest - Gets the method used to compute the error estimate
    763:    used in the convergence test.

    765:    Not Collective

    767:    Input Parameters:
    768: .  nep   - nonlinear eigensolver context obtained from NEPCreate()

    770:    Output Parameters:
    771: .  conv  - the type of convergence test

    773:    Level: intermediate

    775: .seealso: NEPSetConvergenceTest(), NEPConv
    776: @*/
    777: PetscErrorCode NEPGetConvergenceTest(NEP nep,NEPConv *conv)
    778: {
    782:   *conv = nep->conv;
    783:   return(0);
    784: }

    786: /*@C
    787:    NEPSetStoppingTestFunction - Sets a function to decide when to stop the outer
    788:    iteration of the eigensolver.

    790:    Logically Collective on nep

    792:    Input Parameters:
    793: +  nep     - nonlinear eigensolver context obtained from NEPCreate()
    794: .  func    - pointer to the stopping test function
    795: .  ctx     - context for private data for the stopping routine (may be null)
    796: -  destroy - a routine for destroying the context (may be null)

    798:    Calling Sequence of func:
    799: $   func(NEP nep,PetscInt its,PetscInt max_it,PetscInt nconv,PetscInt nev,NEPConvergedReason *reason,void *ctx)

    801: +   nep    - nonlinear eigensolver context obtained from NEPCreate()
    802: .   its    - current number of iterations
    803: .   max_it - maximum number of iterations
    804: .   nconv  - number of currently converged eigenpairs
    805: .   nev    - number of requested eigenpairs
    806: .   reason - (output) result of the stopping test
    807: -   ctx    - optional context, as set by NEPSetStoppingTestFunction()

    809:    Note:
    810:    Normal usage is to first call the default routine NEPStoppingBasic() and then
    811:    set reason to NEP_CONVERGED_USER if some user-defined conditions have been
    812:    met. To let the eigensolver continue iterating, the result must be left as
    813:    NEP_CONVERGED_ITERATING.

    815:    Level: advanced

    817: .seealso: NEPSetStoppingTest(), NEPStoppingBasic()
    818: @*/
    819: PetscErrorCode NEPSetStoppingTestFunction(NEP nep,PetscErrorCode (*func)(NEP,PetscInt,PetscInt,PetscInt,PetscInt,NEPConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
    820: {

    825:   if (nep->stoppingdestroy) {
    826:     (*nep->stoppingdestroy)(nep->stoppingctx);
    827:   }
    828:   nep->stoppinguser    = func;
    829:   nep->stoppingdestroy = destroy;
    830:   nep->stoppingctx     = ctx;
    831:   if (func == NEPStoppingBasic) nep->stop = NEP_STOP_BASIC;
    832:   else {
    833:     nep->stop     = NEP_STOP_USER;
    834:     nep->stopping = nep->stoppinguser;
    835:   }
    836:   return(0);
    837: }

    839: /*@
    840:    NEPSetStoppingTest - Specifies how to decide the termination of the outer
    841:    loop of the eigensolver.

    843:    Logically Collective on nep

    845:    Input Parameters:
    846: +  nep  - nonlinear eigensolver context obtained from NEPCreate()
    847: -  stop - the type of stopping test

    849:    Options Database Keys:
    850: +  -nep_stop_basic - Sets the default stopping test
    851: -  -nep_stop_user  - Selects the user-defined stopping test

    853:    Note:
    854:    The parameter 'stop' can have one of these values
    855: +     NEP_STOP_BASIC - default stopping test
    856: -     NEP_STOP_USER  - function set by NEPSetStoppingTestFunction()

    858:    Level: advanced

    860: .seealso: NEPGetStoppingTest(), NEPSetStoppingTestFunction(), NEPSetConvergenceTest(), NEPStop
    861: @*/
    862: PetscErrorCode NEPSetStoppingTest(NEP nep,NEPStop stop)
    863: {
    867:   switch (stop) {
    868:     case NEP_STOP_BASIC: nep->stopping = NEPStoppingBasic; break;
    869:     case NEP_STOP_USER:
    870:       if (!nep->stoppinguser) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ORDER,"Must call NEPSetStoppingTestFunction() first");
    871:       nep->stopping = nep->stoppinguser;
    872:       break;
    873:     default:
    874:       SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'stop' value");
    875:   }
    876:   nep->stop = stop;
    877:   return(0);
    878: }

    880: /*@
    881:    NEPGetStoppingTest - Gets the method used to decide the termination of the outer
    882:    loop of the eigensolver.

    884:    Not Collective

    886:    Input Parameters:
    887: .  nep   - nonlinear eigensolver context obtained from NEPCreate()

    889:    Output Parameters:
    890: .  stop  - the type of stopping test

    892:    Level: advanced

    894: .seealso: NEPSetStoppingTest(), NEPStop
    895: @*/
    896: PetscErrorCode NEPGetStoppingTest(NEP nep,NEPStop *stop)
    897: {
    901:   *stop = nep->stop;
    902:   return(0);
    903: }

    905: /*@
    906:    NEPSetTrackAll - Specifies if the solver must compute the residual of all
    907:    approximate eigenpairs or not.

    909:    Logically Collective on nep

    911:    Input Parameters:
    912: +  nep      - the eigensolver context
    913: -  trackall - whether compute all residuals or not

    915:    Notes:
    916:    If the user sets trackall=PETSC_TRUE then the solver explicitly computes
    917:    the residual for each eigenpair approximation. Computing the residual is
    918:    usually an expensive operation and solvers commonly compute the associated
    919:    residual to the first unconverged eigenpair.

    921:    The option '-nep_monitor_all' automatically activates this option.

    923:    Level: developer

    925: .seealso: NEPGetTrackAll()
    926: @*/
    927: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)
    928: {
    932:   nep->trackall = trackall;
    933:   return(0);
    934: }

    936: /*@
    937:    NEPGetTrackAll - Returns the flag indicating whether all residual norms must
    938:    be computed or not.

    940:    Not Collective

    942:    Input Parameter:
    943: .  nep - the eigensolver context

    945:    Output Parameter:
    946: .  trackall - the returned flag

    948:    Level: developer

    950: .seealso: NEPSetTrackAll()
    951: @*/
    952: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)
    953: {
    957:   *trackall = nep->trackall;
    958:   return(0);
    959: }

    961: /*@
    962:    NEPSetRefine - Specifies the refinement type (and options) to be used
    963:    after the solve.

    965:    Logically Collective on nep

    967:    Input Parameters:
    968: +  nep    - the nonlinear eigensolver context
    969: .  refine - refinement type
    970: .  npart  - number of partitions of the communicator
    971: .  tol    - the convergence tolerance
    972: .  its    - maximum number of refinement iterations
    973: -  scheme - which scheme to be used for solving the involved linear systems

    975:    Options Database Keys:
    976: +  -nep_refine <type> - refinement type, one of <none,simple,multiple>
    977: .  -nep_refine_partitions <n> - the number of partitions
    978: .  -nep_refine_tol <tol> - the tolerance
    979: .  -nep_refine_its <its> - number of iterations
    980: -  -nep_refine_scheme - to set the scheme for the linear solves

    982:    Notes:
    983:    By default, iterative refinement is disabled, since it may be very
    984:    costly. There are two possible refinement strategies: simple and multiple.
    985:    The simple approach performs iterative refinement on each of the
    986:    converged eigenpairs individually, whereas the multiple strategy works
    987:    with the invariant pair as a whole, refining all eigenpairs simultaneously.
    988:    The latter may be required for the case of multiple eigenvalues.

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

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

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

    1005:    Level: intermediate

    1007: .seealso: NEPGetRefine()
    1008: @*/
    1009: PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its,NEPRefineScheme scheme)
    1010: {
    1012:   PetscMPIInt    size;

    1021:   nep->refine = refine;
    1022:   if (refine) {  /* process parameters only if not REFINE_NONE */
    1023:     if (npart!=nep->npart) {
    1024:       PetscSubcommDestroy(&nep->refinesubc);
    1025:       KSPDestroy(&nep->refineksp);
    1026:     }
    1027:     if (npart == PETSC_DEFAULT || npart == PETSC_DECIDE) {
    1028:       nep->npart = 1;
    1029:     } else {
    1030:       MPI_Comm_size(PetscObjectComm((PetscObject)nep),&size);CHKERRMPI(ierr);
    1031:       if (npart<1 || npart>size) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
    1032:       nep->npart = npart;
    1033:     }
    1034:     if (tol == PETSC_DEFAULT || tol == PETSC_DECIDE) {
    1035:       nep->rtol = PETSC_DEFAULT;
    1036:     } else {
    1037:       if (tol<=0.0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    1038:       nep->rtol = tol;
    1039:     }
    1040:     if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
    1041:       nep->rits = PETSC_DEFAULT;
    1042:     } else {
    1043:       if (its<0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
    1044:       nep->rits = its;
    1045:     }
    1046:     nep->scheme = scheme;
    1047:   }
    1048:   nep->state = NEP_STATE_INITIAL;
    1049:   return(0);
    1050: }

    1052: /*@C
    1053:    NEPGetRefine - Gets the refinement strategy used by the NEP object, and the
    1054:    associated parameters.

    1056:    Not Collective

    1058:    Input Parameter:
    1059: .  nep - the nonlinear eigensolver context

    1061:    Output Parameters:
    1062: +  refine - refinement type
    1063: .  npart  - number of partitions of the communicator
    1064: .  tol    - the convergence tolerance
    1065: -  its    - maximum number of refinement iterations
    1066: -  scheme - the scheme used for solving linear systems

    1068:    Level: intermediate

    1070:    Note:
    1071:    The user can specify NULL for any parameter that is not needed.

    1073: .seealso: NEPSetRefine()
    1074: @*/
    1075: PetscErrorCode NEPGetRefine(NEP nep,NEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its,NEPRefineScheme *scheme)
    1076: {
    1079:   if (refine) *refine = nep->refine;
    1080:   if (npart)  *npart  = nep->npart;
    1081:   if (tol)    *tol    = nep->rtol;
    1082:   if (its)    *its    = nep->rits;
    1083:   if (scheme) *scheme = nep->scheme;
    1084:   return(0);
    1085: }

    1087: /*@C
    1088:    NEPSetOptionsPrefix - Sets the prefix used for searching for all
    1089:    NEP options in the database.

    1091:    Logically Collective on nep

    1093:    Input Parameters:
    1094: +  nep - the nonlinear eigensolver context
    1095: -  prefix - the prefix string to prepend to all NEP option requests

    1097:    Notes:
    1098:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    1099:    The first character of all runtime options is AUTOMATICALLY the
    1100:    hyphen.

    1102:    For example, to distinguish between the runtime options for two
    1103:    different NEP contexts, one could call
    1104: .vb
    1105:       NEPSetOptionsPrefix(nep1,"neig1_")
    1106:       NEPSetOptionsPrefix(nep2,"neig2_")
    1107: .ve

    1109:    Level: advanced

    1111: .seealso: NEPAppendOptionsPrefix(), NEPGetOptionsPrefix()
    1112: @*/
    1113: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char *prefix)
    1114: {

    1119:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
    1120:   BVSetOptionsPrefix(nep->V,prefix);
    1121:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    1122:   DSSetOptionsPrefix(nep->ds,prefix);
    1123:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
    1124:   RGSetOptionsPrefix(nep->rg,prefix);
    1125:   PetscObjectSetOptionsPrefix((PetscObject)nep,prefix);
    1126:   return(0);
    1127: }

    1129: /*@C
    1130:    NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
    1131:    NEP options in the database.

    1133:    Logically Collective on nep

    1135:    Input Parameters:
    1136: +  nep - the nonlinear eigensolver context
    1137: -  prefix - the prefix string to prepend to all NEP option requests

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

    1143:    Level: advanced

    1145: .seealso: NEPSetOptionsPrefix(), NEPGetOptionsPrefix()
    1146: @*/
    1147: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char *prefix)
    1148: {

    1153:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
    1154:   BVAppendOptionsPrefix(nep->V,prefix);
    1155:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    1156:   DSAppendOptionsPrefix(nep->ds,prefix);
    1157:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
    1158:   RGAppendOptionsPrefix(nep->rg,prefix);
    1159:   PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix);
    1160:   return(0);
    1161: }

    1163: /*@C
    1164:    NEPGetOptionsPrefix - Gets the prefix used for searching for all
    1165:    NEP options in the database.

    1167:    Not Collective

    1169:    Input Parameters:
    1170: .  nep - the nonlinear eigensolver context

    1172:    Output Parameters:
    1173: .  prefix - pointer to the prefix string used is returned

    1175:    Note:
    1176:    On the Fortran side, the user should pass in a string 'prefix' of
    1177:    sufficient length to hold the prefix.

    1179:    Level: advanced

    1181: .seealso: NEPSetOptionsPrefix(), NEPAppendOptionsPrefix()
    1182: @*/
    1183: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])
    1184: {

    1190:   PetscObjectGetOptionsPrefix((PetscObject)nep,prefix);
    1191:   return(0);
    1192: }