Date: 2022-08-09T09:05:57+00:00

Actual source code: mfnopts.c
slepc-3.17.2 2022-08-09
Report Typos and Errors

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

     46:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,opt,&viewer,&format,&flg);
     47:   if (!flg) PetscFunctionReturn(0);

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

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

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

     69:    Collective on mfn

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

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

     77:    Level: beginner

     79: .seealso: MFNSetOptionsPrefix()
     80: @*/
     81: PetscErrorCode MFNSetFromOptions(MFN mfn)
     82: {
     84:   char           type[256];
     85:   PetscBool      set,flg,flg1,flg2;
     86:   PetscReal      r;
     87:   PetscInt       i;

     90:   MFNRegisterAll();
     91:   ierr = 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) MFNSetType(mfn,type);
     94:     else if (!((PetscObject)mfn)->type_name) MFNSetType(mfn,MFNKRYLOV);

     96:     i = mfn->max_it;
     97:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
     98:     if (!flg1) i = PETSC_DEFAULT;
     99:     r = mfn->tol;
    100:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",SlepcDefaultTol(mfn->tol),&r,&flg2);
    101:     if (flg1 || flg2) MFNSetTolerances(mfn,r,i);

    103:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
    104:     if (flg) MFNSetDimensions(mfn,i);

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

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

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

    119:     if (mfn->ops->setfromoptions) (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
    120:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
    121:   ierr = PetscOptionsEnd();

    123:   if (!mfn->V) MFNGetBV(mfn,&mfn->V);
    124:   BVSetFromOptions(mfn->V);
    125:   if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
    126:   FNSetFromOptions(mfn->fn);
    127:   PetscFunctionReturn(0);
    128: }

    130: /*@C
    131:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
    132:    by the MFN convergence tests.

    134:    Not Collective

    136:    Input Parameter:
    137: .  mfn - the matrix function context

    139:    Output Parameters:
    140: +  tol - the convergence tolerance
    141: -  maxits - maximum number of iterations

    143:    Notes:
    144:    The user can specify NULL for any parameter that is not needed.

    146:    Level: intermediate

    148: .seealso: MFNSetTolerances()
    149: @*/
    150: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
    151: {
    153:   if (tol)    *tol    = mfn->tol;
    154:   if (maxits) *maxits = mfn->max_it;
    155:   PetscFunctionReturn(0);
    156: }

    158: /*@
    159:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
    160:    by the MFN convergence tests.

    162:    Logically Collective on mfn

    164:    Input Parameters:
    165: +  mfn - the matrix function context
    166: .  tol - the convergence tolerance
    167: -  maxits - maximum number of iterations to use

    169:    Options Database Keys:
    170: +  -mfn_tol <tol> - Sets the convergence tolerance
    171: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

    173:    Notes:
    174:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

    176:    Level: intermediate

    178: .seealso: MFNGetTolerances()
    179: @*/
    180: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
    181: {
    185:   if (tol == PETSC_DEFAULT) {
    186:     mfn->tol = PETSC_DEFAULT;
    187:     mfn->setupcalled = 0;
    188:   } else {
    190:     mfn->tol = tol;
    191:   }
    192:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    193:     mfn->max_it = PETSC_DEFAULT;
    194:     mfn->setupcalled = 0;
    195:   } else {
    197:     mfn->max_it = maxits;
    198:   }
    199:   PetscFunctionReturn(0);
    200: }

    202: /*@
    203:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

    205:    Not Collective

    207:    Input Parameter:
    208: .  mfn - the matrix function context

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

    213:    Level: intermediate

    215: .seealso: MFNSetDimensions()
    216: @*/
    217: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
    218: {
    221:   *ncv = mfn->ncv;
    222:   PetscFunctionReturn(0);
    223: }

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

    228:    Logically Collective on mfn

    230:    Input Parameters:
    231: +  mfn - the matrix function context
    232: -  ncv - the maximum dimension of the subspace to be used by the solver

    234:    Options Database Keys:
    235: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

    237:    Notes:
    238:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
    239:    dependent on the solution method.

    241:    Level: intermediate

    243: .seealso: MFNGetDimensions()
    244: @*/
    245: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
    246: {
    249:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    250:     mfn->ncv = PETSC_DEFAULT;
    251:   } else {
    253:     mfn->ncv = ncv;
    254:   }
    255:   mfn->setupcalled = 0;
    256:   PetscFunctionReturn(0);
    257: }

    259: /*@
    260:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
    261:    solver has not converged.

    263:    Logically Collective on mfn

    265:    Input Parameters:
    266: +  mfn - the matrix function context
    267: -  flg - PETSC_TRUE indicates you want the error generated

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

    272:    Level: intermediate

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

    278: .seealso: MFNGetErrorIfNotConverged()
    279: @*/
    280: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
    281: {
    284:   mfn->errorifnotconverged = flg;
    285:   PetscFunctionReturn(0);
    286: }

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

    292:    Not Collective

    294:    Input Parameter:
    295: .  mfn - the matrix function context

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

    300:    Level: intermediate

    302: .seealso: MFNSetErrorIfNotConverged()
    303: @*/
    304: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
    305: {
    308:   *flag = mfn->errorifnotconverged;
    309:   PetscFunctionReturn(0);
    310: }

    312: /*@C
    313:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
    314:    MFN options in the database.

    316:    Logically Collective on mfn

    318:    Input Parameters:
    319: +  mfn - the matrix function context
    320: -  prefix - the prefix string to prepend to all MFN option requests

    322:    Notes:
    323:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    324:    The first character of all runtime options is AUTOMATICALLY the
    325:    hyphen.

    327:    For example, to distinguish between the runtime options for two
    328:    different MFN contexts, one could call
    329: .vb
    330:       MFNSetOptionsPrefix(mfn1,"fun1_")
    331:       MFNSetOptionsPrefix(mfn2,"fun2_")
    332: .ve

    334:    Level: advanced

    336: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
    337: @*/
    338: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
    339: {
    341:   if (!mfn->V) MFNGetBV(mfn,&mfn->V);
    342:   BVSetOptionsPrefix(mfn->V,prefix);
    343:   if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
    344:   FNSetOptionsPrefix(mfn->fn,prefix);
    345:   PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
    346:   PetscFunctionReturn(0);
    347: }

    349: /*@C
    350:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
    351:    MFN options in the database.

    353:    Logically Collective on mfn

    355:    Input Parameters:
    356: +  mfn - the matrix function context
    357: -  prefix - the prefix string to prepend to all MFN option requests

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

    363:    Level: advanced

    365: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
    366: @*/
    367: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
    368: {
    370:   if (!mfn->V) MFNGetBV(mfn,&mfn->V);
    371:   BVAppendOptionsPrefix(mfn->V,prefix);
    372:   if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
    373:   FNAppendOptionsPrefix(mfn->fn,prefix);
    374:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
    375:   PetscFunctionReturn(0);
    376: }

    378: /*@C
    379:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
    380:    MFN options in the database.

    382:    Not Collective

    384:    Input Parameters:
    385: .  mfn - the matrix function context

    387:    Output Parameters:
    388: .  prefix - pointer to the prefix string used is returned

    390:    Note:
    391:    On the Fortran side, the user should pass in a string 'prefix' of
    392:    sufficient length to hold the prefix.

    394:    Level: advanced

    396: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
    397: @*/
    398: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
    399: {
    402:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
    403:   PetscFunctionReturn(0);
    404: }