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-2015, 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*/
29: /*@
30: MFNSetFromOptions - Sets MFN options from the options database.
31: This routine must be called before MFNSetUp() if the user is to be
32: allowed to set the solver type.
34: Collective on MFN 36: Input Parameters:
37: . mfn - the matrix function context
39: Notes:
40: To see all options, run your program with the -help option.
42: Level: beginner
43: @*/
44: PetscErrorCode MFNSetFromOptions(MFN mfn) 45: {
46: PetscErrorCode ierr;
47: char type[256],monfilename[PETSC_MAX_PATH_LEN];
48: PetscBool flg,flg1,flg2;
49: PetscReal r;
50: PetscInt i;
51: PetscViewer monviewer;
55: MFNRegisterAll();
56: PetscObjectOptionsBegin((PetscObject)mfn);
57: PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
58: if (flg) {
59: MFNSetType(mfn,type);
60: }
61: /*
62: Set the type if it was never set.
63: */
64: if (!((PetscObject)mfn)->type_name) {
65: MFNSetType(mfn,MFNKRYLOV);
66: }
68: i = mfn->max_it;
69: PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
70: if (!flg1) i = PETSC_DEFAULT;
71: r = mfn->tol;
72: PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
73: if (flg1 || flg2) {
74: MFNSetTolerances(mfn,r,i);
75: }
77: PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
78: if (flg) {
79: MFNSetDimensions(mfn,i);
80: }
82: PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);
84: /* -----------------------------------------------------------------------*/
85: /*
86: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
87: */
88: flg = PETSC_FALSE;
89: PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",flg,&flg,NULL);
90: if (flg) {
91: MFNMonitorCancel(mfn);
92: }
93: /*
94: Prints error estimate at each iteration
95: */
96: PetscOptionsString("-mfn_monitor","Monitor error estimate","MFNMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
97: if (flg) {
98: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)mfn),monfilename,&monviewer);
99: MFNMonitorSet(mfn,MFNMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
100: }
101: flg = PETSC_FALSE;
102: PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",flg,&flg,NULL);
103: if (flg) {
104: MFNMonitorSet(mfn,MFNMonitorLG,NULL,NULL);
105: }
106: /* -----------------------------------------------------------------------*/
108: PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",0);
110: if (mfn->ops->setfromoptions) {
111: (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
112: }
113: PetscObjectProcessOptionsHandlers((PetscObject)mfn);
114: PetscOptionsEnd();
116: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
117: BVSetFromOptions(mfn->V);
118: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
119: FNSetFromOptions(mfn->fn);
120: PetscRandomSetFromOptions(mfn->rand);
121: return(0);
122: }
126: /*@
127: MFNGetTolerances - Gets the tolerance and maximum iteration count used
128: by the MFN convergence tests.
130: Not Collective
132: Input Parameter:
133: . mfn - the matrix function context
135: Output Parameters:
136: + tol - the convergence tolerance
137: - maxits - maximum number of iterations
139: Notes:
140: The user can specify NULL for any parameter that is not needed.
142: Level: intermediate
144: .seealso: MFNSetTolerances()
145: @*/
146: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)147: {
150: if (tol) *tol = mfn->tol;
151: if (maxits) *maxits = mfn->max_it;
152: return(0);
153: }
157: /*@
158: MFNSetTolerances - Sets the tolerance and maximum iteration count used
159: by the MFN convergence tests.
161: Logically Collective on MFN163: 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: {
185: if (tol == PETSC_DEFAULT) {
186: mfn->tol = PETSC_DEFAULT;
187: mfn->setupcalled = 0;
188: } else {
189: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
190: mfn->tol = tol;
191: }
192: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
193: mfn->max_it = 0;
194: mfn->setupcalled = 0;
195: } else {
196: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
197: mfn->max_it = maxits;
198: }
199: return(0);
200: }
204: /*@
205: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
207: Not Collective
209: Input Parameter:
210: . mfn - the matrix function context
212: Output Parameter:
213: . ncv - the maximum dimension of the subspace to be used by the solver
215: Level: intermediate
217: .seealso: MFNSetDimensions()
218: @*/
219: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)220: {
224: *ncv = mfn->ncv;
225: return(0);
226: }
230: /*@
231: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
233: Logically Collective on MFN235: Input Parameters:
236: + mfn - the matrix function context
237: - ncv - the maximum dimension of the subspace to be used by the solver
239: Options Database Keys:
240: . -mfn_ncv <ncv> - Sets the dimension of the subspace
242: Notes:
243: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
244: dependent on the solution method.
246: Level: intermediate
248: .seealso: MFNGetDimensions()
249: @*/
250: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)251: {
255: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
256: mfn->ncv = 0;
257: } else {
258: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
259: mfn->ncv = ncv;
260: }
261: mfn->setupcalled = 0;
262: return(0);
263: }
267: /*@
268: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
269: solver has not converged.
271: Logically Collective on MFN273: Input Parameters:
274: + mfn - the matrix function context
275: - flg - PETSC_TRUE indicates you want the error generated
277: Options Database Keys:
278: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
280: Level: intermediate
282: Note:
283: Normally SLEPc continues if the solver fails to converge, you can call
284: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
286: .seealso: MFNGetErrorIfNotConverged()
287: @*/
288: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)289: {
293: mfn->errorifnotconverged = flg;
294: return(0);
295: }
299: /*@
300: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
301: generate an error if the solver does not converge.
303: Not Collective
305: Input Parameter:
306: . mfn - the matrix function context
308: Output Parameter:
309: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
311: Level: intermediate
313: .seealso: MFNSetErrorIfNotConverged()
314: @*/
315: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)316: {
320: *flag = mfn->errorifnotconverged;
321: return(0);
322: }
326: /*@C
327: MFNSetOptionsPrefix - Sets the prefix used for searching for all
328: MFN options in the database.
330: Logically Collective on MFN332: Input Parameters:
333: + mfn - the matrix function context
334: - prefix - the prefix string to prepend to all MFN option requests
336: Notes:
337: A hyphen (-) must NOT be given at the beginning of the prefix name.
338: The first character of all runtime options is AUTOMATICALLY the
339: hyphen.
341: For example, to distinguish between the runtime options for two
342: different MFN contexts, one could call
343: .vb
344: MFNSetOptionsPrefix(mfn1,"fun1_")
345: MFNSetOptionsPrefix(mfn2,"fun2_")
346: .ve
348: Level: advanced
350: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
351: @*/
352: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)353: {
358: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
359: BVSetOptionsPrefix(mfn->V,prefix);
360: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
361: FNSetOptionsPrefix(mfn->fn,prefix);
362: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
363: return(0);
364: }
368: /*@C
369: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
370: MFN options in the database.
372: Logically Collective on MFN374: Input Parameters:
375: + mfn - the matrix function context
376: - prefix - the prefix string to prepend to all MFN option requests
378: Notes:
379: A hyphen (-) must NOT be given at the beginning of the prefix name.
380: The first character of all runtime options is AUTOMATICALLY the hyphen.
382: Level: advanced
384: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
385: @*/
386: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)387: {
392: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
393: BVSetOptionsPrefix(mfn->V,prefix);
394: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
395: FNSetOptionsPrefix(mfn->fn,prefix);
396: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
397: return(0);
398: }
402: /*@C
403: MFNGetOptionsPrefix - Gets the prefix used for searching for all
404: MFN options in the database.
406: Not Collective
408: Input Parameters:
409: . mfn - the matrix function context
411: Output Parameters:
412: . prefix - pointer to the prefix string used is returned
414: Notes: On the fortran side, the user should pass in a string 'prefix' of
415: sufficient length to hold the prefix.
417: Level: advanced
419: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
420: @*/
421: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])422: {
428: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
429: return(0);
430: }