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: }