Date: 2015-09-03T15:05:55+00:00

Actual source code: nepopts.c
slepc-3.6.1 2015-09-03
Report Typos and Errors

      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-2015, 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,flg1,flg2,flg3,flg4,flg5;
     49:   PetscReal        r1,r2,r3;
     50:   PetscScalar      s;
     51:   PetscInt         i,j,k;
     52:   PetscViewer      monviewer;
     53:   SlepcConvMonitor ctx;

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

     66:     PetscOptionsEnum("-nep_refine","Iterative refinement method","NEPSetRefine",NEPRefineTypes,(PetscEnum)nep->refine,(PetscEnum*)&nep->refine,NULL);

     68:     i = nep->npart;
     69:     PetscOptionsInt("-nep_refine_partitions","Number of partitions of the communicator for iterative refinement","NEPSetRefine",nep->npart,&i,&flg1);
     70:     r1 = nep->reftol;
     71:     PetscOptionsReal("-nep_refine_tol","Tolerance for iterative refinement","NEPSetRefine",nep->reftol,&r1,&flg2);
     72:     j = nep->rits;
     73:     PetscOptionsInt("-nep_refine_its","Maximum number of iterations for iterative refinement","NEPSetRefine",nep->rits,&j,&flg3);
     74:     if (flg1 || flg2 || flg3) {
     75:       NEPSetRefine(nep,nep->refine,i,r1,j);
     76:     }

     78:     i = nep->max_it? nep->max_it: PETSC_DEFAULT;
     79:     PetscOptionsInt("-nep_max_it","Maximum number of iterations","NEPSetTolerances",nep->max_it,&i,&flg1);
     80:     j = nep->max_funcs? nep->max_funcs: PETSC_DEFAULT;
     81:     PetscOptionsInt("-nep_max_funcs","Maximum number of function evaluations","NEPSetTolerances",nep->max_funcs,&j,&flg2);
     82:     r1 = nep->abstol;
     83:     PetscOptionsReal("-nep_atol","Absolute tolerance for residual norm","NEPSetTolerances",nep->abstol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->abstol,&r1,&flg3);
     84:     r2 = nep->rtol;
     85:     PetscOptionsReal("-nep_rtol","Relative tolerance for residual norm","NEPSetTolerances",nep->rtol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->rtol,&r2,&flg4);
     86:     r3 = nep->stol;
     87:     PetscOptionsReal("-nep_stol","Relative tolerance for step length","NEPSetTolerances",nep->stol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:nep->stol,&r3,&flg5);
     88:     if (flg1 || flg2 || flg3 || flg4 || flg5) {
     89:       NEPSetTolerances(nep,r1,r2,r3,i,j);
     90:     }

     92:     flg  = PETSC_FALSE;
     93:     PetscOptionsBool("-nep_convergence_default","Default (relative error) convergence test","NEPSetConvergenceTest",flg,&flg,NULL);
     94:     if (flg) {
     95:       NEPSetConvergenceTest(nep,NEPConvergedDefault,NULL,NULL);
     96:     }

     98:     i = nep->nev;
     99:     PetscOptionsInt("-nep_nev","Number of eigenvalues to compute","NEPSetDimensions",nep->nev,&i,&flg1);
    100:     j = nep->ncv? nep->ncv: PETSC_DEFAULT;
    101:     PetscOptionsInt("-nep_ncv","Number of basis vectors","NEPSetDimensions",nep->ncv,&j,&flg2);
    102:     k = nep->mpd? nep->mpd: PETSC_DEFAULT;
    103:     PetscOptionsInt("-nep_mpd","Maximum dimension of projected problem","NEPSetDimensions",nep->mpd,&k,&flg3);
    104:     if (flg1 || flg2 || flg3) {
    105:       NEPSetDimensions(nep,i,j,k);
    106:     }

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

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

    114:     PetscOptionsScalar("-nep_target","Value of the target","NEPSetTarget",nep->target,&s,&flg);
    115:     if (flg) {
    116:       NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE);
    117:       NEPSetTarget(nep,s);
    118:     }

    120:     /* -----------------------------------------------------------------------*/
    121:     /*
    122:       Cancels all monitors hardwired into code before call to NEPSetFromOptions()
    123:     */
    124:     flg = PETSC_FALSE;
    125:     PetscOptionsBool("-nep_monitor_cancel","Remove any hardwired monitor routines","NEPMonitorCancel",flg,&flg,NULL);
    126:     if (flg) {
    127:       NEPMonitorCancel(nep);
    128:     }
    129:     /*
    130:       Prints approximate eigenvalues and error estimates at each iteration
    131:     */
    132:     PetscOptionsString("-nep_monitor","Monitor first unconverged approximate eigenvalue and error estimate","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    133:     if (flg) {
    134:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
    135:       NEPMonitorSet(nep,NEPMonitorFirst,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    136:     }
    137:     PetscOptionsString("-nep_monitor_conv","Monitor approximate eigenvalues and error estimates as they converge","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    138:     if (flg) {
    139:       PetscNew(&ctx);
    140:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&ctx->viewer);
    141:       NEPMonitorSet(nep,NEPMonitorConverged,ctx,(PetscErrorCode (*)(void**))SlepcConvMonitorDestroy);
    142:     }
    143:     PetscOptionsString("-nep_monitor_all","Monitor approximate eigenvalues and error estimates","NEPMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
    144:     if (flg) {
    145:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)nep),monfilename,&monviewer);
    146:       NEPMonitorSet(nep,NEPMonitorAll,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    147:       NEPSetTrackAll(nep,PETSC_TRUE);
    148:     }
    149:     flg = PETSC_FALSE;
    150:     PetscOptionsBool("-nep_monitor_lg","Monitor first unconverged approximate error estimate graphically","NEPMonitorSet",flg,&flg,NULL);
    151:     if (flg) {
    152:       NEPMonitorSet(nep,NEPMonitorLG,NULL,NULL);
    153:     }
    154:     flg = PETSC_FALSE;
    155:     PetscOptionsBool("-nep_monitor_lg_all","Monitor error estimates graphically","NEPMonitorSet",flg,&flg,NULL);
    156:     if (flg) {
    157:       NEPMonitorSet(nep,NEPMonitorLGAll,NULL,NULL);
    158:       NEPSetTrackAll(nep,PETSC_TRUE);
    159:     }
    160:   /* -----------------------------------------------------------------------*/

    162:     PetscOptionsBoolGroupBegin("-nep_largest_magnitude","compute largest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
    163:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_MAGNITUDE); }
    164:     PetscOptionsBoolGroup("-nep_smallest_magnitude","compute smallest eigenvalues in magnitude","NEPSetWhichEigenpairs",&flg);
    165:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_MAGNITUDE); }
    166:     PetscOptionsBoolGroup("-nep_largest_real","compute largest real parts","NEPSetWhichEigenpairs",&flg);
    167:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_REAL); }
    168:     PetscOptionsBoolGroup("-nep_smallest_real","compute smallest real parts","NEPSetWhichEigenpairs",&flg);
    169:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_REAL); }
    170:     PetscOptionsBoolGroup("-nep_largest_imaginary","compute largest imaginary parts","NEPSetWhichEigenpairs",&flg);
    171:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_LARGEST_IMAGINARY); }
    172:     PetscOptionsBoolGroup("-nep_smallest_imaginary","compute smallest imaginary parts","NEPSetWhichEigenpairs",&flg);
    173:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_SMALLEST_IMAGINARY); }
    174:     PetscOptionsBoolGroup("-nep_target_magnitude","compute nearest eigenvalues to target","NEPSetWhichEigenpairs",&flg);
    175:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_MAGNITUDE); }
    176:     PetscOptionsBoolGroup("-nep_target_real","compute eigenvalues with real parts close to target","NEPSetWhichEigenpairs",&flg);
    177:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_REAL); }
    178:     PetscOptionsBoolGroupEnd("-nep_target_imaginary","compute eigenvalues with imaginary parts close to target","NEPSetWhichEigenpairs",&flg);
    179:     if (flg) { NEPSetWhichEigenpairs(nep,NEP_TARGET_IMAGINARY); }

    181:     PetscOptionsName("-nep_view","Print detailed information on solver used","NEPView",0);
    182:     PetscOptionsName("-nep_view_vectors","View computed eigenvectors","NEPVectorsView",0);
    183:     PetscOptionsName("-nep_view_values","View computed eigenvalues","NEPValuesView",0);
    184:     PetscOptionsName("-nep_converged_reason","Print reason for convergence, and number of iterations","NEPReasonView",0);
    185:     PetscOptionsName("-nep_error_absolute","Print absolute errors of each eigenpair","NEPErrorView",0);
    186:     PetscOptionsName("-nep_error_relative","Print relative errors of each eigenpair","NEPErrorView",0);

    188:     if (nep->ops->setfromoptions) {
    189:       (*nep->ops->setfromoptions)(PetscOptionsObject,nep);
    190:     }
    191:     PetscObjectProcessOptionsHandlers((PetscObject)nep);
    192:   PetscOptionsEnd();

    194:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
    195:   BVSetFromOptions(nep->V);
    196:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
    197:   RGSetFromOptions(nep->rg);
    198:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    199:   DSSetFromOptions(nep->ds);
    200:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
    201:   KSPSetOperators(nep->ksp,nep->function,nep->function_pre);
    202:   KSPSetFromOptions(nep->ksp);
    203:   PetscRandomSetFromOptions(nep->rand);
    204:   return(0);
    205: }

    209: /*@
    210:    NEPGetTolerances - Gets the tolerance and maximum iteration count used
    211:    by the NEP convergence tests.

    213:    Not Collective

    215:    Input Parameter:
    216: .  nep - the nonlinear eigensolver context

    218:    Output Parameters:
    219: +  abstol - absolute convergence tolerance
    220: .  rtol   - relative convergence tolerance
    221: .  stol   - convergence tolerance in terms of the norm of the change in the
    222:            solution between steps, || delta x || < stol*|| x ||
    223: .  maxit  - maximum number of iterations
    224: -  maxf   - maximum number of function evaluations

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

    229:    Level: intermediate

    231: .seealso: NEPSetTolerances()
    232: @*/
    233: PetscErrorCode NEPGetTolerances(NEP nep,PetscReal *abstol,PetscReal *rtol,PetscReal *stol,PetscInt *maxit,PetscInt *maxf)
    234: {
    237:   if (abstol) *abstol = nep->abstol;
    238:   if (rtol)   *rtol   = nep->rtol;
    239:   if (stol)   *stol   = nep->stol;
    240:   if (maxit)  *maxit  = nep->max_it;
    241:   if (maxf)   *maxf   = nep->max_funcs;
    242:   return(0);
    243: }

    247: /*@
    248:    NEPSetTolerances - Sets various parameters used in convergence tests.

    250:    Logically Collective on NEP

    252:    Input Parameters:
    253: +  nep    - the nonlinear eigensolver context
    254: .  abstol - absolute convergence tolerance
    255: .  rtol   - relative convergence tolerance
    256: .  stol   - convergence tolerance in terms of the norm of the change in the
    257:             solution between steps, || delta x || < stol*|| x ||
    258: .  maxit  - maximum number of iterations
    259: -  maxf   - maximum number of function evaluations

    261:    Options Database Keys:
    262: +    -nep_atol <abstol> - Sets abstol
    263: .    -nep_rtol <rtol> - Sets rtol
    264: .    -nep_stol <stol> - Sets stol
    265: .    -nep_max_it <maxit> - Sets maxit
    266: -    -nep_max_funcs <maxf> - Sets maxf

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

    271:    Level: intermediate

    273: .seealso: NEPGetTolerances()
    274: @*/
    275: PetscErrorCode NEPSetTolerances(NEP nep,PetscReal abstol,PetscReal rtol,PetscReal stol,PetscInt maxit,PetscInt maxf)
    276: {
    284:   if (abstol == PETSC_DEFAULT) {
    285:     nep->abstol = PETSC_DEFAULT;
    286:   } else {
    287:     if (abstol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Absolute tolerance %g must be non-negative",(double)abstol);
    288:     nep->abstol = abstol;
    289:   }
    290:   if (rtol == PETSC_DEFAULT) {
    291:     nep->rtol = PETSC_DEFAULT;
    292:   } else {
    293:     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",(double)rtol);
    294:     nep->rtol = rtol;
    295:   }
    296:   if (stol == PETSC_DEFAULT) {
    297:     nep->stol = PETSC_DEFAULT;
    298:   } else {
    299:     if (stol < 0.0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Step tolerance %g must be non-negative",(double)stol);
    300:     nep->stol = stol;
    301:   }
    302:   if (maxit == PETSC_DEFAULT || maxit == PETSC_DECIDE) {
    303:     nep->max_it = 0;
    304:     nep->state = NEP_STATE_INITIAL;
    305:   } else {
    306:     if (maxit < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of iterations %D must be non-negative",maxit);
    307:     nep->max_it = maxit;
    308:   }
    309:   if (maxf == PETSC_DEFAULT || maxf == PETSC_DECIDE) {
    310:     nep->max_it = 0;
    311:     nep->state = NEP_STATE_INITIAL;
    312:   } else {
    313:     if (maxf < 0) SETERRQ1(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Maximum number of function evaluations %D must be non-negative",maxf);
    314:     nep->max_funcs = maxf;
    315:   }
    316:   return(0);
    317: }

    321: /*@
    322:    NEPGetDimensions - Gets the number of eigenvalues to compute
    323:    and the dimension of the subspace.

    325:    Not Collective

    327:    Input Parameter:
    328: .  nep - the nonlinear eigensolver context

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

    335:    Notes:
    336:    The user can specify NULL for any parameter that is not needed.

    338:    Level: intermediate

    340: .seealso: NEPSetDimensions()
    341: @*/
    342: PetscErrorCode NEPGetDimensions(NEP nep,PetscInt *nev,PetscInt *ncv,PetscInt *mpd)
    343: {
    346:   if (nev) *nev = nep->nev;
    347:   if (ncv) *ncv = nep->ncv;
    348:   if (mpd) *mpd = nep->mpd;
    349:   return(0);
    350: }

    354: /*@
    355:    NEPSetDimensions - Sets the number of eigenvalues to compute
    356:    and the dimension of the subspace.

    358:    Logically Collective on NEP

    360:    Input Parameters:
    361: +  nep - the nonlinear eigensolver context
    362: .  nev - number of eigenvalues to compute
    363: .  ncv - the maximum dimension of the subspace to be used by the solver
    364: -  mpd - the maximum dimension allowed for the projected problem

    366:    Options Database Keys:
    367: +  -nep_nev <nev> - Sets the number of eigenvalues
    368: .  -nep_ncv <ncv> - Sets the dimension of the subspace
    369: -  -nep_mpd <mpd> - Sets the maximum projected dimension

    371:    Notes:
    372:    Use PETSC_DEFAULT for ncv and mpd to assign a reasonably good value, which is
    373:    dependent on the solution method.

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

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

    384:    Level: intermediate

    386: .seealso: NEPGetDimensions()
    387: @*/
    388: PetscErrorCode NEPSetDimensions(NEP nep,PetscInt nev,PetscInt ncv,PetscInt mpd)
    389: {
    395:   if (nev<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of nev. Must be > 0");
    396:   nep->nev = nev;
    397:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    398:     nep->ncv = 0;
    399:   } else {
    400:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    401:     nep->ncv = ncv;
    402:   }
    403:   if (mpd == PETSC_DECIDE || mpd == PETSC_DEFAULT) {
    404:     nep->mpd = 0;
    405:   } else {
    406:     if (mpd<1) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of mpd. Must be > 0");
    407:     nep->mpd = mpd;
    408:   }
    409:   nep->state = NEP_STATE_INITIAL;
    410:   return(0);
    411: }

    415: /*@
    416:     NEPSetWhichEigenpairs - Specifies which portion of the spectrum is
    417:     to be sought.

    419:     Logically Collective on NEP

    421:     Input Parameters:
    422: +   nep   - eigensolver context obtained from NEPCreate()
    423: -   which - the portion of the spectrum to be sought

    425:     Possible values:
    426:     The parameter 'which' can have one of these values

    428: +     NEP_LARGEST_MAGNITUDE - largest eigenvalues in magnitude (default)
    429: .     NEP_SMALLEST_MAGNITUDE - smallest eigenvalues in magnitude
    430: .     NEP_LARGEST_REAL - largest real parts
    431: .     NEP_SMALLEST_REAL - smallest real parts
    432: .     NEP_LARGEST_IMAGINARY - largest imaginary parts
    433: .     NEP_SMALLEST_IMAGINARY - smallest imaginary parts
    434: .     NEP_TARGET_MAGNITUDE - eigenvalues closest to the target (in magnitude)
    435: .     NEP_TARGET_REAL - eigenvalues with real part closest to target
    436: -     NEP_TARGET_IMAGINARY - eigenvalues with imaginary part closest to target

    438:     Options Database Keys:
    439: +   -nep_largest_magnitude - Sets largest eigenvalues in magnitude
    440: .   -nep_smallest_magnitude - Sets smallest eigenvalues in magnitude
    441: .   -nep_largest_real - Sets largest real parts
    442: .   -nep_smallest_real - Sets smallest real parts
    443: .   -nep_largest_imaginary - Sets largest imaginary parts
    444: .   -nep_smallest_imaginary - Sets smallest imaginary parts
    445: .   -nep_target_magnitude - Sets eigenvalues closest to target
    446: .   -nep_target_real - Sets real parts closest to target
    447: -   -nep_target_imaginary - Sets imaginary parts closest to target

    449:     Notes:
    450:     Not all eigensolvers implemented in NEP account for all the possible values
    451:     stated above. If SLEPc is compiled for real numbers NEP_LARGEST_IMAGINARY
    452:     and NEP_SMALLEST_IMAGINARY use the absolute value of the imaginary part
    453:     for eigenvalue selection.

    455:     Level: intermediate

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

    489: /*@
    490:     NEPGetWhichEigenpairs - Returns which portion of the spectrum is to be
    491:     sought.

    493:     Not Collective

    495:     Input Parameter:
    496: .   nep - eigensolver context obtained from NEPCreate()

    498:     Output Parameter:
    499: .   which - the portion of the spectrum to be sought

    501:     Notes:
    502:     See NEPSetWhichEigenpairs() for possible values of 'which'.

    504:     Level: intermediate

    506: .seealso: NEPSetWhichEigenpairs(), NEPWhich
    507: @*/
    508: PetscErrorCode NEPGetWhichEigenpairs(NEP nep,NEPWhich *which)
    509: {
    513:   *which = nep->which;
    514:   return(0);
    515: }

    519: /*@
    520:     NEPSetLagPreconditioner - Determines when the preconditioner is rebuilt in the
    521:     nonlinear solve.

    523:     Logically Collective on NEP

    525:     Input Parameters:
    526: +   nep - the NEP context
    527: -   lag - 0 indicates NEVER rebuild, 1 means rebuild every time the Jacobian is
    528:           computed within the nonlinear iteration, 2 means every second time
    529:           the Jacobian is built, etc.

    531:     Options Database Keys:
    532: .   -nep_lag_preconditioner <lag>

    534:     Notes:
    535:     The default is 1.
    536:     The preconditioner is ALWAYS built in the first iteration of a nonlinear solve.

    538:     Level: intermediate

    540: .seealso: NEPGetLagPreconditioner()
    541: @*/
    542: PetscErrorCode NEPSetLagPreconditioner(NEP nep,PetscInt lag)
    543: {
    547:   if (lag<0) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Lag must be non-negative");
    548:   nep->lag = lag;
    549:   return(0);
    550: }

    554: /*@
    555:     NEPGetLagPreconditioner - Indicates how often the preconditioner is rebuilt.

    557:     Not Collective

    559:     Input Parameter:
    560: .   nep - the NEP context

    562:     Output Parameter:
    563: .   lag - the lag parameter

    565:     Level: intermediate

    567: .seealso: NEPSetLagPreconditioner()
    568: @*/
    569: PetscErrorCode NEPGetLagPreconditioner(NEP nep,PetscInt *lag)
    570: {
    574:   *lag = nep->lag;
    575:   return(0);
    576: }

    580: /*@
    581:     NEPSetConstCorrectionTol - Sets a flag to keep the tolerance used
    582:     in the linear solver constant.

    584:     Logically Collective on NEP

    586:     Input Parameters:
    587: +   nep - the NEP context
    588: -   cct - a boolean value

    590:     Options Database Keys:
    591: .   -nep_const_correction_tol <cct>

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

    599:     Level: intermediate

    601: .seealso: NEPGetConstCorrectionTol()
    602: @*/
    603: PetscErrorCode NEPSetConstCorrectionTol(NEP nep,PetscBool cct)
    604: {
    608:   nep->cctol = cct;
    609:   return(0);
    610: }

    614: /*@
    615:     NEPGetConstCorrectionTol - Returns the constant tolerance flag.

    617:     Not Collective

    619:     Input Parameter:
    620: .   nep - the NEP context

    622:     Output Parameter:
    623: .   cct - the value of the constant tolerance flag

    625:     Level: intermediate

    627: .seealso: NEPSetConstCorrectionTol()
    628: @*/
    629: PetscErrorCode NEPGetConstCorrectionTol(NEP nep,PetscBool *cct)
    630: {
    634:   *cct = nep->cctol;
    635:   return(0);
    636: }

    640: /*@C
    641:     NEPSetConvergenceTest - Sets the function to be used to test convergence
    642:     of the nonlinear iterative solution.

    644:     Logically Collective on NEP

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

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

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

    665:     Level: advanced

    667: .seealso: NEPSetTolerances()
    668: @*/
    669: PetscErrorCode NEPSetConvergenceTest(NEP nep,PetscErrorCode (*func)(NEP,PetscInt,PetscReal,PetscReal,PetscReal,NEPConvergedReason*,void*),void* ctx,PetscErrorCode (*destroy)(void*))
    670: {

    675:   if (nep->convergeddestroy) {
    676:     (*nep->convergeddestroy)(nep->convergedctx);
    677:   }
    678:   nep->converged        = func;
    679:   nep->convergeddestroy = destroy;
    680:   nep->convergedctx     = ctx;
    681:   return(0);
    682: }

    686: /*@
    687:    NEPSetTrackAll - Specifies if the solver must compute the residual of all
    688:    approximate eigenpairs or not.

    690:    Logically Collective on NEP

    692:    Input Parameters:
    693: +  nep      - the eigensolver context
    694: -  trackall - whether compute all residuals or not

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

    704:    Level: developer

    706: .seealso: NEPGetTrackAll()
    707: @*/
    708: PetscErrorCode NEPSetTrackAll(NEP nep,PetscBool trackall)
    709: {
    713:   nep->trackall = trackall;
    714:   return(0);
    715: }

    719: /*@
    720:    NEPGetTrackAll - Returns the flag indicating whether all residual norms must
    721:    be computed or not.

    723:    Not Collective

    725:    Input Parameter:
    726: .  nep - the eigensolver context

    728:    Output Parameter:
    729: .  trackall - the returned flag

    731:    Level: developer

    733: .seealso: NEPSetTrackAll()
    734: @*/
    735: PetscErrorCode NEPGetTrackAll(NEP nep,PetscBool *trackall)
    736: {
    740:   *trackall = nep->trackall;
    741:   return(0);
    742: }

    746: /*@
    747:    NEPSetRefine - Specifies the refinement type (and options) to be used
    748:    after the solve.

    750:    Logically Collective on NEP

    752:    Input Parameters:
    753: +  nep    - the nonlinear eigensolver context
    754: .  refine - refinement type
    755: .  npart  - number of partitions of the communicator
    756: .  tol    - the convergence tolerance
    757: -  its    - maximum number of refinement iterations

    759:    Options Database Keys:
    760: +  -nep_refine <type> - refinement type, one of <none,simple,multiple>
    761: .  -nep_refine_partitions <n> - the number of partitions
    762: .  -nep_refine_tol <tol> - the tolerance
    763: -  -nep_refine_its <its> - number of iterations

    765:    Notes:
    766:    By default, iterative refinement is disabled, since it may be very
    767:    costly. There are two possible refinement strategies: simple and multiple.
    768:    The simple approach performs iterative refinement on each of the
    769:    converged eigenpairs individually, whereas the multiple strategy works
    770:    with the invariant pair as a whole, refining all eigenpairs simultaneously.
    771:    The latter may be required for the case of multiple eigenvalues.

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

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

    784:    Level: intermediate

    786: .seealso: NEPGetRefine()
    787: @*/
    788: PetscErrorCode NEPSetRefine(NEP nep,NEPRefine refine,PetscInt npart,PetscReal tol,PetscInt its)
    789: {
    791:   PetscMPIInt    size;

    799:   nep->refine = refine;
    800:   if (refine) {  /* process parameters only if not REFINE_NONE */
    801:     if (npart == PETSC_DEFAULT || npart == PETSC_DECIDE) {
    802:       nep->npart = 1;
    803:     } else {
    804:       MPI_Comm_size(PetscObjectComm((PetscObject)nep),&size);
    805:       if (npart<1 || npart>size) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of npart");
    806:       nep->npart = npart;
    807:     }
    808:     if (tol == PETSC_DEFAULT || tol == PETSC_DECIDE) {
    809:       nep->reftol = nep->rtol;
    810:     } else {
    811:       if (tol<=0.0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    812:       nep->reftol = tol;
    813:     }
    814:     if (its==PETSC_DECIDE || its==PETSC_DEFAULT) {
    815:       nep->rits = PETSC_DEFAULT;
    816:     } else {
    817:       if (its<0) SETERRQ(PetscObjectComm((PetscObject)nep),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of its. Must be >= 0");
    818:       nep->rits = its;
    819:     }
    820:   }
    821:   nep->state = NEP_STATE_INITIAL;
    822:   return(0);
    823: }

    827: /*@
    828:    NEPGetRefine - Gets the refinement strategy used by the NEP object, and the
    829:    associated parameters.

    831:    Not Collective

    833:    Input Parameter:
    834: .  nep - the nonlinear eigensolver context

    836:    Output Parameters:
    837: +  refine - refinement type
    838: .  npart  - number of partitions of the communicator
    839: .  tol    - the convergence tolerance
    840: -  its    - maximum number of refinement iterations

    842:    Level: intermediate

    844:    Note:
    845:    The user can specify NULL for any parameter that is not needed.

    847: .seealso: NEPSetRefine()
    848: @*/
    849: PetscErrorCode NEPGetRefine(NEP nep,NEPRefine *refine,PetscInt *npart,PetscReal *tol,PetscInt *its)
    850: {
    853:   if (refine) *refine = nep->refine;
    854:   if (npart)  *npart  = nep->npart;
    855:   if (tol)    *tol    = nep->reftol;
    856:   if (its)    *its    = nep->rits;
    857:   return(0);
    858: }

    862: /*@C
    863:    NEPSetOptionsPrefix - Sets the prefix used for searching for all
    864:    NEP options in the database.

    866:    Logically Collective on NEP

    868:    Input Parameters:
    869: +  nep - the nonlinear eigensolver context
    870: -  prefix - the prefix string to prepend to all NEP option requests

    872:    Notes:
    873:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    874:    The first character of all runtime options is AUTOMATICALLY the
    875:    hyphen.

    877:    For example, to distinguish between the runtime options for two
    878:    different NEP contexts, one could call
    879: .vb
    880:       NEPSetOptionsPrefix(nep1,"neig1_")
    881:       NEPSetOptionsPrefix(nep2,"neig2_")
    882: .ve

    884:    Level: advanced

    886: .seealso: NEPAppendOptionsPrefix(), NEPGetOptionsPrefix()
    887: @*/
    888: PetscErrorCode NEPSetOptionsPrefix(NEP nep,const char *prefix)
    889: {

    894:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
    895:   BVSetOptionsPrefix(nep->V,prefix);
    896:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    897:   DSSetOptionsPrefix(nep->ds,prefix);
    898:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
    899:   RGSetOptionsPrefix(nep->rg,prefix);
    900:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
    901:   KSPSetOptionsPrefix(nep->ksp,prefix);
    902:   KSPAppendOptionsPrefix(nep->ksp,"nep_");
    903:   PetscObjectSetOptionsPrefix((PetscObject)nep,prefix);
    904:   return(0);
    905: }

    909: /*@C
    910:    NEPAppendOptionsPrefix - Appends to the prefix used for searching for all
    911:    NEP options in the database.

    913:    Logically Collective on NEP

    915:    Input Parameters:
    916: +  nep - the nonlinear eigensolver context
    917: -  prefix - the prefix string to prepend to all NEP option requests

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

    923:    Level: advanced

    925: .seealso: NEPSetOptionsPrefix(), NEPGetOptionsPrefix()
    926: @*/
    927: PetscErrorCode NEPAppendOptionsPrefix(NEP nep,const char *prefix)
    928: {

    933:   if (!nep->V) { NEPGetBV(nep,&nep->V); }
    934:   BVSetOptionsPrefix(nep->V,prefix);
    935:   if (!nep->ds) { NEPGetDS(nep,&nep->ds); }
    936:   DSSetOptionsPrefix(nep->ds,prefix);
    937:   if (!nep->rg) { NEPGetRG(nep,&nep->rg); }
    938:   RGSetOptionsPrefix(nep->rg,prefix);
    939:   if (!nep->ksp) { NEPGetKSP(nep,&nep->ksp); }
    940:   KSPSetOptionsPrefix(nep->ksp,prefix);
    941:   KSPAppendOptionsPrefix(nep->ksp,"nep_");
    942:   PetscObjectAppendOptionsPrefix((PetscObject)nep,prefix);
    943:   return(0);
    944: }

    948: /*@C
    949:    NEPGetOptionsPrefix - Gets the prefix used for searching for all
    950:    NEP options in the database.

    952:    Not Collective

    954:    Input Parameters:
    955: .  nep - the nonlinear eigensolver context

    957:    Output Parameters:
    958: .  prefix - pointer to the prefix string used is returned

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

    963:    Level: advanced

    965: .seealso: NEPSetOptionsPrefix(), NEPAppendOptionsPrefix()
    966: @*/
    967: PetscErrorCode NEPGetOptionsPrefix(NEP nep,const char *prefix[])
    968: {

    974:   PetscObjectGetOptionsPrefix((PetscObject)nep,prefix);
    975:   return(0);
    976: }