Date: 2016-09-29T11:13:10+00:00

Actual source code: mfnopts.c
slepc-3.7.3 2016-09-29
Report Typos and Errors

      1: /*
      2:       MFN 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-2016, 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/mfnimpl.h>   /*I "slepcmfn.h" I*/
     26: #include <petscdraw.h>

     30: /*@C
     31:    MFNMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
     32:    indicated by the user.

     34:    Collective on MFN

     36:    Input Parameters:
     37: +  mfn      - the eigensolver context
     38: .  name     - the monitor option name
     39: .  help     - message indicating what monitoring is done
     40: .  manual   - manual page for the monitor
     41: .  monitor  - the monitor function, whose context is a PetscViewerAndFormat
     42: -  trackall - whether this monitor tracks all eigenvalues or not

     44:    Level: developer

     46: .seealso: MFNMonitorSet(), MFNSetTrackAll(), MFNConvMonitorSetFromOptions()
     47: @*/
     48: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*))
     49: {
     50:   PetscErrorCode       ierr;
     51:   PetscBool            flg;
     52:   PetscViewer          viewer;
     53:   PetscViewerFormat    format;
     54:   PetscViewerAndFormat *vf;

     57:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,name,&viewer,&format,&flg);
     58:   if (flg) {
     59:     PetscViewerAndFormatCreate(viewer,format,&vf);
     60:     PetscObjectDereference((PetscObject)viewer);
     61:     MFNMonitorSet(mfn,(PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
     62:   }
     63:   return(0);
     64: }

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

     73:    Collective on MFN

     75:    Input Parameters:
     76: .  mfn - the matrix function context

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

     81:    Level: beginner
     82: @*/
     83: PetscErrorCode MFNSetFromOptions(MFN mfn)
     84: {
     86:   char           type[256];
     87:   PetscBool      set,flg,flg1,flg2;
     88:   PetscReal      r;
     89:   PetscInt       i;
     90:   PetscDrawLG    lg;

     94:   MFNRegisterAll();
     95:   PetscObjectOptionsBegin((PetscObject)mfn);
     96:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
     97:     if (flg) {
     98:       MFNSetType(mfn,type);
     99:     }
    100:     /*
    101:       Set the type if it was never set.
    102:     */
    103:     if (!((PetscObject)mfn)->type_name) {
    104:       MFNSetType(mfn,MFNKRYLOV);
    105:     }

    107:     i = mfn->max_it;
    108:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
    109:     if (!flg1) i = PETSC_DEFAULT;
    110:     r = mfn->tol;
    111:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
    112:     if (flg1 || flg2) {
    113:       MFNSetTolerances(mfn,r,i);
    114:     }

    116:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
    117:     if (flg) {
    118:       MFNSetDimensions(mfn,i);
    119:     }

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

    123:     /* -----------------------------------------------------------------------*/
    124:     /*
    125:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
    126:     */
    127:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
    128:     if (set && flg) {
    129:       MFNMonitorCancel(mfn);
    130:     }
    131:     /*
    132:       Text monitors
    133:     */
    134:     MFNMonitorSetFromOptions(mfn,"-mfn_monitor","Monitor error estimate","MFNMonitorDefault",MFNMonitorDefault);
    135:     /*
    136:       Line graph monitors
    137:     */
    138:     PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",PETSC_FALSE,&flg,&set);
    139:     if (set && flg) {
    140:       MFNMonitorLGCreate(PetscObjectComm((PetscObject)mfn),NULL,"Error estimate",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
    141:       MFNMonitorSet(mfn,MFNMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
    142:     }
    143:   /* -----------------------------------------------------------------------*/

    145:     PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",NULL);

    147:     if (mfn->ops->setfromoptions) {
    148:       (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
    149:     }
    150:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
    151:   PetscOptionsEnd();

    153:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    154:   BVSetFromOptions(mfn->V);
    155:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    156:   FNSetFromOptions(mfn->fn);
    157:   return(0);
    158: }

    162: /*@
    163:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
    164:    by the MFN convergence tests.

    166:    Not Collective

    168:    Input Parameter:
    169: .  mfn - the matrix function context

    171:    Output Parameters:
    172: +  tol - the convergence tolerance
    173: -  maxits - maximum number of iterations

    175:    Notes:
    176:    The user can specify NULL for any parameter that is not needed.

    178:    Level: intermediate

    180: .seealso: MFNSetTolerances()
    181: @*/
    182: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
    183: {
    186:   if (tol)    *tol    = mfn->tol;
    187:   if (maxits) *maxits = mfn->max_it;
    188:   return(0);
    189: }

    193: /*@
    194:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
    195:    by the MFN convergence tests.

    197:    Logically Collective on MFN

    199:    Input Parameters:
    200: +  mfn - the matrix function context
    201: .  tol - the convergence tolerance
    202: -  maxits - maximum number of iterations to use

    204:    Options Database Keys:
    205: +  -mfn_tol <tol> - Sets the convergence tolerance
    206: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

    208:    Notes:
    209:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

    211:    Level: intermediate

    213: .seealso: MFNGetTolerances()
    214: @*/
    215: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
    216: {
    221:   if (tol == PETSC_DEFAULT) {
    222:     mfn->tol = PETSC_DEFAULT;
    223:     mfn->setupcalled = 0;
    224:   } else {
    225:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    226:     mfn->tol = tol;
    227:   }
    228:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    229:     mfn->max_it = 0;
    230:     mfn->setupcalled = 0;
    231:   } else {
    232:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
    233:     mfn->max_it = maxits;
    234:   }
    235:   return(0);
    236: }

    240: /*@
    241:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

    243:    Not Collective

    245:    Input Parameter:
    246: .  mfn - the matrix function context

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

    251:    Level: intermediate

    253: .seealso: MFNSetDimensions()
    254: @*/
    255: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
    256: {
    260:   *ncv = mfn->ncv;
    261:   return(0);
    262: }

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

    269:    Logically Collective on MFN

    271:    Input Parameters:
    272: +  mfn - the matrix function context
    273: -  ncv - the maximum dimension of the subspace to be used by the solver

    275:    Options Database Keys:
    276: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

    278:    Notes:
    279:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
    280:    dependent on the solution method.

    282:    Level: intermediate

    284: .seealso: MFNGetDimensions()
    285: @*/
    286: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
    287: {
    291:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    292:     mfn->ncv = 0;
    293:   } else {
    294:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    295:     mfn->ncv = ncv;
    296:   }
    297:   mfn->setupcalled = 0;
    298:   return(0);
    299: }

    303: /*@
    304:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
    305:    solver has not converged.

    307:    Logically Collective on MFN

    309:    Input Parameters:
    310: +  mfn - the matrix function context
    311: -  flg - PETSC_TRUE indicates you want the error generated

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

    316:    Level: intermediate

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

    322: .seealso: MFNGetErrorIfNotConverged()
    323: @*/
    324: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
    325: {
    329:   mfn->errorifnotconverged = flg;
    330:   return(0);
    331: }

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

    339:    Not Collective

    341:    Input Parameter:
    342: .  mfn - the matrix function context

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

    347:    Level: intermediate

    349: .seealso:  MFNSetErrorIfNotConverged()
    350: @*/
    351: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
    352: {
    356:   *flag = mfn->errorifnotconverged;
    357:   return(0);
    358: }

    362: /*@C
    363:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
    364:    MFN options in the database.

    366:    Logically Collective on MFN

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

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

    377:    For example, to distinguish between the runtime options for two
    378:    different MFN contexts, one could call
    379: .vb
    380:       MFNSetOptionsPrefix(mfn1,"fun1_")
    381:       MFNSetOptionsPrefix(mfn2,"fun2_")
    382: .ve

    384:    Level: advanced

    386: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
    387: @*/
    388: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
    389: {

    394:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    395:   BVSetOptionsPrefix(mfn->V,prefix);
    396:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    397:   FNSetOptionsPrefix(mfn->fn,prefix);
    398:   PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
    399:   return(0);
    400: }

    404: /*@C
    405:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
    406:    MFN options in the database.

    408:    Logically Collective on MFN

    410:    Input Parameters:
    411: +  mfn - the matrix function context
    412: -  prefix - the prefix string to prepend to all MFN option requests

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

    418:    Level: advanced

    420: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
    421: @*/
    422: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
    423: {

    428:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    429:   BVSetOptionsPrefix(mfn->V,prefix);
    430:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    431:   FNSetOptionsPrefix(mfn->fn,prefix);
    432:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
    433:   return(0);
    434: }

    438: /*@C
    439:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
    440:    MFN options in the database.

    442:    Not Collective

    444:    Input Parameters:
    445: .  mfn - the matrix function context

    447:    Output Parameters:
    448: .  prefix - pointer to the prefix string used is returned

    450:    Note:
    451:    On the Fortran side, the user should pass in a string 'prefix' of
    452:    sufficient length to hold the prefix.

    454:    Level: advanced

    456: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
    457: @*/
    458: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
    459: {

    465:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
    466:   return(0);
    467: }