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