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