Date: 2013-09-02T10:08:20+00:00

Actual source code: mfnopts.c

      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-2013, 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;
     49:   PetscReal        r;
     50:   PetscInt         i;
     51:   PetscViewer      monviewer;

     55:   if (!MFNRegisterAllCalled) { MFNRegisterAll(); }
     56:   PetscObjectOptionsBegin((PetscObject)mfn);
     57:     PetscOptionsList("-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:     PetscOptionsBoolGroupBegin("-mfn_exp","matrix exponential","MFNSetFunction",&flg);
     69:     if (flg) {
     70:       MFNSetFunction(mfn,SLEPC_FUNCTION_EXP);
     71:     }

     73:     PetscOptionsScalar("-mfn_scale","Scale factor","MFNSetScaleFactor",mfn->sfactor,&mfn->sfactor,NULL);

     75:     r = i = 0;
     76:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,NULL);
     77:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,NULL);
     78:     MFNSetTolerances(mfn,r,i);

     80:     i = 0;
     81:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,NULL);
     82:     MFNSetDimensions(mfn,i);

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

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

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

    112:     if (mfn->ops->setfromoptions) {
    113:       (*mfn->ops->setfromoptions)(mfn);
    114:     }
    115:     PetscObjectProcessOptionsHandlers((PetscObject)mfn);
    116:   PetscOptionsEnd();

    118:   if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
    119:   IPSetFromOptions(mfn->ip);
    120:   if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
    121:   DSSetFromOptions(mfn->ds);
    122:   PetscRandomSetFromOptions(mfn->rand);
    123:   return(0);
    124: }

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

    132:    Not Collective

    134:    Input Parameter:
    135: .  mfn - the matrix function context

    137:    Output Parameters:
    138: +  tol - the convergence tolerance
    139: -  maxits - maximum number of iterations

    141:    Notes:
    142:    The user can specify NULL for any parameter that is not needed.

    144:    Level: intermediate

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

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

    163:    Logically Collective on MFN

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

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

    174:    Notes:
    175:    Pass 0 for an argument that need not be changed.

    177:    Use PETSC_DECIDE for maxits to assign a reasonably good value, which is
    178:    dependent on the solution method.

    180:    Level: intermediate

    182: .seealso: MFNGetTolerances()
    183: @*/
    184: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
    185: {
    190:   if (tol) {
    191:     if (tol == PETSC_DEFAULT) {
    192:       mfn->tol = PETSC_DEFAULT;
    193:     } else {
    194:       if (tol < 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
    195:       mfn->tol = tol;
    196:     }
    197:   }
    198:   if (maxits) {
    199:     if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
    200:       mfn->max_it = 0;
    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:   }
    207:   return(0);
    208: }

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

    215:    Not Collective

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

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

    223:    Level: intermediate

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

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

    241:    Logically Collective on MFN

    243:    Input Parameters:
    244: +  mfn - the matrix function context
    245: -  ncv - the maximum dimension of the subspace to be used by the solver

    247:    Options Database Keys:
    248: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

    250:    Notes:
    251:    Use PETSC_DECIDE for ncv to assign a reasonably good value, which is
    252:    dependent on the solution method.

    254:    Level: intermediate

    256: .seealso: MFNGetDimensions()
    257: @*/
    258: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
    259: {
    263:   if (ncv) {
    264:     if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
    265:       mfn->ncv = 0;
    266:     } else {
    267:       if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
    268:       mfn->ncv = ncv;
    269:     }
    270:     mfn->setupcalled = 0;
    271:   }
    272:   return(0);
    273: }

    277: /*@
    278:    MFNSetFunction - Specifies the function to be computed.

    280:    Logically Collective on MFN

    282:    Input Parameters:
    283: +  mfn      - the matrix function context
    284: -  fun      - a known function

    286:    Options Database Keys:
    287: .  -mfn_exp - matrix exponential

    289:    Level: beginner

    291: .seealso: MFNSetOperator(), MFNSetType(), MFNGetFunction(), SlepcFunction
    292: @*/
    293: PetscErrorCode MFNSetFunction(MFN mfn,SlepcFunction fun)
    294: {
    298:   switch (fun) {
    299:     case SLEPC_FUNCTION_EXP:
    300:       break;
    301:     default:
    302:       SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Unknown function");
    303:   }
    304:   mfn->function = fun;
    305:   return(0);
    306: }

    310: /*@C
    311:    MFNGetFunction - Gets the function from the MFN object.

    313:    Not Collective

    315:    Input Parameter:
    316: .  mfn - the matrix function context

    318:    Output Parameter:
    319: .  fun - function

    321:    Level: intermediate

    323: .seealso: MFNSetFunction(), SlepcFunction
    324: @*/
    325: PetscErrorCode MFNGetFunction(MFN mfn,SlepcFunction *fun)
    326: {
    330:   *fun = mfn->function;
    331:   return(0);
    332: }

    336: /*@
    337:    MFNSetScaleFactor - Sets the scale factor to multiply the matrix (the
    338:    argument of the function).

    340:    Logically Collective on MFN

    342:    Input Parameters:
    343: +  mfn   - the matrix function context
    344: -  alpha - the scaling factor

    346:    Options Database Keys:
    347: .  -mfn_scale <alpha> - Sets the scaling factor

    349:    Notes:
    350:    The computed result is f(alpha*A)*b. The default is alpha=1.0.

    352:    Level: intermediate

    354: .seealso: MFNGetScaleFactor(), MFNSolve()
    355: @*/
    356: PetscErrorCode MFNSetScaleFactor(MFN mfn,PetscScalar alpha)
    357: {
    361:   mfn->sfactor = alpha;
    362:   return(0);
    363: }

    367: /*@
    368:    MFNGetScaleFactor - Gets the factor used for scaling the matrix.

    370:    Not Collective

    372:    Input Parameter:
    373: .  mfn - the matrix function context

    375:    Output Parameters:
    376: .  alpha - the scaling factor

    378:    Level: intermediate

    380: .seealso: MFNSetScaleFactor(), MFNSolve()
    381: @*/
    382: PetscErrorCode MFNGetScaleFactor(MFN mfn,PetscScalar *alpha)
    383: {
    387:   *alpha = mfn->sfactor;
    388:   return(0);
    389: }

    393: /*@
    394:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
    395:    solver has not converged.

    397:    Logically Collective on MFN

    399:    Input Parameters:
    400: +  mfn - the matrix function context
    401: -  flg - PETSC_TRUE indicates you want the error generated

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

    406:    Level: intermediate

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

    412: .seealso: MFNGetErrorIfNotConverged()
    413: @*/
    414: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
    415: {
    419:   mfn->errorifnotconverged = flg;
    420:   return(0);
    421: }

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

    429:    Not Collective

    431:    Input Parameter:
    432: .  mfn - the matrix function context

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

    437:    Level: intermediate

    439: .seealso:  MFNSetErrorIfNotConverged()
    440: @*/
    441: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
    442: {
    446:   *flag = mfn->errorifnotconverged;
    447:   return(0);
    448: }

    452: /*@C
    453:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
    454:    MFN options in the database.

    456:    Logically Collective on MFN

    458:    Input Parameters:
    459: +  mfn - the matrix function context
    460: -  prefix - the prefix string to prepend to all MFN option requests

    462:    Notes:
    463:    A hyphen (-) must NOT be given at the beginning of the prefix name.
    464:    The first character of all runtime options is AUTOMATICALLY the
    465:    hyphen.

    467:    For example, to distinguish between the runtime options for two
    468:    different MFN contexts, one could call
    469: .vb
    470:       MFNSetOptionsPrefix(mfn1,"fun1_")
    471:       MFNSetOptionsPrefix(mfn2,"fun2_")
    472: .ve

    474:    Level: advanced

    476: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
    477: @*/
    478: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
    479: {

    484:   if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
    485:   IPSetOptionsPrefix(mfn->ip,prefix);
    486:   if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
    487:   DSSetOptionsPrefix(mfn->ds,prefix);
    488:   PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
    489:   return(0);
    490: }

    494: /*@C
    495:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
    496:    MFN options in the database.

    498:    Logically Collective on MFN

    500:    Input Parameters:
    501: +  mfn - the matrix function context
    502: -  prefix - the prefix string to prepend to all MFN option requests

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

    508:    Level: advanced

    510: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
    511: @*/
    512: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
    513: {

    518:   if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
    519:   IPSetOptionsPrefix(mfn->ip,prefix);
    520:   if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
    521:   DSSetOptionsPrefix(mfn->ds,prefix);
    522:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
    523:   return(0);
    524: }

    528: /*@C
    529:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
    530:    MFN options in the database.

    532:    Not Collective

    534:    Input Parameters:
    535: .  mfn - the matrix function context

    537:    Output Parameters:
    538: .  prefix - pointer to the prefix string used is returned

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

    543:    Level: advanced

    545: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
    546: @*/
    547: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
    548: {

    554:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
    555:   return(0);
    556: }