Date: 2015-09-03T15:06:06+00:00

Actual source code: mfnopts.c
slepc-3.6.1 2015-09-03
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-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/mfnimpl.h>   /*I "slepcmfn.h" I*/

     29: /*@
     30:    MFNSetFromOptions - Sets MFN options from the options database.
     31:    This routine must be called before MFNSetUp() if the user is to be
     32:    allowed to set the solver type.

     34:    Collective on MFN

     36:    Input Parameters:
     37: .  mfn - the matrix function context

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

     42:    Level: beginner
     43: @*/
     44: PetscErrorCode MFNSetFromOptions(MFN mfn)
     45: {
     46:   PetscErrorCode   ierr;
     47:   char             type[256],monfilename[PETSC_MAX_PATH_LEN];
     48:   PetscBool        flg,flg1,flg2;
     49:   PetscReal        r;
     50:   PetscInt         i;
     51:   PetscViewer      monviewer;

     55:   MFNRegisterAll();
     56:   PetscObjectOptionsBegin((PetscObject)mfn);
     57:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
     58:     if (flg) {
     59:       MFNSetType(mfn,type);
     60:     }
     61:     /*
     62:       Set the type if it was never set.
     63:     */
     64:     if (!((PetscObject)mfn)->type_name) {
     65:       MFNSetType(mfn,MFNKRYLOV);
     66:     }

     68:     i = mfn->max_it;
     69:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
     70:     if (!flg1) i = PETSC_DEFAULT;
     71:     r = mfn->tol;
     72:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
     73:     if (flg1 || flg2) {
     74:       MFNSetTolerances(mfn,r,i);
     75:     }

     77:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
     78:     if (flg) {
     79:       MFNSetDimensions(mfn,i);
     80:     }

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

     84:     /* -----------------------------------------------------------------------*/
     85:     /*
     86:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
     87:     */
     88:     flg = PETSC_FALSE;
     89:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",flg,&flg,NULL);
     90:     if (flg) {
     91:       MFNMonitorCancel(mfn);
     92:     }
     93:     /*
     94:       Prints error estimate at each iteration
     95:     */
     96:     PetscOptionsString("-mfn_monitor","Monitor error estimate","MFNMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
     97:     if (flg) {
     98:       PetscViewerASCIIOpen(PetscObjectComm((PetscObject)mfn),monfilename,&monviewer);
     99:       MFNMonitorSet(mfn,MFNMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
    100:     }
    101:     flg = PETSC_FALSE;
    102:     PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",flg,&flg,NULL);
    103:     if (flg) {
    104:       MFNMonitorSet(mfn,MFNMonitorLG,NULL,NULL);
    105:     }
    106:   /* -----------------------------------------------------------------------*/

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

    110:     if (mfn->ops->setfromoptions) {
    111:       (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
    112:     }
    113:     PetscObjectProcessOptionsHandlers((PetscObject)mfn);
    114:   PetscOptionsEnd();

    116:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
    117:   BVSetFromOptions(mfn->V);
    118:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
    119:   FNSetFromOptions(mfn->fn);
    120:   PetscRandomSetFromOptions(mfn->rand);
    121:   return(0);
    122: }

    126: /*@
    127:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
    128:    by the MFN convergence tests.

    130:    Not Collective

    132:    Input Parameter:
    133: .  mfn - the matrix function context

    135:    Output Parameters:
    136: +  tol - the convergence tolerance
    137: -  maxits - maximum number of iterations

    139:    Notes:
    140:    The user can specify NULL for any parameter that is not needed.

    142:    Level: intermediate

    144: .seealso: MFNSetTolerances()
    145: @*/
    146: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
    147: {
    150:   if (tol)    *tol    = mfn->tol;
    151:   if (maxits) *maxits = mfn->max_it;
    152:   return(0);
    153: }

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

    161:    Logically Collective on MFN

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

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

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

    175:    Level: intermediate

    177: .seealso: MFNGetTolerances()
    178: @*/
    179: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
    180: {
    185:   if (tol == PETSC_DEFAULT) {
    186:     mfn->tol = PETSC_DEFAULT;
    187:     mfn->setupcalled = 0;
    188:   } else {
    189:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    190:     mfn->tol = tol;
    191:   }
    192:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    193:     mfn->max_it = 0;
    194:     mfn->setupcalled = 0;
    195:   } else {
    196:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
    197:     mfn->max_it = maxits;
    198:   }
    199:   return(0);
    200: }

    204: /*@
    205:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

    207:    Not Collective

    209:    Input Parameter:
    210: .  mfn - the matrix function context

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

    215:    Level: intermediate

    217: .seealso: MFNSetDimensions()
    218: @*/
    219: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
    220: {
    224:   *ncv = mfn->ncv;
    225:   return(0);
    226: }

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

    233:    Logically Collective on MFN

    235:    Input Parameters:
    236: +  mfn - the matrix function context
    237: -  ncv - the maximum dimension of the subspace to be used by the solver

    239:    Options Database Keys:
    240: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

    242:    Notes:
    243:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
    244:    dependent on the solution method.

    246:    Level: intermediate

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

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

    271:    Logically Collective on MFN

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

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

    280:    Level: intermediate

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

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

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

    303:    Not Collective

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

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

    311:    Level: intermediate

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

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

    330:    Logically Collective on MFN

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

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

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

    348:    Level: advanced

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

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

    368: /*@C
    369:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
    370:    MFN options in the database.

    372:    Logically Collective on MFN

    374:    Input Parameters:
    375: +  mfn - the matrix function context
    376: -  prefix - the prefix string to prepend to all MFN option requests

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

    382:    Level: advanced

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

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

    402: /*@C
    403:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
    404:    MFN options in the database.

    406:    Not Collective

    408:    Input Parameters:
    409: .  mfn - the matrix function context

    411:    Output Parameters:
    412: .  prefix - pointer to the prefix string used is returned

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

    417:    Level: advanced

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

    428:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
    429:   return(0);
    430: }