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> - the scaling factor
345: Notes:
346: The computed result is f(alpha*A)*b. The default is alpha=1.0.
348: In the case of complex scalars, a complex value can be provided in the
349: command line with [+/-][realnumber][+/-]realnumberi with no spaces, e.g.
350: -mfn_scale 1.0+2.0i
352: Level: intermediate
354: .seealso: MFNGetScaleFactor(), MFNSolve()
355: @*/
356: PetscErrorCode MFNSetScaleFactor(MFN mfn,PetscScalar alpha)357: {
361: mfn->sfactor = alpha;
362: return(0);
363: }
367: /*@
368: MFNGetScaleFactor - Gets the factor used for scaling the matrix.
370: Not Collective
372: Input Parameter:
373: . mfn - the matrix function context
375: Output Parameters:
376: . alpha - the scaling factor
378: Level: intermediate
380: .seealso: MFNSetScaleFactor(), MFNSolve()
381: @*/
382: PetscErrorCode MFNGetScaleFactor(MFN mfn,PetscScalar *alpha)383: {
387: *alpha = mfn->sfactor;
388: return(0);
389: }
393: /*@
394: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
395: solver has not converged.
397: Logically Collective on MFN399: Input Parameters:
400: + mfn - the matrix function context
401: - flg - PETSC_TRUE indicates you want the error generated
403: Options Database Keys:
404: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
406: Level: intermediate
408: Note:
409: Normally SLEPc continues if the solver fails to converge, you can call
410: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
412: .seealso: MFNGetErrorIfNotConverged()
413: @*/
414: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)415: {
419: mfn->errorifnotconverged = flg;
420: return(0);
421: }
425: /*@
426: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
427: generate an error if the solver does not converge.
429: Not Collective
431: Input Parameter:
432: . mfn - the matrix function context
434: Output Parameter:
435: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
437: Level: intermediate
439: .seealso: MFNSetErrorIfNotConverged()
440: @*/
441: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)442: {
446: *flag = mfn->errorifnotconverged;
447: return(0);
448: }
452: /*@C
453: MFNSetOptionsPrefix - Sets the prefix used for searching for all
454: MFN options in the database.
456: Logically Collective on MFN458: Input Parameters:
459: + mfn - the matrix function context
460: - prefix - the prefix string to prepend to all MFN option requests
462: Notes:
463: A hyphen (-) must NOT be given at the beginning of the prefix name.
464: The first character of all runtime options is AUTOMATICALLY the
465: hyphen.
467: For example, to distinguish between the runtime options for two
468: different MFN contexts, one could call
469: .vb
470: MFNSetOptionsPrefix(mfn1,"fun1_")
471: MFNSetOptionsPrefix(mfn2,"fun2_")
472: .ve
474: Level: advanced
476: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
477: @*/
478: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)479: {
484: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
485: BVSetOptionsPrefix(mfn->V,prefix);
486: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
487: DSSetOptionsPrefix(mfn->ds,prefix);
488: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
489: return(0);
490: }
494: /*@C
495: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
496: MFN options in the database.
498: Logically Collective on MFN500: Input Parameters:
501: + mfn - the matrix function context
502: - prefix - the prefix string to prepend to all MFN option requests
504: Notes:
505: A hyphen (-) must NOT be given at the beginning of the prefix name.
506: The first character of all runtime options is AUTOMATICALLY the hyphen.
508: Level: advanced
510: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
511: @*/
512: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)513: {
518: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
519: BVSetOptionsPrefix(mfn->V,prefix);
520: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
521: DSSetOptionsPrefix(mfn->ds,prefix);
522: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
523: return(0);
524: }
528: /*@C
529: MFNGetOptionsPrefix - Gets the prefix used for searching for all
530: MFN options in the database.
532: Not Collective
534: Input Parameters:
535: . mfn - the matrix function context
537: Output Parameters:
538: . prefix - pointer to the prefix string used is returned
540: Notes: On the fortran side, the user should pass in a string 'prefix' of
541: sufficient length to hold the prefix.
543: Level: advanced
545: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
546: @*/
547: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])548: {
554: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
555: return(0);
556: }