Actual source code: mfnopts.c
slepc-3.21.1 2024-04-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
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: PetscFunctionBegin;
47: PetscCall(PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,opt,&viewer,&format,&flg));
48: if (!flg) PetscFunctionReturn(PETSC_SUCCESS);
50: PetscCall(PetscViewerGetType(viewer,&vtype));
51: PetscCall(SlepcMonitorMakeKey_Internal(name,vtype,format,key));
52: PetscCall(PetscFunctionListFind(MFNMonitorList,key,&mfunc));
53: PetscCheck(mfunc,PetscObjectComm((PetscObject)mfn),PETSC_ERR_SUP,"Specified viewer and format not supported");
54: PetscCall(PetscFunctionListFind(MFNMonitorCreateList,key,&cfunc));
55: PetscCall(PetscFunctionListFind(MFNMonitorDestroyList,key,&dfunc));
56: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
57: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
59: PetscCall((*cfunc)(viewer,format,ctx,&vf));
60: PetscCall(PetscOptionsRestoreViewer(&viewer));
61: PetscCall(MFNMonitorSet(mfn,mfunc,vf,(PetscErrorCode(*)(void **))dfunc));
62: PetscFunctionReturn(PETSC_SUCCESS);
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
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
80: .seealso: MFNSetOptionsPrefix()
81: @*/
82: PetscErrorCode MFNSetFromOptions(MFN mfn)
83: {
84: char type[256];
85: PetscBool set,flg,flg1,flg2;
86: PetscReal r;
87: PetscInt i;
89: PetscFunctionBegin;
91: PetscCall(MFNRegisterAll());
92: PetscObjectOptionsBegin((PetscObject)mfn);
93: PetscCall(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) PetscCall(MFNSetType(mfn,type));
95: else if (!((PetscObject)mfn)->type_name) PetscCall(MFNSetType(mfn,MFNKRYLOV));
97: i = mfn->max_it;
98: PetscCall(PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1));
99: if (!flg1) i = PETSC_DEFAULT;
100: r = mfn->tol;
101: PetscCall(PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",SlepcDefaultTol(mfn->tol),&r,&flg2));
102: if (flg1 || flg2) PetscCall(MFNSetTolerances(mfn,r,i));
104: PetscCall(PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg));
105: if (flg) PetscCall(MFNSetDimensions(mfn,i));
107: PetscCall(PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL));
109: /* -----------------------------------------------------------------------*/
110: /*
111: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
112: */
113: PetscCall(PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set));
114: if (set && flg) PetscCall(MFNMonitorCancel(mfn));
115: PetscCall(MFNMonitorSetFromOptions(mfn,"-mfn_monitor","error_estimate",NULL));
117: /* -----------------------------------------------------------------------*/
118: PetscCall(PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",&set));
120: PetscTryTypeMethod(mfn,setfromoptions,PetscOptionsObject);
121: PetscCall(PetscObjectProcessOptionsHandlers((PetscObject)mfn,PetscOptionsObject));
122: PetscOptionsEnd();
124: if (!mfn->V) PetscCall(MFNGetBV(mfn,&mfn->V));
125: PetscCall(BVSetFromOptions(mfn->V));
126: if (!mfn->fn) PetscCall(MFNGetFN(mfn,&mfn->fn));
127: PetscCall(FNSetFromOptions(mfn->fn));
128: PetscFunctionReturn(PETSC_SUCCESS);
129: }
131: /*@C
132: MFNGetTolerances - Gets the tolerance and maximum iteration count used
133: by the MFN convergence tests.
135: Not Collective
137: Input Parameter:
138: . mfn - the matrix function context
140: Output Parameters:
141: + tol - the convergence tolerance
142: - maxits - maximum number of iterations
144: Notes:
145: The user can specify NULL for any parameter that is not needed.
147: Level: intermediate
149: .seealso: MFNSetTolerances()
150: @*/
151: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
152: {
153: PetscFunctionBegin;
155: if (tol) *tol = mfn->tol;
156: if (maxits) *maxits = mfn->max_it;
157: PetscFunctionReturn(PETSC_SUCCESS);
158: }
160: /*@
161: MFNSetTolerances - Sets the tolerance and maximum iteration count used
162: by the MFN convergence tests.
164: Logically Collective
166: Input Parameters:
167: + mfn - the matrix function context
168: . tol - the convergence tolerance
169: - maxits - maximum number of iterations to use
171: Options Database Keys:
172: + -mfn_tol <tol> - Sets the convergence tolerance
173: - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
175: Notes:
176: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
178: Level: intermediate
180: .seealso: MFNGetTolerances()
181: @*/
182: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
183: {
184: PetscFunctionBegin;
188: if (tol == (PetscReal)PETSC_DEFAULT) {
189: mfn->tol = PETSC_DEFAULT;
190: mfn->setupcalled = 0;
191: } else {
192: PetscCheck(tol>0.0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
193: mfn->tol = tol;
194: }
195: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
196: mfn->max_it = PETSC_DEFAULT;
197: mfn->setupcalled = 0;
198: } else {
199: PetscCheck(maxits>0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
200: mfn->max_it = maxits;
201: }
202: PetscFunctionReturn(PETSC_SUCCESS);
203: }
205: /*@
206: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
208: Not Collective
210: Input Parameter:
211: . mfn - the matrix function context
213: Output Parameter:
214: . ncv - the maximum dimension of the subspace to be used by the solver
216: Level: intermediate
218: .seealso: MFNSetDimensions()
219: @*/
220: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
221: {
222: PetscFunctionBegin;
224: PetscAssertPointer(ncv,2);
225: *ncv = mfn->ncv;
226: PetscFunctionReturn(PETSC_SUCCESS);
227: }
229: /*@
230: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
232: Logically Collective
234: Input Parameters:
235: + mfn - the matrix function context
236: - ncv - the maximum dimension of the subspace to be used by the solver
238: Options Database Keys:
239: . -mfn_ncv <ncv> - Sets the dimension of the subspace
241: Notes:
242: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
243: dependent on the solution method.
245: Level: intermediate
247: .seealso: MFNGetDimensions()
248: @*/
249: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
250: {
251: PetscFunctionBegin;
254: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
255: mfn->ncv = PETSC_DEFAULT;
256: } else {
257: PetscCheck(ncv>0,PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
258: mfn->ncv = ncv;
259: }
260: mfn->setupcalled = 0;
261: PetscFunctionReturn(PETSC_SUCCESS);
262: }
264: /*@
265: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
266: solver has not converged.
268: Logically Collective
270: Input Parameters:
271: + mfn - the matrix function context
272: - flg - PETSC_TRUE indicates you want the error generated
274: Options Database Keys:
275: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
277: Level: intermediate
279: Note:
280: Normally SLEPc continues if the solver fails to converge, you can call
281: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
283: .seealso: MFNGetErrorIfNotConverged()
284: @*/
285: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
286: {
287: PetscFunctionBegin;
290: mfn->errorifnotconverged = flg;
291: PetscFunctionReturn(PETSC_SUCCESS);
292: }
294: /*@
295: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
296: generate an error if the solver does not converge.
298: Not Collective
300: Input Parameter:
301: . mfn - the matrix function context
303: Output Parameter:
304: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
306: Level: intermediate
308: .seealso: MFNSetErrorIfNotConverged()
309: @*/
310: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
311: {
312: PetscFunctionBegin;
314: PetscAssertPointer(flag,2);
315: *flag = mfn->errorifnotconverged;
316: PetscFunctionReturn(PETSC_SUCCESS);
317: }
319: /*@C
320: MFNSetOptionsPrefix - Sets the prefix used for searching for all
321: MFN options in the database.
323: Logically Collective
325: Input Parameters:
326: + mfn - the matrix function context
327: - prefix - the prefix string to prepend to all MFN option requests
329: Notes:
330: A hyphen (-) must NOT be given at the beginning of the prefix name.
331: The first character of all runtime options is AUTOMATICALLY the
332: hyphen.
334: For example, to distinguish between the runtime options for two
335: different MFN contexts, one could call
336: .vb
337: MFNSetOptionsPrefix(mfn1,"fun1_")
338: MFNSetOptionsPrefix(mfn2,"fun2_")
339: .ve
341: Level: advanced
343: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
344: @*/
345: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
346: {
347: PetscFunctionBegin;
349: if (!mfn->V) PetscCall(MFNGetBV(mfn,&mfn->V));
350: PetscCall(BVSetOptionsPrefix(mfn->V,prefix));
351: if (!mfn->fn) PetscCall(MFNGetFN(mfn,&mfn->fn));
352: PetscCall(FNSetOptionsPrefix(mfn->fn,prefix));
353: PetscCall(PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix));
354: PetscFunctionReturn(PETSC_SUCCESS);
355: }
357: /*@C
358: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
359: MFN options in the database.
361: Logically Collective
363: Input Parameters:
364: + mfn - the matrix function context
365: - prefix - the prefix string to prepend to all MFN option requests
367: Notes:
368: A hyphen (-) must NOT be given at the beginning of the prefix name.
369: The first character of all runtime options is AUTOMATICALLY the hyphen.
371: Level: advanced
373: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
374: @*/
375: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
376: {
377: PetscFunctionBegin;
379: if (!mfn->V) PetscCall(MFNGetBV(mfn,&mfn->V));
380: PetscCall(BVAppendOptionsPrefix(mfn->V,prefix));
381: if (!mfn->fn) PetscCall(MFNGetFN(mfn,&mfn->fn));
382: PetscCall(FNAppendOptionsPrefix(mfn->fn,prefix));
383: PetscCall(PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix));
384: PetscFunctionReturn(PETSC_SUCCESS);
385: }
387: /*@C
388: MFNGetOptionsPrefix - Gets the prefix used for searching for all
389: MFN options in the database.
391: Not Collective
393: Input Parameters:
394: . mfn - the matrix function context
396: Output Parameters:
397: . prefix - pointer to the prefix string used is returned
399: Note:
400: On the Fortran side, the user should pass in a string 'prefix' of
401: sufficient length to hold the prefix.
403: Level: advanced
405: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
406: @*/
407: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
408: {
409: PetscFunctionBegin;
411: PetscAssertPointer(prefix,2);
412: PetscCall(PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix));
413: PetscFunctionReturn(PETSC_SUCCESS);
414: }