Date: 2013-09-02T10:07:50+00:00

Actual source code: nepopts.c

      1: /*
      2:       NEP routines related to options that can be set via the command-line
      3:       or procedurally.

      5:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      6:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      7:    Copyright (c) 2002-2013, Universitat Politecnica de Valencia, Spain

      9:    This file is part of SLEPc.

     11:    SLEPc is free software: you can redistribute it and/or modify it under  the
     12:    terms of version 3 of the GNU Lesser General Public License as published by
     13:    the Free Software Foundation.

     15:    SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY
     16:    WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS
     17:    FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for
     18:    more details.

     20:    You  should have received a copy of the GNU Lesser General  Public  License
     21:    along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
     22:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     23: */

     25: #include <slepc-private/nepimpl.h>       /*I "slepcnep.h" I*/

     29: /*@
     30:    NEPSetFromOptions - Sets NEP options from the options database.
     31:    This routine must be called before NEPSetUp() if the user is to be
     32:    allowed to set the solver type.

     34:    Collective on NEP

     36:    Input Parameters:
     37: .  nep - the nonlinear eigensolver context

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

     42:    Level: beginner
     43: @*/
     44: PetscErrorCode NEPSetFromOptions(NEP nep)
     45: {
     46:   PetscErrorCode   ierr;
     47:   char             type[256],monfilename[PETSC_MAX_PATH_LEN];
     48:   PetscBool        flg;
     49:   PetscReal        r1,r2,r3;
     50:   PetscScalar      s;
     51:   PetscInt         i,j,k;
     52:   PetscViewer      monviewer;
     53:   SlepcConvMonitor ctx;
     54:   MatStructure     matflag;

     58:   if (!NEPRegisterAllCalled) { NEPRegisterAll(); }
     59:   PetscObjectOptionsBegin((PetscObject)nep);
     60:     PetscOptionsList("-nep_type","Nonlinear Eigenvalue Problem method","NEPSetType",NEPList,(char*)(((PetscObject)nep)->type_name?((PetscObject)nep)->type_name:NEPRII),type,256,&flg);
     61:     if (flg) {
     62:       NEPSetType(nep,type);
     63:     } else if (!((PetscObject)nep)->type_name) {
     64:       NEPSetType(nep,NEPRII);
     65:     }

     67:     r1 = r2 = r3 = i = j = 0;
     68:     PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,NULL);
     69:     PetscOptionsInt("-nep_max_funcs","Maximum number of function evaluations","NEPSetTolerances",nep->max_funcs,&j,NULL);
     70:     PetscOptionsReal("-nep_atol","Absolute tolerance for residual norm","NEPSetTolerances",nep->abstol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->abstol,&r1,NULL);
     71:     PetscOptionsReal("-nep_rtol","Relative tolerance for residual norm","NEPSetTolerances",nep->rtol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->rtol,&r2,NULL);
     72:     PetscOptionsReal("-nep_stol","Relative tolerance for step length","NEPSetTolerances",nep->stol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->stol,&r3,NULL);
     73:     NEPSetTolerances(nep,r1,r2,r3,i,j);
     74:     flg  = PETSC_FALSE;
     75:     PetscOptionsBool("-nep_convergence_default","Default (relative error) convergence test","NEPSetConvergenceTest",flg,&flg,NULL);
     76:     if (flg) { NEPSetConvergenceTest(nep,NEPConvergedDefault,NULL,NULL); }

     78:     i = j = k = 0;
     79:     PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,NULL);
     80:     PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,NULL);
     81:     PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,NULL);
     82:     NEPSetDimensions(nep,i,j,k);

     84:     i = 0;
     85:     PetscOptionsInt("-nep_lag_preconditioner","Interval to rebuild preconditioner","NEPSetLagPreconditioner",nep->lag,&i,&flg);
     86:     if (flg) { NEPSetLagPreconditioner(nep,i); }

     88:     PetscOptionsBool("-nep_const_correction_tol","Constant correction tolerance for the linear solver","NEPSetConstCorrectionTol",nep->cctol,&nep->cctol,NULL);

     90:     PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg);
     91:     if (flg) {
     92:       NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE);
     93:       NEPSetTarget(nep,s);
     94:     }

     96:     /* -----------------------------------------------------------------------*/
     97:     /*
     98:       Cancels all monitors hardwired into code before call to NEPSetFromOptions()
     99:     */
    100:     flg  = PETSC_FALSE;
    101:     PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",flg,&flg,NULL);
    102:     if (flg) {
    103:       NEPMonitorCancel(nep);
    104:     }
    105:     /*
    106:       Prints approximate eigenvalues and error estimates at each iteration
    107:     */
    108:     PetscOptionsString("-nep_monitor","Monitor first unconverged approximate eigenvalue and error estimate","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    109:     if (flg) {
    110:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
    111:       NEPMonitorSet(nep,NEPMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    112:     }
    113:     PetscOptionsString("-nep_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    114:     if (flg) {
    115:       PetscNew(struct _n_SlepcConvMonitor,&ctx);
    116:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&ctx->viewer);
    117:       NEPMonitorSet(nep,NEPMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
    118:     }
    119:     PetscOptionsString("-nep_monitor_all","Monitor approximate eigenvalues and error estimates","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    120:     if (flg) {
    121:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
    122:       NEPMonitorSet(nep,NEPMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    123:       NEPSetTrackAll(nep,PETSC_TRUE);
    124:     }
    125:     flg = PETSC_FALSE;
    126:     PetscOptionsBool("-nep_monitor_lg","Monitor first unconverged approximate error estimate graphically","NEPMonitorSet",flg,&flg,NULL);
    127:     if (flg) {
    128:       NEPMonitorSet(nep,NEPMonitorLG,NULL,NULL);
    129:     }
    130:     flg = PETSC_FALSE;
    131:     PetscOptionsBool("-nep_monitor_lg_all","Monitor error estimates graphically","NEPMonitorSet",flg,&flg,NULL);
    132:     if (flg) {
    133:       NEPMonitorSet(nep,NEPMonitorLGAll,NULL,NULL);
    134:       NEPSetTrackAll(nep,PETSC_TRUE);
    135:     }
    136:   /* -----------------------------------------------------------------------*/

    138:     PetscOptionsBoolGroupBegin("-nep_largest_magnitude","compute largest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
    139:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_MAGNITUDE); }
    140:     PetscOptionsBoolGroup("-nep_smallest_magnitude","compute smallest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
    141:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_MAGNITUDE); }
    142:     PetscOptionsBoolGroup("-nep_largest_real","compute largest real parts","NEPSetWhichEigenpairs",&flg);
    143:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_REAL); }
    144:     PetscOptionsBoolGroup("-nep_smallest_real","compute smallest real parts","NEPSetWhichEigenpairs",&flg);
    145:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_REAL); }
    146:     PetscOptionsBoolGroup("-nep_largest_imaginary","compute largest imaginary parts","NEPSetWhichEigenpairs",&flg);
    147:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_IMAGINARY); }
    148:     PetscOptionsBoolGroup("-nep_smallest_imaginary","compute smallest imaginary parts","NEPSetWhichEigenpairs",&flg);
    149:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_IMAGINARY); }
    150:     PetscOptionsBoolGroup("-nep_target_magnitude","compute nearest eigenvalues to target","NEPSetWhichEigenpairs",&flg);
    151:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE); }
    152:     PetscOptionsBoolGroup("-nep_target_real","compute eigenvalues with real parts close to target","NEPSetWhichEigenpairs",&flg);
    153:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_REAL); }
    154:     PetscOptionsBoolGroupEnd("-nep_target_imaginary","compute eigenvalues with imaginary parts close to target","NEPSetWhichEigenpairs",&flg);
    155:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_IMAGINARY); }

    157:     PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",0);
    158:     PetscOptionsName("-nep_plot_eigs","Make a plot of the computed eigenvalues","NEPSolve",0);

    160:     if (nep->ops->setfromoptions) {
    161:       (*nep->ops->setfromoptions)(nep);
    162:     }
    163:     PetscObjectProcessOptionsHandlers((PetscObject)nep);
    164:   PetscOptionsEnd();

    166:   if (!nep->ip) { NEPGetIP(nep,&nep->ip); }
    167:   IPSetFromOptions(nep->ip);
    168:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    169:   DSSetFromOptions(nep->ds);
    170:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
    171:   KSPGetOperators(nep->ksp,NULL,NULL,&matflag);
    172:   KSPSetOperators(nep->ksp,nep->function,nep->function_pre,matflag);
    173:   KSPSetFromOptions(nep->ksp);
    174:   PetscRandomSetFromOptions(nep->rand);
    175:   return(0);
    176: }

    180: /*@
    181:    NEPGetTolerances - Gets the tolerance and maximum iteration count used
    182:    by the NEP convergence tests.

    184:    Not Collective

    186:    Input Parameter:
    187: .  nep - the nonlinear eigensolver context

    189:    Output Parameters:
    190: +  abstol - absolute convergence tolerance
    191: .  rtol   - relative convergence tolerance
    192: .  stol   - convergence tolerance in terms of the norm of the change in the
    193:            solution between steps, || delta x || < stol*|| x ||
    194: .  maxit  - maximum number of iterations
    195: -  maxf   - maximum number of function evaluations

    197:    Notes:
    198:    The user can specify NULL for any parameter that is not needed.

    200:    Level: intermediate

    202: .seealso: NEPSetTolerances()
    203: @*/
    204: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *abstol,PetscReal *rtol,PetscReal *stol,PetscInt *maxit,PetscInt *maxf)
    205: {
    208:   if (abstol) *abstol = nep->abstol;
    209:   if (rtol)   *rtol   = nep->rtol;
    210:   if (stol)   *stol   = nep->stol;
    211:   if (maxit)  *maxit  = nep->max_it;
    212:   if (maxf)   *maxf   = nep->max_funcs;
    213:   return(0);
    214: }

    218: /*@
    219:    NEPSetTolerances - Sets various parameters used in convergence tests.

    221:    Logically Collective on NEP

    223:    Input Parameters:
    224: +  nep    - the nonlinear eigensolver context
    225: .  abstol - absolute convergence tolerance
    226: .  rtol   - relative convergence tolerance
    227: .  stol   - convergence tolerance in terms of the norm of the change in the
    228:             solution between steps, || delta x || < stol*|| x ||
    229: .  maxit  - maximum number of iterations
    230: -  maxf   - maximum number of function evaluations

    232:    Options Database Keys:
    233: +    -nep_atol <abstol> - Sets abstol
    234: .    -nep_rtol <rtol> - Sets rtol
    235: .    -nep_stol <stol> - Sets stol
    236: .    -nep_max_it <maxit> - Sets maxit
    237: -    -nep_max_funcs <maxf> - Sets maxf

    239:    Notes:
    240:    Pass 0 for an argument that need not be changed.

    242:    Use PETSC_DECIDE for maxits to assign a reasonably good value, which is
    243:    dependent on the solution method.

    245:    Level: intermediate

    247: .seealso: NEPGetTolerances()
    248: @*/
    249: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal abstol,PetscReal rtol,PetscReal stol,PetscInt maxit,PetscInt maxf)
    250: {
    258:   if (abstol) {
    259:     if (abstol == PETSC_DEFAULT) {
    260:       nep->abstol = PETSC_DEFAULT;
    261:     } else {
    262:       if (abstol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Absolute tolerance %G must be non-negative",abstol);
    263:       nep->abstol = abstol;
    264:     }
    265:   }
    266:   if (rtol) {
    267:     if (rtol == PETSC_DEFAULT) {
    268:       nep->rtol = PETSC_DEFAULT;
    269:     } else {
    270:       if (rtol < 0.0 || 1.0 <= rtol) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Relative tolerance %G must be non-negative and less than 1.0",rtol);
    271:       nep->rtol = rtol;
    272:     }
    273:   }
    274:   if (stol) {
    275:     if (stol == PETSC_DEFAULT) {
    276:       nep->stol = PETSC_DEFAULT;
    277:     } else {
    278:       if (stol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Step tolerance %G must be non-negative",stol);
    279:       nep->stol = stol;
    280:     }
    281:   }
    282:   if (maxit) {
    283:     if (maxit == PETSC_DEFAULT || maxit == PETSC_DECIDE) {
    284:       nep->max_it = 0;
    285:       nep->setupcalled = 0;
    286:     } else {
    287:       if (maxit < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of iterations %D must be non-negative",maxit);
    288:       nep->max_it = maxit;
    289:     }
    290:   }
    291:   if (maxf) {
    292:     if (maxf == PETSC_DEFAULT || maxf == PETSC_DECIDE) {
    293:       nep->max_it = 0;
    294:       nep->setupcalled = 0;
    295:     } else {
    296:       if (maxf < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of function evaluations %D must be non-negative",maxf);
    297:       nep->max_funcs = maxf;
    298:     }
    299:   }
    300:   return(0);
    301: }

    305: /*@
    306:    NEPGetDimensions - Gets the number of eigenvalues to compute
    307:    and the dimension of the subspace.

    309:    Not Collective

    311:    Input Parameter:
    312: .  nep - the nonlinear eigensolver context

    314:    Output Parameters:
    315: +  nev - number of eigenvalues to compute
    316: .  ncv - the maximum dimension of the subspace to be used by the solver
    317: -  mpd - the maximum dimension allowed for the projected problem

    319:    Notes:
    320:    The user can specify NULL for any parameter that is not needed.

    322:    Level: intermediate

    324: .seealso: NEPSetDimensions()
    325: @*/
    326: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
    327: {
    330:   if (nev) *nev = nep->nev;
    331:   if (ncv) *ncv = nep->ncv;
    332:   if (mpd) *mpd = nep->mpd;
    333:   return(0);
    334: }

    338: /*@
    339:    NEPSetDimensions - Sets the number of eigenvalues to compute
    340:    and the dimension of the subspace.

    342:    Logically Collective on NEP

    344:    Input Parameters:
    345: +  nep - the nonlinear eigensolver context
    346: .  nev - number of eigenvalues to compute
    347: .  ncv - the maximum dimension of the subspace to be used by the solver
    348: -  mpd - the maximum dimension allowed for the projected problem

    350:    Options Database Keys:
    351: +  -nep_nev <nev> - Sets the number of eigenvalues
    352: .  -nep_ncv <ncv> - Sets the dimension of the subspace
    353: -  -nep_mpd <mpd> - Sets the maximum projected dimension

    355:    Notes:
    356:    Pass 0 to retain the previous value of any parameter.

    358:    Use PETSC_DECIDE for ncv and mpd to assign a reasonably good value, which is
    359:    dependent on the solution method.

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

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

    370:    Level: intermediate

    372: .seealso: NEPGetDimensions()
    373: @*/
    374: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)
    375: {
    381:   if (nev) {
    382:     if (nev<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
    383:     nep->nev = nev;
    384:     nep->setupcalled = 0;
    385:   }
    386:   if (ncv) {
    387:     if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    388:       nep->ncv = 0;
    389:     } else {
    390:       if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    391:       nep->ncv = ncv;
    392:     }
    393:     nep->setupcalled = 0;
    394:   }
    395:   if (mpd) {
    396:     if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
    397:       nep->mpd = 0;
    398:     } else {
    399:       if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
    400:       nep->mpd = mpd;
    401:     }
    402:   }
    403:   return(0);
    404: }

    408: /*@
    409:     NEPSetWhichEigenpairs - Specifies which portion of the spectrum is
    410:     to be sought.

    412:     Logically Collective on NEP

    414:     Input Parameters:
    415: +   nep   - eigensolver context obtained from NEPCreate()
    416: -   which - the portion of the spectrum to be sought

    418:     Possible values:
    419:     The parameter 'which' can have one of these values

    421: +     NEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
    422: .     NEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
    423: .     NEP_LARGEST_REAL - largest real parts
    424: .     NEP_SMALLEST_REAL - smallest real parts
    425: .     NEP_LARGEST_IMAGINARY - largest imaginary parts
    426: .     NEP_SMALLEST_IMAGINARY - smallest imaginary parts
    427: .     NEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
    428: .     NEP_TARGET_REAL - eigenvalues with real part closest to target
    429: -     NEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target

    431:     Options Database Keys:
    432: +   -nep_largest_magnitude - Sets largest eigenvalues in magnitude
    433: .   -nep_smallest_magnitude - Sets smallest eigenvalues in magnitude
    434: .   -nep_largest_real - Sets largest real parts
    435: .   -nep_smallest_real - Sets smallest real parts
    436: .   -nep_largest_imaginary - Sets largest imaginary parts
    437: .   -nep_smallest_imaginary - Sets smallest imaginary parts
    438: .   -nep_target_magnitude - Sets eigenvalues closest to target
    439: .   -nep_target_real - Sets real parts closest to target
    440: -   -nep_target_imaginary - Sets imaginary parts closest to target

    442:     Notes:
    443:     Not all eigensolvers implemented in NEP account for all the possible values
    444:     stated above. If SLEPc is compiled for real numbers NEP_LARGEST_IMAGINARY
    445:     and NEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
    446:     for eigenvalue selection.

    448:     Level: intermediate

    450: .seealso: NEPGetWhichEigenpairs(), NEPWhich
    451: @*/
    452: PetscErrorCode NEPSetWhichEigenpairs(NEP nep,NEPWhich which)
    453: {
    457:   if (which) {
    458:     if (which==PETSC_DECIDE || which==PETSC_DEFAULT) nep->which = (NEPWhich)0;
    459:     else switch (which) {
    460:       case NEP_LARGEST_MAGNITUDE:
    461:       case NEP_SMALLEST_MAGNITUDE:
    462:       case NEP_LARGEST_REAL:
    463:       case NEP_SMALLEST_REAL:
    464:       case NEP_LARGEST_IMAGINARY:
    465:       case NEP_SMALLEST_IMAGINARY:
    466:       case NEP_TARGET_MAGNITUDE:
    467:       case NEP_TARGET_REAL:
    468: #if defined(PETSC_USE_COMPLEX)
    469:       case NEP_TARGET_IMAGINARY:
    470: #endif
    471:         if (nep->which != which) {
    472:           nep->setupcalled = 0;
    473:           nep->which = which;
    474:         }
    475:         break;
    476:       default:
    477:         SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Invalid 'which' value");
    478:     }
    479:   }
    480:   return(0);
    481: }

    485: /*@C
    486:     NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
    487:     sought.

    489:     Not Collective

    491:     Input Parameter:
    492: .   nep - eigensolver context obtained from NEPCreate()

    494:     Output Parameter:
    495: .   which - the portion of the spectrum to be sought

    497:     Notes:
    498:     See NEPSetWhichEigenpairs() for possible values of 'which'.

    500:     Level: intermediate

    502: .seealso: NEPSetWhichEigenpairs(), NEPWhich
    503: @*/
    504: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)
    505: {
    509:   *which = nep->which;
    510:   return(0);
    511: }

    515: /*@
    516:     NEPSetLagPreconditioner - Determines when the preconditioner is rebuilt in the
    517:     nonlinear solve.

    519:     Logically Collective on NEP

    521:     Input Parameters:
    522: +   nep - the NEP context
    523: -   lag - 0 indicates NEVER rebuild, 1 means rebuild every time the Jacobian is
    524:           computed within the nonlinear iteration, 2 means every second time
    525:           the Jacobian is built, etc.

    527:     Options Database Keys:
    528: .   -nep_lag_preconditioner <lag>

    530:     Notes:
    531:     The default is 1.
    532:     The preconditioner is ALWAYS built in the first iteration of a nonlinear solve.

    534:     Level: intermediate

    536: .seealso: NEPGetLagPreconditioner()
    537: @*/
    538: PetscErrorCode NEPSetLagPreconditioner(NEP nep,PetscInt lag)
    539: {
    543:   if (lag<0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Lag must be non-negative");
    544:   nep->lag = lag;
    545:   return(0);
    546: }

    550: /*@
    551:     NEPGetLagPreconditioner - Indicates how often the preconditioner is rebuilt.

    553:     Not Collective

    555:     Input Parameter:
    556: .   nep - the NEP context

    558:     Output Parameter:
    559: .   lag - the lag parameter

    561:     Level: intermediate

    563: .seealso: NEPSetLagPreconditioner()
    564: @*/
    565: PetscErrorCode NEPGetLagPreconditioner(NEP nep,PetscInt *lag)
    566: {
    570:   *lag = nep->lag;
    571:   return(0);
    572: }

    576: /*@
    577:     NEPSetConstCorrectionTol - Sets a flag to keep the tolerance used
    578:     in the linear solver constant.

    580:     Logically Collective on NEP

    582:     Input Parameters:
    583: +   nep - the NEP context
    584: -   cct - a boolean value

    586:     Options Database Keys:
    587: .   -nep_const_correction_tol <cct>

    589:     Notes:
    590:     By default, an exponentially decreasing tolerance is set in the KSP used
    591:     within the nonlinear iteration, so that each Newton iteration requests
    592:     better accuracy than the previous one. The constant correction tolerance
    593:     flag stops this behaviour.

    595:     Level: intermediate

    597: .seealso: NEPGetConstCorrectionTol()
    598: @*/
    599: PetscErrorCode NEPSetConstCorrectionTol(NEP nep,PetscBool cct)
    600: {
    604:   nep->cctol = cct;
    605:   return(0);
    606: }

    610: /*@
    611:     NEPGetConstCorrectionTol - Returns the constant tolerance flag.

    613:     Not Collective

    615:     Input Parameter:
    616: .   nep - the NEP context

    618:     Output Parameter:
    619: .   cct - the value of the constant tolerance flag

    621:     Level: intermediate

    623: .seealso: NEPSetConstCorrectionTol()
    624: @*/
    625: PetscErrorCode NEPGetConstCorrectionTol(NEP nep,PetscBool *cct)
    626: {
    630:   *cct = nep->cctol;
    631:   return(0);
    632: }

    636: /*@C
    637:     NEPSetConvergenceTest - Sets the function to be used to test convergence
    638:     of the nonlinear iterative solution.

    640:     Logically Collective on NEP

    642:     Input Parameters:
    643: +   nep     - the NEP context
    644: .   func    - a pointer to the convergence test function
    645: .   ctx     - [optional] context for private data for the convergence routine
    646:               (may be NULL)
    647: -   destroy - [optional] destructor for the context (may be NULL;
    648:               PETSC_NULL_FUNCTION in Fortran)

    650:     Calling Sequence of func:
    651: $   func(NEP nep,PetscInt it,PetscReal xnorm,PetscReal snorm,PetscReal fnorm,NEPConvergedReason reason*,void *fctx)

    653: +   nep    - the NEP context
    654: .   it     - iteration number
    655: .   xnorm  - norm of the current solution
    656: .   snorm  - norm of the step (difference between two consecutive solutions)
    657: .   fnorm  - norm of the function (residual)
    658: .   reason - (output) result of the convergence test
    659: -   fctx   - optional context, as set by NEPSetConvergenceTest()

    661:     Level: advanced

    663: .seealso: NEPSetTolerances()
    664: @*/
    665: PetscErrorCode NEPSetConvergenceTest(NEP nep,PetscErrorCode (*func)(NEP,PetscInt,PetscReal,PetscReal,PetscReal,NEPConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
    666: {

    671:   if (nep->convergeddestroy) {
    672:     (*nep->convergeddestroy)(nep->convergedctx);
    673:   }
    674:   nep->converged        = func;
    675:   nep->convergeddestroy = destroy;
    676:   nep->convergedctx     = ctx;
    677:   return(0);
    678: }

    682: /*@
    683:    NEPSetTrackAll - Specifies if the solver must compute the residual of all
    684:    approximate eigenpairs or not.

    686:    Logically Collective on NEP

    688:    Input Parameters:
    689: +  nep      - the eigensolver context
    690: -  trackall - whether compute all residuals or not

    692:    Notes:
    693:    If the user sets trackall=PETSC_TRUE then the solver explicitly computes
    694:    the residual for each eigenpair approximation. Computing the residual is
    695:    usually an expensive operation and solvers commonly compute the associated
    696:    residual to the first unconverged eigenpair.
    697:    The options '-nep_monitor_all' and '-nep_monitor_lg_all' automatically
    698:    activate this option.

    700:    Level: intermediate

    702: .seealso: NEPGetTrackAll()
    703: @*/
    704: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)
    705: {
    709:   nep->trackall = trackall;
    710:   return(0);
    711: }

    715: /*@
    716:    NEPGetTrackAll - Returns the flag indicating whether all residual norms must
    717:    be computed or not.

    719:    Not Collective

    721:    Input Parameter:
    722: .  nep - the eigensolver context

    724:    Output Parameter:
    725: .  trackall - the returned flag

    727:    Level: intermediate

    729: .seealso: NEPSetTrackAll()
    730: @*/
    731: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)
    732: {
    736:   *trackall = nep->trackall;
    737:   return(0);
    738: }

    742: /*@C
    743:    NEPSetOptionsPrefix - Sets the prefix used for searching for all
    744:    NEP options in the database.

    746:    Logically Collective on NEP

    748:    Input Parameters:
    749: +  nep - the nonlinear eigensolver context
    750: -  prefix - the prefix string to prepend to all NEP option requests

    752:    Notes:
    753:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    754:    The first character of all runtime options is AUTOMATICALLY the
    755:    hyphen.

    757:    For example, to distinguish between the runtime options for two
    758:    different NEP contexts, one could call
    759: .vb
    760:       NEPSetOptionsPrefix(nep1,"neig1_")
    761:       NEPSetOptionsPrefix(nep2,"neig2_")
    762: .ve

    764:    Level: advanced

    766: .seealso: NEPAppendOptionsPrefix(), NEPGetOptionsPrefix()
    767: @*/
    768: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char *prefix)
    769: {

    774:   if (!nep->ip) { NEPGetIP(nep,&nep->ip); }
    775:   IPSetOptionsPrefix(nep->ip,prefix);
    776:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    777:   DSSetOptionsPrefix(nep->ds,prefix);
    778:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
    779:   KSPSetOptionsPrefix(nep->ksp,prefix);
    780:   KSPAppendOptionsPrefix(nep->ksp,"nep_");
    781:   PetscObjectSetOptionsPrefix((PetscObject)nep,prefix);
    782:   return(0);
    783: }

    787: /*@C
    788:    NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
    789:    NEP options in the database.

    791:    Logically Collective on NEP

    793:    Input Parameters:
    794: +  nep - the nonlinear eigensolver context
    795: -  prefix - the prefix string to prepend to all NEP option requests

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

    801:    Level: advanced

    803: .seealso: NEPSetOptionsPrefix(), NEPGetOptionsPrefix()
    804: @*/
    805: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char *prefix)
    806: {

    811:   if (!nep->ip) { NEPGetIP(nep,&nep->ip); }
    812:   IPSetOptionsPrefix(nep->ip,prefix);
    813:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    814:   DSSetOptionsPrefix(nep->ds,prefix);
    815:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
    816:   KSPSetOptionsPrefix(nep->ksp,prefix);
    817:   KSPAppendOptionsPrefix(nep->ksp,"nep_");
    818:   PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix);
    819:   return(0);
    820: }

    824: /*@C
    825:    NEPGetOptionsPrefix - Gets the prefix used for searching for all
    826:    NEP options in the database.

    828:    Not Collective

    830:    Input Parameters:
    831: .  nep - the nonlinear eigensolver context

    833:    Output Parameters:
    834: .  prefix - pointer to the prefix string used is returned

    836:    Notes: On the fortran side, the user should pass in a string 'prefix' of
    837:    sufficient length to hold the prefix.

    839:    Level: advanced

    841: .seealso: NEPSetOptionsPrefix(), NEPAppendOptionsPrefix()
    842: @*/
    843: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])
    844: {

    850:   PetscObjectGetOptionsPrefix((PetscObject)nep,prefix);
    851:   return(0);
    852: }