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