Actual source code: mfnopts.c

slepc-3.16.0 2021-09-30
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:   PetscFunctionListFind(MFNMonitorCreateList,key,&cfunc);
 55:   PetscFunctionListFind(MFNMonitorDestroyList,key,&dfunc);
 56:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
 57:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

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

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

 70:    Collective on mfn

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

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

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

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

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

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

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

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

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

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

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

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

139:    Not Collective

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

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

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

151:    Level: intermediate

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

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

168:    Logically Collective on mfn

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

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

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

182:    Level: intermediate

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

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

212:    Not Collective

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

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

220:    Level: intermediate

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

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

236:    Logically Collective on mfn

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

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

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

249:    Level: intermediate

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

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

272:    Logically Collective on mfn

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

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

281:    Level: intermediate

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

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

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

302:    Not Collective

304:    Input Parameter:
305: .  mfn - the matrix function context

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

310:    Level: intermediate

312: .seealso:  MFNSetErrorIfNotConverged()
313: @*/
314: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
315: {
319:   *flag = mfn->errorifnotconverged;
320:   return(0);
321: }

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

327:    Logically Collective on mfn

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

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

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

345:    Level: advanced

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

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

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

367:    Logically Collective on mfn

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

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

377:    Level: advanced

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

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

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

399:    Not Collective

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

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

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

411:    Level: advanced

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

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