Actual source code: mfnopts.c

slepc-3.16.1 2021-11-17
Report Typos and Errors
  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-2021, 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>
 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 matrix function context
 26: .  opt  - the command line option for this monitor
 27: .  name - the monitor type one is seeking
 28: -  ctx  - an optional user context for the monitor, or NULL

 30:    Level: developer

 32: .seealso: MFNMonitorSet()
 33: @*/
 34: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char opt[],const char name[],void *ctx)
 35: {
 36:   PetscErrorCode       (*mfunc)(MFN,PetscInt,PetscReal,void*);
 37:   PetscErrorCode       (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
 38:   PetscErrorCode       (*dfunc)(PetscViewerAndFormat**);
 39:   PetscViewerAndFormat *vf;
 40:   PetscViewer          viewer;
 41:   PetscViewerFormat    format;
 42:   PetscViewerType      vtype;
 43:   char                 key[PETSC_MAX_PATH_LEN];
 44:   PetscBool            flg;
 45:   PetscErrorCode       ierr;

 48:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,opt,&viewer,&format,&flg);
 49:   if (!flg) return(0);

 51:   PetscViewerGetType(viewer,&vtype);
 52:   SlepcMonitorMakeKey_Internal(name,vtype,format,key);
 53:   PetscFunctionListFind(MFNMonitorList,key,&mfunc);
 54:   if (!mfunc) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_SUP,"Specified viewer and format not supported");
 55:   PetscFunctionListFind(MFNMonitorCreateList,key,&cfunc);
 56:   PetscFunctionListFind(MFNMonitorDestroyList,key,&dfunc);
 57:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
 58:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

 60:   (*cfunc)(viewer,format,ctx,&vf);
 61:   PetscObjectDereference((PetscObject)viewer);
 62:   MFNMonitorSet(mfn,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
 63:   return(0);
 64: }

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

 71:    Collective on mfn

 73:    Input Parameters:
 74: .  mfn - the matrix function context

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

 79:    Level: beginner
 80: @*/
 81: PetscErrorCode MFNSetFromOptions(MFN mfn)
 82: {
 84:   char           type[256];
 85:   PetscBool      set,flg,flg1,flg2;
 86:   PetscReal      r;
 87:   PetscInt       i;

 91:   MFNRegisterAll();
 92:   PetscObjectOptionsBegin((PetscObject)mfn);
 93:     PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,sizeof(type),&flg);
 94:     if (flg) {
 95:       MFNSetType(mfn,type);
 96:     } else if (!((PetscObject)mfn)->type_name) {
 97:       MFNSetType(mfn,MFNKRYLOV);
 98:     }

100:     i = mfn->max_it;
101:     PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
102:     if (!flg1) i = PETSC_DEFAULT;
103:     r = mfn->tol;
104:     PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",SlepcDefaultTol(mfn->tol),&r,&flg2);
105:     if (flg1 || flg2) { MFNSetTolerances(mfn,r,i); }

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

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

112:     /* -----------------------------------------------------------------------*/
113:     /*
114:       Cancels all monitors hardwired into code before call to MFNSetFromOptions()
115:     */
116:     PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
117:     if (set && flg) { MFNMonitorCancel(mfn); }
118:     MFNMonitorSetFromOptions(mfn,"-mfn_monitor","error_estimate",NULL);

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

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

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

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

140:    Not Collective

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

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

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

152:    Level: intermediate

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

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

169:    Logically Collective on mfn

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

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

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

183:    Level: intermediate

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

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

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

237:    Logically Collective on mfn

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

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

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

250:    Level: intermediate

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

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

273:    Logically Collective on mfn

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

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

282:    Level: intermediate

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

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

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

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

328:    Logically Collective on mfn

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

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

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

346:    Level: advanced

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

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

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

368:    Logically Collective on mfn

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

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

378:    Level: advanced

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

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

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

400:    Not Collective

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

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

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

412:    Level: advanced

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

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