Actual source code: mfnopts.c

slepc-3.17.1 2022-04-11
Report Typos and Errors
  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-, 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;

 46:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,opt,&viewer,&format,&flg);
 47:   if (!flg) PetscFunctionReturn(0);

 49:   PetscViewerGetType(viewer,&vtype);
 50:   SlepcMonitorMakeKey_Internal(name,vtype,format,key);
 51:   PetscFunctionListFind(MFNMonitorList,key,&mfunc);
 53:   PetscFunctionListFind(MFNMonitorCreateList,key,&cfunc);
 54:   PetscFunctionListFind(MFNMonitorDestroyList,key,&dfunc);
 55:   if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
 56:   if (!dfunc) dfunc = PetscViewerAndFormatDestroy;

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

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

 69:    Collective on mfn

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

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

 77:    Level: beginner

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

 90:   MFNRegisterAll();
 91:   ierr = 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) MFNSetType(mfn,type);
 94:     else if (!((PetscObject)mfn)->type_name) MFNSetType(mfn,MFNKRYLOV);

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

103:     PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
104:     if (flg) MFNSetDimensions(mfn,i);

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

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

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

119:     if (mfn->ops->setfromoptions) (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
120:     PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
121:   ierr = PetscOptionsEnd();

123:   if (!mfn->V) MFNGetBV(mfn,&mfn->V);
124:   BVSetFromOptions(mfn->V);
125:   if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
126:   FNSetFromOptions(mfn->fn);
127:   PetscFunctionReturn(0);
128: }

130: /*@C
131:    MFNGetTolerances - Gets the tolerance and maximum iteration count used
132:    by the MFN convergence tests.

134:    Not Collective

136:    Input Parameter:
137: .  mfn - the matrix function context

139:    Output Parameters:
140: +  tol - the convergence tolerance
141: -  maxits - maximum number of iterations

143:    Notes:
144:    The user can specify NULL for any parameter that is not needed.

146:    Level: intermediate

148: .seealso: MFNSetTolerances()
149: @*/
150: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
151: {
153:   if (tol)    *tol    = mfn->tol;
154:   if (maxits) *maxits = mfn->max_it;
155:   PetscFunctionReturn(0);
156: }

158: /*@
159:    MFNSetTolerances - Sets the tolerance and maximum iteration count used
160:    by the MFN convergence tests.

162:    Logically Collective on mfn

164:    Input Parameters:
165: +  mfn - the matrix function context
166: .  tol - the convergence tolerance
167: -  maxits - maximum number of iterations to use

169:    Options Database Keys:
170: +  -mfn_tol <tol> - Sets the convergence tolerance
171: -  -mfn_max_it <maxits> - Sets the maximum number of iterations allowed

173:    Notes:
174:    Use PETSC_DEFAULT for either argument to assign a reasonably good value.

176:    Level: intermediate

178: .seealso: MFNGetTolerances()
179: @*/
180: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
181: {
185:   if (tol == PETSC_DEFAULT) {
186:     mfn->tol = PETSC_DEFAULT;
187:     mfn->setupcalled = 0;
188:   } else {
190:     mfn->tol = tol;
191:   }
192:   if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
193:     mfn->max_it = PETSC_DEFAULT;
194:     mfn->setupcalled = 0;
195:   } else {
197:     mfn->max_it = maxits;
198:   }
199:   PetscFunctionReturn(0);
200: }

202: /*@
203:    MFNGetDimensions - Gets the dimension of the subspace used by the solver.

205:    Not Collective

207:    Input Parameter:
208: .  mfn - the matrix function context

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

213:    Level: intermediate

215: .seealso: MFNSetDimensions()
216: @*/
217: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
218: {
221:   *ncv = mfn->ncv;
222:   PetscFunctionReturn(0);
223: }

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

228:    Logically Collective on mfn

230:    Input Parameters:
231: +  mfn - the matrix function context
232: -  ncv - the maximum dimension of the subspace to be used by the solver

234:    Options Database Keys:
235: .  -mfn_ncv <ncv> - Sets the dimension of the subspace

237:    Notes:
238:    Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
239:    dependent on the solution method.

241:    Level: intermediate

243: .seealso: MFNGetDimensions()
244: @*/
245: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
246: {
249:   if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
250:     mfn->ncv = PETSC_DEFAULT;
251:   } else {
253:     mfn->ncv = ncv;
254:   }
255:   mfn->setupcalled = 0;
256:   PetscFunctionReturn(0);
257: }

259: /*@
260:    MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
261:    solver has not converged.

263:    Logically Collective on mfn

265:    Input Parameters:
266: +  mfn - the matrix function context
267: -  flg - PETSC_TRUE indicates you want the error generated

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

272:    Level: intermediate

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

278: .seealso: MFNGetErrorIfNotConverged()
279: @*/
280: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
281: {
284:   mfn->errorifnotconverged = flg;
285:   PetscFunctionReturn(0);
286: }

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

292:    Not Collective

294:    Input Parameter:
295: .  mfn - the matrix function context

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

300:    Level: intermediate

302: .seealso: MFNSetErrorIfNotConverged()
303: @*/
304: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
305: {
308:   *flag = mfn->errorifnotconverged;
309:   PetscFunctionReturn(0);
310: }

312: /*@C
313:    MFNSetOptionsPrefix - Sets the prefix used for searching for all
314:    MFN options in the database.

316:    Logically Collective on mfn

318:    Input Parameters:
319: +  mfn - the matrix function context
320: -  prefix - the prefix string to prepend to all MFN option requests

322:    Notes:
323:    A hyphen (-) must NOT be given at the beginning of the prefix name.
324:    The first character of all runtime options is AUTOMATICALLY the
325:    hyphen.

327:    For example, to distinguish between the runtime options for two
328:    different MFN contexts, one could call
329: .vb
330:       MFNSetOptionsPrefix(mfn1,"fun1_")
331:       MFNSetOptionsPrefix(mfn2,"fun2_")
332: .ve

334:    Level: advanced

336: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
337: @*/
338: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
339: {
341:   if (!mfn->V) MFNGetBV(mfn,&mfn->V);
342:   BVSetOptionsPrefix(mfn->V,prefix);
343:   if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
344:   FNSetOptionsPrefix(mfn->fn,prefix);
345:   PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
346:   PetscFunctionReturn(0);
347: }

349: /*@C
350:    MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
351:    MFN options in the database.

353:    Logically Collective on mfn

355:    Input Parameters:
356: +  mfn - the matrix function context
357: -  prefix - the prefix string to prepend to all MFN option requests

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

363:    Level: advanced

365: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
366: @*/
367: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
368: {
370:   if (!mfn->V) MFNGetBV(mfn,&mfn->V);
371:   BVAppendOptionsPrefix(mfn->V,prefix);
372:   if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
373:   FNAppendOptionsPrefix(mfn->fn,prefix);
374:   PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
375:   PetscFunctionReturn(0);
376: }

378: /*@C
379:    MFNGetOptionsPrefix - Gets the prefix used for searching for all
380:    MFN options in the database.

382:    Not Collective

384:    Input Parameters:
385: .  mfn - the matrix function context

387:    Output Parameters:
388: .  prefix - pointer to the prefix string used is returned

390:    Note:
391:    On the Fortran side, the user should pass in a string 'prefix' of
392:    sufficient length to hold the prefix.

394:    Level: advanced

396: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
397: @*/
398: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
399: {
402:   PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
403:   PetscFunctionReturn(0);
404: }