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

Actual source code: mfnopts.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:    MFN routines related to options that can be set via the command-line
     12:    or procedurally
     13: */

     15: #include <slepc/private/mfnimpl.h>
     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 matrix function 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

     30:    Level: developer

     32: .seealso: MFNMonitorSet()
     33: @*/
     34: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char opt[],const char name[],void *ctx)
     35: {
     36:   PetscErrorCode       (*mfunc)(MFN,PetscInt,PetscReal,void*);
     37:   PetscErrorCode       (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
     38:   PetscErrorCode       (*dfunc)(PetscViewerAndFormat**);
     39:   PetscViewerAndFormat *vf;
     40:   PetscViewer          viewer;
     41:   PetscViewerFormat    format;
     42:   PetscViewerType      vtype;
     43:   char                 key[PETSC_MAX_PATH_LEN];
     44:   PetscBool            flg;
     45:   PetscErrorCode       ierr;

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

     51:   PetscViewerGetType(viewer,&vtype);
     52:   SlepcMonitorMakeKey_Internal(name,vtype,format,key);
     53:   PetscFunctionListFind(MFNMonitorList,key,&mfunc);
     54:   PetscFunctionListFind(MFNMonitorCreateList,key,&cfunc);
     55:   PetscFunctionListFind(MFNMonitorDestroyList,key,&dfunc);
     56:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
     57:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

     59:   (*cfunc)(viewer,format,ctx,&vf);
     60:   PetscObjectDereference((PetscObject)viewer);
     61:   MFNMonitorSet(mfn,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
     62:   return(0);
     63: }

     65: /*@
     66:    MFNSetFromOptions - Sets MFN options from the options database.
     67:    This routine must be called before MFNSetUp() if the user is to be
     68:    allowed to set the solver type.

     70:    Collective on mfn

     72:    Input Parameters:
     73: .  mfn - the matrix function context

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

     78:    Level: beginner
     79: @*/
     80: PetscErrorCode MFNSetFromOptions(MFN mfn)
     81: {
     83:   char           type[256];
     84:   PetscBool      set,flg,flg1,flg2;
     85:   PetscReal      r;
     86:   PetscInt       i;

     90:   MFNRegisterAll();
     91:   PetscObjectOptionsBegin((PetscObject)mfn);
     92:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,sizeof(type),&flg);
     93:     if (flg) {
     94:       MFNSetType(mfn,type);
     95:     } else if (!((PetscObject)mfn)->type_name) {
     96:       MFNSetType(mfn,MFNKRYLOV);
     97:     }

     99:     i = mfn->max_it;
    100:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
    101:     if (!flg1) i = PETSC_DEFAULT;
    102:     r = mfn->tol;
    103:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
    104:     if (flg1 || flg2) { MFNSetTolerances(mfn,r,i); }

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

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

    111:     /* -----------------------------------------------------------------------*/
    112:     /*
    113:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
    114:     */
    115:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
    116:     if (set && flg) { MFNMonitorCancel(mfn); }
    117:     MFNMonitorSetFromOptions(mfn,"-mfn_monitor","error_estimate",NULL);

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

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

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

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

    139:    Not Collective

    141:    Input Parameter:
    142: .  mfn - the matrix function context

    144:    Output Parameters:
    145: +  tol - the convergence tolerance
    146: -  maxits - maximum number of iterations

    148:    Notes:
    149:    The user can specify NULL for any parameter that is not needed.

    151:    Level: intermediate

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

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

    168:    Logically Collective on mfn

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

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

    179:    Notes:
    180:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

    182:    Level: intermediate

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

    209: /*@
    210:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

    212:    Not Collective

    214:    Input Parameter:
    215: .  mfn - the matrix function context

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

    220:    Level: intermediate

    222: .seealso: MFNSetDimensions()
    223: @*/
    224: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
    225: {
    229:   *ncv = mfn->ncv;
    230:   return(0);
    231: }

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

    236:    Logically Collective on mfn

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

    242:    Options Database Keys:
    243: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

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

    249:    Level: intermediate

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

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

    272:    Logically Collective on mfn

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

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

    281:    Level: intermediate

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

    287: .seealso: MFNGetErrorIfNotConverged()
    288: @*/
    289: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
    290: {
    294:   mfn->errorifnotconverged = flg;
    295:   return(0);
    296: }

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

    302:    Not Collective

    304:    Input Parameter:
    305: .  mfn - the matrix function context

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

    310:    Level: intermediate

    312: .seealso:  MFNSetErrorIfNotConverged()
    313: @*/
    314: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
    315: {
    319:   *flag = mfn->errorifnotconverged;
    320:   return(0);
    321: }

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

    327:    Logically Collective on mfn

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

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

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

    345:    Level: advanced

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

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

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

    367:    Logically Collective on mfn

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

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

    377:    Level: advanced

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

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

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

    399:    Not Collective

    401:    Input Parameters:
    402: .  mfn - the matrix function context

    404:    Output Parameters:
    405: .  prefix - pointer to the prefix string used is returned

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

    411:    Level: advanced

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

    422:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
    423:   return(0);
    424: }