Actual source code: mfnopts.c
slepc-3.10.1 2018-10-23
Report Typos and Errors

      1: /*
      2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      4:    Copyright (c) 2002-2018, 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:    MFN routines related to options that can be set via the command-line
     12:    or procedurally
     13: */

     15: #include <slepc/private/mfnimpl.h>   /*I "slepcmfn.h" I*/
     16: #include <petscdraw.h>

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

     22:    Collective on MFN

     24:    Input Parameters:
     25: +  mfn      - the eigensolver context
     26: .  name     - the monitor option name
     27: .  help     - message indicating what monitoring is done
     28: .  manual   - manual page for the monitor
     29: -  monitor  - the monitor function, whose context is a PetscViewerAndFormat

     31:    Level: developer

     33: .seealso: MFNMonitorSet()
     34: @*/
     35: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*))
     36: {
     37:   PetscErrorCode       ierr;
     38:   PetscBool            flg;
     39:   PetscViewer          viewer;
     40:   PetscViewerFormat    format;
     41:   PetscViewerAndFormat *vf;

     44:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,name,&viewer,&format,&flg);
     45:   if (flg) {
     46:     PetscViewerAndFormatCreate(viewer,format,&vf);
     47:     PetscObjectDereference((PetscObject)viewer);
     48:     MFNMonitorSet(mfn,(PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
     49:   }
     50:   return(0);
     51: }

     53: /*@
     54:    MFNSetFromOptions - Sets MFN options from the options database.
     55:    This routine must be called before MFNSetUp() if the user is to be
     56:    allowed to set the solver type.

     58:    Collective on MFN

     60:    Input Parameters:
     61: .  mfn - the matrix function context

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

     66:    Level: beginner
     67: @*/
     68: PetscErrorCode MFNSetFromOptions(MFN mfn)
     69: {
     71:   char           type[256];
     72:   PetscBool      set,flg,flg1,flg2;
     73:   PetscReal      r;
     74:   PetscInt       i;
     75:   PetscDrawLG    lg;

     79:   MFNRegisterAll();
     80:   PetscObjectOptionsBegin((PetscObject)mfn);
     81:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
     82:     if (flg) {
     83:       MFNSetType(mfn,type);
     84:     } else if (!((PetscObject)mfn)->type_name) {
     85:       MFNSetType(mfn,MFNKRYLOV);
     86:     }

     88:     i = mfn->max_it;
     89:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
     90:     if (!flg1) i = PETSC_DEFAULT;
     91:     r = mfn->tol;
     92:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
     93:     if (flg1 || flg2) { MFNSetTolerances(mfn,r,i); }

     95:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
     96:     if (flg) { MFNSetDimensions(mfn,i); }

     98:     PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);

    100:     /* -----------------------------------------------------------------------*/
    101:     /*
    102:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
    103:     */
    104:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
    105:     if (set && flg) {
    106:       MFNMonitorCancel(mfn);
    107:     }
    108:     /*
    109:       Text monitors
    110:     */
    111:     MFNMonitorSetFromOptions(mfn,"-mfn_monitor","Monitor error estimate","MFNMonitorDefault",MFNMonitorDefault);
    112:     /*
    113:       Line graph monitors
    114:     */
    115:     PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",PETSC_FALSE,&flg,&set);
    116:     if (set && flg) {
    117:       MFNMonitorLGCreate(PetscObjectComm((PetscObject)mfn),NULL,"Error estimate",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
    118:       MFNMonitorSet(mfn,MFNMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
    119:     }

    121:     /* -----------------------------------------------------------------------*/
    122:     PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",NULL);

    124:     if (mfn->ops->setfromoptions) {
    125:       (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
    126:     }
    127:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
    128:   PetscOptionsEnd();

    130:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    131:   BVSetFromOptions(mfn->V);
    132:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    133:   FNSetFromOptions(mfn->fn);
    134:   return(0);
    135: }

    137: /*@C
    138:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
    139:    by the MFN convergence tests.

    141:    Not Collective

    143:    Input Parameter:
    144: .  mfn - the matrix function context

    146:    Output Parameters:
    147: +  tol - the convergence tolerance
    148: -  maxits - maximum number of iterations

    150:    Notes:
    151:    The user can specify NULL for any parameter that is not needed.

    153:    Level: intermediate

    155: .seealso: MFNSetTolerances()
    156: @*/
    157: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
    158: {
    161:   if (tol)    *tol    = mfn->tol;
    162:   if (maxits) *maxits = mfn->max_it;
    163:   return(0);
    164: }

    166: /*@
    167:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
    168:    by the MFN convergence tests.

    170:    Logically Collective on MFN

    172:    Input Parameters:
    173: +  mfn - the matrix function context
    174: .  tol - the convergence tolerance
    175: -  maxits - maximum number of iterations to use

    177:    Options Database Keys:
    178: +  -mfn_tol <tol> - Sets the convergence tolerance
    179: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

    181:    Notes:
    182:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

    184:    Level: intermediate

    186: .seealso: MFNGetTolerances()
    187: @*/
    188: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
    189: {
    194:   if (tol == PETSC_DEFAULT) {
    195:     mfn->tol = PETSC_DEFAULT;
    196:     mfn->setupcalled = 0;
    197:   } else {
    198:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    199:     mfn->tol = tol;
    200:   }
    201:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    202:     mfn->max_it = 0;
    203:     mfn->setupcalled = 0;
    204:   } else {
    205:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
    206:     mfn->max_it = maxits;
    207:   }
    208:   return(0);
    209: }

    211: /*@
    212:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

    214:    Not Collective

    216:    Input Parameter:
    217: .  mfn - the matrix function context

    219:    Output Parameter:
    220: .  ncv - the maximum dimension of the subspace to be used by the solver

    222:    Level: intermediate

    224: .seealso: MFNSetDimensions()
    225: @*/
    226: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
    227: {
    231:   *ncv = mfn->ncv;
    232:   return(0);
    233: }

    235: /*@
    236:    MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.

    238:    Logically Collective on MFN

    240:    Input Parameters:
    241: +  mfn - the matrix function context
    242: -  ncv - the maximum dimension of the subspace to be used by the solver

    244:    Options Database Keys:
    245: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

    247:    Notes:
    248:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
    249:    dependent on the solution method.

    251:    Level: intermediate

    253: .seealso: MFNGetDimensions()
    254: @*/
    255: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
    256: {
    260:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    261:     mfn->ncv = 0;
    262:   } else {
    263:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    264:     mfn->ncv = ncv;
    265:   }
    266:   mfn->setupcalled = 0;
    267:   return(0);
    268: }

    270: /*@
    271:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
    272:    solver has not converged.

    274:    Logically Collective on MFN

    276:    Input Parameters:
    277: +  mfn - the matrix function context
    278: -  flg - PETSC_TRUE indicates you want the error generated

    280:    Options Database Keys:
    281: .  -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)

    283:    Level: intermediate

    285:    Note:
    286:    Normally SLEPc continues if the solver fails to converge, you can call
    287:    MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.

    289: .seealso: MFNGetErrorIfNotConverged()
    290: @*/
    291: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
    292: {
    296:   mfn->errorifnotconverged = flg;
    297:   return(0);
    298: }

    300: /*@
    301:    MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
    302:    generate an error if the solver does not converge.

    304:    Not Collective

    306:    Input Parameter:
    307: .  mfn - the matrix function context

    309:    Output Parameter:
    310: .  flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE

    312:    Level: intermediate

    314: .seealso:  MFNSetErrorIfNotConverged()
    315: @*/
    316: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
    317: {
    321:   *flag = mfn->errorifnotconverged;
    322:   return(0);
    323: }

    325: /*@C
    326:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
    327:    MFN options in the database.

    329:    Logically Collective on MFN

    331:    Input Parameters:
    332: +  mfn - the matrix function context
    333: -  prefix - the prefix string to prepend to all MFN option requests

    335:    Notes:
    336:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    337:    The first character of all runtime options is AUTOMATICALLY the
    338:    hyphen.

    340:    For example, to distinguish between the runtime options for two
    341:    different MFN contexts, one could call
    342: .vb
    343:       MFNSetOptionsPrefix(mfn1,"fun1_")
    344:       MFNSetOptionsPrefix(mfn2,"fun2_")
    345: .ve

    347:    Level: advanced

    349: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
    350: @*/
    351: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
    352: {

    357:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    358:   BVSetOptionsPrefix(mfn->V,prefix);
    359:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    360:   FNSetOptionsPrefix(mfn->fn,prefix);
    361:   PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
    362:   return(0);
    363: }

    365: /*@C
    366:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
    367:    MFN options in the database.

    369:    Logically Collective on MFN

    371:    Input Parameters:
    372: +  mfn - the matrix function context
    373: -  prefix - the prefix string to prepend to all MFN option requests

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

    379:    Level: advanced

    381: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
    382: @*/
    383: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
    384: {

    389:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    390:   BVAppendOptionsPrefix(mfn->V,prefix);
    391:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    392:   FNAppendOptionsPrefix(mfn->fn,prefix);
    393:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
    394:   return(0);
    395: }

    397: /*@C
    398:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
    399:    MFN options in the database.

    401:    Not Collective

    403:    Input Parameters:
    404: .  mfn - the matrix function context

    406:    Output Parameters:
    407: .  prefix - pointer to the prefix string used is returned

    409:    Note:
    410:    On the Fortran side, the user should pass in a string 'prefix' of
    411:    sufficient length to hold the prefix.

    413:    Level: advanced

    415: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
    416: @*/
    417: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
    418: {

    424:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
    425:   return(0);
    426: }