Actual source code: mfnopts.c

slepc-3.7.2 2016-07-19
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-2016, 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*/
 26: #include <petscdraw.h>

 30: /*@C
 31:    MFNMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
 32:    indicated by the user.

 34:    Collective on MFN

 36:    Input Parameters:
 37: +  mfn      - the eigensolver context
 38: .  name     - the monitor option name
 39: .  help     - message indicating what monitoring is done
 40: .  manual   - manual page for the monitor
 41: .  monitor  - the monitor function, whose context is a PetscViewerAndFormat
 42: -  trackall - whether this monitor tracks all eigenvalues or not

 44:    Level: developer

 46: .seealso: MFNMonitorSet(), MFNSetTrackAll(), MFNConvMonitorSetFromOptions()
 47: @*/
 48: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*))
 49: {
 50:   PetscErrorCode       ierr;
 51:   PetscBool            flg;
 52:   PetscViewer          viewer;
 53:   PetscViewerFormat    format;
 54:   PetscViewerAndFormat *vf;

 57:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,name,&viewer,&format,&flg);
 58:   if (flg) {
 59:     PetscViewerAndFormatCreate(viewer,format,&vf);
 60:     PetscObjectDereference((PetscObject)viewer);
 61:     MFNMonitorSet(mfn,(PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
 62:   }
 63:   return(0);
 64: }

 68: /*@
 69:    MFNSetFromOptions - Sets MFN options from the options database.
 70:    This routine must be called before MFNSetUp() if the user is to be
 71:    allowed to set the solver type.

 73:    Collective on MFN

 75:    Input Parameters:
 76: .  mfn - the matrix function context

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

 81:    Level: beginner
 82: @*/
 83: PetscErrorCode MFNSetFromOptions(MFN mfn)
 84: {
 86:   char           type[256];
 87:   PetscBool      set,flg,flg1,flg2;
 88:   PetscReal      r;
 89:   PetscInt       i;
 90:   PetscDrawLG    lg;

 94:   MFNRegisterAll();
 95:   PetscObjectOptionsBegin((PetscObject)mfn);
 96:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
 97:     if (flg) {
 98:       MFNSetType(mfn,type);
 99:     }
100:     /*
101:       Set the type if it was never set.
102:     */
103:     if (!((PetscObject)mfn)->type_name) {
104:       MFNSetType(mfn,MFNKRYLOV);
105:     }

107:     i = mfn->max_it;
108:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
109:     if (!flg1) i = PETSC_DEFAULT;
110:     r = mfn->tol;
111:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
112:     if (flg1 || flg2) {
113:       MFNSetTolerances(mfn,r,i);
114:     }

116:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
117:     if (flg) {
118:       MFNSetDimensions(mfn,i);
119:     }

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

123:     /* -----------------------------------------------------------------------*/
124:     /*
125:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
126:     */
127:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
128:     if (set && flg) {
129:       MFNMonitorCancel(mfn);
130:     }
131:     /*
132:       Text monitors
133:     */
134:     MFNMonitorSetFromOptions(mfn,"-mfn_monitor","Monitor error estimate","MFNMonitorDefault",MFNMonitorDefault);
135:     /*
136:       Line graph monitors
137:     */
138:     PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",PETSC_FALSE,&flg,&set);
139:     if (set && flg) {
140:       MFNMonitorLGCreate(PetscObjectComm((PetscObject)mfn),NULL,"Error estimate",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
141:       MFNMonitorSet(mfn,MFNMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
142:     }
143:   /* -----------------------------------------------------------------------*/

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

147:     if (mfn->ops->setfromoptions) {
148:       (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
149:     }
150:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
151:   PetscOptionsEnd();

153:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
154:   BVSetFromOptions(mfn->V);
155:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
156:   FNSetFromOptions(mfn->fn);
157:   return(0);
158: }

162: /*@
163:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
164:    by the MFN convergence tests.

166:    Not Collective

168:    Input Parameter:
169: .  mfn - the matrix function context

171:    Output Parameters:
172: +  tol - the convergence tolerance
173: -  maxits - maximum number of iterations

175:    Notes:
176:    The user can specify NULL for any parameter that is not needed.

178:    Level: intermediate

180: .seealso: MFNSetTolerances()
181: @*/
182: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
183: {
186:   if (tol)    *tol    = mfn->tol;
187:   if (maxits) *maxits = mfn->max_it;
188:   return(0);
189: }

193: /*@
194:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
195:    by the MFN convergence tests.

197:    Logically Collective on MFN

199:    Input Parameters:
200: +  mfn - the matrix function context
201: .  tol - the convergence tolerance
202: -  maxits - maximum number of iterations to use

204:    Options Database Keys:
205: +  -mfn_tol <tol> - Sets the convergence tolerance
206: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

208:    Notes:
209:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

211:    Level: intermediate

213: .seealso: MFNGetTolerances()
214: @*/
215: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
216: {
221:   if (tol == PETSC_DEFAULT) {
222:     mfn->tol = PETSC_DEFAULT;
223:     mfn->setupcalled = 0;
224:   } else {
225:     if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
226:     mfn->tol = tol;
227:   }
228:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
229:     mfn->max_it = 0;
230:     mfn->setupcalled = 0;
231:   } else {
232:     if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
233:     mfn->max_it = maxits;
234:   }
235:   return(0);
236: }

240: /*@
241:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

243:    Not Collective

245:    Input Parameter:
246: .  mfn - the matrix function context

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

251:    Level: intermediate

253: .seealso: MFNSetDimensions()
254: @*/
255: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
256: {
260:   *ncv = mfn->ncv;
261:   return(0);
262: }

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

269:    Logically Collective on MFN

271:    Input Parameters:
272: +  mfn - the matrix function context
273: -  ncv - the maximum dimension of the subspace to be used by the solver

275:    Options Database Keys:
276: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

278:    Notes:
279:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
280:    dependent on the solution method.

282:    Level: intermediate

284: .seealso: MFNGetDimensions()
285: @*/
286: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
287: {
291:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
292:     mfn->ncv = 0;
293:   } else {
294:     if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
295:     mfn->ncv = ncv;
296:   }
297:   mfn->setupcalled = 0;
298:   return(0);
299: }

303: /*@
304:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
305:    solver has not converged.

307:    Logically Collective on MFN

309:    Input Parameters:
310: +  mfn - the matrix function context
311: -  flg - PETSC_TRUE indicates you want the error generated

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

316:    Level: intermediate

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

322: .seealso: MFNGetErrorIfNotConverged()
323: @*/
324: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
325: {
329:   mfn->errorifnotconverged = flg;
330:   return(0);
331: }

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

339:    Not Collective

341:    Input Parameter:
342: .  mfn - the matrix function context

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

347:    Level: intermediate

349: .seealso:  MFNSetErrorIfNotConverged()
350: @*/
351: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
352: {
356:   *flag = mfn->errorifnotconverged;
357:   return(0);
358: }

362: /*@C
363:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
364:    MFN options in the database.

366:    Logically Collective on MFN

368:    Input Parameters:
369: +  mfn - the matrix function context
370: -  prefix - the prefix string to prepend to all MFN option requests

372:    Notes:
373:    A hyphen (-) must NOT be given at the beginning of the prefix name.
374:    The first character of all runtime options is AUTOMATICALLY the
375:    hyphen.

377:    For example, to distinguish between the runtime options for two
378:    different MFN contexts, one could call
379: .vb
380:       MFNSetOptionsPrefix(mfn1,"fun1_")
381:       MFNSetOptionsPrefix(mfn2,"fun2_")
382: .ve

384:    Level: advanced

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

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

404: /*@C
405:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
406:    MFN options in the database.

408:    Logically Collective on MFN

410:    Input Parameters:
411: +  mfn - the matrix function context
412: -  prefix - the prefix string to prepend to all MFN option requests

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

418:    Level: advanced

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

428:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
429:   BVSetOptionsPrefix(mfn->V,prefix);
430:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
431:   FNSetOptionsPrefix(mfn->fn,prefix);
432:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
433:   return(0);
434: }

438: /*@C
439:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
440:    MFN options in the database.

442:    Not Collective

444:    Input Parameters:
445: .  mfn - the matrix function context

447:    Output Parameters:
448: .  prefix - pointer to the prefix string used is returned

450:    Note:
451:    On the Fortran side, the user should pass in a string 'prefix' of
452:    sufficient length to hold the prefix.

454:    Level: advanced

456: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
457: @*/
458: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
459: {

465:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
466:   return(0);
467: }