1: /*
2: MFN routines related to options that can be set via the command-line
3: or procedurally.
5: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6: SLEPc - Scalable Library for Eigenvalue Problem Computations
7: Copyright (c) 2002-2016, Universitat Politecnica de Valencia, Spain
9: This file is part of SLEPc.
11: SLEPc is free software: you can redistribute it and/or modify it under the
12: terms of version 3 of the GNU Lesser General Public License as published by
13: the Free Software Foundation.
15: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
16: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
18: more details.
20: You should have received a copy of the GNU Lesser General Public License
21: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
22: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
23: */
25: #include <slepc/private/mfnimpl.h> /*I "slepcmfn.h" I*/
26: #include <petscdraw.h>
30: /*@C
31: MFNMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
32: indicated by the user.
34: Collective on MFN 36: Input Parameters:
37: + mfn - the eigensolver context
38: . name - the monitor option name
39: . help - message indicating what monitoring is done
40: . manual - manual page for the monitor
41: . monitor - the monitor function, whose context is a PetscViewerAndFormat
42: - trackall - whether this monitor tracks all eigenvalues or not
44: Level: developer
46: .seealso: MFNMonitorSet(), MFNSetTrackAll(), MFNConvMonitorSetFromOptions()
47: @*/
48: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*)) 49: {
50: PetscErrorCode ierr;
51: PetscBool flg;
52: PetscViewer viewer;
53: PetscViewerFormat format;
54: PetscViewerAndFormat *vf;
57: PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,name,&viewer,&format,&flg);
58: if (flg) {
59: PetscViewerAndFormatCreate(viewer,format,&vf);
60: PetscObjectDereference((PetscObject)viewer);
61: MFNMonitorSet(mfn,(PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
62: }
63: return(0);
64: }
68: /*@
69: MFNSetFromOptions - Sets MFN options from the options database.
70: This routine must be called before MFNSetUp() if the user is to be
71: allowed to set the solver type.
73: Collective on MFN 75: Input Parameters:
76: . mfn - the matrix function context
78: Notes:
79: To see all options, run your program with the -help option.
81: Level: beginner
82: @*/
83: PetscErrorCode MFNSetFromOptions(MFN mfn) 84: {
86: char type[256];
87: PetscBool set,flg,flg1,flg2;
88: PetscReal r;
89: PetscInt i;
90: PetscDrawLG lg;
94: MFNRegisterAll();
95: PetscObjectOptionsBegin((PetscObject)mfn);
96: PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
97: if (flg) {
98: MFNSetType(mfn,type);
99: }
100: /*
101: Set the type if it was never set.
102: */
103: if (!((PetscObject)mfn)->type_name) {
104: MFNSetType(mfn,MFNKRYLOV);
105: }
107: i = mfn->max_it;
108: PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
109: if (!flg1) i = PETSC_DEFAULT;
110: r = mfn->tol;
111: PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
112: if (flg1 || flg2) {
113: MFNSetTolerances(mfn,r,i);
114: }
116: PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
117: if (flg) {
118: MFNSetDimensions(mfn,i);
119: }
121: PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);
123: /* -----------------------------------------------------------------------*/
124: /*
125: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
126: */
127: PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
128: if (set && flg) {
129: MFNMonitorCancel(mfn);
130: }
131: /*
132: Text monitors
133: */
134: MFNMonitorSetFromOptions(mfn,"-mfn_monitor","Monitor error estimate","MFNMonitorDefault",MFNMonitorDefault);
135: /*
136: Line graph monitors
137: */
138: PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",PETSC_FALSE,&flg,&set);
139: if (set && flg) {
140: MFNMonitorLGCreate(PetscObjectComm((PetscObject)mfn),NULL,"Error estimate",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
141: MFNMonitorSet(mfn,MFNMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
142: }
143: /* -----------------------------------------------------------------------*/
145: PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",NULL);
147: if (mfn->ops->setfromoptions) {
148: (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
149: }
150: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
151: PetscOptionsEnd();
153: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
154: BVSetFromOptions(mfn->V);
155: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
156: FNSetFromOptions(mfn->fn);
157: return(0);
158: }
162: /*@
163: MFNGetTolerances - Gets the tolerance and maximum iteration count used
164: by the MFN convergence tests.
166: Not Collective
168: Input Parameter:
169: . mfn - the matrix function context
171: Output Parameters:
172: + tol - the convergence tolerance
173: - maxits - maximum number of iterations
175: Notes:
176: The user can specify NULL for any parameter that is not needed.
178: Level: intermediate
180: .seealso: MFNSetTolerances()
181: @*/
182: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)183: {
186: if (tol) *tol = mfn->tol;
187: if (maxits) *maxits = mfn->max_it;
188: return(0);
189: }
193: /*@
194: MFNSetTolerances - Sets the tolerance and maximum iteration count used
195: by the MFN convergence tests.
197: Logically Collective on MFN199: Input Parameters:
200: + mfn - the matrix function context
201: . tol - the convergence tolerance
202: - maxits - maximum number of iterations to use
204: Options Database Keys:
205: + -mfn_tol <tol> - Sets the convergence tolerance
206: - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
208: Notes:
209: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
211: Level: intermediate
213: .seealso: MFNGetTolerances()
214: @*/
215: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)216: {
221: if (tol == PETSC_DEFAULT) {
222: mfn->tol = PETSC_DEFAULT;
223: mfn->setupcalled = 0;
224: } else {
225: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
226: mfn->tol = tol;
227: }
228: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
229: mfn->max_it = 0;
230: mfn->setupcalled = 0;
231: } else {
232: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
233: mfn->max_it = maxits;
234: }
235: return(0);
236: }
240: /*@
241: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
243: Not Collective
245: Input Parameter:
246: . mfn - the matrix function context
248: Output Parameter:
249: . ncv - the maximum dimension of the subspace to be used by the solver
251: Level: intermediate
253: .seealso: MFNSetDimensions()
254: @*/
255: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)256: {
260: *ncv = mfn->ncv;
261: return(0);
262: }
266: /*@
267: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
269: Logically Collective on MFN271: Input Parameters:
272: + mfn - the matrix function context
273: - ncv - the maximum dimension of the subspace to be used by the solver
275: Options Database Keys:
276: . -mfn_ncv <ncv> - Sets the dimension of the subspace
278: Notes:
279: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
280: dependent on the solution method.
282: Level: intermediate
284: .seealso: MFNGetDimensions()
285: @*/
286: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)287: {
291: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
292: mfn->ncv = 0;
293: } else {
294: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
295: mfn->ncv = ncv;
296: }
297: mfn->setupcalled = 0;
298: return(0);
299: }
303: /*@
304: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
305: solver has not converged.
307: Logically Collective on MFN309: Input Parameters:
310: + mfn - the matrix function context
311: - flg - PETSC_TRUE indicates you want the error generated
313: Options Database Keys:
314: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
316: Level: intermediate
318: Note:
319: Normally SLEPc continues if the solver fails to converge, you can call
320: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
322: .seealso: MFNGetErrorIfNotConverged()
323: @*/
324: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)325: {
329: mfn->errorifnotconverged = flg;
330: return(0);
331: }
335: /*@
336: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
337: generate an error if the solver does not converge.
339: Not Collective
341: Input Parameter:
342: . mfn - the matrix function context
344: Output Parameter:
345: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
347: Level: intermediate
349: .seealso: MFNSetErrorIfNotConverged()
350: @*/
351: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)352: {
356: *flag = mfn->errorifnotconverged;
357: return(0);
358: }
362: /*@C
363: MFNSetOptionsPrefix - Sets the prefix used for searching for all
364: MFN options in the database.
366: Logically Collective on MFN368: Input Parameters:
369: + mfn - the matrix function context
370: - prefix - the prefix string to prepend to all MFN option requests
372: Notes:
373: A hyphen (-) must NOT be given at the beginning of the prefix name.
374: The first character of all runtime options is AUTOMATICALLY the
375: hyphen.
377: For example, to distinguish between the runtime options for two
378: different MFN contexts, one could call
379: .vb
380: MFNSetOptionsPrefix(mfn1,"fun1_")
381: MFNSetOptionsPrefix(mfn2,"fun2_")
382: .ve
384: Level: advanced
386: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
387: @*/
388: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)389: {
394: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
395: BVSetOptionsPrefix(mfn->V,prefix);
396: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
397: FNSetOptionsPrefix(mfn->fn,prefix);
398: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
399: return(0);
400: }
404: /*@C
405: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
406: MFN options in the database.
408: Logically Collective on MFN410: Input Parameters:
411: + mfn - the matrix function context
412: - prefix - the prefix string to prepend to all MFN option requests
414: Notes:
415: A hyphen (-) must NOT be given at the beginning of the prefix name.
416: The first character of all runtime options is AUTOMATICALLY the hyphen.
418: Level: advanced
420: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
421: @*/
422: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)423: {
428: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
429: BVSetOptionsPrefix(mfn->V,prefix);
430: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
431: FNSetOptionsPrefix(mfn->fn,prefix);
432: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
433: return(0);
434: }
438: /*@C
439: MFNGetOptionsPrefix - Gets the prefix used for searching for all
440: MFN options in the database.
442: Not Collective
444: Input Parameters:
445: . mfn - the matrix function context
447: Output Parameters:
448: . prefix - pointer to the prefix string used is returned
450: Note:
451: On the Fortran side, the user should pass in a string 'prefix' of
452: sufficient length to hold the prefix.
454: Level: advanced
456: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
457: @*/
458: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])459: {
465: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
466: return(0);
467: }