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-2014, 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: if (!MFNRegisterAllCalled) { 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: PetscOptionsBoolGroupBegin("-mfn_exp","matrix exponential","MFNSetFunction",&flg);
69: if (flg) {
70: MFNSetFunction(mfn,SLEPC_FUNCTION_EXP);
71: }
73: PetscOptionsScalar("-mfn_scale","Scale factor","MFNSetScaleFactor",mfn->sfactor,&mfn->sfactor,NULL);
75: i = mfn->max_it;
76: PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
77: r = mfn->tol;
78: PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
79: if (flg1 || flg2) {
80: MFNSetTolerances(mfn,r,i);
81: }
83: PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
84: if (flg) {
85: MFNSetDimensions(mfn,i);
86: }
88: PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);
90: /* -----------------------------------------------------------------------*/
91: /*
92: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
93: */
94: flg = PETSC_FALSE;
95: PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",flg,&flg,NULL);
96: if (flg) {
97: MFNMonitorCancel(mfn);
98: }
99: /*
100: Prints error estimate at each iteration
101: */
102: PetscOptionsString("-mfn_monitor","Monitor error estimate","MFNMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
103: if (flg) {
104: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)mfn),monfilename,&monviewer);
105: MFNMonitorSet(mfn,MFNMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
106: }
107: flg = PETSC_FALSE;
108: PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",flg,&flg,NULL);
109: if (flg) {
110: MFNMonitorSet(mfn,MFNMonitorLG,NULL,NULL);
111: }
112: /* -----------------------------------------------------------------------*/
114: PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",0);
116: if (mfn->ops->setfromoptions) {
117: (*mfn->ops->setfromoptions)(mfn);
118: }
119: PetscObjectProcessOptionsHandlers((PetscObject)mfn);
120: PetscOptionsEnd();
122: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
123: BVSetFromOptions(mfn->V);
124: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
125: DSSetFromOptions(mfn->ds);
126: PetscRandomSetFromOptions(mfn->rand);
127: return(0);
128: }
132: /*@
133: MFNGetTolerances - Gets the tolerance and maximum iteration count used
134: by the MFN convergence tests.
136: Not Collective
138: Input Parameter:
139: . mfn - the matrix function context
141: Output Parameters:
142: + tol - the convergence tolerance
143: - maxits - maximum number of iterations
145: Notes:
146: The user can specify NULL for any parameter that is not needed.
148: Level: intermediate
150: .seealso: MFNSetTolerances()
151: @*/
152: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)153: {
156: if (tol) *tol = mfn->tol;
157: if (maxits) *maxits = mfn->max_it;
158: return(0);
159: }
163: /*@
164: MFNSetTolerances - Sets the tolerance and maximum iteration count used
165: by the MFN convergence tests.
167: Logically Collective on MFN169: Input Parameters:
170: + mfn - the matrix function context
171: . tol - the convergence tolerance
172: - maxits - maximum number of iterations to use
174: Options Database Keys:
175: + -mfn_tol <tol> - Sets the convergence tolerance
176: - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
178: Notes:
179: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
181: Level: intermediate
183: .seealso: MFNGetTolerances()
184: @*/
185: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)186: {
191: if (tol == PETSC_DEFAULT) {
192: mfn->tol = PETSC_DEFAULT;
193: mfn->setupcalled = 0;
194: } else {
195: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
196: mfn->tol = tol;
197: }
198: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
199: mfn->max_it = 0;
200: mfn->setupcalled = 0;
201: } else {
202: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
203: mfn->max_it = maxits;
204: }
205: return(0);
206: }
210: /*@
211: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
213: Not Collective
215: Input Parameter:
216: . mfn - the matrix function context
218: Output Parameter:
219: . ncv - the maximum dimension of the subspace to be used by the solver
221: Level: intermediate
223: .seealso: MFNSetDimensions()
224: @*/
225: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)226: {
230: *ncv = mfn->ncv;
231: return(0);
232: }
236: /*@
237: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
239: Logically Collective on MFN241: Input Parameters:
242: + mfn - the matrix function context
243: - ncv - the maximum dimension of the subspace to be used by the solver
245: Options Database Keys:
246: . -mfn_ncv <ncv> - Sets the dimension of the subspace
248: Notes:
249: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
250: dependent on the solution method.
252: Level: intermediate
254: .seealso: MFNGetDimensions()
255: @*/
256: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)257: {
261: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
262: mfn->ncv = 0;
263: } else {
264: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
265: mfn->ncv = ncv;
266: }
267: mfn->setupcalled = 0;
268: return(0);
269: }
273: /*@
274: MFNSetFunction - Specifies the function to be computed.
276: Logically Collective on MFN278: Input Parameters:
279: + mfn - the matrix function context
280: - fun - a known function
282: Options Database Keys:
283: . -mfn_exp - matrix exponential
285: Level: beginner
287: .seealso: MFNSetOperator(), MFNSetType(), MFNGetFunction(), SlepcFunction
288: @*/
289: PetscErrorCode MFNSetFunction(MFN mfn,SlepcFunction fun)290: {
294: switch (fun) {
295: case SLEPC_FUNCTION_EXP:
296: break;
297: default:298: SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Unknown function");
299: }
300: mfn->function = fun;
301: return(0);
302: }
306: /*@C
307: MFNGetFunction - Gets the function from the MFN object.
309: Not Collective
311: Input Parameter:
312: . mfn - the matrix function context
314: Output Parameter:
315: . fun - function
317: Level: intermediate
319: .seealso: MFNSetFunction(), SlepcFunction
320: @*/
321: PetscErrorCode MFNGetFunction(MFN mfn,SlepcFunction *fun)322: {
326: *fun = mfn->function;
327: return(0);
328: }
332: /*@
333: MFNSetScaleFactor - Sets the scale factor to multiply the matrix (the
334: argument of the function).
336: Logically Collective on MFN338: Input Parameters:
339: + mfn - the matrix function context
340: - alpha - the scaling factor
342: Options Database Keys:
343: . -mfn_scale <alpha> - Sets the scaling factor
345: Notes:
346: The computed result is f(alpha*A)*b. The default is alpha=1.0.
348: Level: intermediate
350: .seealso: MFNGetScaleFactor(), MFNSolve()
351: @*/
352: PetscErrorCode MFNSetScaleFactor(MFN mfn,PetscScalar alpha)353: {
357: mfn->sfactor = alpha;
358: return(0);
359: }
363: /*@
364: MFNGetScaleFactor - Gets the factor used for scaling the matrix.
366: Not Collective
368: Input Parameter:
369: . mfn - the matrix function context
371: Output Parameters:
372: . alpha - the scaling factor
374: Level: intermediate
376: .seealso: MFNSetScaleFactor(), MFNSolve()
377: @*/
378: PetscErrorCode MFNGetScaleFactor(MFN mfn,PetscScalar *alpha)379: {
383: *alpha = mfn->sfactor;
384: return(0);
385: }
389: /*@
390: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
391: solver has not converged.
393: Logically Collective on MFN395: Input Parameters:
396: + mfn - the matrix function context
397: - flg - PETSC_TRUE indicates you want the error generated
399: Options Database Keys:
400: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
402: Level: intermediate
404: Note:
405: Normally SLEPc continues if the solver fails to converge, you can call
406: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
408: .seealso: MFNGetErrorIfNotConverged()
409: @*/
410: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)411: {
415: mfn->errorifnotconverged = flg;
416: return(0);
417: }
421: /*@
422: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
423: generate an error if the solver does not converge.
425: Not Collective
427: Input Parameter:
428: . mfn - the matrix function context
430: Output Parameter:
431: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
433: Level: intermediate
435: .seealso: MFNSetErrorIfNotConverged()
436: @*/
437: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)438: {
442: *flag = mfn->errorifnotconverged;
443: return(0);
444: }
448: /*@C
449: MFNSetOptionsPrefix - Sets the prefix used for searching for all
450: MFN options in the database.
452: Logically Collective on MFN454: Input Parameters:
455: + mfn - the matrix function context
456: - prefix - the prefix string to prepend to all MFN option requests
458: Notes:
459: A hyphen (-) must NOT be given at the beginning of the prefix name.
460: The first character of all runtime options is AUTOMATICALLY the
461: hyphen.
463: For example, to distinguish between the runtime options for two
464: different MFN contexts, one could call
465: .vb
466: MFNSetOptionsPrefix(mfn1,"fun1_")
467: MFNSetOptionsPrefix(mfn2,"fun2_")
468: .ve
470: Level: advanced
472: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
473: @*/
474: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)475: {
480: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
481: BVSetOptionsPrefix(mfn->V,prefix);
482: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
483: DSSetOptionsPrefix(mfn->ds,prefix);
484: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
485: return(0);
486: }
490: /*@C
491: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
492: MFN options in the database.
494: Logically Collective on MFN496: Input Parameters:
497: + mfn - the matrix function context
498: - prefix - the prefix string to prepend to all MFN option requests
500: Notes:
501: A hyphen (-) must NOT be given at the beginning of the prefix name.
502: The first character of all runtime options is AUTOMATICALLY the hyphen.
504: Level: advanced
506: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
507: @*/
508: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)509: {
514: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
515: BVSetOptionsPrefix(mfn->V,prefix);
516: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
517: DSSetOptionsPrefix(mfn->ds,prefix);
518: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
519: return(0);
520: }
524: /*@C
525: MFNGetOptionsPrefix - Gets the prefix used for searching for all
526: MFN options in the database.
528: Not Collective
530: Input Parameters:
531: . mfn - the matrix function context
533: Output Parameters:
534: . prefix - pointer to the prefix string used is returned
536: Notes: On the fortran side, the user should pass in a string 'prefix' of
537: sufficient length to hold the prefix.
539: Level: advanced
541: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
542: @*/
543: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])544: {
550: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
551: return(0);
552: }