Actual source code: mfnopts.c
slepc-3.18.2 2023-01-26
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) return 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: return 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: {
83: char type[256];
84: PetscBool set,flg,flg1,flg2;
85: PetscReal r;
86: PetscInt i;
89: MFNRegisterAll();
90: PetscObjectOptionsBegin((PetscObject)mfn);
91: PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,sizeof(type),&flg);
92: if (flg) MFNSetType(mfn,type);
93: else if (!((PetscObject)mfn)->type_name) MFNSetType(mfn,MFNKRYLOV);
95: i = mfn->max_it;
96: PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
97: if (!flg1) i = PETSC_DEFAULT;
98: r = mfn->tol;
99: PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",SlepcDefaultTol(mfn->tol),&r,&flg2);
100: if (flg1 || flg2) MFNSetTolerances(mfn,r,i);
102: PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
103: if (flg) MFNSetDimensions(mfn,i);
105: PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);
107: /* -----------------------------------------------------------------------*/
108: /*
109: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
110: */
111: PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
112: if (set && flg) MFNMonitorCancel(mfn);
113: MFNMonitorSetFromOptions(mfn,"-mfn_monitor","error_estimate",NULL);
115: /* -----------------------------------------------------------------------*/
116: PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",NULL);
118: PetscTryTypeMethod(mfn,setfromoptions,PetscOptionsObject);
119: PetscObjectProcessOptionsHandlers((PetscObject)mfn,PetscOptionsObject);
120: PetscOptionsEnd();
122: if (!mfn->V) MFNGetBV(mfn,&mfn->V);
123: BVSetFromOptions(mfn->V);
124: if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
125: FNSetFromOptions(mfn->fn);
126: return 0;
127: }
129: /*@C
130: MFNGetTolerances - Gets the tolerance and maximum iteration count used
131: by the MFN convergence tests.
133: Not Collective
135: Input Parameter:
136: . mfn - the matrix function context
138: Output Parameters:
139: + tol - the convergence tolerance
140: - maxits - maximum number of iterations
142: Notes:
143: The user can specify NULL for any parameter that is not needed.
145: Level: intermediate
147: .seealso: MFNSetTolerances()
148: @*/
149: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
150: {
152: if (tol) *tol = mfn->tol;
153: if (maxits) *maxits = mfn->max_it;
154: return 0;
155: }
157: /*@
158: MFNSetTolerances - Sets the tolerance and maximum iteration count used
159: by the MFN convergence tests.
161: Logically Collective on mfn
163: Input Parameters:
164: + mfn - the matrix function context
165: . tol - the convergence tolerance
166: - maxits - maximum number of iterations to use
168: Options Database Keys:
169: + -mfn_tol <tol> - Sets the convergence tolerance
170: - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
172: Notes:
173: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
175: Level: intermediate
177: .seealso: MFNGetTolerances()
178: @*/
179: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
180: {
184: if (tol == PETSC_DEFAULT) {
185: mfn->tol = PETSC_DEFAULT;
186: mfn->setupcalled = 0;
187: } else {
189: mfn->tol = tol;
190: }
191: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
192: mfn->max_it = PETSC_DEFAULT;
193: mfn->setupcalled = 0;
194: } else {
196: mfn->max_it = maxits;
197: }
198: return 0;
199: }
201: /*@
202: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
204: Not Collective
206: Input Parameter:
207: . mfn - the matrix function context
209: Output Parameter:
210: . ncv - the maximum dimension of the subspace to be used by the solver
212: Level: intermediate
214: .seealso: MFNSetDimensions()
215: @*/
216: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
217: {
220: *ncv = mfn->ncv;
221: return 0;
222: }
224: /*@
225: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
227: Logically Collective on mfn
229: Input Parameters:
230: + mfn - the matrix function context
231: - ncv - the maximum dimension of the subspace to be used by the solver
233: Options Database Keys:
234: . -mfn_ncv <ncv> - Sets the dimension of the subspace
236: Notes:
237: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
238: dependent on the solution method.
240: Level: intermediate
242: .seealso: MFNGetDimensions()
243: @*/
244: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
245: {
248: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
249: mfn->ncv = PETSC_DEFAULT;
250: } else {
252: mfn->ncv = ncv;
253: }
254: mfn->setupcalled = 0;
255: return 0;
256: }
258: /*@
259: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
260: solver has not converged.
262: Logically Collective on mfn
264: Input Parameters:
265: + mfn - the matrix function context
266: - flg - PETSC_TRUE indicates you want the error generated
268: Options Database Keys:
269: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
271: Level: intermediate
273: Note:
274: Normally SLEPc continues if the solver fails to converge, you can call
275: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
277: .seealso: MFNGetErrorIfNotConverged()
278: @*/
279: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
280: {
283: mfn->errorifnotconverged = flg;
284: return 0;
285: }
287: /*@
288: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
289: generate an error if the solver does not converge.
291: Not Collective
293: Input Parameter:
294: . mfn - the matrix function context
296: Output Parameter:
297: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
299: Level: intermediate
301: .seealso: MFNSetErrorIfNotConverged()
302: @*/
303: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
304: {
307: *flag = mfn->errorifnotconverged;
308: return 0;
309: }
311: /*@C
312: MFNSetOptionsPrefix - Sets the prefix used for searching for all
313: MFN options in the database.
315: Logically Collective on mfn
317: Input Parameters:
318: + mfn - the matrix function context
319: - prefix - the prefix string to prepend to all MFN option requests
321: Notes:
322: A hyphen (-) must NOT be given at the beginning of the prefix name.
323: The first character of all runtime options is AUTOMATICALLY the
324: hyphen.
326: For example, to distinguish between the runtime options for two
327: different MFN contexts, one could call
328: .vb
329: MFNSetOptionsPrefix(mfn1,"fun1_")
330: MFNSetOptionsPrefix(mfn2,"fun2_")
331: .ve
333: Level: advanced
335: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
336: @*/
337: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
338: {
340: if (!mfn->V) MFNGetBV(mfn,&mfn->V);
341: BVSetOptionsPrefix(mfn->V,prefix);
342: if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
343: FNSetOptionsPrefix(mfn->fn,prefix);
344: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
345: return 0;
346: }
348: /*@C
349: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
350: MFN options in the database.
352: Logically Collective on mfn
354: Input Parameters:
355: + mfn - the matrix function context
356: - prefix - the prefix string to prepend to all MFN option requests
358: Notes:
359: A hyphen (-) must NOT be given at the beginning of the prefix name.
360: The first character of all runtime options is AUTOMATICALLY the hyphen.
362: Level: advanced
364: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
365: @*/
366: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
367: {
369: if (!mfn->V) MFNGetBV(mfn,&mfn->V);
370: BVAppendOptionsPrefix(mfn->V,prefix);
371: if (!mfn->fn) MFNGetFN(mfn,&mfn->fn);
372: FNAppendOptionsPrefix(mfn->fn,prefix);
373: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
374: return 0;
375: }
377: /*@C
378: MFNGetOptionsPrefix - Gets the prefix used for searching for all
379: MFN options in the database.
381: Not Collective
383: Input Parameters:
384: . mfn - the matrix function context
386: Output Parameters:
387: . prefix - pointer to the prefix string used is returned
389: Note:
390: On the Fortran side, the user should pass in a string 'prefix' of
391: sufficient length to hold the prefix.
393: Level: advanced
395: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
396: @*/
397: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
398: {
401: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
402: return 0;
403: }