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