Actual source code: mfnopts.c

slepc-3.11.2 2019-07-30
Report Typos and Errors
  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-2019, Universitat Politecnica de Valencia, Spain

  6:    This file is part of SLEPc.
  7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
  8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  9: */
 10: /*
 11:    MFN routines related to options that can be set via the command-line
 12:    or procedurally
 13: */

 15: #include <slepc/private/mfnimpl.h>   /*I "slepcmfn.h" I*/
 16: #include <petscdraw.h>

 18: /*@C
 19:    MFNMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
 20:    indicated by the user.

 22:    Collective on MFN

 24:    Input Parameters:
 25: +  mfn      - the eigensolver context
 26: .  name     - the monitor option name
 27: .  help     - message indicating what monitoring is done
 28: .  manual   - manual page for the monitor
 29: -  monitor  - the monitor function, whose context is a PetscViewerAndFormat

 31:    Level: developer

 33: .seealso: MFNMonitorSet()
 34: @*/
 35: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*))
 36: {
 37:   PetscErrorCode       ierr;
 38:   PetscBool            flg;
 39:   PetscViewer          viewer;
 40:   PetscViewerFormat    format;
 41:   PetscViewerAndFormat *vf;

 44:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,name,&viewer,&format,&flg);
 45:   if (flg) {
 46:     PetscViewerAndFormatCreate(viewer,format,&vf);
 47:     PetscObjectDereference((PetscObject)viewer);
 48:     MFNMonitorSet(mfn,(PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
 49:   }
 50:   return(0);
 51: }

 53: /*@
 54:    MFNSetFromOptions - Sets MFN options from the options database.
 55:    This routine must be called before MFNSetUp() if the user is to be
 56:    allowed to set the solver type.

 58:    Collective on MFN

 60:    Input Parameters:
 61: .  mfn - the matrix function context

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

 66:    Level: beginner
 67: @*/
 68: PetscErrorCode MFNSetFromOptions(MFN mfn)
 69: {
 71:   char           type[256];
 72:   PetscBool      set,flg,flg1,flg2;
 73:   PetscReal      r;
 74:   PetscInt       i;
 75:   PetscDrawLG    lg;

 79:   MFNRegisterAll();
 80:   PetscObjectOptionsBegin((PetscObject)mfn);
 81:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
 82:     if (flg) {
 83:       MFNSetType(mfn,type);
 84:     } else if (!((PetscObject)mfn)->type_name) {
 85:       MFNSetType(mfn,MFNKRYLOV);
 86:     }

 88:     i = mfn->max_it;
 89:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
 90:     if (!flg1) i = PETSC_DEFAULT;
 91:     r = mfn->tol;
 92:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
 93:     if (flg1 || flg2) { MFNSetTolerances(mfn,r,i); }

 95:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
 96:     if (flg) { MFNSetDimensions(mfn,i); }

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

100:     /* -----------------------------------------------------------------------*/
101:     /*
102:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
103:     */
104:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
105:     if (set && flg) {
106:       MFNMonitorCancel(mfn);
107:     }
108:     /*
109:       Text monitors
110:     */
111:     MFNMonitorSetFromOptions(mfn,"-mfn_monitor","Monitor error estimate","MFNMonitorDefault",MFNMonitorDefault);
112:     /*
113:       Line graph monitors
114:     */
115:     PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",PETSC_FALSE,&flg,&set);
116:     if (set && flg) {
117:       MFNMonitorLGCreate(PetscObjectComm((PetscObject)mfn),NULL,"Error estimate",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
118:       MFNMonitorSet(mfn,MFNMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
119:     }

121:     /* -----------------------------------------------------------------------*/
122:     PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",NULL);

124:     if (mfn->ops->setfromoptions) {
125:       (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
126:     }
127:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
128:   PetscOptionsEnd();

130:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
131:   BVSetFromOptions(mfn->V);
132:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
133:   FNSetFromOptions(mfn->fn);
134:   return(0);
135: }

137: /*@C
138:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
139:    by the MFN convergence tests.

141:    Not Collective

143:    Input Parameter:
144: .  mfn - the matrix function context

146:    Output Parameters:
147: +  tol - the convergence tolerance
148: -  maxits - maximum number of iterations

150:    Notes:
151:    The user can specify NULL for any parameter that is not needed.

153:    Level: intermediate

155: .seealso: MFNSetTolerances()
156: @*/
157: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
158: {
161:   if (tol)    *tol    = mfn->tol;
162:   if (maxits) *maxits = mfn->max_it;
163:   return(0);
164: }

166: /*@
167:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
168:    by the MFN convergence tests.

170:    Logically Collective on MFN

172:    Input Parameters:
173: +  mfn - the matrix function context
174: .  tol - the convergence tolerance
175: -  maxits - maximum number of iterations to use

177:    Options Database Keys:
178: +  -mfn_tol <tol> - Sets the convergence tolerance
179: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

181:    Notes:
182:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

184:    Level: intermediate

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

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

214:    Not Collective

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

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

222:    Level: intermediate

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

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

238:    Logically Collective on MFN

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

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

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

251:    Level: intermediate

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

270: /*@
271:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
272:    solver has not converged.

274:    Logically Collective on MFN

276:    Input Parameters:
277: +  mfn - the matrix function context
278: -  flg - PETSC_TRUE indicates you want the error generated

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

283:    Level: intermediate

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

289: .seealso: MFNGetErrorIfNotConverged()
290: @*/
291: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
292: {
296:   mfn->errorifnotconverged = flg;
297:   return(0);
298: }

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

304:    Not Collective

306:    Input Parameter:
307: .  mfn - the matrix function context

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

312:    Level: intermediate

314: .seealso:  MFNSetErrorIfNotConverged()
315: @*/
316: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
317: {
321:   *flag = mfn->errorifnotconverged;
322:   return(0);
323: }

325: /*@C
326:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
327:    MFN options in the database.

329:    Logically Collective on MFN

331:    Input Parameters:
332: +  mfn - the matrix function context
333: -  prefix - the prefix string to prepend to all MFN option requests

335:    Notes:
336:    A hyphen (-) must NOT be given at the beginning of the prefix name.
337:    The first character of all runtime options is AUTOMATICALLY the
338:    hyphen.

340:    For example, to distinguish between the runtime options for two
341:    different MFN contexts, one could call
342: .vb
343:       MFNSetOptionsPrefix(mfn1,"fun1_")
344:       MFNSetOptionsPrefix(mfn2,"fun2_")
345: .ve

347:    Level: advanced

349: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
350: @*/
351: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
352: {

357:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
358:   BVSetOptionsPrefix(mfn->V,prefix);
359:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
360:   FNSetOptionsPrefix(mfn->fn,prefix);
361:   PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
362:   return(0);
363: }

365: /*@C
366:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
367:    MFN options in the database.

369:    Logically Collective on MFN

371:    Input Parameters:
372: +  mfn - the matrix function context
373: -  prefix - the prefix string to prepend to all MFN option requests

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

379:    Level: advanced

381: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
382: @*/
383: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
384: {

389:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
390:   BVAppendOptionsPrefix(mfn->V,prefix);
391:   if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
392:   FNAppendOptionsPrefix(mfn->fn,prefix);
393:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
394:   return(0);
395: }

397: /*@C
398:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
399:    MFN options in the database.

401:    Not Collective

403:    Input Parameters:
404: .  mfn - the matrix function context

406:    Output Parameters:
407: .  prefix - pointer to the prefix string used is returned

409:    Note:
410:    On the Fortran side, the user should pass in a string 'prefix' of
411:    sufficient length to hold the prefix.

413:    Level: advanced

415: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
416: @*/
417: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
418: {

424:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
425:   return(0);
426: }