Actual source code: mfnopts.c

slepc-3.5.2 2014-10-10
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-2014, 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:   if (!MFNRegisterAllCalled) { 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:     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:     i = mfn->max_it;
 76:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
 77:     r = mfn->tol;
 78:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
 79:     if (flg1 || flg2) {
 80:       MFNSetTolerances(mfn,r,i);
 81:     }

 83:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
 84:     if (flg) {
 85:       MFNSetDimensions(mfn,i);
 86:     }

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

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

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

116:     if (mfn->ops->setfromoptions) {
117:       (*mfn->ops->setfromoptions)(mfn);
118:     }
119:     PetscObjectProcessOptionsHandlers((PetscObject)mfn);
120:   PetscOptionsEnd();

122:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
123:   BVSetFromOptions(mfn->V);
124:   if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
125:   DSSetFromOptions(mfn->ds);
126:   PetscRandomSetFromOptions(mfn->rand);
127:   return(0);
128: }

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

136:    Not Collective

138:    Input Parameter:
139: .  mfn - the matrix function context

141:    Output Parameters:
142: +  tol - the convergence tolerance
143: -  maxits - maximum number of iterations

145:    Notes:
146:    The user can specify NULL for any parameter that is not needed.

148:    Level: intermediate

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

163: /*@
164:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
165:    by the MFN convergence tests.

167:    Logically Collective on MFN

169:    Input Parameters:
170: +  mfn - the matrix function context
171: .  tol - the convergence tolerance
172: -  maxits - maximum number of iterations to use

174:    Options Database Keys:
175: +  -mfn_tol <tol> - Sets the convergence tolerance
176: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

178:    Notes:
179:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

181:    Level: intermediate

183: .seealso: MFNGetTolerances()
184: @*/
185: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
186: {
191:   if (tol == PETSC_DEFAULT) {
192:     mfn->tol = PETSC_DEFAULT;
193:     mfn->setupcalled = 0;
194:   } else {
195:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
196:     mfn->tol = tol;
197:   }
198:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
199:     mfn->max_it = 0;
200:     mfn->setupcalled = 0;
201:   } else {
202:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
203:     mfn->max_it = maxits;
204:   }
205:   return(0);
206: }

210: /*@
211:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

213:    Not Collective

215:    Input Parameter:
216: .  mfn - the matrix function context

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

221:    Level: intermediate

223: .seealso: MFNSetDimensions()
224: @*/
225: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
226: {
230:   *ncv = mfn->ncv;
231:   return(0);
232: }

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

239:    Logically Collective on MFN

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

245:    Options Database Keys:
246: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

248:    Notes:
249:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
250:    dependent on the solution method.

252:    Level: intermediate

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

273: /*@
274:    MFNSetFunction - Specifies the function to be computed.

276:    Logically Collective on MFN

278:    Input Parameters:
279: +  mfn      - the matrix function context
280: -  fun      - a known function

282:    Options Database Keys:
283: .  -mfn_exp - matrix exponential

285:    Level: beginner

287: .seealso: MFNSetOperator(), MFNSetType(), MFNGetFunction(), SlepcFunction
288: @*/
289: PetscErrorCode MFNSetFunction(MFN mfn,SlepcFunction fun)
290: {
294:   switch (fun) {
295:     case SLEPC_FUNCTION_EXP:
296:       break;
297:     default:
298:       SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Unknown function");
299:   }
300:   mfn->function = fun;
301:   return(0);
302: }

306: /*@C
307:    MFNGetFunction - Gets the function from the MFN object.

309:    Not Collective

311:    Input Parameter:
312: .  mfn - the matrix function context

314:    Output Parameter:
315: .  fun - function

317:    Level: intermediate

319: .seealso: MFNSetFunction(), SlepcFunction
320: @*/
321: PetscErrorCode MFNGetFunction(MFN mfn,SlepcFunction *fun)
322: {
326:   *fun = mfn->function;
327:   return(0);
328: }

332: /*@
333:    MFNSetScaleFactor - Sets the scale factor to multiply the matrix (the
334:    argument of the function).

336:    Logically Collective on MFN

338:    Input Parameters:
339: +  mfn   - the matrix function context
340: -  alpha - the scaling factor

342:    Options Database Keys:
343: .  -mfn_scale <alpha> - the scaling factor

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

348:    In the case of complex scalars, a complex value can be provided in the
349:    command line with [+/-][realnumber][+/-]realnumberi with no spaces, e.g.
350:    -mfn_scale 1.0+2.0i

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->V) { MFNGetBV(mfn,&mfn->V); }
485:   BVSetOptionsPrefix(mfn->V,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->V) { MFNGetBV(mfn,&mfn->V); }
519:   BVSetOptionsPrefix(mfn->V,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: }